@codyswann/lisa 4.19.0 → 4.21.0

package/all/copy-contents/.gitattributes

@@ -2,7 +2,8 @@
 
 # The project learnings ledger is written by concurrent learner passes that
 # each run on their own branch. Git's default line merge corrupts it with
-# conflict markers; this driver unions entries by id instead. The driver
+# conflict markers; this driver merges entries by id and fingerprint. The
+# driver preserves concurrent stable-id successors instead of guessing. Its
 # command is machine-local — run `lisa install-merge-driver` to register it.
 # `lisa doctor` already reports this as "Merge drivers registered?" when a
 # mapping here has no registered driver — named at the symptom site on

package/all/create-only/.lisa/PROJECT_LEARNINGS.md

@@ -1,6 +1,6 @@
 # Project Learnings
 
-<!-- lisa-learnings-contract:v1 -->
+<!-- lisa-learnings-contract:v2 -->
 
 ```jsonl
 

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

@@ -1,53 +1,36 @@
 /**
- * Reference survival across supersede-in-place consolidation.
+ * Reference survival across stamped 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).
+ * Learning ids are stable public references, while fingerprints are immutable
+ * content-version tokens. An exact stamped consolidation keeps the
+ * deterministic primary target id, but a multi-target consolidation removes
+ * the other live ids. Anything that cited one of those secondary ids (a
+ * tracker comment, a gardener ticket, or a cross-link from another learning)
+ * would otherwise point at an entry that no longer exists
+ * (CodySwannGT/lisa#1997).
  *
- * ## Why an alias map and NOT "carry the earliest superseded id forward"
+ * ## Why aliases still matter after stable-id carry-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**.
+ * The persisted v2 fingerprint is the compare-and-swap token that makes stable
+ * ids safe. Two learner passes racing from the same `{ id, fingerprint }`
+ * snapshot cannot overwrite one another: the first exact writer carries the id
+ * forward, the second sees a fingerprint mismatch and appends without removing
+ * the winner (#1995). A legitimate chained writer holding the winner's current
+ * fingerprint can replace it in place.
  *
- * 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*.
+ * Stable carry-forward preserves the deterministic primary id. Aliases preserve
+ * every other exact target and inherited ancestor in a multi-entry
+ * consolidation. They are therefore a reference-history layer, never a stale
+ * write workaround and never a substitute for stamped compare-and-swap.
  *
  * ## 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.
+ * In the entry's own `provenance`, as `supersedes:<old id>` references. No
+ * additional schema field or sidecar is required: 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
@@ -55,11 +38,9 @@
  * 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.
+ * An alias is recorded ONLY for a target whose exact stamp was present and
+ * removed. A stale all-or-nothing plan removes nothing and records no alias, so
+ * it cannot hijack a reference that the winning writer legitimately owns.
  * @module core/learnings-alias
  */
 import { type LearningEntry } from "./learnings-contract.js";

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

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

@@ -1,53 +1,36 @@
 /**
- * Reference survival across supersede-in-place consolidation.
+ * Reference survival across stamped 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*.
+ * Learning ids are stable public references, while fingerprints are immutable
+ * content-version tokens. An exact stamped consolidation keeps the
+ * deterministic primary target id, but a multi-target consolidation removes
+ * the other live ids. Anything that cited one of those secondary ids (a
+ * tracker comment, a gardener ticket, or a cross-link from another learning)
+ * would otherwise point at an entry that no longer exists
+ * (CodySwannGT/lisa#1997).
+ *
+ * ## Why aliases still matter after stable-id carry-forward
+ *
+ * The persisted v2 fingerprint is the compare-and-swap token that makes stable
+ * ids safe. Two learner passes racing from the same `{ id, fingerprint }`
+ * snapshot cannot overwrite one another: the first exact writer carries the id
+ * forward, the second sees a fingerprint mismatch and appends without removing
+ * the winner (#1995). A legitimate chained writer holding the winner's current
+ * fingerprint can replace it in place.
+ *
+ * Stable carry-forward preserves the deterministic primary id. Aliases preserve
+ * every other exact target and inherited ancestor in a multi-entry
+ * consolidation. They are therefore a reference-history layer, never a stale
+ * write workaround and never a substitute for stamped compare-and-swap.
  *
  * ## 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.
+ * In the entry's own `provenance`, as `supersedes:<old id>` references. No
+ * additional schema field or sidecar is required: 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
@@ -55,11 +38,9 @@
  * 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.
+ * An alias is recorded ONLY for a target whose exact stamp was present and
+ * removed. A stale all-or-nothing plan removes nothing and records no alias, so
+ * it cannot hijack a reference that the winning writer legitimately owns.
  * @module core/learnings-alias
  */
 import { LEARNINGS_CONTRACT, } from "./learnings-contract.js";

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

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

package/dist/core/learnings-budget-check.d.ts

@@ -95,9 +95,10 @@ export declare function checkLearningsBudget(file: string): Promise<LearningsBud
  * failed. This verdict is the same fact, said before anyone pays for it.
  * @param entryCount - Entries the document holds
  * @param measuredTokens - Measured document size under the contract's measure
+ * @param maxTokens - Source-version byte ceiling used for saturation
  * @returns Single-line saturation clause, or undefined when room remains
  */
-export declare function describeLearningsSaturation(entryCount: number, measuredTokens: number): string | undefined;
+export declare function describeLearningsSaturation(entryCount: number, measuredTokens: number, maxTokens?: number): string | undefined;
 /**
  * Render the one operator-facing verdict line for a within-budget document.
  *

package/dist/core/learnings-budget-check.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"learnings-budget-check.d.ts","sourceRoot":"","sources":["../../src/core/learnings-budget-check.ts"],"names":[],"mappings":"AAgCA,yDAAyD;AACzD,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,IAAI,EAAE,IAAI,CAAC;IACpB,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;IAChC,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B;;;;;;;;;;;OAWG;IACH,QAAQ,CAAC,UAAU,EAAE,MAAM,GAAG,SAAS,CAAC;CACzC;AAED,gFAAgF;AAChF,MAAM,WAAW,sBAAsB;IACrC,QAAQ,CAAC,IAAI,EAAE,SAAS,CAAC;IACzB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;CACzB;AAED,8EAA8E;AAC9E,MAAM,WAAW,wBAAwB;IACvC,QAAQ,CAAC,IAAI,EAAE,WAAW,CAAC;IAC3B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;CACzB;AAED,8CAA8C;AAC9C,MAAM,MAAM,qBAAqB,GAC7B,iBAAiB,GACjB,sBAAsB,GACtB,wBAAwB,CAAC;AAE7B;;;;;;GAMG;AACH,wBAAsB,oBAAoB,CACxC,IAAI,EAAE,MAAM,GACX,OAAO,CAAC,qBAAqB,CAAC,CAiChC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAyDG;AACH,wBAAgB,2BAA2B,CACzC,UAAU,EAAE,MAAM,EAClB,cAAc,EAAE,MAAM,GACrB,MAAM,GAAG,SAAS,CAWpB;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,mBAAmB,CACjC,IAAI,EAAE,MAAM,EACZ,MAAM,EAAE,iBAAiB,GACxB,MAAM,CAKR;AAiDD;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,CAYxD;AAoCD;;;;GAIG;AACH,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAEzD"}
+{"version":3,"file":"learnings-budget-check.d.ts","sourceRoot":"","sources":["../../src/core/learnings-budget-check.ts"],"names":[],"mappings":"AA+BA,yDAAyD;AACzD,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,IAAI,EAAE,IAAI,CAAC;IACpB,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;IAChC,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B;;;;;;;;;;;OAWG;IACH,QAAQ,CAAC,UAAU,EAAE,MAAM,GAAG,SAAS,CAAC;CACzC;AAED,gFAAgF;AAChF,MAAM,WAAW,sBAAsB;IACrC,QAAQ,CAAC,IAAI,EAAE,SAAS,CAAC;IACzB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;CACzB;AAED,8EAA8E;AAC9E,MAAM,WAAW,wBAAwB;IACvC,QAAQ,CAAC,IAAI,EAAE,WAAW,CAAC;IAC3B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;CACzB;AAED,8CAA8C;AAC9C,MAAM,MAAM,qBAAqB,GAC7B,iBAAiB,GACjB,sBAAsB,GACtB,wBAAwB,CAAC;AAE7B;;;;;;GAMG;AACH,wBAAsB,oBAAoB,CACxC,IAAI,EAAE,MAAM,GACX,OAAO,CAAC,qBAAqB,CAAC,CAiChC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA0DG;AACH,wBAAgB,2BAA2B,CACzC,UAAU,EAAE,MAAM,EAClB,cAAc,EAAE,MAAM,EACtB,SAAS,GAAE,MAAqC,GAC/C,MAAM,GAAG,SAAS,CAcpB;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,mBAAmB,CACjC,IAAI,EAAE,MAAM,EACZ,MAAM,EAAE,iBAAiB,GACxB,MAAM,CAKR;AAiDD;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,CAYxD;AAoCD;;;;GAIG;AACH,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAEzD"}

package/dist/core/learnings-budget-check.js

@@ -17,7 +17,7 @@
 import { constants } from "node:fs";
 import { open } from "node:fs/promises";
 import { LEARNINGS_CONTRACT, PER_ENTRY_BYTE_ALLOWANCE, estimateLearningTokens, } from "./learnings-contract.js";
-import { CONFLICT_MARKER_DIAGNOSIS, conflictMarkerError, findConflictMarkerInBytes, parseLearningsFile, renderLearningsFile, } from "./learnings-document.js";
+import { CONFLICT_MARKER_DIAGNOSIS, conflictMarkerError, findConflictMarkerInBytes, parseLearningsDocument, } from "./learnings-document.js";
 import { validateLearningEntry } from "./learnings-entry.js";
 /**
  * Check one already-resolved absolute learnings path against the shared hard
@@ -30,14 +30,12 @@ export async function checkLearningsBudget(file) {
     try {
         const content = await readBoundedRegularFile(file, LEARNINGS_CONTRACT.maxTokens);
         const measuredTokens = estimateLearningTokens(content);
-        if (measuredTokens > LEARNINGS_CONTRACT.maxTokens) {
-            throw new Error(`maxTokens exceeded: measured ${measuredTokens}, allowed ${LEARNINGS_CONTRACT.maxTokens}`);
-        }
-        const entries = parseLearningsFile(content);
+        const document = parseLearningsDocument(content);
+        const entries = document.entries;
         for (const entry of entries) {
             validateLearningEntry(entry);
         }
-        if (renderLearningsFile(entries) !== content) {
+        if (!document.canonicalSource) {
             throw new Error("non-canonical project learnings format");
         }
         return {
@@ -45,8 +43,8 @@ export async function checkLearningsBudget(file) {
             entryCount: entries.length,
             maxEntries: LEARNINGS_CONTRACT.maxEntries,
             measuredTokens,
-            maxTokens: LEARNINGS_CONTRACT.maxTokens,
-            saturation: describeLearningsSaturation(entries.length, measuredTokens),
+            maxTokens: document.sourceMaxTokens,
+            saturation: describeLearningsSaturation(entries.length, measuredTokens, document.sourceMaxTokens),
         };
     }
     catch (error) {
@@ -112,17 +110,21 @@ export async function checkLearningsBudget(file) {
  * failed. This verdict is the same fact, said before anyone pays for it.
  * @param entryCount - Entries the document holds
  * @param measuredTokens - Measured document size under the contract's measure
+ * @param maxTokens - Source-version byte ceiling used for saturation
  * @returns Single-line saturation clause, or undefined when room remains
  */
-export function describeLearningsSaturation(entryCount, measuredTokens) {
+export function describeLearningsSaturation(entryCount, measuredTokens, maxTokens = LEARNINGS_CONTRACT.maxTokens) {
+    const averageEntryAllowance = maxTokens === LEARNINGS_CONTRACT.maxTokens
+        ? PER_ENTRY_BYTE_ALLOWANCE
+        : Math.floor(maxTokens / LEARNINGS_CONTRACT.maxEntries);
     const entriesFull = entryCount >= LEARNINGS_CONTRACT.maxEntries;
-    const bytesFull = measuredTokens + PER_ENTRY_BYTE_ALLOWANCE > LEARNINGS_CONTRACT.maxTokens;
+    const bytesFull = measuredTokens + averageEntryAllowance > maxTokens;
     if (!entriesFull && !bytesFull) {
         return undefined;
     }
     const reason = entriesFull
         ? `every one of the ${LEARNINGS_CONTRACT.maxEntries} entry slots is taken`
-        : `fewer than ${PER_ENTRY_BYTE_ALLOWANCE} bytes remain, less than one average entry`;
+        : `fewer than ${averageEntryAllowance} bytes remain, less than one average entry`;
     return `${reason}, so the next learning captured here will be rejected. Retire or promote an entry with the gardener (\`/lisa:learnings:audit\`); raising the cap is not the remedy`;
 }
 /**

package/dist/core/learnings-budget-check.js.map

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

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

@@ -7,19 +7,34 @@
 export declare const LEARNING_CONFIDENCE_VALUES: readonly ["low", "medium", "high"];
 /** Confidence vocabulary persisted in every learning entry. */
 export type LearningConfidence = (typeof LEARNING_CONFIDENCE_VALUES)[number];
+/** Exact persisted fields accepted from the compatibility-window v1 schema. */
+export declare const LEGACY_LEARNING_ENTRY_FIELDS: readonly ["id", "rule", "why", "provenance", "first_learned", "last_confirmed", "confidence"];
+/** Historical v1 byte ceiling, retained only for source-version validation. */
+export declare const LEGACY_LEARNINGS_MAX_TOKENS = 12000;
+/**
+ * Maximum UTF-8 bytes in a persisted id or fingerprint.
+ *
+ * Stable tokens are machine keys, not prose. Bounding them keeps comparison
+ * and diagnostics cheap and, critically, closes the v1 compatibility window:
+ * v1 duplicated every id into the new fingerprint field during migration.
+ */
+export declare const MAX_STABLE_TOKEN_BYTES = 128;
 /**
  * Average per-entry byte allowance used to DERIVE the whole-file byte budget
  * (`maxTokens = maxEntries * PER_ENTRY_BYTE_ALLOWANCE`), so the entry cap and
- * the byte cap can never contradict.
+ * the byte cap can never contradict. It is the historical v1 average plus the
+ * maximum bytes v2 adds when migration persists `fingerprint = id`:
+ * `600 + 17 + 128 = 745`. Therefore every accepted 12,000-byte v1 document
+ * with at most 20 bounded ids renders as v2 within 14,900 bytes.
  *
  * This is an AVERAGE budget, not a per-entry maximum: `maxTokens` is enforced
  * against the whole rendered document — every entry plus the ```jsonl framing
- * (~72 B observed) — and there is NO per-entry byte cap (`rule` is char-capped
- * at `maxRuleCharacters`; `why` is bounded only by the document total). At 600
- * against a ~490 B observed average, each entry carries ~110 B of headroom, so
- * a full 20-entry ledger budgets 12000 B while real content lands near 9800 B —
- * the ~2.2 KB slack absorbs the document framing many times over and leaves room
- * for larger-than-average entries. A single pathologically large `why` can
+ * (~72 B observed) — and there is no aggregate per-entry byte cap (machine
+ * identity tokens have their migration bound, `rule` is char-capped at
+ * `maxRuleCharacters`, and `why` is bounded only by the document total). The
+ * v2 allowance includes the persisted fingerprint while preserving meaningful
+ * framing and variance headroom at the full 20-entry ceiling. A single
+ * pathologically large `why` can
  * consume a disproportionate share; that is intended — the document total is the
  * real constraint, and the near-boundary regression test pins that behavior.
  *
@@ -28,10 +43,10 @@ export type LearningConfidence = (typeof LEARNING_CONFIDENCE_VALUES)[number];
  * valid captures far under the entry ceiling (CodySwannGT/lisa#1959). Deriving
  * the byte cap from the entry cap removes that contradiction at the source.
  */
-export declare const PER_ENTRY_BYTE_ALLOWANCE = 600;
+export declare const PER_ENTRY_BYTE_ALLOWANCE: number;
 export declare const LEARNINGS_CONTRACT: Readonly<{
-    readonly version: 1;
-    readonly fields: readonly ["id", "rule", "why", "provenance", "first_learned", "last_confirmed", "confidence"];
+    readonly version: 2;
+    readonly fields: readonly ["id", "fingerprint", "rule", "why", "provenance", "first_learned", "last_confirmed", "confidence"];
     readonly maxRuleCharacters: 240;
     readonly maxRuleLines: 2;
     readonly maxProvenanceReferences: 20;
@@ -42,6 +57,8 @@ export declare const LEARNINGS_CONTRACT: Readonly<{
 /** Complete persisted schema for one project learning. */
 export interface LearningEntry {
     readonly id: string;
+    /** Content-version token used for exact supersede compare-and-swap. */
+    readonly fingerprint: string;
     readonly rule: string;
     readonly why: string;
     readonly provenance: readonly string[];

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

@@ -1 +1 @@
-{"version":3,"file":"learnings-contract.d.ts","sourceRoot":"","sources":["../../src/core/learnings-contract.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,eAAO,MAAM,0BAA0B,oCAAqC,CAAC;AAE7E,+DAA+D;AAC/D,MAAM,MAAM,kBAAkB,GAAG,CAAC,OAAO,0BAA0B,CAAC,CAAC,MAAM,CAAC,CAAC;AAK7E;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,eAAO,MAAM,wBAAwB,MAAM,CAAC;AAE5C,eAAO,MAAM,kBAAkB;;;;;;;;;EAiBpB,CAAC;AAEZ,0DAA0D;AAC1D,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,UAAU,EAAE,SAAS,MAAM,EAAE,CAAC;IACvC,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAC/B,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;IAChC,QAAQ,CAAC,UAAU,EAAE,kBAAkB,CAAC;CACzC;AAED;;;;;;GAMG;AACH,wBAAgB,sBAAsB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAE9D"}
+{"version":3,"file":"learnings-contract.d.ts","sourceRoot":"","sources":["../../src/core/learnings-contract.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,eAAO,MAAM,0BAA0B,oCAAqC,CAAC;AAE7E,+DAA+D;AAC/D,MAAM,MAAM,kBAAkB,GAAG,CAAC,OAAO,0BAA0B,CAAC,CAAC,MAAM,CAAC,CAAC;AAK7E,+EAA+E;AAC/E,eAAO,MAAM,4BAA4B,+FAQ9B,CAAC;AAEZ,+EAA+E;AAC/E,eAAO,MAAM,2BAA2B,QAAS,CAAC;AAElD;;;;;;GAMG;AACH,eAAO,MAAM,sBAAsB,MAAM,CAAC;AAK1C;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,eAAO,MAAM,wBAAwB,QAGb,CAAC;AAEzB,eAAO,MAAM,kBAAkB;;;;;;;;;EAkBpB,CAAC;AAEZ,0DAA0D;AAC1D,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,uEAAuE;IACvE,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,UAAU,EAAE,SAAS,MAAM,EAAE,CAAC;IACvC,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAC/B,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;IAChC,QAAQ,CAAC,UAAU,EAAE,kBAAkB,CAAC;CACzC;AAED;;;;;;GAMG;AACH,wBAAgB,sBAAsB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAE9D"}

package/dist/core/learnings-contract.js

@@ -7,19 +7,44 @@
 export const LEARNING_CONFIDENCE_VALUES = ["low", "medium", "high"];
 /** Maximum number of durable entries the ledger retains. */
 const MAX_ENTRIES = 20;
+/** Exact persisted fields accepted from the compatibility-window v1 schema. */
+export const LEGACY_LEARNING_ENTRY_FIELDS = Object.freeze([
+    "id",
+    "rule",
+    "why",
+    "provenance",
+    "first_learned",
+    "last_confirmed",
+    "confidence",
+]);
+/** Historical v1 byte ceiling, retained only for source-version validation. */
+export const LEGACY_LEARNINGS_MAX_TOKENS = 12_000;
+/**
+ * Maximum UTF-8 bytes in a persisted id or fingerprint.
+ *
+ * Stable tokens are machine keys, not prose. Bounding them keeps comparison
+ * and diagnostics cheap and, critically, closes the v1 compatibility window:
+ * v1 duplicated every id into the new fingerprint field during migration.
+ */
+export const MAX_STABLE_TOKEN_BYTES = 128;
+/** JSON bytes v2 adds around each migrated v1 id: `,"fingerprint":""`. */
+const FINGERPRINT_FIELD_BYTE_OVERHEAD = 17;
 /**
  * Average per-entry byte allowance used to DERIVE the whole-file byte budget
  * (`maxTokens = maxEntries * PER_ENTRY_BYTE_ALLOWANCE`), so the entry cap and
- * the byte cap can never contradict.
+ * the byte cap can never contradict. It is the historical v1 average plus the
+ * maximum bytes v2 adds when migration persists `fingerprint = id`:
+ * `600 + 17 + 128 = 745`. Therefore every accepted 12,000-byte v1 document
+ * with at most 20 bounded ids renders as v2 within 14,900 bytes.
  *
  * This is an AVERAGE budget, not a per-entry maximum: `maxTokens` is enforced
  * against the whole rendered document — every entry plus the ```jsonl framing
- * (~72 B observed) — and there is NO per-entry byte cap (`rule` is char-capped
- * at `maxRuleCharacters`; `why` is bounded only by the document total). At 600
- * against a ~490 B observed average, each entry carries ~110 B of headroom, so
- * a full 20-entry ledger budgets 12000 B while real content lands near 9800 B —
- * the ~2.2 KB slack absorbs the document framing many times over and leaves room
- * for larger-than-average entries. A single pathologically large `why` can
+ * (~72 B observed) — and there is no aggregate per-entry byte cap (machine
+ * identity tokens have their migration bound, `rule` is char-capped at
+ * `maxRuleCharacters`, and `why` is bounded only by the document total). The
+ * v2 allowance includes the persisted fingerprint while preserving meaningful
+ * framing and variance headroom at the full 20-entry ceiling. A single
+ * pathologically large `why` can
  * consume a disproportionate share; that is intended — the document total is the
  * real constraint, and the near-boundary regression test pins that behavior.
  *
@@ -28,11 +53,14 @@ const MAX_ENTRIES = 20;
  * valid captures far under the entry ceiling (CodySwannGT/lisa#1959). Deriving
  * the byte cap from the entry cap removes that contradiction at the source.
  */
-export const PER_ENTRY_BYTE_ALLOWANCE = 600;
+export const PER_ENTRY_BYTE_ALLOWANCE = LEGACY_LEARNINGS_MAX_TOKENS / MAX_ENTRIES +
+    FINGERPRINT_FIELD_BYTE_OVERHEAD +
+    MAX_STABLE_TOKEN_BYTES;
 export const LEARNINGS_CONTRACT = Object.freeze({
-    version: 1,
+    version: 2,
     fields: Object.freeze([
         "id",
+        "fingerprint",
         "rule",
         "why",
         "provenance",

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

@@ -1 +1 @@
-{"version":3,"file":"learnings-contract.js","sourceRoot":"","sources":["../../src/core/learnings-contract.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,MAAM,CAAC,MAAM,0BAA0B,GAAG,CAAC,KAAK,EAAE,QAAQ,EAAE,MAAM,CAAU,CAAC;AAK7E,4DAA4D;AAC5D,MAAM,WAAW,GAAG,EAAE,CAAC;AAEvB;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,MAAM,CAAC,MAAM,wBAAwB,GAAG,GAAG,CAAC;AAE5C,MAAM,CAAC,MAAM,kBAAkB,GAAG,MAAM,CAAC,MAAM,CAAC;IAC9C,OAAO,EAAE,CAAC;IACV,MAAM,EAAE,MAAM,CAAC,MAAM,CAAC;QACpB,IAAI;QACJ,MAAM;QACN,KAAK;QACL,YAAY;QACZ,eAAe;QACf,gBAAgB;QAChB,YAAY;KACJ,CAAC;IACX,iBAAiB,EAAE,GAAG;IACtB,YAAY,EAAE,CAAC;IACf,uBAAuB,EAAE,EAAE;IAC3B,UAAU,EAAE,WAAW;IACvB,SAAS,EAAE,WAAW,GAAG,wBAAwB;IACjD,WAAW,EAAE,wBAAwB;CAC7B,CAAC,CAAC;AAaZ;;;;;;GAMG;AACH,MAAM,UAAU,sBAAsB,CAAC,OAAe;IACpD,OAAO,MAAM,CAAC,UAAU,CAAC,OAAO,EAAE,MAAM,CAAC,CAAC;AAC5C,CAAC"}
+{"version":3,"file":"learnings-contract.js","sourceRoot":"","sources":["../../src/core/learnings-contract.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,MAAM,CAAC,MAAM,0BAA0B,GAAG,CAAC,KAAK,EAAE,QAAQ,EAAE,MAAM,CAAU,CAAC;AAK7E,4DAA4D;AAC5D,MAAM,WAAW,GAAG,EAAE,CAAC;AAEvB,+EAA+E;AAC/E,MAAM,CAAC,MAAM,4BAA4B,GAAG,MAAM,CAAC,MAAM,CAAC;IACxD,IAAI;IACJ,MAAM;IACN,KAAK;IACL,YAAY;IACZ,eAAe;IACf,gBAAgB;IAChB,YAAY;CACJ,CAAC,CAAC;AAEZ,+EAA+E;AAC/E,MAAM,CAAC,MAAM,2BAA2B,GAAG,MAAM,CAAC;AAElD;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,sBAAsB,GAAG,GAAG,CAAC;AAE1C,0EAA0E;AAC1E,MAAM,+BAA+B,GAAG,EAAE,CAAC;AAE3C;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,MAAM,CAAC,MAAM,wBAAwB,GACnC,2BAA2B,GAAG,WAAW;IACzC,+BAA+B;IAC/B,sBAAsB,CAAC;AAEzB,MAAM,CAAC,MAAM,kBAAkB,GAAG,MAAM,CAAC,MAAM,CAAC;IAC9C,OAAO,EAAE,CAAC;IACV,MAAM,EAAE,MAAM,CAAC,MAAM,CAAC;QACpB,IAAI;QACJ,aAAa;QACb,MAAM;QACN,KAAK;QACL,YAAY;QACZ,eAAe;QACf,gBAAgB;QAChB,YAAY;KACJ,CAAC;IACX,iBAAiB,EAAE,GAAG;IACtB,YAAY,EAAE,CAAC;IACf,uBAAuB,EAAE,EAAE;IAC3B,UAAU,EAAE,WAAW;IACvB,SAAS,EAAE,WAAW,GAAG,wBAAwB;IACjD,WAAW,EAAE,wBAAwB;CAC7B,CAAC,CAAC;AAeZ;;;;;;GAMG;AACH,MAAM,UAAU,sBAAsB,CAAC,OAAe;IACpD,OAAO,MAAM,CAAC,UAAU,CAAC,OAAO,EAAE,MAAM,CAAC,CAAC;AAC5C,CAAC"}

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

@@ -11,12 +11,30 @@ export declare const CONFLICT_MARKER_DIAGNOSIS = "Project learnings file contain
  * @returns Canonical Markdown plus JSONL document
  */
 export declare function renderLearningsFile(entries: readonly LearningEntry[]): string;
+/** Metadata-preserving parse result for one supported source version. */
+export interface ParsedLearningsDocument {
+    /** Contract version declared by the source bytes. */
+    readonly sourceVersion: 1 | 2;
+    /** Entries normalized to the current exact eight-field schema. */
+    readonly entries: readonly LearningEntry[];
+    /** Whether the bytes are canonical for their declared source version. */
+    readonly canonicalSource: boolean;
+    /** Byte ceiling that governed the source version before normalization. */
+    readonly sourceMaxTokens: number;
+}
 /**
  * Parse and revalidate an existing file before it participates in a write.
  * @param content - Existing learnings document
  * @returns Revalidated entries from the document
  */
 export declare function parseLearningsFile(content: string): LearningEntry[];
+/**
+ * Parse a v1 or v2 document while retaining the source-version facts writers
+ * need to migrate only when they already have a reason to mutate.
+ * @param content - Existing learnings document
+ * @returns Normalized entries plus source-version and canonicality metadata
+ */
+export declare function parseLearningsDocument(content: string): ParsedLearningsDocument;
 /**
  * A document that does not fit the hard entry-count or token budget.
  *
@@ -40,8 +58,9 @@ export declare class LearningsBudgetError extends Error {
  * @param content - Canonical document
  * @param entryCount - Number of entries in the document
  * @param context - Error-message prefix
+ * @param maxTokens - Source-version byte ceiling to enforce
  */
-export declare function assertDocumentBudget(content: string, entryCount: number, context: string): void;
+export declare function assertDocumentBudget(content: string, entryCount: number, context: string, maxTokens?: number): void;
 /**
  * Locate the first line git left a conflict marker on.
  *

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;;;;;;;;;;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"}
+{"version":3,"file":"learnings-document.d.ts","sourceRoot":"","sources":["../../src/core/learnings-document.ts"],"names":[],"mappings":"AAAA,+EAA+E;AAC/E,OAAO,EAIL,KAAK,aAAa,EACnB,MAAM,yBAAyB,CAAC;AAsCjC;;;GAGG;AACH,eAAO,MAAM,yBAAyB,0DACmB,CAAC;AAE1D;;;;GAIG;AACH,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,SAAS,aAAa,EAAE,GAAG,MAAM,CAG7E;AAED,yEAAyE;AACzE,MAAM,WAAW,uBAAuB;IACtC,qDAAqD;IACrD,QAAQ,CAAC,aAAa,EAAE,CAAC,GAAG,CAAC,CAAC;IAC9B,kEAAkE;IAClE,QAAQ,CAAC,OAAO,EAAE,SAAS,aAAa,EAAE,CAAC;IAC3C,yEAAyE;IACzE,QAAQ,CAAC,eAAe,EAAE,OAAO,CAAC;IAClC,0EAA0E;IAC1E,QAAQ,CAAC,eAAe,EAAE,MAAM,CAAC;CAClC;AAED;;;;GAIG;AACH,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,MAAM,GAAG,aAAa,EAAE,CAEnE;AAED;;;;;GAKG;AACH,wBAAgB,sBAAsB,CACpC,OAAO,EAAE,MAAM,GACd,uBAAuB,CAsEzB;AAoCD;;;;;;;;;;GAUG;AACH,qBAAa,oBAAqB,SAAQ,KAAK;IAC7C;;;OAGG;gBACS,OAAO,EAAE,MAAM;CAI5B;AAED;;;;;;GAMG;AACH,wBAAgB,oBAAoB,CAClC,OAAO,EAAE,MAAM,EACf,UAAU,EAAE,MAAM,EAClB,OAAO,EAAE,MAAM,EACf,SAAS,GAAE,MAAqC,GAC/C,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"}