{
  "pack_id": "lora-memory-and-shimming",
  "title": "LoRA memory and shimming",
  "version": "0.1.0",
  "summary": "A collection of nouns and verbs for compiling post-cutoff Task Objects into leakage-checked parametric-memory LoRA training pairs, choosing between prompt/context shimming, weight updates and hybrid routing, and evaluating pre-registered holdout paired bootstrap CI promotion gates.",
  "dependencies": [
    "continuous-tuning",
    "freshness-checks"
  ],
  "boundaries": [
    "Compiled training pairs and synthetic smoke evaluations are never presented as admitted adapters or proven model improvements.",
    "Training pairs must pass 4-gram Jaccard disjointness against pre-registered holdouts before any weight update is evaluated.",
    "Fast-churning or instantly revocable facts route to prompt/context shims rather than LoRA weights.",
    "Importing the pack writes nothing, enqueues nothing and installs no code."
  ],
  "nouns": [
    {
      "slug": "pack",
      "category": "noun.skill_pack",
      "role": "pack",
      "title": "A collection of nouns and verbs for compiling post-cutoff Task Objects into LoRA pairs, routing between shims and weight updates, and gating promotion on holdout bootstrap CIs",
      "value": {
        "lets_workers": "Decide whether post-cutoff knowledge belongs in a revocable prompt shim, a parametric LoRA adapter or a hybrid combination, compile direct-recall, supersession-contrast and scope-abstention pairs verified disjoint from holdouts, and gate promotion on paired bootstrap 95 percent confidence intervals.",
        "flow": [
          {
            "verb": {
              "$verb": "lora-memory-and-shimming.route-shim-or-lora"
            },
            "when": "Evaluate churn half-life, query frequency and token amortization before training."
          },
          {
            "verb": {
              "$verb": "lora-memory-and-shimming.compile-lora-pairs"
            },
            "when": "Compile verified post-cutoff Task Objects into leakage-checked SFT pairs."
          },
          {
            "verb": {
              "$verb": "lora-memory-and-shimming.evaluate-bootstrap-gate"
            },
            "when": "Gate candidate weights or shims on pre-registered holdout bootstrap CIs and retention floors."
          }
        ],
        "guardrails": [
          {
            "$pin": "guardrail.smoke-is-not-improvement"
          },
          {
            "$pin": "guardrail.holdout-ngram-disjointness"
          },
          {
            "$pin": "guardrail.shim-volatile-facts"
          }
        ],
        "tool": {
          "$pin": "tool.lora-memory"
        },
        "worked_example": "Synthetic 2-object post-cutoff bundle recomputed in test_lora_memory.py: compiles 6 pairs (direct, supersession, abstention) with zero holdout leakage, selects hybrid_shim_and_lora, and verifies paired bootstrap promotion gates."
      },
      "relations": [
        [
          "requires_noun",
          "guardrail.smoke-is-not-improvement"
        ],
        [
          "requires_noun",
          "guardrail.holdout-ngram-disjointness"
        ],
        [
          "requires_noun",
          "guardrail.shim-volatile-facts"
        ],
        [
          "requires_noun",
          "spec.routing-and-gates"
        ],
        [
          "requires_noun",
          "rules.pair-compilation"
        ],
        [
          "requires_noun",
          "tool.lora-memory"
        ],
        [
          "requires_noun",
          "template.gate-decision"
        ]
      ]
    },
    {
      "slug": "guardrail.smoke-is-not-improvement",
      "category": "noun.skill_pack",
      "role": "guardrail",
      "title": "Guardrail: never present a compiled pair set or smoke run as a proven model improvement",
      "category_reason": "Enforces honest separation between dataset preparation and statistically gated promotion.",
      "value": {
        "rule": "A candidate adapter passes only when paired bootstrap 95 percent CI lower bounds clear target gain (>= +0.05), general retention (>= -0.015) and hallucination rate (<= 0.02) on pre-registered holdouts.",
        "how_it_is_checked": "evaluate_promotion_gate checks all three bounds simultaneously and lists any failed gate."
      }
    },
    {
      "slug": "guardrail.holdout-ngram-disjointness",
      "category": "noun.skill_pack",
      "role": "guardrail",
      "title": "Guardrail: training prompts must remain n-gram disjoint from pre-registered holdout prompts",
      "category_reason": "Prevents memorization of holdout phrasing from inflating post-cutoff gains.",
      "value": {
        "rule": "Every compiled training prompt has zero exact match and 4-gram Jaccard <= 0.35 against every holdout prompt.",
        "how_it_is_checked": "check_holdout_disjointness scans all train-holdout pairs and blocks promotion on any collision."
      }
    },
    {
      "slug": "guardrail.shim-volatile-facts",
      "category": "noun.skill_pack",
      "role": "guardrail",
      "title": "Guardrail: facts with half-life under 14 days or instant revocation needs stay in prompt shims",
      "category_reason": "Prevents baking transient version numbers or revocable policies into model weights.",
      "value": {
        "rule": "When churn_half_life_days < 14 or requires_instant_revocation is true, route_adaptation_strategy selects prompt_context_shim regardless of query volume.",
        "how_it_is_checked": "route_adaptation_strategy enforces the volatility and revocation check before amortization."
      }
    },
    {
      "slug": "spec.routing-and-gates",
      "category": "noun.benchmark_suite",
      "role": "spec",
      "title": "Specification: shim-vs-LoRA routing policy and paired bootstrap (B=1000) promotion gates",
      "category_reason": "Defines deterministic thresholds for routing and holdout statistical gating.",
      "value": {
        "routing": {
          "min_churn_days_for_weights": 14.0,
          "pure_lora_min_churn_days": 30.0,
          "default_training_equivalent_tokens": 2000000,
          "modes": [
            "prompt_context_shim",
            "lora_weight_update",
            "hybrid_shim_and_lora"
          ]
        },
        "promotion_gates": {
          "bootstrap_resamples": 1000,
          "confidence_level": 0.95,
          "min_target_gain_ci_low": 0.05,
          "max_retention_drop": 0.015,
          "max_hallucination_rate": 0.02
        }
      }
    },
    {
      "slug": "rules.pair-compilation",
      "category": "noun.reflex_procedure",
      "role": "rules",
      "title": "Compilation rules: direct recall, supersession contrast and scope abstention SFT pairs",
      "category_reason": "Zero-call transformation from pinned post-cutoff Task Objects to balanced training pairs.",
      "value": {
        "pair_families": [
          "direct_fact",
          "supersession_guard",
          "scope_abstention"
        ],
        "ngram_n": 4,
        "max_holdout_jaccard": 0.35,
        "model_calls": 0
      }
    },
    {
      "slug": "tool.lora-memory",
      "category": "noun.code_node",
      "role": "tool_card",
      "title": "Tool card: post-cutoff LoRA compiler, shim router and bootstrap gate evaluator",
      "category_reason": "Tested Python standard-library package pinned by path, file count and digest.",
      "value": {
        "name": "LoRA memory and shimming",
        "code": {
          "$code": "lora-memory-and-shimming"
        },
        "runtime": "Python 3.10 or later, standard library only.",
        "commands": [
          "python -m lora_memory route --spec-json ROUTING_SPEC.json",
          "python -m lora_memory compile --input POST_CUTOFF_BUNDLE.json",
          "python -m lora_memory gate --eval-json HOLDOUT_EVAL.json"
        ],
        "does": [
          "Routes adaptation requests across prompt_context_shim, lora_weight_update and hybrid_shim_and_lora.",
          "Compiles direct, supersession and abstention SFT pairs and verifies 4-gram Jaccard disjointness against holdouts.",
          "Computes seeded paired bootstrap 95 percent CIs for target gain, general retention and hallucination rate."
        ],
        "does_not": [
          "Run GPU gradient updates, mutate deployed model weights or claim unverified benchmark improvements."
        ],
        "code_license": "MIT"
      },
      "relations": [
        [
          "verifies",
          "spec.routing-and-gates"
        ]
      ]
    },
    {
      "slug": "template.gate-decision",
      "category": "noun.scene_recipe",
      "role": "template",
      "title": "Template: LoRA vs shim routing and holdout bootstrap gate decision",
      "value": {
        "describes": "a deterministic record of compiled pair count, holdout disjointness, chosen adaptation strategy and paired bootstrap promotion gate result",
        "schema": {
          "type": "object",
          "additionalProperties": false,
          "required": [
            "compiled_pair_count",
            "holdout_disjoint",
            "selected_strategy",
            "promote",
            "target_gain_ci_low",
            "failed_gates"
          ],
          "properties": {
            "compiled_pair_count": {
              "type": "integer",
              "minimum": 1
            },
            "holdout_disjoint": {
              "type": "boolean"
            },
            "selected_strategy": {
              "type": "string",
              "enum": [
                "prompt_context_shim",
                "lora_weight_update",
                "hybrid_shim_and_lora"
              ]
            },
            "promote": {
              "type": "boolean"
            },
            "target_gain_ci_low": {
              "type": "number",
              "minimum": -1,
              "maximum": 1
            },
            "failed_gates": {
              "type": "array",
              "items": {
                "type": "string"
              }
            }
          }
        },
        "example": {
          "compiled_pair_count": 6,
          "holdout_disjoint": true,
          "selected_strategy": "hybrid_shim_and_lora",
          "promote": true,
          "target_gain_ci_low": 0.2575,
          "failed_gates": []
        }
      }
    },
    {
      "slug": "example.post-cutoff-bundle",
      "category": "noun.eval_run",
      "role": "example",
      "synthetic": true,
      "title": "Worked example input: synthetic post-cutoff Task Objects, routing spec and pre-registered holdout scores",
      "category_reason": "Synthetic inputs recomputed by test_lora_memory.py.",
      "value": {
        "task_objects": [
          {
            "id": "spec.worker-rpc-v2",
            "subject": "Worker RPC v2 batch envelope",
            "effective_date": "2026-10-01",
            "canonical_fact": "batchInvoke requires an idempotencyKey header and caps payloads at 256 KiB",
            "superseded_claim": "batchInvoke accepted unkeyed 2 MiB envelopes",
            "scope_boundary": "streaming websocket backpressure limits"
          },
          {
            "id": "spec.catalog-iceberg-v3",
            "subject": "Catalog Iceberg partition pruning flag",
            "effective_date": "2026-10-12",
            "canonical_fact": "pruneManifests defaults to strict_timestamp_bounds",
            "superseded_claim": "pruneManifests defaulted to permissive_scan",
            "scope_boundary": "cross-account bucket replication fees"
          }
        ],
        "holdout_prompts": [
          "Construct a valid Worker RPC v2 batchInvoke call and state its payload ceiling.",
          "Which manifest pruning mode runs by default on a Catalog Iceberg query?"
        ],
        "routing_spec": {
          "churn_half_life_days": 45,
          "queries_per_day": 600,
          "shim_tokens_per_query": 550,
          "training_equivalent_tokens": 2000000,
          "requires_instant_revocation": false,
          "has_volatile_pins_plus_stable_syntax": true
        },
        "holdout_eval": {
          "target_baseline": [
            0.35,
            0.4,
            0.45,
            0.3,
            0.5,
            0.4,
            0.35,
            0.45,
            0.4,
            0.35,
            0.5,
            0.4,
            0.3,
            0.45,
            0.4,
            0.35,
            0.45,
            0.4,
            0.5,
            0.35
          ],
          "target_candidate": [
            0.65,
            0.7,
            0.7,
            0.6,
            0.75,
            0.65,
            0.6,
            0.7,
            0.65,
            0.65,
            0.75,
            0.7,
            0.6,
            0.7,
            0.65,
            0.6,
            0.7,
            0.65,
            0.75,
            0.65
          ],
          "retention_baseline": [
            0.82,
            0.85,
            0.8,
            0.84,
            0.88,
            0.79,
            0.83,
            0.86,
            0.81,
            0.85,
            0.84,
            0.82,
            0.8,
            0.87,
            0.83,
            0.85,
            0.81,
            0.84,
            0.86,
            0.82
          ],
          "retention_candidate": [
            0.82,
            0.84,
            0.81,
            0.84,
            0.88,
            0.79,
            0.83,
            0.85,
            0.82,
            0.85,
            0.84,
            0.82,
            0.8,
            0.87,
            0.83,
            0.84,
            0.82,
            0.84,
            0.86,
            0.82
          ],
          "candidate_hallucination_flags": [
            0,
            0,
            0,
            0,
            0,
            0,
            0,
            0,
            0,
            0,
            0,
            0,
            0,
            0,
            0,
            0,
            0,
            0,
            0,
            0
          ]
        }
      }
    },
    {
      "slug": "example.gate-decision",
      "category": "noun.eval_run",
      "role": "example",
      "synthetic": true,
      "title": "Worked example output: recomputed hybrid routing and paired bootstrap gate decision",
      "category_reason": "Deterministic output conforming to template.gate-decision.",
      "value": {
        "conforms_to": {
          "$pin": "template.gate-decision"
        },
        "instance": {
          "compiled_pair_count": 6,
          "holdout_disjoint": true,
          "selected_strategy": "hybrid_shim_and_lora",
          "promote": true,
          "target_gain_ci_low": 0.2575,
          "failed_gates": []
        }
      },
      "relations": [
        [
          "derives_from",
          "example.post-cutoff-bundle"
        ],
        [
          "verifies",
          "template.gate-decision"
        ]
      ]
    }
  ],
  "verbs": [
    {
      "slug": "route-shim-or-lora",
      "kind": "verb.situate",
      "title": "Choose prompt/context shimming, LoRA weight update or hybrid routing",
      "claimant": "agent",
      "model_use": "none",
      "summary": "Compare knowledge churn half-life, daily query volume, context shim token overhead and instant-revocation needs against LoRA training cost to choose the right adaptation mechanism.",
      "outcome": "Selected strategy, horizon token amortization and breakeven query count.",
      "ready_outcome": "adaptation_strategy_routed",
      "pinned": [
        "spec.routing-and-gates",
        "tool.lora-memory",
        "guardrail.shim-volatile-facts"
      ],
      "slots": [
        {
          "name": "routing_spec",
          "category": "noun.shim_provision",
          "description": "Pin of churn, volume and token budget parameters."
        }
      ],
      "produces": [
        {
          "name": "routing_decision",
          "template": "template.gate-decision"
        }
      ],
      "steps": [
        "Run python -m lora_memory route on the workload and churn parameters.",
        "Record selected_strategy, breakeven_queries and rationale."
      ],
      "acceptance": [
        {
          "id": "routing-recomputed",
          "check": "route_adaptation_strategy reproduces selected_strategy and breakeven_queries.",
          "method": "deterministic"
        }
      ]
    },
    {
      "slug": "compile-lora-pairs",
      "kind": "verb.distill_reflex",
      "title": "Compile verified post-cutoff Task Objects into leakage-checked LoRA pairs",
      "claimant": "agent",
      "model_use": "none",
      "summary": "Generate direct-fact, supersession-guard and scope-abstention SFT pairs from pinned post-cutoff Task Objects and verify 4-gram Jaccard disjointness against pre-registered holdouts.",
      "outcome": "Compiled SFT pairs and holdout disjointness audit.",
      "ready_outcome": "lora_pairs_compiled",
      "pinned": [
        "rules.pair-compilation",
        "tool.lora-memory",
        "guardrail.holdout-ngram-disjointness"
      ],
      "slots": [
        {
          "name": "post_cutoff_bundle",
          "category": "noun.public_source",
          "description": "Pin of verified post-cutoff Task Objects and holdout prompt list."
        }
      ],
      "produces": [
        {
          "name": "compiled_pairs",
          "template": "template.gate-decision"
        }
      ],
      "steps": [
        "Compile direct, supersession and abstention pairs with compile_post_cutoff_pairs.",
        "Verify disjoint == true via check_holdout_disjointness before allowing training."
      ],
      "acceptance": [
        {
          "id": "zero-holdout-leakage",
          "check": "check_holdout_disjointness returns disjoint == true with max_observed_jaccard <= 0.35.",
          "method": "deterministic"
        }
      ],
      "follows": [
        "lora-memory-and-shimming.route-shim-or-lora"
      ]
    },
    {
      "slug": "evaluate-bootstrap-gate",
      "kind": "verb.verify_gate",
      "title": "Evaluate paired bootstrap CI promotion gates on pre-registered holdouts",
      "claimant": "agent",
      "model_use": "none",
      "summary": "Run 1,000 seeded paired bootstrap resamples comparing candidate versus baseline scores on target holdouts and general-capability retention, enforcing gain, retention and hallucination gates.",
      "outcome": "A conforming gate-decision record stating promote true or false and all CI bounds.",
      "ready_outcome": "promotion_gate_evaluated",
      "pinned": [
        "spec.routing-and-gates",
        "tool.lora-memory",
        "template.gate-decision",
        "guardrail.smoke-is-not-improvement"
      ],
      "slots": [
        {
          "name": "holdout_evaluation",
          "category": "noun.eval_run",
          "description": "Pin of paired baseline and candidate item scores on target and retention suites."
        }
      ],
      "produces": [
        {
          "name": "gate_decision",
          "template": "template.gate-decision"
        }
      ],
      "steps": [
        "Run evaluate_promotion_gate with seed=42 and n_bootstrap=1000.",
        "Validate the decision summary against template.gate-decision."
      ],
      "acceptance": [
        {
          "id": "matches-gate-schema",
          "check": "Output passes schema_errors against template.gate-decision.",
          "method": "deterministic"
        },
        {
          "id": "bootstrap-reproducible",
          "check": "evaluate_promotion_gate with seed=42 reproduces target_gain_ci_low and promote.",
          "method": "deterministic"
        }
      ],
      "follows": [
        "lora-memory-and-shimming.compile-lora-pairs"
      ]
    }
  ]
}