@codyswann/lisa 4.20.0 → 4.21.0

package/dist/core/learnings-merge.js

@@ -27,8 +27,11 @@
  * Per id, against the base: if only one side changed it, that side wins
  * (including a removal). If both sides made the SAME change, it is not a
  * conflict. If both sides changed it differently, the merge FAILS rather than
- * guessing — with one narrow exception: when the only differing field is
- * `last_confirmed`, the later date wins, because that field is a monotonic
+ * guessing — with two information-preserving exceptions. First, two distinct
+ * fingerprint successors of the same base stamp are a concurrent stable-id
+ * fork: both survive deterministically, with the lower fingerprint retaining
+ * the stable id and the other keyed by its fingerprint. Second, when the only
+ * differing field is `last_confirmed`, the later date wins, because that field is a monotonic
  * "this rule demonstrably applied again" stamp and taking the later one loses
  * no information. A confirmation bump never beats a content edit; that is a
  * genuine conflict, because preferring the later timestamp would silently
@@ -42,6 +45,7 @@
  */
 import { LEARNINGS_CONTRACT, } from "./learnings-contract.js";
 import { assertDocumentBudget, parseLearningsFile, renderLearningsFile, } from "./learnings-document.js";
+import { validateLearningEntry } from "./learnings-entry.js";
 /**
  * Merge two divergent ledger versions against their common ancestor.
  * @param base - Merge-base document, or undefined when the file is new on both sides
@@ -100,16 +104,32 @@ function resolveAllIds(base, ours, theirs) {
             reason: `Both branches changed learning ${conflictingIds.map(id => `'${id}'`).join(", ")} differently; recompact by hand to keep the intended content`,
         };
     }
-    return {
-        kind: "entries",
-        entries: resolutions
-            .filter((resolution) => resolution !== "absent" && resolution !== "conflict")
-            .sort((left, right) => left.id.localeCompare(right.id)),
-    };
+    const unsortedEntries = resolutions.flatMap(resolution => resolution === "absent" || resolution === "conflict"
+        ? []
+        : Array.isArray(resolution)
+            ? resolution
+            : [resolution]);
+    const entries = sortLearningEntries(unsortedEntries);
+    const duplicateId = findDuplicate(entries.map(entry => entry.id));
+    if (duplicateId !== undefined) {
+        return {
+            kind: "conflict",
+            reason: `Concurrent learning fork would collide with live id '${duplicateId}'; recompact by hand to preserve both entries`,
+        };
+    }
+    const duplicateFingerprint = findDuplicate(entries.map(entry => entry.fingerprint));
+    if (duplicateFingerprint !== undefined) {
+        return {
+            kind: "conflict",
+            reason: `Merged project learnings contain duplicate fingerprint '${duplicateFingerprint}'; recompact by hand rather than guessing which identical capture wins`,
+        };
+    }
+    return { kind: "entries", entries };
 }
 /**
  * Resolve one id with standard three-way semantics.
  * @param base - Ancestor version, if any
+ * @param base - Common ancestor version, if any
  * @param ours - Current-branch version, if any
  * @param theirs - Incoming-branch version, if any
  * @returns The winning entry, `absent` when both sides removed it, or `conflict`
@@ -126,27 +146,93 @@ function resolveOneId(base, ours, theirs) {
     if (sameEntry(base, theirs)) {
         return ours ?? "absent";
     }
-    return resolveDivergentEdit(ours, theirs);
+    return resolveDivergentEdit(base, ours, theirs);
 }
 /**
  * Resolve the one divergence that is safe to auto-merge: both branches only
  * re-confirmed the same entry, so the later monotonic stamp wins.
+ * @param base - Common ancestor version, if any
  * @param ours - Current-branch version, if any
  * @param theirs - Incoming-branch version, if any
  * @returns The later-confirmed entry, or `conflict`
  */
-function resolveDivergentEdit(ours, theirs) {
+function resolveDivergentEdit(base, ours, theirs) {
     if (ours === undefined || theirs === undefined) {
         // One side edited the entry while the other superseded it. Dropping the
         // edit or resurrecting the removal are both information loss.
         return "conflict";
     }
+    const fork = forkConcurrentStableRewrite(base, ours, theirs);
+    if (fork !== undefined) {
+        return fork;
+    }
     // Neutralize only `last_confirmed`: if the entries match once that field is
     // aligned, it was the sole difference and taking the later stamp loses nothing.
     return sameEntry({ ...ours, last_confirmed: theirs.last_confirmed }, theirs)
         ? pickLaterConfirmation(ours, theirs)
         : "conflict";
 }
+/**
+ * Preserve both successors when two branches legitimately rewrote the same
+ * stable identity from the same fingerprint snapshot.
+ *
+ * The lower fingerprint keeps the stable public id; the other successor is
+ * re-keyed to its own globally unique fingerprint. This ordering is independent
+ * of ours/theirs orientation, so reversing merge sides produces identical
+ * bytes. A confirmation-versus-rewrite is not a fork: both successors must
+ * carry new, distinct fingerprints relative to the base.
+ * @param base - Common ancestor entry
+ * @param ours - Current-branch successor
+ * @param theirs - Incoming-branch successor
+ * @returns Two deterministic survivors, or undefined when this is not a fork
+ */
+function forkConcurrentStableRewrite(base, ours, theirs) {
+    if (base === undefined ||
+        ours.id !== base.id ||
+        theirs.id !== base.id ||
+        ours.fingerprint === base.fingerprint ||
+        theirs.fingerprint === base.fingerprint ||
+        ours.fingerprint === theirs.fingerprint) {
+        return undefined;
+    }
+    const [primary, forked] = compareTokens(ours.fingerprint, theirs.fingerprint) <= 0
+        ? [ours, theirs]
+        : [theirs, ours];
+    return [
+        primary,
+        validateLearningEntry({ ...forked, id: forked.fingerprint }),
+    ];
+}
+/**
+ * Find the first repeated token in encounter order.
+ * @param values - Stable tokens to inspect
+ * @returns First duplicate, when one exists
+ */
+function findDuplicate(values) {
+    return values.find((value, index) => values.indexOf(value) !== index);
+}
+/**
+ * Compare stable tokens without locale dependence.
+ * @param left - First token
+ * @param right - Second token
+ * @returns Negative, zero, or positive ordering result
+ */
+function compareTokens(left, right) {
+    return left === right ? 0 : left < right ? -1 : 1;
+}
+/**
+ * Sort entries by id without mutating a caller-owned or local array.
+ * @param entries - Entries in arbitrary order
+ * @returns New deterministically ordered array
+ */
+function sortLearningEntries(entries) {
+    return entries.reduce((ordered, entry) => {
+        const insertion = ordered.findIndex(current => compareTokens(entry.id, current.id) < 0);
+        return insertion === -1
+            ? [...ordered, entry]
+            : [...ordered.slice(0, insertion), entry, ...ordered.slice(insertion)];
+    }, []);
+}
 /**
  * Choose the later of two confirmation stamps.
  * @param ours - Current-branch version

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

@@ -1 +1 @@
-{"version":3,"file":"learnings-merge.js","sourceRoot":"","sources":["../../src/core/learnings-merge.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"learnings-merge.js","sourceRoot":"","sources":["../../src/core/learnings-merge.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4CG;AACH,OAAO,EACL,kBAAkB,GAEnB,MAAM,yBAAyB,CAAC;AACjC,OAAO,EACL,oBAAoB,EACpB,kBAAkB,EAClB,mBAAmB,GACpB,MAAM,yBAAyB,CAAC;AACjC,OAAO,EAAE,qBAAqB,EAAE,MAAM,sBAAsB,CAAC;AAqB7D;;;;;;GAMG;AACH,MAAM,UAAU,uBAAuB,CACrC,IAAwB,EACxB,IAAY,EACZ,MAAc;IAEd,IAAI,CAAC;QACH,MAAM,WAAW,GAAG,SAAS,CAAC,IAAI,CAAC,CAAC;QACpC,MAAM,UAAU,GAAG,SAAS,CAAC,IAAI,CAAC,CAAC;QACnC,MAAM,YAAY,GAAG,SAAS,CAAC,MAAM,CAAC,CAAC;QACvC,MAAM,QAAQ,GAAG,aAAa,CAAC,WAAW,EAAE,UAAU,EAAE,YAAY,CAAC,CAAC;QACtE,IAAI,QAAQ,CAAC,IAAI,KAAK,UAAU,EAAE,CAAC;YACjC,OAAO,QAAQ,CAAC;QAClB,CAAC;QACD,OAAO,kBAAkB,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAC;IAC9C,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,OAAO;YACL,IAAI,EAAE,UAAU;YAChB,MAAM,EAAE,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC;SAC/D,CAAC;IACJ,CAAC;AACH,CAAC;AAED;;;;;;;;GAQG;AACH,SAAS,SAAS,CAChB,OAA2B;IAE3B,IAAI,OAAO,KAAK,SAAS,IAAI,OAAO,KAAK,EAAE,EAAE,CAAC;QAC5C,OAAO,IAAI,GAAG,EAAE,CAAC;IACnB,CAAC;IACD,OAAO,IAAI,GAAG,CAAC,kBAAkB,CAAC,OAAO,CAAC,CAAC,GAAG,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC,KAAK,CAAC,EAAE,EAAE,KAAK,CAAC,CAAC,CAAC,CAAC;AAC9E,CAAC;AAED;;;;;;GAMG;AACH,SAAS,aAAa,CACpB,IAAwC,EACxC,IAAwC,EACxC,MAA0C;IAI1C,MAAM,GAAG,GAAG,CAAC,GAAG,IAAI,GAAG,CAAC,CAAC,GAAG,IAAI,CAAC,IAAI,EAAE,EAAE,GAAG,IAAI,CAAC,IAAI,EAAE,EAAE,GAAG,MAAM,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC,CAAC;IAC7E,MAAM,WAAW,GAAG,GAAG,CAAC,GAAG,CAAC,EAAE,CAAC,EAAE,CAC/B,YAAY,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,EAAE,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,EAAE,MAAM,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC,CACzD,CAAC;IACF,MAAM,UAAU,GAAG,WAAW,CAAC,IAAI,CAAC,UAAU,CAAC,EAAE,CAAC,UAAU,KAAK,UAAU,CAAC,CAAC;IAC7E,IAAI,UAAU,KAAK,SAAS,EAAE,CAAC;QAC7B,MAAM,cAAc,GAAG,GAAG,CAAC,MAAM,CAC/B,CAAC,OAAO,EAAE,KAAK,EAAE,EAAE,CAAC,WAAW,CAAC,KAAK,CAAC,KAAK,UAAU,CACtD,CAAC;QACF,OAAO;YACL,IAAI,EAAE,UAAU;YAChB,MAAM,EAAE,kCAAkC,cAAc,CAAC,GAAG,CAAC,EAAE,CAAC,EAAE,CAAC,IAAI,EAAE,GAAG,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,8DAA8D;SACvJ,CAAC;IACJ,CAAC;IACD,MAAM,eAAe,GAAG,WAAW,CAAC,OAAO,CAAC,UAAU,CAAC,EAAE,CACvD,UAAU,KAAK,QAAQ,IAAI,UAAU,KAAK,UAAU;QAClD,CAAC,CAAC,EAAE;QACJ,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,UAAU,CAAC;YACzB,CAAC,CAAC,UAAU;YACZ,CAAC,CAAC,CAAC,UAAU,CAAC,CACnB,CAAC;IACF,MAAM,OAAO,GAAG,mBAAmB,CAAC,eAAe,CAAC,CAAC;IACrD,MAAM,WAAW,GAAG,aAAa,CAAC,OAAO,CAAC,GAAG,CAAC,KAAK,CAAC,EAAE,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC,CAAC;IAClE,IAAI,WAAW,KAAK,SAAS,EAAE,CAAC;QAC9B,OAAO;YACL,IAAI,EAAE,UAAU;YAChB,MAAM,EAAE,wDAAwD,WAAW,+CAA+C;SAC3H,CAAC;IACJ,CAAC;IACD,MAAM,oBAAoB,GAAG,aAAa,CACxC,OAAO,CAAC,GAAG,CAAC,KAAK,CAAC,EAAE,CAAC,KAAK,CAAC,WAAW,CAAC,CACxC,CAAC;IACF,IAAI,oBAAoB,KAAK,SAAS,EAAE,CAAC;QACvC,OAAO;YACL,IAAI,EAAE,UAAU;YAChB,MAAM,EAAE,2DAA2D,oBAAoB,wEAAwE;SAChK,CAAC;IACJ,CAAC;IACD,OAAO,EAAE,IAAI,EAAE,SAAS,EAAE,OAAO,EAAE,CAAC;AACtC,CAAC;AAED;;;;;;;GAOG;AACH,SAAS,YAAY,CACnB,IAA+B,EAC/B,IAA+B,EAC/B,MAAiC;IAEjC,IAAI,SAAS,CAAC,IAAI,EAAE,MAAM,CAAC,EAAE,CAAC;QAC5B,OAAO,IAAI,IAAI,QAAQ,CAAC;IAC1B,CAAC;IACD,wEAAwE;IACxE,sEAAsE;IACtE,IAAI,SAAS,CAAC,IAAI,EAAE,IAAI,CAAC,EAAE,CAAC;QAC1B,OAAO,MAAM,IAAI,QAAQ,CAAC;IAC5B,CAAC;IACD,IAAI,SAAS,CAAC,IAAI,EAAE,MAAM,CAAC,EAAE,CAAC;QAC5B,OAAO,IAAI,IAAI,QAAQ,CAAC;IAC1B,CAAC;IACD,OAAO,oBAAoB,CAAC,IAAI,EAAE,IAAI,EAAE,MAAM,CAAC,CAAC;AAClD,CAAC;AAED;;;;;;;GAOG;AACH,SAAS,oBAAoB,CAC3B,IAA+B,EAC/B,IAA+B,EAC/B,MAAiC;IAEjC,IAAI,IAAI,KAAK,SAAS,IAAI,MAAM,KAAK,SAAS,EAAE,CAAC;QAC/C,wEAAwE;QACxE,8DAA8D;QAC9D,OAAO,UAAU,CAAC;IACpB,CAAC;IACD,MAAM,IAAI,GAAG,2BAA2B,CAAC,IAAI,EAAE,IAAI,EAAE,MAAM,CAAC,CAAC;IAC7D,IAAI,IAAI,KAAK,SAAS,EAAE,CAAC;QACvB,OAAO,IAAI,CAAC;IACd,CAAC;IACD,4EAA4E;IAC5E,gFAAgF;IAChF,OAAO,SAAS,CAAC,EAAE,GAAG,IAAI,EAAE,cAAc,EAAE,MAAM,CAAC,cAAc,EAAE,EAAE,MAAM,CAAC;QAC1E,CAAC,CAAC,qBAAqB,CAAC,IAAI,EAAE,MAAM,CAAC;QACrC,CAAC,CAAC,UAAU,CAAC;AACjB,CAAC;AAED;;;;;;;;;;;;;GAaG;AACH,SAAS,2BAA2B,CAClC,IAA+B,EAC/B,IAAmB,EACnB,MAAqB;IAErB,IACE,IAAI,KAAK,SAAS;QAClB,IAAI,CAAC,EAAE,KAAK,IAAI,CAAC,EAAE;QACnB,MAAM,CAAC,EAAE,KAAK,IAAI,CAAC,EAAE;QACrB,IAAI,CAAC,WAAW,KAAK,IAAI,CAAC,WAAW;QACrC,MAAM,CAAC,WAAW,KAAK,IAAI,CAAC,WAAW;QACvC,IAAI,CAAC,WAAW,KAAK,MAAM,CAAC,WAAW,EACvC,CAAC;QACD,OAAO,SAAS,CAAC;IACnB,CAAC;IACD,MAAM,CAAC,OAAO,EAAE,MAAM,CAAC,GACrB,aAAa,CAAC,IAAI,CAAC,WAAW,EAAE,MAAM,CAAC,WAAW,CAAC,IAAI,CAAC;QACtD,CAAC,CAAC,CAAC,IAAI,EAAE,MAAM,CAAC;QAChB,CAAC,CAAC,CAAC,MAAM,EAAE,IAAI,CAAC,CAAC;IACrB,OAAO;QACL,OAAO;QACP,qBAAqB,CAAC,EAAE,GAAG,MAAM,EAAE,EAAE,EAAE,MAAM,CAAC,WAAW,EAAE,CAAC;KAC7D,CAAC;AACJ,CAAC;AAED;;;;GAIG;AACH,SAAS,aAAa,CAAC,MAAyB;IAC9C,OAAO,MAAM,CAAC,IAAI,CAAC,CAAC,KAAK,EAAE,KAAK,EAAE,EAAE,CAAC,MAAM,CAAC,OAAO,CAAC,KAAK,CAAC,KAAK,KAAK,CAAC,CAAC;AACxE,CAAC;AAED;;;;;GAKG;AACH,SAAS,aAAa,CAAC,IAAY,EAAE,KAAa;IAChD,OAAO,IAAI,KAAK,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,GAAG,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;AACpD,CAAC;AAED;;;;GAIG;AACH,SAAS,mBAAmB,CAC1B,OAAiC;IAEjC,OAAO,OAAO,CAAC,MAAM,CAA2B,CAAC,OAAO,EAAE,KAAK,EAAE,EAAE;QACjE,MAAM,SAAS,GAAG,OAAO,CAAC,SAAS,CACjC,OAAO,CAAC,EAAE,CAAC,aAAa,CAAC,KAAK,CAAC,EAAE,EAAE,OAAO,CAAC,EAAE,CAAC,GAAG,CAAC,CACnD,CAAC;QACF,OAAO,SAAS,KAAK,CAAC,CAAC;YACrB,CAAC,CAAC,CAAC,GAAG,OAAO,EAAE,KAAK,CAAC;YACrB,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,KAAK,CAAC,CAAC,EAAE,SAAS,CAAC,EAAE,KAAK,EAAE,GAAG,OAAO,CAAC,KAAK,CAAC,SAAS,CAAC,CAAC,CAAC;IAC3E,CAAC,EAAE,EAAE,CAAC,CAAC;AACT,CAAC;AAED;;;;;GAKG;AACH,SAAS,qBAAqB,CAC5B,IAAmB,EACnB,MAAqB;IAErB,OAAO,MAAM,CAAC,cAAc,GAAG,IAAI,CAAC,cAAc,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,IAAI,CAAC;AACrE,CAAC;AAED;;;;;;;;GAQG;AACH,SAAS,SAAS,CAChB,IAA+B,EAC/B,KAAgC;IAEhC,IAAI,IAAI,KAAK,SAAS,IAAI,KAAK,KAAK,SAAS,EAAE,CAAC;QAC9C,OAAO,IAAI,KAAK,SAAS,IAAI,KAAK,KAAK,SAAS,CAAC;IACnD,CAAC;IACD,OAAO,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,KAAK,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,CAAC;AACxD,CAAC;AAED;;;;;;;;;GASG;AACH,SAAS,kBAAkB,CACzB,OAAiC;IAEjC,MAAM,OAAO,GAAG,mBAAmB,CAAC,OAAO,CAAC,CAAC;IAC7C,IAAI,CAAC;QACH,oBAAoB,CAAC,OAAO,EAAE,OAAO,CAAC,MAAM,EAAE,0BAA0B,CAAC,CAAC;QAC1E,OAAO,EAAE,IAAI,EAAE,QAAQ,EAAE,OAAO,EAAE,CAAC;IACrC,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,MAAM,MAAM,GAAG,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;QACtE,OAAO;YACL,IAAI,EAAE,UAAU;YAChB,MAAM,EAAE,GAAG,MAAM,kDAAkD,kBAAkB,CAAC,UAAU,2CAA2C;SAC5I,CAAC;IACJ,CAAC;AACH,CAAC"}

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

@@ -1 +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;AAgBjC;;;;;;;;;GASG;AACH,wBAAgB,4BAA4B,CAAC,aAAa,EAAE,MAAM,GAAG,MAAM,CAI1E;AA6CD,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,CAIpC;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;AA0BD;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAsB,uBAAuB,CAC3C,WAAW,EAAE,MAAM,EACnB,KAAK,EAAE,aAAa,EACpB,MAAM,EAAE,oBAAoB,GAC3B,OAAO,CAAC,KAAK,CAAC,CAyBhB"}
+{"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;AAiBjC;;;;;;;;;GASG;AACH,wBAAgB,4BAA4B,CAAC,aAAa,EAAE,MAAM,GAAG,MAAM,CAI1E;AA6CD,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,CAIpC;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;AAoHD;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAsB,uBAAuB,CAC3C,WAAW,EAAE,MAAM,EACnB,KAAK,EAAE,aAAa,EACpB,MAAM,EAAE,oBAAoB,GAC3B,OAAO,CAAC,KAAK,CAAC,CA0BhB"}

package/dist/core/learnings-overflow.js

@@ -23,7 +23,7 @@
  * Being tracked means it has the very concurrent-writer problem the ledger just
  * had (CodySwannGT/lisa#1995), which is exactly why it reuses the ledger's
  * canonical document format verbatim: one `.gitattributes` line binds it to the
- * SAME union-by-id merge driver, `parseLearningsFile` gives it the SAME
+ * SAME id-and-fingerprint merge driver, `parseLearningsFile` gives it the SAME
  * conflict-marker guard, and `checkLearningsBudget` can gate it in CI unchanged.
  * A bespoke format would have needed all of that written a second time.
  *
@@ -49,6 +49,7 @@ import * as fse from "fs-extra";
 import * as path from "node:path";
 import { writeFileAtomically } from "../utils/atomic-file-write.js";
 import { LearningsBudgetError, assertDocumentBudget, parseLearningsFile, renderLearningsFile, } from "./learnings-document.js";
+import { validateLearningEntry } from "./learnings-entry.js";
 import { assertLearningsUnchanged, assertSafeLearningParents, readExistingLearnings, resolveSafeLearningTarget, } from "./learnings-file-safety.js";
 import { withFileTargetLock } from "./learnings-lock.js";
 import { readProjectConfig, resolveProjectLearningsFile, } from "./project-config.js";
@@ -156,6 +157,10 @@ export async function drainLearningsOverflow(projectRoot, ids) {
 async function publishOverflow(root, target, entries, preImage) {
     const rendered = renderLearningsFile(entries);
     assertDocumentBudget(rendered, entries.length, "Learnings overflow");
+    // Budget checks alone do not prove identity uniqueness or exact schema.
+    // Reparse the COMPLETE candidate while the overflow lock is held, before a
+    // temporary file can be renamed over the last known-good document.
+    parseLearningsFile(rendered);
     await fse.ensureDir(path.dirname(target));
     await writeFileAtomically(target, rendered, {
         beforeRename: async () => {
@@ -164,6 +169,69 @@ async function publishOverflow(root, target, entries, preImage) {
         },
     });
 }
+/**
+ * Resolve an incoming capture against overflow identity without losing either
+ * version. Exact byte-equivalent identity is the only idempotent case. When a
+ * distinct fingerprint arrives under an occupied stable id, the fingerprint
+ * becomes its deterministic fork id, matching the merge driver's concurrent
+ * stable-id policy. Every other id/fingerprint collision fails before publish.
+ * @param entries - Validated overflow entries read under its lock
+ * @param entry - Validated dropped capture
+ * @returns Complete candidate entries, or undefined for an exact replay
+ */
+function resolveOverflowEntries(entries, entry) {
+    const byId = entries.find(current => current.id === entry.id);
+    const byFingerprint = entries.find(current => current.fingerprint === entry.fingerprint);
+    if (byId !== undefined && byFingerprint === byId) {
+        return resolveExactOverflowReplay(byId, entry);
+    }
+    if (byFingerprint !== undefined) {
+        throw new Error(`Duplicate learning fingerprint '${entry.fingerprint}' in the overflow`);
+    }
+    if (byId === undefined) {
+        return [...entries, entry];
+    }
+    // A self-identifying version (`id === fingerprint`) owns that stable id. For
+    // two rewritten versions, the lower fingerprint owns it, exactly as in the
+    // merge driver. The rule is independent of lock-arrival order.
+    const primary = selectOverflowPrimary(byId, entry);
+    const forked = primary === byId ? entry : byId;
+    if (entries.some(current => current.id === forked.fingerprint)) {
+        throw new Error(`Cannot preserve learning '${entry.id}': deterministic fork id '${forked.fingerprint}' already exists in the overflow`);
+    }
+    const rekeyed = validateLearningEntry({
+        ...forked,
+        id: forked.fingerprint,
+    });
+    return entries.flatMap(current => current === byId ? [primary, rekeyed] : [current]);
+}
+/**
+ * Accept only a byte-identical replay of one occupied id/fingerprint pair.
+ * @param current - Existing overflow identity
+ * @param incoming - Incoming entry with the same id and fingerprint
+ * @returns Undefined for an exact idempotent replay
+ */
+function resolveExactOverflowReplay(current, incoming) {
+    if (JSON.stringify(current) === JSON.stringify(incoming)) {
+        return undefined;
+    }
+    throw new Error(`Duplicate learning identity '${incoming.id}' has different content in the overflow`);
+}
+/**
+ * Pick the version that owns a colliding stable id independently of arrival.
+ * @param current - Version already in the overflow
+ * @param incoming - Distinct version arriving under the same id
+ * @returns Stable-id owner
+ */
+function selectOverflowPrimary(current, incoming) {
+    if (current.id === current.fingerprint) {
+        return current;
+    }
+    if (incoming.id === incoming.fingerprint) {
+        return incoming;
+    }
+    return incoming.fingerprint < current.fingerprint ? incoming : current;
+}
 /**
  * Preserve a capture the ledger had no budget for, then re-raise the breach.
  *
@@ -188,11 +256,12 @@ export async function preserveDroppedLearning(projectRoot, entry, breach) {
         // Re-establish containment after the lock wait; see drainLearningsOverflow.
         await assertSafeLearningParents(root, path.dirname(target));
         const { entries, image } = await readOverflowEntries(target);
-        if (entries.some(current => current.id === entry.id)) {
+        const next = resolveOverflowEntries(entries, entry);
+        if (next === undefined) {
             return true;
         }
         try {
-            await publishOverflow(root, target, [...entries, entry], image);
+            await publishOverflow(root, target, next, image);
             return true;
         }
         catch (error) {

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

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

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

@@ -0,0 +1,56 @@
+/**
+ * @file learnings-supersede.ts
+ * @description Plans exact stamped supersedes without mutating shared state
+ * @module core/learnings-supersede
+ */
+import { type LearningEntry } from "./learnings-contract.js";
+/** Exact identity and content version a caller observed before consolidation. */
+export interface LearningEntryStamp {
+    /** Stable public identity expected in the locked ledger. */
+    readonly id: string;
+    /** Content fingerprint expected at that identity. */
+    readonly fingerprint: string;
+}
+/** Why an observed supersede stamp no longer authorizes replacement. */
+export type StaleSupersedeReason = "absent" | "fingerprint-mismatch";
+/** One target whose locked state differs from the caller's snapshot. */
+export interface StaleSupersedeTarget {
+    /** Exact identity and fingerprint the caller observed. */
+    readonly expected: LearningEntryStamp;
+    /** Current fingerprint; absent when the identity no longer exists. */
+    readonly actualFingerprint?: string;
+    /** Whether the identity disappeared or now names different content. */
+    readonly reason: StaleSupersedeReason;
+}
+/** Immutable plan produced from the state read inside the writer lock. */
+export interface LearningSupersedePlan {
+    /** Entry to append or replace, carrying the stable primary id when exact. */
+    readonly entry: LearningEntry;
+    /** Existing entries retained byte-for-byte. */
+    readonly retained: readonly LearningEntry[];
+    /** Exact targets removed together; empty on any stale target. */
+    readonly removed: readonly LearningEntry[];
+    /** Stale targets that forced a safe append instead of replacement. */
+    readonly stale: readonly StaleSupersedeTarget[];
+}
+/**
+ * Validate caller-supplied version stamps before any filesystem work.
+ * @param stamps - Possibly untrusted supersede option
+ * @returns Frozen, id-unique stamps in caller order
+ */
+export declare function validateLearningEntryStamps(stamps: readonly LearningEntryStamp[] | undefined): readonly LearningEntryStamp[];
+/**
+ * Plan an all-or-nothing stamped replacement against locked current state.
+ *
+ * Fingerprint collision is checked first because it is the durable dedupe
+ * boundary. An exact target set is removed together and the lexicographically
+ * first target id becomes the stable primary. Any missing or changed target
+ * makes the whole request a safe append: no target is removed and no alias is
+ * claimed.
+ * @param entries - Current validated entries read inside the lock
+ * @param candidate - New validated content composed by the caller
+ * @param expected - Validated version stamps from the caller's snapshot
+ * @returns Deterministic append-or-replace plan
+ */
+export declare function planLearningSupersede(entries: readonly LearningEntry[], candidate: LearningEntry, expected: readonly LearningEntryStamp[]): LearningSupersedePlan;
+//# sourceMappingURL=learnings-supersede.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"learnings-supersede.d.ts","sourceRoot":"","sources":["../../src/core/learnings-supersede.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,OAAO,EAGL,KAAK,aAAa,EACnB,MAAM,yBAAyB,CAAC;AAOjC,iFAAiF;AACjF,MAAM,WAAW,kBAAkB;IACjC,4DAA4D;IAC5D,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,qDAAqD;IACrD,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;CAC9B;AAED,wEAAwE;AACxE,MAAM,MAAM,oBAAoB,GAAG,QAAQ,GAAG,sBAAsB,CAAC;AAErE,wEAAwE;AACxE,MAAM,WAAW,oBAAoB;IACnC,0DAA0D;IAC1D,QAAQ,CAAC,QAAQ,EAAE,kBAAkB,CAAC;IACtC,sEAAsE;IACtE,QAAQ,CAAC,iBAAiB,CAAC,EAAE,MAAM,CAAC;IACpC,uEAAuE;IACvE,QAAQ,CAAC,MAAM,EAAE,oBAAoB,CAAC;CACvC;AAED,0EAA0E;AAC1E,MAAM,WAAW,qBAAqB;IACpC,6EAA6E;IAC7E,QAAQ,CAAC,KAAK,EAAE,aAAa,CAAC;IAC9B,+CAA+C;IAC/C,QAAQ,CAAC,QAAQ,EAAE,SAAS,aAAa,EAAE,CAAC;IAC5C,iEAAiE;IACjE,QAAQ,CAAC,OAAO,EAAE,SAAS,aAAa,EAAE,CAAC;IAC3C,sEAAsE;IACtE,QAAQ,CAAC,KAAK,EAAE,SAAS,oBAAoB,EAAE,CAAC;CACjD;AAED;;;;GAIG;AACH,wBAAgB,2BAA2B,CACzC,MAAM,EAAE,SAAS,kBAAkB,EAAE,GAAG,SAAS,GAChD,SAAS,kBAAkB,EAAE,CAc/B;AAuDD;;;;;;;;;;;;GAYG;AACH,wBAAgB,qBAAqB,CACnC,OAAO,EAAE,SAAS,aAAa,EAAE,EACjC,SAAS,EAAE,aAAa,EACxB,QAAQ,EAAE,SAAS,kBAAkB,EAAE,GACtC,qBAAqB,CAgCvB"}

package/dist/core/learnings-supersede.js

@@ -0,0 +1,199 @@
+/**
+ * @file learnings-supersede.ts
+ * @description Plans exact stamped supersedes without mutating shared state
+ * @module core/learnings-supersede
+ */
+import { LEARNINGS_CONTRACT, MAX_STABLE_TOKEN_BYTES, } from "./learnings-contract.js";
+import { validateLearningEntry } from "./learnings-entry.js";
+const STABLE_TOKEN = /^[a-z0-9]+(?:[._-][a-z0-9]+)*$/;
+const EXACT_STAMP_ERROR = "Invalid supersede stamp: expected exactly {id, fingerprint}";
+/**
+ * Validate caller-supplied version stamps before any filesystem work.
+ * @param stamps - Possibly untrusted supersede option
+ * @returns Frozen, id-unique stamps in caller order
+ */
+export function validateLearningEntryStamps(stamps) {
+    if (stamps === undefined) {
+        return [];
+    }
+    if (!Array.isArray(stamps)) {
+        throw new Error("Invalid supersede option: expected learning {id, fingerprint} stamps");
+    }
+    const validated = validateStampArray(stamps);
+    if (new Set(validated.map(stamp => stamp.id)).size !== validated.length) {
+        throw new Error("Invalid supersede option: duplicate stamped ids");
+    }
+    return Object.freeze(validated);
+}
+/**
+ * Read a dense, expando-free supersede array entirely through own descriptors.
+ * Native iteration methods invoke indexed getters and skip sparse holes, which
+ * lets hostile containers change the target set while validation is running.
+ * The ledger cap bounds descriptor traversal before any member is inspected.
+ * @param stamps - Array already established by Array.isArray
+ * @returns Frozen validated stamps in exact index order
+ */
+function validateStampArray(stamps) {
+    const lengthDescriptor = Object.getOwnPropertyDescriptor(stamps, "length");
+    if (lengthDescriptor === undefined ||
+        !("value" in lengthDescriptor) ||
+        typeof lengthDescriptor.value !== "number" ||
+        !Number.isSafeInteger(lengthDescriptor.value) ||
+        lengthDescriptor.value < 0) {
+        throw new Error("Invalid supersede array: expected a dense array");
+    }
+    const length = lengthDescriptor.value;
+    if (length > LEARNINGS_CONTRACT.maxEntries) {
+        throw new Error(`Invalid supersede array exceeds maxEntries ${LEARNINGS_CONTRACT.maxEntries}`);
+    }
+    const expectedKeys = new Set([
+        "length",
+        ...Array.from({ length }, (_unused, index) => String(index)),
+    ]);
+    const ownKeys = Reflect.ownKeys(stamps);
+    if (ownKeys.length !== expectedKeys.size ||
+        ownKeys.some(key => typeof key !== "string" || !expectedKeys.has(key))) {
+        throw new Error("Invalid supersede array: expected dense indexed values without extra or symbol fields");
+    }
+    return Object.freeze(Array.from({ length }, (_unused, index) => {
+        const descriptor = Object.getOwnPropertyDescriptor(stamps, String(index));
+        if (descriptor === undefined || !("value" in descriptor)) {
+            throw new Error("Invalid supersede array: indexed accessors are not allowed");
+        }
+        return validateStamp(descriptor.value);
+    }));
+}
+/**
+ * Plan an all-or-nothing stamped replacement against locked current state.
+ *
+ * Fingerprint collision is checked first because it is the durable dedupe
+ * boundary. An exact target set is removed together and the lexicographically
+ * first target id becomes the stable primary. Any missing or changed target
+ * makes the whole request a safe append: no target is removed and no alias is
+ * claimed.
+ * @param entries - Current validated entries read inside the lock
+ * @param candidate - New validated content composed by the caller
+ * @param expected - Validated version stamps from the caller's snapshot
+ * @returns Deterministic append-or-replace plan
+ */
+export function planLearningSupersede(entries, candidate, expected) {
+    const stale = expected.flatMap(stamp => staleTarget(entries, stamp));
+    const targetIds = new Set(expected.map(stamp => stamp.id));
+    const removed = sortLearningEntries(entries.filter(entry => targetIds.has(entry.id)));
+    const primary = removed[0];
+    const retained = entries.filter(entry => !targetIds.has(entry.id));
+    if (entries.some(entry => entry.fingerprint === candidate.fingerprint)) {
+        throw new Error(`Duplicate learning fingerprint: ${candidate.fingerprint}`);
+    }
+    if (stale.length > 0 || expected.length === 0) {
+        if (entries.some(entry => entry.id === candidate.id)) {
+            throw new Error(`Duplicate learning id: ${candidate.id}`);
+        }
+        return {
+            entry: candidate,
+            retained: entries,
+            removed: [],
+            stale,
+        };
+    }
+    if (primary === undefined) {
+        throw new Error("Invalid supersede plan: exact target set was empty");
+    }
+    return {
+        entry: validateLearningEntry({ ...candidate, id: primary.id }),
+        retained,
+        removed,
+        stale: [],
+    };
+}
+/**
+ * Validate one inert, exact two-field stamp.
+ * @param candidate - Untrusted stamp value
+ * @returns Frozen exact stamp
+ */
+function validateStamp(candidate) {
+    if (candidate === null ||
+        typeof candidate !== "object" ||
+        Array.isArray(candidate)) {
+        throw new Error(EXACT_STAMP_ERROR);
+    }
+    const keys = Reflect.ownKeys(candidate);
+    if (keys.length !== 2 ||
+        keys.some(key => typeof key !== "string" || (key !== "id" && key !== "fingerprint")) ||
+        !Object.hasOwn(candidate, "id") ||
+        !Object.hasOwn(candidate, "fingerprint")) {
+        throw new Error(EXACT_STAMP_ERROR);
+    }
+    const idDescriptor = Object.getOwnPropertyDescriptor(candidate, "id");
+    const fingerprintDescriptor = Object.getOwnPropertyDescriptor(candidate, "fingerprint");
+    if (idDescriptor === undefined || fingerprintDescriptor === undefined) {
+        throw new Error(EXACT_STAMP_ERROR);
+    }
+    const id = readStampToken(idDescriptor, "id");
+    const fingerprint = readStampToken(fingerprintDescriptor, "fingerprint");
+    return Object.freeze({ id, fingerprint });
+}
+/**
+ * Read one accessor-free stable token from a stamp descriptor.
+ * @param descriptor - Own field descriptor
+ * @param field - Stamp field being validated
+ * @returns Validated stable token
+ */
+function readStampToken(descriptor, field) {
+    if (!("value" in descriptor) || typeof descriptor.value !== "string") {
+        throw new Error(`Invalid supersede stamp ${field}: expected a data string`);
+    }
+    const value = descriptor.value;
+    if (Buffer.byteLength(value, "utf8") > MAX_STABLE_TOKEN_BYTES) {
+        throw new Error(`Invalid supersede stamp ${field}: ${field} exceeds max stable token bytes ${MAX_STABLE_TOKEN_BYTES}`);
+    }
+    if (value.trim() !== value || !STABLE_TOKEN.test(value)) {
+        throw new Error(`Invalid supersede stamp ${field}: expected a stable token`);
+    }
+    return value;
+}
+/**
+ * Describe a target that no longer matches its exact stamp.
+ * @param entries - Current entries inside the writer lock
+ * @param expected - Caller-observed target stamp
+ * @returns Empty for an exact match, otherwise one stale diagnosis
+ */
+function staleTarget(entries, expected) {
+    const actual = entries.find(entry => entry.id === expected.id);
+    if (actual === undefined) {
+        return [{ expected, reason: "absent" }];
+    }
+    if (actual.fingerprint !== expected.fingerprint) {
+        return [
+            {
+                expected,
+                actualFingerprint: actual.fingerprint,
+                reason: "fingerprint-mismatch",
+            },
+        ];
+    }
+    return [];
+}
+/**
+ * Compare tokens for locale-independent primary selection.
+ * @param left - First token
+ * @param right - Second token
+ * @returns Negative, zero, or positive ordering result
+ */
+function compareTokens(left, right) {
+    return left === right ? 0 : left < right ? -1 : 1;
+}
+/**
+ * Sort entries by stable id without mutating shared state.
+ * @param entries - Entries in arbitrary order
+ * @returns New deterministically ordered array
+ */
+function sortLearningEntries(entries) {
+    return entries.reduce((ordered, entry) => {
+        const insertion = ordered.findIndex(current => compareTokens(entry.id, current.id) < 0);
+        return insertion === -1
+            ? [...ordered, entry]
+            : [...ordered.slice(0, insertion), entry, ...ordered.slice(insertion)];
+    }, []);
+}
+//# sourceMappingURL=learnings-supersede.js.map

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

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

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

@@ -1,11 +1,13 @@
+import { type LearningEntryStamp, type StaleSupersedeTarget } from "./learnings-supersede.js";
 /** Write-time consolidation options for {@link persistConsolidatedLearning}. */
 export interface ConsolidatedLearningOptions {
-    /** Ids of existing entries the new entry merges or replaces. */
-    readonly supersede?: readonly string[];
+    /** Exact versions of existing entries the new entry merges or replaces. */
+    readonly supersede?: readonly LearningEntryStamp[];
+    /** Called when any target no longer matches its observed version stamp. */
+    readonly onStaleSupersede?: (targets: readonly StaleSupersedeTarget[]) => void;
     /**
-     * Called when a supersede target was already absent at write time — almost
-     * always because a concurrent pass consolidated it first. The write still
-     * succeeds; this is a diagnostic, not a failure hook.
+     * Compatibility diagnostic for targets that are absent (not merely changed).
+     * @deprecated Use {@link onStaleSupersede}, which distinguishes both cases.
      */
     readonly onAbsentSupersede?: (ids: readonly string[]) => void;
     /**
@@ -21,7 +23,7 @@ export interface ConsolidatedLearningOptions {
  * entry point; consolidation-aware writers use
  * {@link persistConsolidatedLearning} instead.
  * @param projectRoot - Absolute path to the host project root
- * @param candidate - Untrusted seven-field learning entry
+ * @param candidate - Untrusted eight-field learning entry
  * @returns Absolute path to the persisted learnings file
  */
 export declare function persistLearningEntry(projectRoot: string, candidate: unknown): Promise<string>;
@@ -34,7 +36,7 @@ export declare function persistLearningEntry(projectRoot: string, candidate: unk
  * consolidation. Without `supersede` this is exactly the append-only
  * {@link persistLearningEntry} behavior, including the duplicate-id throw.
  * @param projectRoot - Absolute path to the host project root
- * @param candidate - Untrusted seven-field learning entry
+ * @param candidate - Untrusted eight-field learning entry
  * @param options - Optional consolidation directives
  * @returns Absolute path to the persisted learnings file
  */