@codyswann/lisa 2.298.1 → 2.299.1

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})`);
     }
 }
 /**

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

@@ -1 +1 @@
-{"version":3,"file":"learnings-document.js","sourceRoot":"","sources":["../../src/core/learnings-document.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"learnings-document.js","sourceRoot":"","sources":["../../src/core/learnings-document.ts"],"names":[],"mappings":"AAAA,+EAA+E;AAC/E,OAAO,EACL,kBAAkB,EAClB,sBAAsB,GAEvB,MAAM,yBAAyB,CAAC;AACjC,OAAO,EAAE,qBAAqB,EAAE,MAAM,sBAAsB,CAAC;AAE7D,MAAM,WAAW,GAAG;;gCAEY,kBAAkB,CAAC,OAAO;;CAEzD,CAAC;AACF,MAAM,gBAAgB,GAAG,YAAY,CAAC;AACtC,MAAM,cAAc,GAAG,SAAS,CAAC;AAEjC;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,eAAe,GAAG,uCAAuC,CAAC;AAEhE;;;GAGG;AACH,MAAM,CAAC,MAAM,yBAAyB,GACpC,uDAAuD,CAAC;AAE1D;;;;GAIG;AACH,MAAM,UAAU,mBAAmB,CAAC,OAAiC;IACnE,MAAM,KAAK,GAAG,OAAO,CAAC,GAAG,CAAC,KAAK,CAAC,EAAE,CAAC,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IACrE,OAAO,GAAG,WAAW,GAAG,gBAAgB,GAAG,KAAK,GAAG,cAAc,EAAE,CAAC;AACtE,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,kBAAkB,CAAC,OAAe;IAChD,4EAA4E;IAC5E,6EAA6E;IAC7E,4EAA4E;IAC5E,6EAA6E;IAC7E,MAAM,YAAY,GAAG,sBAAsB,CAAC,OAAO,CAAC,CAAC;IACrD,IAAI,YAAY,KAAK,SAAS,EAAE,CAAC;QAC/B,MAAM,mBAAmB,CAAC,YAAY,CAAC,CAAC;IAC1C,CAAC;IACD,IAAI,sBAAsB,CAAC,OAAO,CAAC,GAAG,kBAAkB,CAAC,SAAS,EAAE,CAAC;QACnE,MAAM,IAAI,KAAK,CACb,+CAA+C,kBAAkB,CAAC,SAAS,EAAE,CAC9E,CAAC;IACJ,CAAC;IACD,IACE,CAAC,OAAO,CAAC,UAAU,CAAC,GAAG,WAAW,GAAG,gBAAgB,EAAE,CAAC;QACxD,CAAC,OAAO,CAAC,QAAQ,CAAC,cAAc,CAAC,EACjC,CAAC;QACD,MAAM,IAAI,KAAK,CAAC,uCAAuC,CAAC,CAAC;IAC3D,CAAC;IACD,MAAM,SAAS,GAAG,WAAW,CAAC,MAAM,GAAG,gBAAgB,CAAC,MAAM,CAAC;IAC/D,MAAM,OAAO,GAAG,OAAO,CAAC,MAAM,GAAG,cAAc,CAAC,MAAM,CAAC;IACvD,MAAM,OAAO,GAAG,cAAc,CAAC,OAAO,CAAC,KAAK,CAAC,SAAS,EAAE,OAAO,CAAC,CAAC,CAAC,GAAG,CACnE,2BAA2B,CAC5B,CAAC;IACF,IAAI,IAAI,GAAG,CAAC,OAAO,CAAC,GAAG,CAAC,KAAK,CAAC,EAAE,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC,CAAC,IAAI,KAAK,OAAO,CAAC,MAAM,EAAE,CAAC;QACpE,MAAM,IAAI,KAAK,CAAC,kDAAkD,CAAC,CAAC;IACtE,CAAC;IACD,oBAAoB,CAAC,OAAO,EAAE,OAAO,CAAC,MAAM,EAAE,2BAA2B,CAAC,CAAC;IAC3E,OAAO,OAAO,CAAC;AACjB,CAAC;AAED;;;;;;;;;;GAUG;AACH,MAAM,OAAO,oBAAqB,SAAQ,KAAK;IAC7C;;;OAGG;IACH,YAAY,OAAe;QACzB,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,IAAI,GAAG,sBAAsB,CAAC;IACrC,CAAC;CACF;AAED;;;;;GAKG;AACH,MAAM,UAAU,oBAAoB,CAClC,OAAe,EACf,UAAkB,EAClB,OAAe;IAEf,IAAI,UAAU,GAAG,kBAAkB,CAAC,UAAU,EAAE,CAAC;QAC/C,MAAM,IAAI,oBAAoB,CAC5B,GAAG,OAAO,iCAAiC,UAAU,aAAa,kBAAkB,CAAC,UAAU,EAAE,CAClG,CAAC;IACJ,CAAC;IACD,MAAM,eAAe,GAAG,sBAAsB,CAAC,OAAO,CAAC,CAAC;IACxD,IAAI,eAAe,GAAG,kBAAkB,CAAC,SAAS,EAAE,CAAC;QACnD,MAAM,IAAI,oBAAoB,CAC5B,GAAG,OAAO,sBAAsB,kBAAkB,CAAC,SAAS,cAAc,eAAe,GAAG,CAC7F,CAAC;IACJ,CAAC;AACH,CAAC;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,UAAU,sBAAsB,CAAC,OAAe;IACpD,MAAM,KAAK,GAAG,OAAO;SAClB,KAAK,CAAC,IAAI,CAAC;SACX,SAAS,CAAC,IAAI,CAAC,EAAE,CAAC,eAAe,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC;IACjD,OAAO,KAAK,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,KAAK,GAAG,CAAC,CAAC;AAC9C,CAAC;AAED;;;;;;;;;;GAUG;AACH,MAAM,UAAU,mBAAmB,CAAC,IAAY;IAC9C,OAAO,IAAI,KAAK,CACd,GAAG,yBAAyB,YAAY,IAAI,oKAAoK,CACjN,CAAC;AACJ,CAAC;AAED;;;;;;;;;GASG;AACH,MAAM,UAAU,yBAAyB,CACvC,MAAkB;IAElB,OAAO,sBAAsB,CAAC,IAAI,WAAW,CAAC,OAAO,CAAC,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC;AACzE,CAAC;AAED;;;;;GAKG;AACH,SAAS,2BAA2B,CAClC,SAAkB,EAClB,KAAa;IAEb,IAAI,CAAC;QACH,OAAO,qBAAqB,CAAC,SAAS,CAAC,CAAC;IAC1C,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,MAAM,EAAE,GAAG,qBAAqB,CAAC,SAAS,CAAC,CAAC;QAC5C,0EAA0E;QAC1E,wEAAwE;QACxE,yEAAyE;QACzE,yEAAyE;QACzE,4BAA4B;QAC5B,MAAM,KAAK,GAAG,EAAE,KAAK,SAAS,CAAC,CAAC,CAAC,SAAS,KAAK,GAAG,CAAC,EAAE,CAAC,CAAC,CAAC,UAAU,EAAE,GAAG,CAAC;QACxE,MAAM,MAAM,GAAG,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;QACtE,MAAM,IAAI,KAAK,CAAC,oBAAoB,KAAK,KAAK,MAAM,EAAE,CAAC,CAAC;IAC1D,CAAC;AACH,CAAC;AAED;;;;GAIG;AACH,SAAS,qBAAqB,CAAC,SAAkB;IAC/C,IAAI,SAAS,KAAK,IAAI,IAAI,OAAO,SAAS,KAAK,QAAQ,EAAE,CAAC;QACxD,OAAO,SAAS,CAAC;IACnB,CAAC;IACD,MAAM,UAAU,GAAG,MAAM,CAAC,wBAAwB,CAAC,SAAS,EAAE,IAAI,CAAC,CAAC;IACpE,OAAO,UAAU,KAAK,SAAS;QAC7B,OAAO,IAAI,UAAU;QACrB,OAAO,UAAU,CAAC,KAAK,KAAK,QAAQ;QACpC,CAAC,CAAC,UAAU,CAAC,KAAK;QAClB,CAAC,CAAC,SAAS,CAAC;AAChB,CAAC;AAED;;;;GAIG;AACH,SAAS,cAAc,CAAC,OAAe;IACrC,IAAI,OAAO,KAAK,EAAE,EAAE,CAAC;QACnB,OAAO,EAAE,CAAC;IACZ,CAAC;IACD,IAAI,CAAC;QACH,OAAO,OAAO,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,GAAG,CAAC,IAAI,CAAC,EAAE,CAAC,IAAI,CAAC,KAAK,CAAC,IAAI,CAAY,CAAC,CAAC;IACtE,CAAC;IAAC,MAAM,CAAC;QACP,MAAM,IAAI,KAAK,CAAC,yCAAyC,CAAC,CAAC;IAC7D,CAAC;AACH,CAAC"}

package/dist/core/learnings-merge-driver.d.ts

@@ -1,36 +1,3 @@
-/**
- * Registration contract for the project-learnings union merge driver.
- *
- * A git merge driver has two halves that live in different places:
- *
- * 1. **The attribute** (`.gitattributes`) says WHICH driver a path uses. It is
- *    a committed file, so Lisa ships it to the repository and to every host
- *    project through the template pipeline.
- * 2. **The driver command** (`merge.<name>.driver`) says HOW to run it. Git
- *    deliberately keeps this in machine-local config and never reads it from
- *    the repository, because a committed driver command would let a cloned
- *    repository execute arbitrary code on `git merge`.
- *
- * So the attribute alone is inert. Until the command is registered, git falls
- * back to its built-in text merge — which is exactly today's behavior, so an
- * unregistered checkout is degraded, never broken. That fallback is asserted in
- * `tests/unit/core/learnings-merge-driver.test.ts`.
- *
- * Registration is AUTOMATIC, not operator-initiated. `EnsureLearningsMergeDriver`
- * runs on every `lisa apply`, and the TypeScript stack's `package.lisa.json`
- * wires `lisa apply` into `postinstall` — so an ordinary `npm install` in a host
- * project writes `merge.lisa-learnings.driver` into `.git/config` with no
- * separate human step, and against Lisa's own repository too.
- *
- * That is worth stating plainly because of what it implies: the registration
- * persists an executable hook in local git config that fires on ordinary git
- * operations, outside npm's lifecycle. It is not an escalation over `npm
- * install` itself (which already runs arbitrary code), but it does outlive it.
- * Hosts that would rather not carry that hook set `learnings.mergeDriver: false`
- * in `.lisa.config.json`; `lisa install-merge-driver` remains available to
- * register it by hand in a clone that apply has not touched.
- * @module core/learnings-merge-driver
- */
 /** Git merge-driver name shared by `.gitattributes` and the local git config. */
 export declare const LEARNINGS_MERGE_DRIVER_NAME = "lisa-learnings";
 /** Human-readable driver name recorded alongside the command. */
@@ -76,6 +43,14 @@ export declare function buildLearningsAttributeLine(ledgerPath: string): string;
  * Wrapped in the same guardrail markers the `.gitignore` template uses, so the
  * `copy-contents` strategy replaces exactly this block on re-apply and leaves
  * every host-authored rule outside it untouched.
+ *
+ * Both halves of the learnings surface are bound. The overflow file
+ * (CodySwannGT/lisa#1996) is written by the same concurrent learner passes, on
+ * the same per-fingerprint branches, in the same canonical document format — so
+ * it has the ledger's exact merge problem and the exact same union-by-id
+ * resolution. Binding only the ledger would leave the overflow on git's default
+ * text merge, silently re-introducing the corruption this driver exists to
+ * remove, on the one file whose whole job is not losing content.
  * @param ledgerPath - Project-relative learnings file path
  * @returns Managed block, newline-terminated
  */

package/dist/core/learnings-merge-driver.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"learnings-merge-driver.d.ts","sourceRoot":"","sources":["../../src/core/learnings-merge-driver.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AAEH,iFAAiF;AACjF,eAAO,MAAM,2BAA2B,mBAAmB,CAAC;AAE5D,iEAAiE;AACjE,eAAO,MAAM,kCAAkC,wCACR,CAAC;AAExC,wEAAwE;AACxE,eAAO,MAAM,0BAA0B,2BAA2B,CAAC;AAEnE,wEAAwE;AACxE,eAAO,MAAM,wBAAwB,yBAAyB,CAAC;AAE/D;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,wBAAgB,gCAAgC,CAAC,UAAU,EAAE,MAAM,GAAG,MAAM,CAE3E;AAED;;;;GAIG;AACH,wBAAgB,2BAA2B,CAAC,UAAU,EAAE,MAAM,GAAG,MAAM,CAEtE;AAED;;;;;;;;GAQG;AACH,wBAAgB,iCAAiC,CAAC,UAAU,EAAE,MAAM,GAAG,MAAM,CAa5E"}
+{"version":3,"file":"learnings-merge-driver.d.ts","sourceRoot":"","sources":["../../src/core/learnings-merge-driver.ts"],"names":[],"mappings":"AAmCA,iFAAiF;AACjF,eAAO,MAAM,2BAA2B,mBAAmB,CAAC;AAE5D,iEAAiE;AACjE,eAAO,MAAM,kCAAkC,wCACR,CAAC;AAExC,wEAAwE;AACxE,eAAO,MAAM,0BAA0B,2BAA2B,CAAC;AAEnE,wEAAwE;AACxE,eAAO,MAAM,wBAAwB,yBAAyB,CAAC;AAE/D;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,wBAAgB,gCAAgC,CAAC,UAAU,EAAE,MAAM,GAAG,MAAM,CAE3E;AAED;;;;GAIG;AACH,wBAAgB,2BAA2B,CAAC,UAAU,EAAE,MAAM,GAAG,MAAM,CAEtE;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,iCAAiC,CAAC,UAAU,EAAE,MAAM,GAAG,MAAM,CAmB5E"}

package/dist/core/learnings-merge-driver.js

@@ -31,6 +31,7 @@
  * register it by hand in a clone that apply has not touched.
  * @module core/learnings-merge-driver
  */
+import { resolveLearningsOverflowFile } from "./learnings-overflow.js";
 /** Git merge-driver name shared by `.gitattributes` and the local git config. */
 export const LEARNINGS_MERGE_DRIVER_NAME = "lisa-learnings";
 /** Human-readable driver name recorded alongside the command. */
@@ -80,6 +81,14 @@ export function buildLearningsAttributeLine(ledgerPath) {
  * Wrapped in the same guardrail markers the `.gitignore` template uses, so the
  * `copy-contents` strategy replaces exactly this block on re-apply and leaves
  * every host-authored rule outside it untouched.
+ *
+ * Both halves of the learnings surface are bound. The overflow file
+ * (CodySwannGT/lisa#1996) is written by the same concurrent learner passes, on
+ * the same per-fingerprint branches, in the same canonical document format — so
+ * it has the ledger's exact merge problem and the exact same union-by-id
+ * resolution. Binding only the ledger would leave the overflow on git's default
+ * text merge, silently re-introducing the corruption this driver exists to
+ * remove, on the one file whose whole job is not losing content.
  * @param ledgerPath - Project-relative learnings file path
  * @returns Managed block, newline-terminated
  */
@@ -93,6 +102,12 @@ export function renderLearningsGitattributesBlock(ledgerPath) {
         "# command is machine-local — run `lisa install-merge-driver` to register it.",
         buildLearningsAttributeLine(ledgerPath),
         "",
+        "# 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.",
+        buildLearningsAttributeLine(resolveLearningsOverflowFile(ledgerPath)),
+        "",
         GITATTRIBUTES_END_MARKER,
         "",
     ].join("\n");

package/dist/core/learnings-merge-driver.js.map

@@ -1 +1 @@
-{"version":3,"file":"learnings-merge-driver.js","sourceRoot":"","sources":["../../src/core/learnings-merge-driver.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AAEH,iFAAiF;AACjF,MAAM,CAAC,MAAM,2BAA2B,GAAG,gBAAgB,CAAC;AAE5D,iEAAiE;AACjE,MAAM,CAAC,MAAM,kCAAkC,GAC7C,qCAAqC,CAAC;AAExC,wEAAwE;AACxE,MAAM,CAAC,MAAM,0BAA0B,GAAG,wBAAwB,CAAC;AAEnE,wEAAwE;AACxE,MAAM,CAAC,MAAM,wBAAwB,GAAG,sBAAsB,CAAC;AAE/D;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,MAAM,UAAU,gCAAgC,CAAC,UAAkB;IACjE,OAAO,GAAG,UAAU,4DAA4D,CAAC;AACnF,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,2BAA2B,CAAC,UAAkB;IAC5D,OAAO,GAAG,UAAU,UAAU,2BAA2B,EAAE,CAAC;AAC9D,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,UAAU,iCAAiC,CAAC,UAAkB;IAClE,OAAO;QACL,0BAA0B;QAC1B,EAAE;QACF,6EAA6E;QAC7E,2EAA2E;QAC3E,0EAA0E;QAC1E,8EAA8E;QAC9E,2BAA2B,CAAC,UAAU,CAAC;QACvC,EAAE;QACF,wBAAwB;QACxB,EAAE;KACH,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AACf,CAAC"}
+{"version":3,"file":"learnings-merge-driver.js","sourceRoot":"","sources":["../../src/core/learnings-merge-driver.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AACH,OAAO,EAAE,4BAA4B,EAAE,MAAM,yBAAyB,CAAC;AAEvE,iFAAiF;AACjF,MAAM,CAAC,MAAM,2BAA2B,GAAG,gBAAgB,CAAC;AAE5D,iEAAiE;AACjE,MAAM,CAAC,MAAM,kCAAkC,GAC7C,qCAAqC,CAAC;AAExC,wEAAwE;AACxE,MAAM,CAAC,MAAM,0BAA0B,GAAG,wBAAwB,CAAC;AAEnE,wEAAwE;AACxE,MAAM,CAAC,MAAM,wBAAwB,GAAG,sBAAsB,CAAC;AAE/D;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,MAAM,UAAU,gCAAgC,CAAC,UAAkB;IACjE,OAAO,GAAG,UAAU,4DAA4D,CAAC;AACnF,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,2BAA2B,CAAC,UAAkB;IAC5D,OAAO,GAAG,UAAU,UAAU,2BAA2B,EAAE,CAAC;AAC9D,CAAC;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,UAAU,iCAAiC,CAAC,UAAkB;IAClE,OAAO;QACL,0BAA0B;QAC1B,EAAE;QACF,6EAA6E;QAC7E,2EAA2E;QAC3E,0EAA0E;QAC1E,8EAA8E;QAC9E,2BAA2B,CAAC,UAAU,CAAC;QACvC,EAAE;QACF,0EAA0E;QAC1E,2EAA2E;QAC3E,4EAA4E;QAC5E,0BAA0B;QAC1B,2BAA2B,CAAC,4BAA4B,CAAC,UAAU,CAAC,CAAC;QACrE,EAAE;QACF,wBAAwB;QACxB,EAAE;KACH,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AACf,CAAC"}

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

@@ -0,0 +1,76 @@
+import { type LearningEntry } from "./learnings-contract.js";
+import { LearningsBudgetError } from "./learnings-document.js";
+/**
+ * Derive the overflow path from a project's configured ledger path.
+ *
+ * Derived rather than separately configurable so a project that relocates its
+ * ledger through `learnings.file` cannot end up with the two halves of one
+ * mechanism in different directories — and so there is no second config key to
+ * validate, contain, and keep in sync.
+ * @param learningsFile - Project-relative ledger path
+ * @returns Project-relative overflow path
+ */
+export declare function resolveLearningsOverflowFile(learningsFile: string): string;
+/** Entries currently awaiting drain, and where they live. */
+export interface LearningsOverflowContents {
+    /** Absolute overflow path, whether or not the file exists yet. */
+    readonly file: string;
+    /** Validated entries awaiting drain. */
+    readonly entries: readonly LearningEntry[];
+}
+/**
+ * Read the overflow without modifying it.
+ *
+ * An absent file is the common, expected case and reads as empty — a project
+ * that has never dropped a capture must not have to special-case its absence.
+ * @param projectRoot - Absolute path to the host project root
+ * @returns Overflow path and the entries awaiting drain
+ */
+export declare function readLearningsOverflow(projectRoot: string): Promise<LearningsOverflowContents>;
+/** Outcome of draining entries the gardener has finished with. */
+export interface LearningsOverflowDrain {
+    /** Absolute overflow path. */
+    readonly file: string;
+    /** Ids that were present and have now been removed. */
+    readonly drained: readonly string[];
+    /** Requested ids that were not in the overflow — reported, never fatal. */
+    readonly absent: readonly string[];
+    /** How many entries still await drain. */
+    readonly remaining: number;
+}
+/**
+ * Remove entries the gardener has durably captured elsewhere.
+ *
+ * Drain is BY ID and never "empty the file", because the gardener's real
+ * sequence is read → file a ticket per entry → drain. Clearing everything up
+ * front would lose any entry whose ticket failed to file; removing only the ids
+ * that already have a durable home makes a partial run safely resumable.
+ *
+ * An unknown id is reported rather than thrown, for the same reason an absent
+ * supersede target is tolerated: on a re-run, an id another pass already drained
+ * is indistinguishable from a bogus one, and failing the drain would strand
+ * every other entry in the batch.
+ * @param projectRoot - Absolute path to the host project root
+ * @param ids - Entry ids to remove
+ * @returns Which ids were drained, which were absent, and what remains
+ */
+export declare function drainLearningsOverflow(projectRoot: string, ids: readonly string[]): Promise<LearningsOverflowDrain>;
+/**
+ * Preserve a capture the ledger had no budget for, then re-raise the breach.
+ *
+ * Never returns normally: the capture genuinely did not land in the ledger, and
+ * a caller that treated preservation as success would report a learning as
+ * persisted when the projection will never serve it. The re-raised error names
+ * the overflow file so the drop is actionable rather than merely fatal.
+ *
+ * If the overflow is itself full, the original ledger breach is re-raised with
+ * both surfaces named. Nothing is evicted to make room — silently discarding an
+ * older dropped learning to store a newer one is the exact data loss this whole
+ * mechanism exists to prevent.
+ * @param projectRoot - Absolute path to the host project root
+ * @param entry - The validated entry the ledger rejected
+ * @param breach - The budget breach the ledger write raised
+ * @returns Never — always throws
+ */
+export declare function preserveDroppedLearning(projectRoot: string, entry: LearningEntry, breach: LearningsBudgetError): Promise<never>;
+//# sourceMappingURL=learnings-overflow.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"learnings-overflow.d.ts","sourceRoot":"","sources":["../../src/core/learnings-overflow.ts"],"names":[],"mappings":"AAkDA,OAAO,EAAE,KAAK,aAAa,EAAE,MAAM,yBAAyB,CAAC;AAC7D,OAAO,EACL,oBAAoB,EAIrB,MAAM,yBAAyB,CAAC;AAejC;;;;;;;;;GASG;AACH,wBAAgB,4BAA4B,CAAC,aAAa,EAAE,MAAM,GAAG,MAAM,CAI1E;AAmCD,6DAA6D;AAC7D,MAAM,WAAW,yBAAyB;IACxC,kEAAkE;IAClE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,wCAAwC;IACxC,QAAQ,CAAC,OAAO,EAAE,SAAS,aAAa,EAAE,CAAC;CAC5C;AAED;;;;;;;GAOG;AACH,wBAAsB,qBAAqB,CACzC,WAAW,EAAE,MAAM,GAClB,OAAO,CAAC,yBAAyB,CAAC,CAGpC;AAED,kEAAkE;AAClE,MAAM,WAAW,sBAAsB;IACrC,8BAA8B;IAC9B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,uDAAuD;IACvD,QAAQ,CAAC,OAAO,EAAE,SAAS,MAAM,EAAE,CAAC;IACpC,2EAA2E;IAC3E,QAAQ,CAAC,MAAM,EAAE,SAAS,MAAM,EAAE,CAAC;IACnC,0CAA0C;IAC1C,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;CAC5B;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAsB,sBAAsB,CAC1C,WAAW,EAAE,MAAM,EACnB,GAAG,EAAE,SAAS,MAAM,EAAE,GACrB,OAAO,CAAC,sBAAsB,CAAC,CAwBjC;AAqBD;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAsB,uBAAuB,CAC3C,WAAW,EAAE,MAAM,EACnB,KAAK,EAAE,aAAa,EACpB,MAAM,EAAE,oBAAoB,GAC3B,OAAO,CAAC,KAAK,CAAC,CAyBhB"}