@codyswann/lisa 2.298.1 → 2.299.0

package/all/copy-contents/.gitattributes

@@ -6,4 +6,10 @@
 # command is machine-local — run `lisa install-merge-driver` to register it.
 .lisa/PROJECT_LEARNINGS.md merge=lisa-learnings
 
+# The overflow buffer holds captures the ledger had no budget for, until
+# the gardener drains them. Same writers, same branches, same format — so
+# it needs the same union merge, or a merge could destroy the very content
+# it exists to preserve.
+.lisa/PROJECT_LEARNINGS.overflow.md merge=lisa-learnings
+
 # END: AI GUARDRAILS

package/dist/cli/gate-commands.d.ts

@@ -5,11 +5,13 @@ import type { FileUpstreamOptions } from "./file-upstream-cmd.js";
  * Gate runners kept structural to avoid importing the whole CLI dependency
  * record.
  *
- * `merge-learnings` and `install-merge-driver` are deliberately NOT members.
- * They are invoked by git and by an operator repairing a repository, never
- * substituted by the root CLI, and both mutate real state — the merge driver
- * overwrites the file git hands it, and the installer writes local git config.
- * An optional, defaulted field would be the worst shape here: a caller that
+ * `merge-learnings`, `install-merge-driver`, and `learnings-overflow` are
+ * deliberately NOT members. They are invoked by git, by an operator repairing a
+ * repository, or by the gardener draining its buffer — never substituted by the
+ * root CLI — and all three mutate real state: the merge driver overwrites the
+ * file git hands it, the installer writes local git config, and the drain
+ * removes entries from the only durable copy of a dropped capture. An optional,
+ * defaulted field would be the worst shape here: a caller that
  * believed it had stubbed every gate command would silently run the real driver
  * against real files. Leaving them off the record makes non-injectability
  * explicit; they are covered directly by unit tests and by end-to-end tests
@@ -26,7 +28,7 @@ export interface GateCommandDependencies {
  * ledger, so a network update check would stall the merge and pollute the
  * driver's output.
  */
-export declare const GATE_COMMAND_NAMES: readonly ["check-learnings-budget", "file-upstream", "merge-learnings", "install-merge-driver"];
+export declare const GATE_COMMAND_NAMES: readonly ["check-learnings-budget", "file-upstream", "learnings-overflow", "merge-learnings", "install-merge-driver"];
 /**
  * Register all non-project gate commands.
  * @param program - Commander program

package/dist/cli/gate-commands.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"gate-commands.d.ts","sourceRoot":"","sources":["../../src/cli/gate-commands.ts"],"names":[],"mappings":"AAAA,yEAAyE;AACzE,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAEzC,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,wBAAwB,CAAC;AAOlE;;;;;;;;;;;;;GAaG;AACH,MAAM,WAAW,uBAAuB;IACtC,uBAAuB,EAAE,CAAC,IAAI,EAAE,MAAM,GAAG,SAAS,KAAK,OAAO,CAAC,MAAM,CAAC,CAAC;IACvE,eAAe,EAAE,CAAC,OAAO,EAAE,mBAAmB,KAAK,OAAO,CAAC,MAAM,CAAC,CAAC;CACpE;AAED;;;;;;GAMG;AACH,eAAO,MAAM,kBAAkB,iGAKrB,CAAC;AAuFX;;;;GAIG;AACH,wBAAgB,eAAe,CAC7B,OAAO,EAAE,OAAO,EAChB,YAAY,EAAE,uBAAuB,GACpC,IAAI,CAKN"}
+{"version":3,"file":"gate-commands.d.ts","sourceRoot":"","sources":["../../src/cli/gate-commands.ts"],"names":[],"mappings":"AAAA,yEAAyE;AACzE,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAEzC,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,wBAAwB,CAAC;AAWlE;;;;;;;;;;;;;;;GAeG;AACH,MAAM,WAAW,uBAAuB;IACtC,uBAAuB,EAAE,CAAC,IAAI,EAAE,MAAM,GAAG,SAAS,KAAK,OAAO,CAAC,MAAM,CAAC,CAAC;IACvE,eAAe,EAAE,CAAC,OAAO,EAAE,mBAAmB,KAAK,OAAO,CAAC,MAAM,CAAC,CAAC;CACpE;AAED;;;;;;GAMG;AACH,eAAO,MAAM,kBAAkB,uHAMrB,CAAC;AA8GX;;;;GAIG;AACH,wBAAgB,eAAe,CAC7B,OAAO,EAAE,OAAO,EAChB,YAAY,EAAE,uBAAuB,GACpC,IAAI,CAMN"}

package/dist/cli/gate-commands.js

@@ -1,4 +1,5 @@
 import { runInstallMergeDriver } from "./install-merge-driver-cmd.js";
+import { runLearningsOverflow, } from "./learnings-overflow-cmd.js";
 import { runMergeLearnings, } from "./merge-learnings-cmd.js";
 /**
  * Gate commands skip the root npm update check.
@@ -10,6 +11,7 @@ import { runMergeLearnings, } from "./merge-learnings-cmd.js";
 export const GATE_COMMAND_NAMES = [
     "check-learnings-budget",
     "file-upstream",
+    "learnings-overflow",
     "merge-learnings",
     "install-merge-driver",
 ];
@@ -45,6 +47,24 @@ function addFileUpstreamCommand(program, dependencies) {
             process.exitCode = code;
     });
 }
+/**
+ * Register the overflow inspect/drain handle the gardener uses.
+ *
+ * Not injectable: the drain removes entries from the only durable copy of a
+ * budget-dropped capture, so a caller must never be able to stub it away.
+ * @param program - Commander program
+ */
+function addLearningsOverflowCommand(program) {
+    program
+        .command("learnings-overflow")
+        .description("List or drain learnings the ledger had no budget to accept (JSON output)")
+        .option("--drain <ids...>", "Entry ids to remove once they have a durable home elsewhere")
+        .action(async (options) => {
+        const code = await runLearningsOverflow(options);
+        if (code !== 0)
+            process.exitCode = code;
+    });
+}
 /**
  * Register the project-learnings union merge driver.
  *
@@ -89,6 +109,7 @@ function addInstallMergeDriverCommand(program) {
 export function addGateCommands(program, dependencies) {
     addCheckLearningsBudgetCommand(program, dependencies);
     addFileUpstreamCommand(program, dependencies);
+    addLearningsOverflowCommand(program);
     addMergeLearningsCommand(program);
     addInstallMergeDriverCommand(program);
 }

package/dist/cli/gate-commands.js.map

@@ -1 +1 @@
-{"version":3,"file":"gate-commands.js","sourceRoot":"","sources":["../../src/cli/gate-commands.ts"],"names":[],"mappings":"AAIA,OAAO,EAAE,qBAAqB,EAAE,MAAM,+BAA+B,CAAC;AACtE,OAAO,EACL,iBAAiB,GAElB,MAAM,0BAA0B,CAAC;AAqBlC;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,kBAAkB,GAAG;IAChC,wBAAwB;IACxB,eAAe;IACf,iBAAiB;IACjB,sBAAsB;CACd,CAAC;AAEX;;;;GAIG;AACH,SAAS,8BAA8B,CACrC,OAAgB,EAChB,YAAqC;IAErC,OAAO;SACJ,OAAO,CAAC,wBAAwB,CAAC;SACjC,WAAW,CACV,kFAAkF,CACnF;SACA,QAAQ,CACP,QAAQ,EACR,oEAAoE,CACrE;SACA,MAAM,CAAC,KAAK,EAAE,UAA8B,EAAE,EAAE;QAC/C,MAAM,IAAI,GAAG,MAAM,YAAY,CAAC,uBAAuB,CAAC,UAAU,CAAC,CAAC;QACpE,IAAI,IAAI,KAAK,CAAC;YAAE,OAAO,CAAC,QAAQ,GAAG,IAAI,CAAC;IAC1C,CAAC,CAAC,CAAC;AACP,CAAC;AAED;;;;GAIG;AACH,SAAS,sBAAsB,CAC7B,OAAgB,EAChB,YAAqC;IAErC,OAAO;SACJ,OAAO,CAAC,eAAe,CAAC;SACxB,WAAW,CACV,wEAAwE,CACzE;SACA,MAAM,CAAC,gBAAgB,EAAE,yCAAyC,CAAC;SACnE,MAAM,CAAC,KAAK,EAAE,OAA4B,EAAE,EAAE;QAC7C,MAAM,IAAI,GAAG,MAAM,YAAY,CAAC,eAAe,CAAC,OAAO,CAAC,CAAC;QACzD,IAAI,IAAI,KAAK,CAAC;YAAE,OAAO,CAAC,QAAQ,GAAG,IAAI,CAAC;IAC1C,CAAC,CAAC,CAAC;AACP,CAAC;AAED;;;;;;GAMG;AACH,SAAS,wBAAwB,CAAC,OAAgB;IAChD,OAAO;SACJ,OAAO,CAAC,iBAAiB,CAAC;SAC1B,WAAW,CACV,kEAAkE,CACnE;SACA,MAAM,CAAC,eAAe,EAAE,6BAA6B,CAAC;SACtD,MAAM,CAAC,eAAe,EAAE,2CAA2C,CAAC;SACpE,MAAM,CAAC,iBAAiB,EAAE,wBAAwB,CAAC;SACnD,MAAM,CAAC,eAAe,EAAE,wCAAwC,CAAC;SACjE,MAAM,CAAC,KAAK,EAAE,OAA8B,EAAE,EAAE;QAC/C,MAAM,IAAI,GAAG,MAAM,iBAAiB,CAAC,OAAO,CAAC,CAAC;QAC9C,IAAI,IAAI,KAAK,CAAC;YAAE,OAAO,CAAC,QAAQ,GAAG,IAAI,CAAC;IAC1C,CAAC,CAAC,CAAC;AACP,CAAC;AAED;;;GAGG;AACH,SAAS,4BAA4B,CAAC,OAAgB;IACpD,OAAO;SACJ,OAAO,CAAC,sBAAsB,CAAC;SAC/B,WAAW,CACV,uEAAuE,CACxE;SACA,QAAQ,CAAC,QAAQ,EAAE,gDAAgD,CAAC;SACpE,MAAM,CAAC,KAAK,EAAE,UAA8B,EAAE,EAAE;QAC/C,MAAM,IAAI,GAAG,MAAM,qBAAqB,CAAC,UAAU,CAAC,CAAC;QACrD,IAAI,IAAI,KAAK,CAAC;YAAE,OAAO,CAAC,QAAQ,GAAG,IAAI,CAAC;IAC1C,CAAC,CAAC,CAAC;AACP,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,eAAe,CAC7B,OAAgB,EAChB,YAAqC;IAErC,8BAA8B,CAAC,OAAO,EAAE,YAAY,CAAC,CAAC;IACtD,sBAAsB,CAAC,OAAO,EAAE,YAAY,CAAC,CAAC;IAC9C,wBAAwB,CAAC,OAAO,CAAC,CAAC;IAClC,4BAA4B,CAAC,OAAO,CAAC,CAAC;AACxC,CAAC"}
+{"version":3,"file":"gate-commands.js","sourceRoot":"","sources":["../../src/cli/gate-commands.ts"],"names":[],"mappings":"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"}

package/dist/cli/learnings-overflow-cmd.d.ts

@@ -0,0 +1,27 @@
+/** Command-line options for {@link runLearningsOverflow}. */
+export interface LearningsOverflowOptions {
+    /** Entry ids to remove once they have a durable home elsewhere. */
+    readonly drain?: readonly string[];
+}
+/** Injectable collaborators for {@link runLearningsOverflow}. */
+export interface LearningsOverflowDependencies {
+    /** Working directory used to resolve the project config (defaults to cwd). */
+    readonly cwd?: string;
+    /** Sink for the JSON payload (defaults to stdout). */
+    readonly log?: (message: string) => void;
+    /** Sink for the failure diagnostic (defaults to stderr). */
+    readonly error?: (message: string) => void;
+}
+/**
+ * Read or drain the overflow and print the outcome as JSON.
+ *
+ * A malformed or unsafe overflow is a real failure and exits non-zero: unlike a
+ * missing file (which is the ordinary case and reads as empty), a document the
+ * contract refuses to parse must not be reported as "nothing to drain" — that
+ * would present a corrupted buffer as a healthy one.
+ * @param options - Parsed command-line options
+ * @param dependencies - Injectable collaborators for tests
+ * @returns Process exit code
+ */
+export declare function runLearningsOverflow(options: LearningsOverflowOptions, dependencies?: LearningsOverflowDependencies): Promise<number>;
+//# sourceMappingURL=learnings-overflow-cmd.d.ts.map

package/dist/cli/learnings-overflow-cmd.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"learnings-overflow-cmd.d.ts","sourceRoot":"","sources":["../../src/cli/learnings-overflow-cmd.ts"],"names":[],"mappings":"AAsBA,6DAA6D;AAC7D,MAAM,WAAW,wBAAwB;IACvC,mEAAmE;IACnE,QAAQ,CAAC,KAAK,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;CACpC;AAED,iEAAiE;AACjE,MAAM,WAAW,6BAA6B;IAC5C,8EAA8E;IAC9E,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,CAAC;IACtB,sDAAsD;IACtD,QAAQ,CAAC,GAAG,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,IAAI,CAAC;IACzC,4DAA4D;IAC5D,QAAQ,CAAC,KAAK,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,IAAI,CAAC;CAC5C;AAED;;;;;;;;;;GAUG;AACH,wBAAsB,oBAAoB,CACxC,OAAO,EAAE,wBAAwB,EACjC,YAAY,GAAE,6BAAkC,GAC/C,OAAO,CAAC,MAAM,CAAC,CAajB"}

package/dist/cli/learnings-overflow-cmd.js

@@ -0,0 +1,57 @@
+/**
+ * `lisa learnings-overflow` — inspect and drain captures the ledger had no
+ * budget to accept (CodySwannGT/lisa#1996).
+ *
+ * This is the gardener's drain handle. The audit skill is forbidden from
+ * hand-parsing or hand-editing any learnings surface, so the only way to give it
+ * the contract's containment checks, cross-process lock, and atomic write is to
+ * ship them behind a command — exactly as `check-learnings-budget` ships the
+ * budget gate and `merge-learnings` ships the union driver.
+ *
+ * Output is JSON because the consumer is an agent, not a human reading a
+ * terminal: the gardener reads the pending entries, files one ticket per entry,
+ * and only then drains the ids it durably re-homed. Drain is therefore BY ID and
+ * never "empty it" — a run whose ticket filing fails part-way leaves every
+ * unfiled capture exactly where it was, and is safely resumable.
+ * @module cli/learnings-overflow-cmd
+ */
+import { drainLearningsOverflow, readLearningsOverflow, } from "../core/learnings-overflow.js";
+/**
+ * Read or drain the overflow and print the outcome as JSON.
+ *
+ * A malformed or unsafe overflow is a real failure and exits non-zero: unlike a
+ * missing file (which is the ordinary case and reads as empty), a document the
+ * contract refuses to parse must not be reported as "nothing to drain" — that
+ * would present a corrupted buffer as a healthy one.
+ * @param options - Parsed command-line options
+ * @param dependencies - Injectable collaborators for tests
+ * @returns Process exit code
+ */
+export async function runLearningsOverflow(options, dependencies = {}) {
+    const cwd = dependencies.cwd ?? process.cwd();
+    const log = dependencies.log ?? ((message) => console.log(message));
+    const error = dependencies.error ?? ((message) => console.error(message));
+    try {
+        log(JSON.stringify(await resolvePayload(cwd, options.drain), null, 2));
+        return 0;
+    }
+    catch (caught) {
+        const detail = caught instanceof Error ? caught.message : String(caught);
+        error(`learnings-overflow: ${detail}`);
+        return 1;
+    }
+}
+/**
+ * Produce the read payload or the drain payload, depending on the request.
+ * @param cwd - Project directory
+ * @param drain - Entry ids to remove, when draining
+ * @returns JSON-serializable outcome
+ */
+async function resolvePayload(cwd, drain) {
+    if (drain === undefined || drain.length === 0) {
+        const { file, entries } = await readLearningsOverflow(cwd);
+        return { file, pending: entries.length, entries };
+    }
+    return drainLearningsOverflow(cwd, drain);
+}
+//# sourceMappingURL=learnings-overflow-cmd.js.map

package/dist/cli/learnings-overflow-cmd.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"learnings-overflow-cmd.js","sourceRoot":"","sources":["../../src/cli/learnings-overflow-cmd.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AACH,OAAO,EACL,sBAAsB,EACtB,qBAAqB,GACtB,MAAM,+BAA+B,CAAC;AAkBvC;;;;;;;;;;GAUG;AACH,MAAM,CAAC,KAAK,UAAU,oBAAoB,CACxC,OAAiC,EACjC,eAA8C,EAAE;IAEhD,MAAM,GAAG,GAAG,YAAY,CAAC,GAAG,IAAI,OAAO,CAAC,GAAG,EAAE,CAAC;IAC9C,MAAM,GAAG,GAAG,YAAY,CAAC,GAAG,IAAI,CAAC,CAAC,OAAe,EAAE,EAAE,CAAC,OAAO,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC;IAC5E,MAAM,KAAK,GACT,YAAY,CAAC,KAAK,IAAI,CAAC,CAAC,OAAe,EAAE,EAAE,CAAC,OAAO,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC;IACtE,IAAI,CAAC;QACH,GAAG,CAAC,IAAI,CAAC,SAAS,CAAC,MAAM,cAAc,CAAC,GAAG,EAAE,OAAO,CAAC,KAAK,CAAC,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC,CAAC;QACvE,OAAO,CAAC,CAAC;IACX,CAAC;IAAC,OAAO,MAAM,EAAE,CAAC;QAChB,MAAM,MAAM,GAAG,MAAM,YAAY,KAAK,CAAC,CAAC,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC;QACzE,KAAK,CAAC,uBAAuB,MAAM,EAAE,CAAC,CAAC;QACvC,OAAO,CAAC,CAAC;IACX,CAAC;AACH,CAAC;AAED;;;;;GAKG;AACH,KAAK,UAAU,cAAc,CAC3B,GAAW,EACX,KAAoC;IAEpC,IAAI,KAAK,KAAK,SAAS,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QAC9C,MAAM,EAAE,IAAI,EAAE,OAAO,EAAE,GAAG,MAAM,qBAAqB,CAAC,GAAG,CAAC,CAAC;QAC3D,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,OAAO,CAAC,MAAM,EAAE,OAAO,EAAE,CAAC;IACpD,CAAC;IACD,OAAO,sBAAsB,CAAC,GAAG,EAAE,KAAK,CAAC,CAAC;AAC5C,CAAC"}

package/dist/core/learnings-alias.d.ts

@@ -0,0 +1,156 @@
+/**
+ * Reference survival across supersede-in-place consolidation.
+ *
+ * ## The problem
+ *
+ * `persistConsolidatedLearning(..., { supersede: [ids] })` removes the
+ * superseded entries and adds a new one under the caller's own id — the
+ * learner's content fingerprint. So every consolidation churns the id, and
+ * anything that had cited the old id (a tracker comment, a gardener ticket, a
+ * cross-link from another learning) silently points at an entry that no longer
+ * exists (CodySwannGT/lisa#1997).
+ *
+ * ## Why an alias map and NOT "carry the earliest superseded id forward"
+ *
+ * The issue offered both. Carry-forward was implemented first and had to be
+ * abandoned, because the churning fingerprint id is doing a second job nobody
+ * wrote down: it is an accidental **compare-and-swap token**.
+ *
+ * Two learner passes racing to consolidate the same entry `base` each hold a
+ * stale snapshot. Today the first writer removes `base` and lands under `a`; the
+ * second finds `base` already gone, is tolerated rather than fatal (#1995), and
+ * lands under `b`. Both learnings survive — "at worst two entries where one
+ * consolidation was intended," exactly the cost the writer documents.
+ *
+ * Carry the id forward and that protection evaporates: the first writer lands
+ * under `base`, so the second writer's stale "supersede base" now MATCHES,
+ * removes the first writer's entry, and overwrites it. `learnings-supersede-race`
+ * proves the damage — nine writers consolidating one target went from nine
+ * preserved learnings to **one**, destroying eight. That is the #1995 data-loss
+ * symptom re-opened, which the brief explicitly forbids.
+ *
+ * The fix is undecidable from the seven fields alone: a stale "supersede base"
+ * and a legitimate chained "supersede base" are the same bytes. Telling them
+ * apart needs a real version token — the fingerprint retained as an eighth,
+ * disambiguating field, per the issue's parenthetical. That is a persisted-schema
+ * change: a contract version bump propagated through every reader, the merge
+ * driver, the CI budget gate, and all six plugin skill projections. It is the
+ * principled long-term answer and it deserves its own change.
+ *
+ * So this takes the issue's second option. Ids keep churning — the CAS token,
+ * the #1995 guarantee, and the fingerprint-is-the-id dedupe model are all left
+ * exactly as they are — and references survive because the consolidated entry
+ * *records what it replaced*.
+ *
+ * ## Where the map lives
+ *
+ * In the entry's own `provenance`, as `supersedes:<old id>` references. No new
+ * field, no new file, no new format: provenance is already a validated,
+ * rendered, merged, budget-counted list of stable references, and "this entry
+ * replaced that one" is precisely a provenance claim.
+ *
+ * Resolution is ONE HOP, never transitive. When an entry is consolidated, the
+ * writer copies the removed entries' own alias references forward, so a lineage
+ * `base → a → b` leaves `b` carrying both `supersedes:a` and `supersedes:base`.
+ * There is no chain for a reader to walk and therefore no cycle or depth limit
+ * to get wrong.
+ *
+ * An alias is recorded ONLY for a target that was actually present and removed.
+ * A supersede naming an already-consolidated id removed nothing, so claiming its
+ * reference would hijack a pointer that the earlier writer legitimately owns —
+ * in the nine-writer race, only the one writer that truly removed `base` claims
+ * `base`, and the reference stays unambiguous.
+ * @module core/learnings-alias
+ */
+import { type LearningEntry } from "./learnings-contract.js";
+/** Prefix marking a provenance reference as a superseded-id alias. */
+export declare const SUPERSEDES_PREFIX = "supersedes:";
+/**
+ * Build the provenance reference recording that an entry replaced another.
+ * @param id - Id of the entry that was removed
+ * @returns Canonical alias reference
+ */
+export declare function buildSupersedesReference(id: string): string;
+/**
+ * Reject a caller trying to mint its own `supersedes:` reference.
+ *
+ * The prefix is WRITER-OWNED. An alias is a factual claim that this write
+ * removed that entry, and the writer is the only party that knows whether it
+ * did — so a hand-written `supersedes:<id>` would let any caller capture a
+ * reference to an entry it never touched, silently redirecting an old id at
+ * content of its choosing.
+ *
+ * This lives at the writer's entry point rather than inside
+ * `validateLearningEntry` on purpose: that validator also runs on every entry
+ * parsed back off disk and on every side of a merge, where writer-added
+ * `supersedes:` references are legitimate and must be accepted. Rejecting there
+ * would make the contract unable to read its own output.
+ * @param entry - Validated entry exactly as the caller composed it
+ * @returns The rejection to throw, or undefined when the provenance is clean
+ */
+export declare function findCallerMintedAliasError(entry: LearningEntry): Error | undefined;
+/**
+ * Read the ids one entry declares it superseded.
+ * @param entry - Validated learning entry
+ * @returns Superseded ids, in the order they were recorded
+ */
+export declare function readSupersededIds(entry: LearningEntry): readonly string[];
+/** Result of folding alias references into a consolidated entry. */
+export interface AliasedLearningEntry {
+    /** Entry provenance with as many alias references as the contract allows. */
+    readonly provenance: readonly string[];
+    /**
+     * Alias references that did not fit and were dropped. Never silent: the
+     * writer reports these so a reference that is about to stop resolving is
+     * visible instead of quietly disappearing.
+     */
+    readonly dropped: readonly string[];
+}
+/**
+ * Fold alias references into a caller's provenance within the contract cap.
+ *
+ * Caller-supplied provenance is NEVER sacrificed for an alias. It is the
+ * evidence the learning rests on — the tracker links and commits that justify
+ * the rule existing at all — while an alias is a convenience for finding the
+ * entry by a name it used to have. Evicting evidence to store a convenience
+ * would quietly delete the reason a learning is believed.
+ *
+ * When the two together exceed `maxProvenanceReferences`, the NEWEST aliases
+ * drop first, so the oldest surviving reference is kept longest. An alias gets
+ * MORE valuable as it ages, not less: an id that churned in this very pull
+ * request is still discoverable from the branch, the commit, and the capture
+ * report, whereas a months-old tracker comment citing an old id has no other
+ * way home — and silently breaking exactly those references is what
+ * CodySwannGT/lisa#1997 exists to fix. (An earlier revision dropped oldest-first
+ * on the theory that ancient references were probably already closed out; that
+ * has it backwards. A closed ticket citing an id is precisely where someone
+ * searching history lands.)
+ * @param entry - New entry as the caller composed it
+ * @param removed - Entries this write actually removed from the document
+ * @returns Merged provenance plus any alias references that did not fit
+ */
+export declare function applySupersedeAliases(entry: LearningEntry, removed: readonly LearningEntry[]): AliasedLearningEntry;
+/**
+ * Resolve every entry an id could refer to, live id first.
+ *
+ * A live id always wins: if an entry still carries the id, that entry IS the
+ * reference and no alias can shadow it.
+ *
+ * More than one entry can claim the same alias in exactly one situation — the
+ * union merge driver joined two branches that had each removed the same target
+ * — so this returns all claimants in deterministic id order rather than
+ * pretending the ambiguity away. {@link resolveLearningReference} takes the
+ * first for callers that just need a pointer.
+ * @param entries - Validated entries from the document
+ * @param id - Possibly-superseded id to resolve
+ * @returns Matching entries, deterministically ordered
+ */
+export declare function resolveLearningReferences(entries: readonly LearningEntry[], id: string): readonly LearningEntry[];
+/**
+ * Resolve one id to the entry that now carries its content.
+ * @param entries - Validated entries from the document
+ * @param id - Possibly-superseded id to resolve
+ * @returns The entry the reference now points at, when one exists
+ */
+export declare function resolveLearningReference(entries: readonly LearningEntry[], id: string): LearningEntry | undefined;
+//# sourceMappingURL=learnings-alias.d.ts.map

package/dist/core/learnings-alias.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"learnings-alias.d.ts","sourceRoot":"","sources":["../../src/core/learnings-alias.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+DG;AACH,OAAO,EAEL,KAAK,aAAa,EACnB,MAAM,yBAAyB,CAAC;AAEjC,sEAAsE;AACtE,eAAO,MAAM,iBAAiB,gBAAgB,CAAC;AAE/C;;;;GAIG;AACH,wBAAgB,wBAAwB,CAAC,EAAE,EAAE,MAAM,GAAG,MAAM,CAE3D;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,0BAA0B,CACxC,KAAK,EAAE,aAAa,GACnB,KAAK,GAAG,SAAS,CASnB;AAED;;;;GAIG;AACH,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,aAAa,GAAG,SAAS,MAAM,EAAE,CAKzE;AA4BD,oEAAoE;AACpE,MAAM,WAAW,oBAAoB;IACnC,6EAA6E;IAC7E,QAAQ,CAAC,UAAU,EAAE,SAAS,MAAM,EAAE,CAAC;IACvC;;;;OAIG;IACH,QAAQ,CAAC,OAAO,EAAE,SAAS,MAAM,EAAE,CAAC;CACrC;AAED;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAgB,qBAAqB,CACnC,KAAK,EAAE,aAAa,EACpB,OAAO,EAAE,SAAS,aAAa,EAAE,GAChC,oBAAoB,CActB;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,yBAAyB,CACvC,OAAO,EAAE,SAAS,aAAa,EAAE,EACjC,EAAE,EAAE,MAAM,GACT,SAAS,aAAa,EAAE,CAS1B;AAED;;;;;GAKG;AACH,wBAAgB,wBAAwB,CACtC,OAAO,EAAE,SAAS,aAAa,EAAE,EACjC,EAAE,EAAE,MAAM,GACT,aAAa,GAAG,SAAS,CAE3B"}

package/dist/core/learnings-alias.js

@@ -0,0 +1,199 @@
+/**
+ * Reference survival across supersede-in-place consolidation.
+ *
+ * ## The problem
+ *
+ * `persistConsolidatedLearning(..., { supersede: [ids] })` removes the
+ * superseded entries and adds a new one under the caller's own id — the
+ * learner's content fingerprint. So every consolidation churns the id, and
+ * anything that had cited the old id (a tracker comment, a gardener ticket, a
+ * cross-link from another learning) silently points at an entry that no longer
+ * exists (CodySwannGT/lisa#1997).
+ *
+ * ## Why an alias map and NOT "carry the earliest superseded id forward"
+ *
+ * The issue offered both. Carry-forward was implemented first and had to be
+ * abandoned, because the churning fingerprint id is doing a second job nobody
+ * wrote down: it is an accidental **compare-and-swap token**.
+ *
+ * Two learner passes racing to consolidate the same entry `base` each hold a
+ * stale snapshot. Today the first writer removes `base` and lands under `a`; the
+ * second finds `base` already gone, is tolerated rather than fatal (#1995), and
+ * lands under `b`. Both learnings survive — "at worst two entries where one
+ * consolidation was intended," exactly the cost the writer documents.
+ *
+ * Carry the id forward and that protection evaporates: the first writer lands
+ * under `base`, so the second writer's stale "supersede base" now MATCHES,
+ * removes the first writer's entry, and overwrites it. `learnings-supersede-race`
+ * proves the damage — nine writers consolidating one target went from nine
+ * preserved learnings to **one**, destroying eight. That is the #1995 data-loss
+ * symptom re-opened, which the brief explicitly forbids.
+ *
+ * The fix is undecidable from the seven fields alone: a stale "supersede base"
+ * and a legitimate chained "supersede base" are the same bytes. Telling them
+ * apart needs a real version token — the fingerprint retained as an eighth,
+ * disambiguating field, per the issue's parenthetical. That is a persisted-schema
+ * change: a contract version bump propagated through every reader, the merge
+ * driver, the CI budget gate, and all six plugin skill projections. It is the
+ * principled long-term answer and it deserves its own change.
+ *
+ * So this takes the issue's second option. Ids keep churning — the CAS token,
+ * the #1995 guarantee, and the fingerprint-is-the-id dedupe model are all left
+ * exactly as they are — and references survive because the consolidated entry
+ * *records what it replaced*.
+ *
+ * ## Where the map lives
+ *
+ * In the entry's own `provenance`, as `supersedes:<old id>` references. No new
+ * field, no new file, no new format: provenance is already a validated,
+ * rendered, merged, budget-counted list of stable references, and "this entry
+ * replaced that one" is precisely a provenance claim.
+ *
+ * Resolution is ONE HOP, never transitive. When an entry is consolidated, the
+ * writer copies the removed entries' own alias references forward, so a lineage
+ * `base → a → b` leaves `b` carrying both `supersedes:a` and `supersedes:base`.
+ * There is no chain for a reader to walk and therefore no cycle or depth limit
+ * to get wrong.
+ *
+ * An alias is recorded ONLY for a target that was actually present and removed.
+ * A supersede naming an already-consolidated id removed nothing, so claiming its
+ * reference would hijack a pointer that the earlier writer legitimately owns —
+ * in the nine-writer race, only the one writer that truly removed `base` claims
+ * `base`, and the reference stays unambiguous.
+ * @module core/learnings-alias
+ */
+import { LEARNINGS_CONTRACT, } from "./learnings-contract.js";
+/** Prefix marking a provenance reference as a superseded-id alias. */
+export const SUPERSEDES_PREFIX = "supersedes:";
+/**
+ * Build the provenance reference recording that an entry replaced another.
+ * @param id - Id of the entry that was removed
+ * @returns Canonical alias reference
+ */
+export function buildSupersedesReference(id) {
+    return `${SUPERSEDES_PREFIX}${id}`;
+}
+/**
+ * Reject a caller trying to mint its own `supersedes:` reference.
+ *
+ * The prefix is WRITER-OWNED. An alias is a factual claim that this write
+ * removed that entry, and the writer is the only party that knows whether it
+ * did — so a hand-written `supersedes:<id>` would let any caller capture a
+ * reference to an entry it never touched, silently redirecting an old id at
+ * content of its choosing.
+ *
+ * This lives at the writer's entry point rather than inside
+ * `validateLearningEntry` on purpose: that validator also runs on every entry
+ * parsed back off disk and on every side of a merge, where writer-added
+ * `supersedes:` references are legitimate and must be accepted. Rejecting there
+ * would make the contract unable to read its own output.
+ * @param entry - Validated entry exactly as the caller composed it
+ * @returns The rejection to throw, or undefined when the provenance is clean
+ */
+export function findCallerMintedAliasError(entry) {
+    const minted = entry.provenance.filter(reference => reference.startsWith(SUPERSEDES_PREFIX));
+    return minted.length === 0
+        ? undefined
+        : new Error(`Invalid provenance: '${SUPERSEDES_PREFIX}' references are added by the writer, not the caller (found ${minted.join(", ")})`);
+}
+/**
+ * Read the ids one entry declares it superseded.
+ * @param entry - Validated learning entry
+ * @returns Superseded ids, in the order they were recorded
+ */
+export function readSupersededIds(entry) {
+    return entry.provenance
+        .filter(reference => reference.startsWith(SUPERSEDES_PREFIX))
+        .map(reference => reference.slice(SUPERSEDES_PREFIX.length))
+        .filter(id => id !== "");
+}
+/**
+ * Compose the alias references a consolidated entry must carry.
+ *
+ * Ordering is oldest-lineage-first: the ids inherited from the removed entries
+ * come before the removed entries' own ids, so the reference that has existed
+ * longest sits earliest and survives longest under the cap below.
+ *
+ * An entry that supersedes its OWN id is editing itself in place, not renaming
+ * itself — the reference never broke, so it earns no alias. Its inherited
+ * lineage is still carried forward, because an in-place edit must not drop the
+ * ancestors that already resolve through it.
+ * @param removed - Entries this write actually removed from the document
+ * @param selfId - Id of the entry being written
+ * @returns Deduplicated alias references in lineage order
+ */
+function composeAliasReferences(removed, selfId) {
+    const inherited = removed.flatMap(entry => readSupersededIds(entry));
+    const direct = removed.map(entry => entry.id);
+    return [...new Set([...inherited, ...direct])]
+        .filter(id => id !== selfId)
+        .map(buildSupersedesReference);
+}
+/**
+ * Fold alias references into a caller's provenance within the contract cap.
+ *
+ * Caller-supplied provenance is NEVER sacrificed for an alias. It is the
+ * evidence the learning rests on — the tracker links and commits that justify
+ * the rule existing at all — while an alias is a convenience for finding the
+ * entry by a name it used to have. Evicting evidence to store a convenience
+ * would quietly delete the reason a learning is believed.
+ *
+ * When the two together exceed `maxProvenanceReferences`, the NEWEST aliases
+ * drop first, so the oldest surviving reference is kept longest. An alias gets
+ * MORE valuable as it ages, not less: an id that churned in this very pull
+ * request is still discoverable from the branch, the commit, and the capture
+ * report, whereas a months-old tracker comment citing an old id has no other
+ * way home — and silently breaking exactly those references is what
+ * CodySwannGT/lisa#1997 exists to fix. (An earlier revision dropped oldest-first
+ * on the theory that ancient references were probably already closed out; that
+ * has it backwards. A closed ticket citing an id is precisely where someone
+ * searching history lands.)
+ * @param entry - New entry as the caller composed it
+ * @param removed - Entries this write actually removed from the document
+ * @returns Merged provenance plus any alias references that did not fit
+ */
+export function applySupersedeAliases(entry, removed) {
+    const provenance = entry.provenance;
+    const existing = new Set(provenance);
+    const aliases = composeAliasReferences(removed, entry.id).filter(reference => !existing.has(reference));
+    const room = Math.max(0, LEARNINGS_CONTRACT.maxProvenanceReferences - provenance.length);
+    return {
+        provenance: [...provenance, ...aliases.slice(0, room)],
+        dropped: aliases.slice(room),
+    };
+}
+/**
+ * Resolve every entry an id could refer to, live id first.
+ *
+ * A live id always wins: if an entry still carries the id, that entry IS the
+ * reference and no alias can shadow it.
+ *
+ * More than one entry can claim the same alias in exactly one situation — the
+ * union merge driver joined two branches that had each removed the same target
+ * — so this returns all claimants in deterministic id order rather than
+ * pretending the ambiguity away. {@link resolveLearningReference} takes the
+ * first for callers that just need a pointer.
+ * @param entries - Validated entries from the document
+ * @param id - Possibly-superseded id to resolve
+ * @returns Matching entries, deterministically ordered
+ */
+export function resolveLearningReferences(entries, id) {
+    const live = entries.find(entry => entry.id === id);
+    if (live !== undefined) {
+        return [live];
+    }
+    const alias = buildSupersedesReference(id);
+    return entries
+        .filter(entry => entry.provenance.includes(alias))
+        .sort((left, right) => (left.id < right.id ? -1 : 1));
+}
+/**
+ * Resolve one id to the entry that now carries its content.
+ * @param entries - Validated entries from the document
+ * @param id - Possibly-superseded id to resolve
+ * @returns The entry the reference now points at, when one exists
+ */
+export function resolveLearningReference(entries, id) {
+    return resolveLearningReferences(entries, id)[0];
+}
+//# sourceMappingURL=learnings-alias.js.map

package/dist/core/learnings-alias.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"learnings-alias.js","sourceRoot":"","sources":["../../src/core/learnings-alias.ts"],"names":[],"mappings":"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"}

package/dist/core/learnings-document.d.ts

@@ -17,6 +17,24 @@ export declare function renderLearningsFile(entries: readonly LearningEntry[]):
  * @returns Revalidated entries from the document
  */
 export declare function parseLearningsFile(content: string): LearningEntry[];
+/**
+ * A document that does not fit the hard entry-count or token budget.
+ *
+ * Typed so the writer can tell "this capture has nowhere to go" apart from every
+ * other write failure. That distinction is load-bearing: a budget breach is the
+ * one failure whose dropped CONTENT is still worth preserving in the overflow
+ * file (CodySwannGT/lisa#1996), whereas an unsafe path or a corrupted document
+ * must fail outright rather than have content salvaged out of it. The messages
+ * are unchanged from the plain-`Error` era so existing diagnostics and their
+ * assertions still read the same.
+ */
+export declare class LearningsBudgetError extends Error {
+    /**
+     * Build a budget breach carrying the caller-facing diagnosis.
+     * @param message - Single-line budget diagnosis
+     */
+    constructor(message: string);
+}
 /**
  * Enforce the shared entry-count and model-agnostic token upper bounds.
  * @param content - Canonical document

package/dist/core/learnings-document.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"learnings-document.d.ts","sourceRoot":"","sources":["../../src/core/learnings-document.ts"],"names":[],"mappings":"AAAA,+EAA+E;AAC/E,OAAO,EAGL,KAAK,aAAa,EACnB,MAAM,yBAAyB,CAAC;AA+BjC;;;GAGG;AACH,eAAO,MAAM,yBAAyB,0DACmB,CAAC;AAE1D;;;;GAIG;AACH,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,SAAS,aAAa,EAAE,GAAG,MAAM,CAG7E;AAED;;;;GAIG;AACH,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,MAAM,GAAG,aAAa,EAAE,CA8BnE;AAED;;;;;GAKG;AACH,wBAAgB,oBAAoB,CAClC,OAAO,EAAE,MAAM,EACf,UAAU,EAAE,MAAM,EAClB,OAAO,EAAE,MAAM,GACd,IAAI,CAYN;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,sBAAsB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAK1E;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,MAAM,GAAG,KAAK,CAIvD;AAED;;;;;;;;;GASG;AACH,wBAAgB,yBAAyB,CACvC,MAAM,EAAE,UAAU,GACjB,MAAM,GAAG,SAAS,CAEpB"}
+{"version":3,"file":"learnings-document.d.ts","sourceRoot":"","sources":["../../src/core/learnings-document.ts"],"names":[],"mappings":"AAAA,+EAA+E;AAC/E,OAAO,EAGL,KAAK,aAAa,EACnB,MAAM,yBAAyB,CAAC;AA+BjC;;;GAGG;AACH,eAAO,MAAM,yBAAyB,0DACmB,CAAC;AAE1D;;;;GAIG;AACH,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,SAAS,aAAa,EAAE,GAAG,MAAM,CAG7E;AAED;;;;GAIG;AACH,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,MAAM,GAAG,aAAa,EAAE,CA8BnE;AAED;;;;;;;;;;GAUG;AACH,qBAAa,oBAAqB,SAAQ,KAAK;IAC7C;;;OAGG;gBACS,OAAO,EAAE,MAAM;CAI5B;AAED;;;;;GAKG;AACH,wBAAgB,oBAAoB,CAClC,OAAO,EAAE,MAAM,EACf,UAAU,EAAE,MAAM,EAClB,OAAO,EAAE,MAAM,GACd,IAAI,CAYN;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,sBAAsB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAK1E;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,MAAM,GAAG,KAAK,CAIvD;AAED;;;;;;;;;GASG;AACH,wBAAgB,yBAAyB,CACvC,MAAM,EAAE,UAAU,GACjB,MAAM,GAAG,SAAS,CAEpB"}

package/dist/core/learnings-document.js

@@ -71,6 +71,27 @@ export function parseLearningsFile(content) {
     assertDocumentBudget(content, entries.length, "Project learnings payload");
     return entries;
 }
+/**
+ * A document that does not fit the hard entry-count or token budget.
+ *
+ * Typed so the writer can tell "this capture has nowhere to go" apart from every
+ * other write failure. That distinction is load-bearing: a budget breach is the
+ * one failure whose dropped CONTENT is still worth preserving in the overflow
+ * file (CodySwannGT/lisa#1996), whereas an unsafe path or a corrupted document
+ * must fail outright rather than have content salvaged out of it. The messages
+ * are unchanged from the plain-`Error` era so existing diagnostics and their
+ * assertions still read the same.
+ */
+export class LearningsBudgetError extends Error {
+    /**
+     * Build a budget breach carrying the caller-facing diagnosis.
+     * @param message - Single-line budget diagnosis
+     */
+    constructor(message) {
+        super(message);
+        this.name = "LearningsBudgetError";
+    }
+}
 /**
  * Enforce the shared entry-count and model-agnostic token upper bounds.
  * @param content - Canonical document
@@ -79,11 +100,11 @@ export function parseLearningsFile(content) {
  */
 export function assertDocumentBudget(content, entryCount, context) {
     if (entryCount > LEARNINGS_CONTRACT.maxEntries) {
-        throw new Error(`${context} exceeds maxEntries: measured ${entryCount}, allowed ${LEARNINGS_CONTRACT.maxEntries}`);
+        throw new LearningsBudgetError(`${context} exceeds maxEntries: measured ${entryCount}, allowed ${LEARNINGS_CONTRACT.maxEntries}`);
     }
     const estimatedTokens = estimateLearningTokens(content);
     if (estimatedTokens > LEARNINGS_CONTRACT.maxTokens) {
-        throw new Error(`${context} exceeds maxTokens ${LEARNINGS_CONTRACT.maxTokens} (measured ${estimatedTokens})`);
+        throw new LearningsBudgetError(`${context} exceeds maxTokens ${LEARNINGS_CONTRACT.maxTokens} (measured ${estimatedTokens})`);
     }
 }
 /**