@codyswann/lisa 2.298.1 → 2.299.1

package/dist/core/learnings-overflow.js

@@ -0,0 +1,212 @@
+/**
+ * Durable holding area for learnings the ledger had no budget to accept.
+ *
+ * ## Why this exists
+ *
+ * When a judged-durable capture cannot fit the ledger's hard caps, the writer
+ * drops it. Before this module the dropped CONTENT survived only in the capture
+ * report's text, so once that scrolled away a genuinely valuable learning was
+ * gone and the gardener had nothing to drain (CodySwannGT/lisa#1996).
+ * CodySwannGT/lisa#1959 raised the byte budget and added the
+ * `[lisa-ledger-saturated]` tracker signal — the signal says "saturated"; this
+ * file says "and here is exactly what was dropped".
+ *
+ * ## Why it is git-tracked, in the ledger's own format
+ *
+ * A learner pass runs on its own `learning/<fingerprint>` branch in its own
+ * worktree, and those worktrees are disposable. An untracked, machine-local
+ * overflow would be deleted by ordinary worktree cleanup before any gardener
+ * saw it — durable in name only, and invisible to a gardener running anywhere
+ * else. So the overflow ships to `main` on the same pull request as the capture
+ * that produced it.
+ *
+ * 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
+ * conflict-marker guard, and `checkLearningsBudget` can gate it in CI unchanged.
+ * A bespoke format would have needed all of that written a second time.
+ *
+ * ## Why it carries the same budget
+ *
+ * The overflow is a hand-off buffer the gardener drains, not an archive. Letting
+ * it grow without bound would relocate the very context-bloat problem the
+ * contract exists to prevent, and a repository file that only ever grows is its
+ * own incident. So it is capped exactly like the ledger, nothing is ever
+ * silently evicted from it, and an overflow that is itself full surfaces as a
+ * loud failure naming both surfaces.
+ *
+ * ## Lock discipline
+ *
+ * The ledger lock and the overflow lock are NEVER held at the same time. The
+ * writer's ledger transaction fails and fully releases its lock before
+ * {@link preserveDroppedLearning} takes the overflow lock, so the two paths are
+ * strictly sequential and the pair cannot deadlock regardless of acquisition
+ * order between processes.
+ * @module core/learnings-overflow
+ */
+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 { assertSafeLearningParents, readExistingLearnings, resolveSafeLearningTarget, } from "./learnings-file-safety.js";
+import { withFileTargetLock } from "./learnings-lock.js";
+import { readProjectConfig, resolveProjectLearningsFile, } from "./project-config.js";
+/** Suffix distinguishing the overflow from the ledger it belongs to. */
+const OVERFLOW_SUFFIX = ".overflow";
+/**
+ * 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 function resolveLearningsOverflowFile(learningsFile) {
+    const extension = path.posix.extname(learningsFile);
+    const base = learningsFile.slice(0, learningsFile.length - extension.length);
+    return `${base}${OVERFLOW_SUFFIX}${extension}`;
+}
+/**
+ * Resolve and contain the overflow target for one project.
+ * @param projectRoot - Absolute path to the host project root
+ * @returns Resolved project root and absolute overflow path
+ */
+async function resolveOverflowTarget(projectRoot) {
+    const config = await readProjectConfig(projectRoot);
+    const relative = resolveLearningsOverflowFile(resolveProjectLearningsFile(config));
+    return resolveSafeLearningTarget(projectRoot, relative);
+}
+/**
+ * Read the entries currently held in the overflow.
+ * @param target - Absolute overflow path
+ * @returns Validated entries, empty when the file does not exist
+ */
+async function readOverflowEntries(target) {
+    const existing = await readExistingLearnings(target);
+    return existing === undefined ? [] : parseLearningsFile(existing);
+}
+/**
+ * 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 async function readLearningsOverflow(projectRoot) {
+    const { target } = await resolveOverflowTarget(projectRoot);
+    return { file: target, entries: await readOverflowEntries(target) };
+}
+/**
+ * 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 async function drainLearningsOverflow(projectRoot, ids) {
+    const requested = new Set(validateOverflowIds(ids));
+    const { root, target } = await resolveOverflowTarget(projectRoot);
+    await assertSafeLearningParents(root, path.dirname(target));
+    return withFileTargetLock(target, async () => {
+        // The pre-lock check can go stale while waiting on the lock, so the
+        // containment guarantee has to be re-established once the read is
+        // actually about to happen. Same discipline as the ledger writer.
+        await assertSafeLearningParents(root, path.dirname(target));
+        const entries = await readOverflowEntries(target);
+        const drained = entries
+            .filter(entry => requested.has(entry.id))
+            .map(entry => entry.id);
+        const retained = entries.filter(entry => !requested.has(entry.id));
+        if (drained.length > 0) {
+            await publishOverflow(root, target, retained);
+        }
+        return {
+            file: target,
+            drained,
+            absent: [...requested].filter(id => !drained.includes(id)),
+            remaining: retained.length,
+        };
+    });
+}
+/**
+ * Render, budget-check, and atomically publish the overflow document.
+ * @param root - Resolved project root
+ * @param target - Absolute overflow path
+ * @param entries - Entries the overflow should now hold
+ */
+async function publishOverflow(root, target, entries) {
+    const rendered = renderLearningsFile(entries);
+    assertDocumentBudget(rendered, entries.length, "Learnings overflow");
+    await fse.ensureDir(path.dirname(target));
+    await writeFileAtomically(target, rendered, {
+        beforeRename: () => assertSafeLearningParents(root, path.dirname(target)),
+    });
+}
+/**
+ * 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 async function preserveDroppedLearning(projectRoot, entry, breach) {
+    const { root, target } = await resolveOverflowTarget(projectRoot);
+    await assertSafeLearningParents(root, path.dirname(target));
+    const preserved = await withFileTargetLock(target, async () => {
+        // Re-establish containment after the lock wait; see drainLearningsOverflow.
+        await assertSafeLearningParents(root, path.dirname(target));
+        const entries = await readOverflowEntries(target);
+        if (entries.some(current => current.id === entry.id)) {
+            return true;
+        }
+        try {
+            await publishOverflow(root, target, [...entries, entry]);
+            return true;
+        }
+        catch (error) {
+            if (error instanceof LearningsBudgetError) {
+                return false;
+            }
+            throw error;
+        }
+    });
+    throw new LearningsBudgetError(preserved
+        ? `${breach.message} — the capture was preserved in ${target}; drain it with \`lisa learnings-overflow\` (the gardener does this automatically)`
+        : `${breach.message} — the overflow at ${target} is full too, so the capture could not be preserved; drain the overflow, then promote or retire a learning`);
+}
+/**
+ * Reject malformed drain directives before any filesystem work.
+ * @param ids - Caller-supplied (possibly untrusted) entry ids
+ * @returns Deduplicated list of validated ids
+ */
+function validateOverflowIds(ids) {
+    if (!Array.isArray(ids) ||
+        ids.some(id => typeof id !== "string" || id.trim() === "")) {
+        throw new Error("Invalid overflow drain ids: expected non-empty learning id strings");
+    }
+    return [...new Set(ids)];
+}
+//# sourceMappingURL=learnings-overflow.js.map

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

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

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

@@ -8,6 +8,12 @@ export interface ConsolidatedLearningOptions {
      * succeeds; this is a diagnostic, not a failure hook.
      */
     readonly onAbsentSupersede?: (ids: readonly string[]) => void;
+    /**
+     * Called when a `supersedes:` alias reference did not fit inside the entry's
+     * provenance cap and was dropped. A reference that is about to stop resolving
+     * must never disappear silently; the write still succeeds.
+     */
+    readonly onAliasesDropped?: (references: readonly string[]) => void;
 }
 /**
  * Persist one already-selected learning without generating or truncating it.

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

@@ -1 +1 @@
-{"version":3,"file":"learnings-writer.d.ts","sourceRoot":"","sources":["../../src/core/learnings-writer.ts"],"names":[],"mappings":"AAsBA,gFAAgF;AAChF,MAAM,WAAW,2BAA2B;IAC1C,gEAAgE;IAChE,QAAQ,CAAC,SAAS,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IACvC;;;;OAIG;IACH,QAAQ,CAAC,iBAAiB,CAAC,EAAE,CAAC,GAAG,EAAE,SAAS,MAAM,EAAE,KAAK,IAAI,CAAC;CAC/D;AAED;;;;;;;;GAQG;AACH,wBAAsB,oBAAoB,CACxC,WAAW,EAAE,MAAM,EACnB,SAAS,EAAE,OAAO,GACjB,OAAO,CAAC,MAAM,CAAC,CAEjB;AAED;;;;;;;;;;;;GAYG;AACH,wBAAsB,2BAA2B,CAC/C,WAAW,EAAE,MAAM,EACnB,SAAS,EAAE,OAAO,EAClB,OAAO,GAAE,2BAAgC,GACxC,OAAO,CAAC,MAAM,CAAC,CAiBjB;AAkCD,2DAA2D;AAC3D,MAAM,MAAM,qBAAqB,GAAG,WAAW,GAAG,WAAW,GAAG,WAAW,CAAC;AAE5E,uEAAuE;AACvE,MAAM,WAAW,qBAAqB;IACpC,8EAA8E;IAC9E,QAAQ,CAAC,MAAM,EAAE,qBAAqB,CAAC;IACvC,gDAAgD;IAChD,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB;;;;OAIG;IACH,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IACvB,mEAAmE;IACnE,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;CAC5B;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAsB,oBAAoB,CACxC,WAAW,EAAE,MAAM,EACnB,EAAE,EAAE,MAAM,EACV,IAAI,EAAE,MAAM,GACX,OAAO,CAAC,qBAAqB,CAAC,CA2ChC;AAED,OAAO,EACL,kBAAkB,EAClB,mBAAmB,GACpB,MAAM,yBAAyB,CAAC;AACjC,OAAO,EAAE,qBAAqB,EAAE,MAAM,sBAAsB,CAAC"}
+{"version":3,"file":"learnings-writer.d.ts","sourceRoot":"","sources":["../../src/core/learnings-writer.ts"],"names":[],"mappings":"AA4BA,gFAAgF;AAChF,MAAM,WAAW,2BAA2B;IAC1C,gEAAgE;IAChE,QAAQ,CAAC,SAAS,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IACvC;;;;OAIG;IACH,QAAQ,CAAC,iBAAiB,CAAC,EAAE,CAAC,GAAG,EAAE,SAAS,MAAM,EAAE,KAAK,IAAI,CAAC;IAC9D;;;;OAIG;IACH,QAAQ,CAAC,gBAAgB,CAAC,EAAE,CAAC,UAAU,EAAE,SAAS,MAAM,EAAE,KAAK,IAAI,CAAC;CACrE;AAED;;;;;;;;GAQG;AACH,wBAAsB,oBAAoB,CACxC,WAAW,EAAE,MAAM,EACnB,SAAS,EAAE,OAAO,GACjB,OAAO,CAAC,MAAM,CAAC,CAEjB;AAED;;;;;;;;;;;;GAYG;AACH,wBAAsB,2BAA2B,CAC/C,WAAW,EAAE,MAAM,EACnB,SAAS,EAAE,OAAO,EAClB,OAAO,GAAE,2BAAgC,GACxC,OAAO,CAAC,MAAM,CAAC,CA8BjB;AAsED,2DAA2D;AAC3D,MAAM,MAAM,qBAAqB,GAAG,WAAW,GAAG,WAAW,GAAG,WAAW,CAAC;AAE5E,uEAAuE;AACvE,MAAM,WAAW,qBAAqB;IACpC,8EAA8E;IAC9E,QAAQ,CAAC,MAAM,EAAE,qBAAqB,CAAC;IACvC,gDAAgD;IAChD,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB;;;;OAIG;IACH,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IACvB,mEAAmE;IACnE,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;CAC5B;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAsB,oBAAoB,CACxC,WAAW,EAAE,MAAM,EACnB,EAAE,EAAE,MAAM,EACV,IAAI,EAAE,MAAM,GACX,OAAO,CAAC,qBAAqB,CAAC,CA2ChC;AAED,OAAO,EACL,kBAAkB,EAClB,mBAAmB,GACpB,MAAM,yBAAyB,CAAC;AACjC,OAAO,EAAE,qBAAqB,EAAE,MAAM,sBAAsB,CAAC"}

package/dist/core/learnings-writer.js

@@ -2,10 +2,12 @@
 import * as fse from "fs-extra";
 import * as path from "node:path";
 import { writeFileAtomically } from "../utils/atomic-file-write.js";
-import { assertDocumentBudget, parseLearningsFile, renderLearningsFile, } from "./learnings-document.js";
+import { applySupersedeAliases, findCallerMintedAliasError, } from "./learnings-alias.js";
+import { LearningsBudgetError, assertDocumentBudget, parseLearningsFile, renderLearningsFile, } from "./learnings-document.js";
 import { requireIsoDate, validateLearningEntry } from "./learnings-entry.js";
 import { assertSafeLearningParents, readExistingLearnings, resolveSafeLearningTarget, } from "./learnings-file-safety.js";
 import { withLearningTargetLock } from "./learnings-lock.js";
+import { preserveDroppedLearning } from "./learnings-overflow.js";
 import { readProjectConfig, resolveProjectLearningsFile, } from "./project-config.js";
 /**
  * Persist one already-selected learning without generating or truncating it.
@@ -34,6 +36,10 @@ export async function persistLearningEntry(projectRoot, candidate) {
  */
 export async function persistConsolidatedLearning(projectRoot, candidate, options = {}) {
     const entry = validateLearningEntry(candidate);
+    const mintedAlias = findCallerMintedAliasError(entry);
+    if (mintedAlias !== undefined) {
+        throw mintedAlias;
+    }
     const supersede = validateSupersedeIds(options.supersede);
     const config = await readProjectConfig(projectRoot);
     const relativeFile = resolveProjectLearningsFile(config);
@@ -42,32 +48,75 @@ export async function persistConsolidatedLearning(projectRoot, candidate, option
     buildNextDocument([], entry, []);
     await assertSafeLearningParents(root, path.dirname(target));
     await fse.ensureDir(path.dirname(target));
-    return writeLearningEntriesWithLock(root, target, entry, supersede, options.onAbsentSupersede);
+    try {
+        return await writeLearningEntriesWithLock({ root, target }, entry, supersede, options);
+    }
+    catch (error) {
+        if (!(error instanceof LearningsBudgetError)) {
+            throw error;
+        }
+        // The ledger lock is fully released by now — `withLearningTargetLock`
+        // releases in a `finally` — so the overflow lock below is taken with no
+        // other learnings lock held. The two are never nested.
+        return preserveDroppedLearning(projectRoot, entry, error);
+    }
 }
 /**
  * Perform the locked read-validate-write transaction for a learnings update.
- * @param root - Resolved project root
- * @param target - Absolute learnings file path
+ * @param location - Resolved project root and absolute learnings file path
+ * @param location.root - Resolved project root
+ * @param location.target - Absolute learnings file path
  * @param entry - New validated entry
  * @param supersede - Ids of existing entries the new entry replaces
- * @param onAbsentSupersede - Diagnostic sink for already-consolidated targets
+ * @param options - Caller diagnostics for absent targets and dropped aliases
  * @returns Absolute path to the persisted learnings file
  */
-function writeLearningEntriesWithLock(root, target, entry, supersede, onAbsentSupersede) {
+function writeLearningEntriesWithLock({ root, target }, entry, supersede, options) {
     return withLearningTargetLock(target, async () => {
         await assertSafeLearningParents(root, path.dirname(target));
         const existing = await readExistingLearnings(target);
         const entries = existing === undefined ? [] : parseLearningsFile(existing);
         const absent = supersede.filter(id => !entries.some(current => current.id === id));
         if (absent.length > 0)
-            onAbsentSupersede?.(absent);
-        const rendered = buildNextDocument(entries, entry, supersede);
+            options.onAbsentSupersede?.(absent);
+        const aliased = aliasSupersededEntries(entries, entry, supersede, options);
+        const rendered = buildNextDocument(entries, aliased, supersede);
         await writeFileAtomically(target, rendered, {
             beforeRename: () => assertSafeLearningParents(root, path.dirname(target)),
         });
         return target;
     });
 }
+/**
+ * Record, in the new entry's provenance, which entries this write replaced.
+ *
+ * Only targets that are genuinely PRESENT contribute an alias. A supersede
+ * naming an already-consolidated id removed nothing, so claiming its reference
+ * would hijack a pointer the earlier writer legitimately owns — see
+ * `learnings-alias.ts` for why that distinction is what keeps the #1995
+ * losing-writer guarantee intact.
+ *
+ * The rewritten entry is pushed back through `validateLearningEntry` rather than
+ * spread-and-trusted, so the added references are held to the same schema as any
+ * caller-supplied one and the persisted object stays a frozen, exactly-seven-field
+ * entry.
+ * @param entries - Entries currently in the document
+ * @param entry - New validated entry as the caller composed it
+ * @param supersede - Validated supersede ids
+ * @param options - Caller diagnostics
+ * @returns The entry to persist, carrying its supersede aliases
+ */
+function aliasSupersededEntries(entries, entry, supersede, options) {
+    const superseded = new Set(supersede);
+    const removed = entries.filter(current => superseded.has(current.id));
+    if (removed.length === 0) {
+        return entry;
+    }
+    const aliased = applySupersedeAliases(entry, removed);
+    if (aliased.dropped.length > 0)
+        options.onAliasesDropped?.(aliased.dropped);
+    return validateLearningEntry({ ...entry, provenance: aliased.provenance });
+}
 /**
  * Surgically advance ONLY one entry's `last_confirmed` timestamp — the
  * claim-time "this rule demonstrably applied" confirmation (#1579). Uses the

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

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

package/dist/core/learnings.d.ts

@@ -1,4 +1,6 @@
+export * from "./learnings-alias.js";
 export * from "./learnings-contract.js";
+export * from "./learnings-overflow.js";
 export * from "./learnings-projection.js";
 export * from "./learnings-writer.js";
 export * from "./upstream-attribution-body.js";

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

@@ -1 +1 @@
-{"version":3,"file":"learnings.d.ts","sourceRoot":"","sources":["../../src/core/learnings.ts"],"names":[],"mappings":"AAAA,cAAc,yBAAyB,CAAC;AACxC,cAAc,2BAA2B,CAAC;AAC1C,cAAc,uBAAuB,CAAC;AACtC,cAAc,gCAAgC,CAAC;AAC/C,OAAO,EACL,8BAA8B,EAC9B,0BAA0B,EAC1B,0BAA0B,EAC1B,iBAAiB,EACjB,iCAAiC,EACjC,2BAA2B,EAC3B,uBAAuB,EACvB,KAAK,eAAe,EACpB,KAAK,aAAa,GACnB,MAAM,qBAAqB,CAAC"}
+{"version":3,"file":"learnings.d.ts","sourceRoot":"","sources":["../../src/core/learnings.ts"],"names":[],"mappings":"AAAA,cAAc,sBAAsB,CAAC;AACrC,cAAc,yBAAyB,CAAC;AACxC,cAAc,yBAAyB,CAAC;AACxC,cAAc,2BAA2B,CAAC;AAC1C,cAAc,uBAAuB,CAAC;AACtC,cAAc,gCAAgC,CAAC;AAC/C,OAAO,EACL,8BAA8B,EAC9B,0BAA0B,EAC1B,0BAA0B,EAC1B,iBAAiB,EACjB,iCAAiC,EACjC,2BAA2B,EAC3B,uBAAuB,EACvB,KAAK,eAAe,EACpB,KAAK,aAAa,GACnB,MAAM,qBAAqB,CAAC"}

package/dist/core/learnings.js

@@ -1,4 +1,6 @@
+export * from "./learnings-alias.js";
 export * from "./learnings-contract.js";
+export * from "./learnings-overflow.js";
 export * from "./learnings-projection.js";
 export * from "./learnings-writer.js";
 export * from "./upstream-attribution-body.js";

package/dist/core/learnings.js.map

@@ -1 +1 @@
-{"version":3,"file":"learnings.js","sourceRoot":"","sources":["../../src/core/learnings.ts"],"names":[],"mappings":"AAAA,cAAc,yBAAyB,CAAC;AACxC,cAAc,2BAA2B,CAAC;AAC1C,cAAc,uBAAuB,CAAC;AACtC,cAAc,gCAAgC,CAAC;AAC/C,OAAO,EACL,8BAA8B,EAC9B,0BAA0B,EAC1B,0BAA0B,EAC1B,iBAAiB,EACjB,iCAAiC,EACjC,2BAA2B,EAC3B,uBAAuB,GAGxB,MAAM,qBAAqB,CAAC"}
+{"version":3,"file":"learnings.js","sourceRoot":"","sources":["../../src/core/learnings.ts"],"names":[],"mappings":"AAAA,cAAc,sBAAsB,CAAC;AACrC,cAAc,yBAAyB,CAAC;AACxC,cAAc,yBAAyB,CAAC;AACxC,cAAc,2BAA2B,CAAC;AAC1C,cAAc,uBAAuB,CAAC;AACtC,cAAc,gCAAgC,CAAC;AAC/C,OAAO,EACL,8BAA8B,EAC9B,0BAA0B,EAC1B,0BAA0B,EAC1B,iBAAiB,EACjB,iCAAiC,EACjC,2BAA2B,EAC3B,uBAAuB,GAGxB,MAAM,qBAAqB,CAAC"}

package/dist/core/upstream-evidence-manifest.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"upstream-evidence-manifest.d.ts","sourceRoot":"","sources":["../../src/core/upstream-evidence-manifest.ts"],"names":[],"mappings":"AACA,iFAAiF;AACjF,eAAO,MAAM,0BAA0B,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAkiEpE,CAAC;AAEL,4EAA4E;AAC5E,eAAO,MAAM,yBAAyB,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,IAAI,CAAC,CAkyMjE,CAAC;AAEL,sFAAsF;AACtF,eAAO,MAAM,uBAAuB,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,IAAI,CAAC,CAk6I/D,CAAC"}
+{"version":3,"file":"upstream-evidence-manifest.d.ts","sourceRoot":"","sources":["../../src/core/upstream-evidence-manifest.ts"],"names":[],"mappings":"AACA,iFAAiF;AACjF,eAAO,MAAM,0BAA0B,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAkiEpE,CAAC;AAEL,4EAA4E;AAC5E,eAAO,MAAM,yBAAyB,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,IAAI,CAAC,CA0yMjE,CAAC;AAEL,sFAAsF;AACtF,eAAO,MAAM,uBAAuB,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,IAAI,CAAC,CAk6I/D,CAAC"}

package/dist/core/upstream-evidence-manifest.js

@@ -1,7 +1,7 @@
 /* eslint-disable max-lines -- generated exact public-evidence allowlist */
 /** Generated by scripts/generate-upstream-evidence-manifest.mjs. Do not edit. */
 export const UPSTREAM_EVIDENCE_MANIFEST = Object.freeze({
-    "all/copy-contents/.gitattributes": "f5b6d4b75afe753f17dc9a2027eb8eca4dcee326921cc59a36bd0616bfb0636a",
+    "all/copy-contents/.gitattributes": "9d3831007e681186a3673e1037ef3fc82980cab2fc04e27c0868e562912c9e9f",
     "all/copy-contents/gitignore": "06b56376465d5421db55d0b04958bbc79fdbf33b42f0559fe5ef6875ced1160f",
     "all/copy-overwrite/scripts/lisa-work-item.mjs": "5eb31c284e820a51312d4484f0669128007326af55ee515923fec33700d003a1",
     "all/create-only/.claude/rules/PROJECT_RULES.md": "6e1c7923ad2a15356babc60c97e7f97be728d790af285b6a7cd7d1b4d39cd97f",
@@ -455,7 +455,7 @@ export const UPSTREAM_EVIDENCE_MANIFEST = Object.freeze({
     "plugins/src/base/skills/lisa-jira-write-ticket/SKILL.md": "7328f4d8df5b20002ddcf0af6eb59d32a3e1cd6ec3c10521a3e828e6c09f6722",
     "plugins/src/base/skills/lisa-jsdoc-best-practices/SKILL.md": "7cf0729966ac0afcab6e2c043f192772a9e9e7c72fae61e55b300e97308f970e",
     "plugins/src/base/skills/lisa-kane-browser/SKILL.md": "e082517cb42f437eeb22b3935aa0fef09299874736e55184e88d2b64f7860a7d",
-    "plugins/src/base/skills/lisa-learnings-audit/SKILL.md": "b7281362b34f0fb56dd5102926496105d5c031a13fc9bf3158ae5d67b078b063",
+    "plugins/src/base/skills/lisa-learnings-audit/SKILL.md": "0f56daf610cab90a2127cebf83a5bbe05cdcba0f692ebfae8fcf3da153826316",
     "plugins/src/base/skills/lisa-linear-access/SKILL.md": "f6034d41014561aad0caf42a76bbc82329423ba1ee90d9eb832b7800a7c6d3bc",
     "plugins/src/base/skills/lisa-linear-add-journey/SKILL.md": "0a9f2bd0e19fbaa4794537e436c22748c7621644253a91923d84bc77ca43f793",
     "plugins/src/base/skills/lisa-linear-build-intake/SKILL.md": "e1924eb8d968151127ac29d2242ba5bb220fe86c69f7f92e651867b97819581b",
@@ -487,7 +487,7 @@ export const UPSTREAM_EVIDENCE_MANIFEST = Object.freeze({
     "plugins/src/base/skills/lisa-parity-sentry-seer/SKILL.md": "f44216fa7c8f0c3c3371c65ff73bbeadd1717579502a5603f16b3b33291cab7a",
     "plugins/src/base/skills/lisa-parity-skill-creator/SKILL.md": "616e0493f75fe92c18137548d7c86a91a9b04d9844ca76fa3f14156e3e7814e5",
     "plugins/src/base/skills/lisa-performance-review/SKILL.md": "351542c256e54940e6d672a70606b8414425c6435ae6f026841bcc02f9fce9c4",
-    "plugins/src/base/skills/lisa-persist-learning/SKILL.md": "d1dc476137dbec1e9de31eb467d69424e48f3ac0271ae36eb66b2e7b110db603",
+    "plugins/src/base/skills/lisa-persist-learning/SKILL.md": "41ffd8a415c6b1b98952061760e54837f3d6e6ea046e4d1c122dd53878af84de",
     "plugins/src/base/skills/lisa-plan/SKILL.md": "9c372e106afd53ff988046119cf36b0f6519c4426775dd8ad3c9d9baeee5d3e2",
     "plugins/src/base/skills/lisa-plugin-sync-explain/SKILL.md": "b41619f3d0d342af2438afd54cb97db7d2445e54e3fc7bb012292079acbc6a4f",
     "plugins/src/base/skills/lisa-posthog-access/SKILL.md": "977aef803160b04312c0408136882ac106d8357caf5063a523e72f265bf20cb1",
@@ -6359,6 +6359,7 @@ export const UPSTREAM_SURFACE_MANIFEST = Object.freeze({
     "src/cli/index.ts": true,
     "src/cli/install-merge-driver-cmd.ts": true,
     "src/cli/kane-cmd.ts": true,
+    "src/cli/learnings-overflow-cmd.ts": true,
     "src/cli/merge-learnings-cmd.ts": true,
     "src/cli/print-update-warning.ts": true,
     "src/cli/prompts.ts": true,
@@ -6466,6 +6467,7 @@ export const UPSTREAM_SURFACE_MANIFEST = Object.freeze({
     "src/core/kane-pilot-report.ts": true,
     "src/core/kane-pilot-types.ts": true,
     "src/core/kane-pilot.ts": true,
+    "src/core/learnings-alias.ts": true,
     "src/core/learnings-budget-check.ts": true,
     "src/core/learnings-contract.ts": true,
     "src/core/learnings-document.ts": true,
@@ -6476,6 +6478,7 @@ export const UPSTREAM_SURFACE_MANIFEST = Object.freeze({
     "src/core/learnings-merge-driver-install.ts": true,
     "src/core/learnings-merge-driver.ts": true,
     "src/core/learnings-merge.ts": true,
+    "src/core/learnings-overflow.ts": true,
     "src/core/learnings-projection.ts": true,
     "src/core/learnings-writer.ts": true,
     "src/core/learnings.ts": true,
@@ -6740,6 +6743,7 @@ export const UPSTREAM_SURFACE_MANIFEST = Object.freeze({
     "tests/unit/cli/index.test.ts": true,
     "tests/unit/cli/kane-cmd.test.ts": true,
     "tests/unit/cli/kane-index.test.ts": true,
+    "tests/unit/cli/learnings-overflow-cmd.test.ts": true,
     "tests/unit/cli/merge-learnings-cmd.test.ts": true,
     "tests/unit/cli/prompts.test.ts": true,
     "tests/unit/cli/setup-project.test.ts": true,
@@ -6838,6 +6842,7 @@ export const UPSTREAM_SURFACE_MANIFEST = Object.freeze({
     "tests/unit/core/kane-cli.test.ts": true,
     "tests/unit/core/kane-pilot.test.ts": true,
     "tests/unit/core/kane-readiness.test.ts": true,
+    "tests/unit/core/learnings-alias-provenance.test.ts": true,
     "tests/unit/core/learnings-barrel.test.ts": true,
     "tests/unit/core/learnings-budget-check.test.ts": true,
     "tests/unit/core/learnings-concurrency.test.ts": true,
@@ -6850,7 +6855,9 @@ export const UPSTREAM_SURFACE_MANIFEST = Object.freeze({
     "tests/unit/core/learnings-merge-driver-install.test.ts": true,
     "tests/unit/core/learnings-merge-driver.test.ts": true,
     "tests/unit/core/learnings-merge.test.ts": true,
+    "tests/unit/core/learnings-overflow.test.ts": true,
     "tests/unit/core/learnings-projection.test.ts": true,
+    "tests/unit/core/learnings-stable-ids.test.ts": true,
     "tests/unit/core/learnings-supersede-race.test.ts": true,
     "tests/unit/core/learnings-unlocked-read.test.ts": true,
     "tests/unit/core/learnings-writer.test.ts": true,
@@ -7069,6 +7076,7 @@ export const UPSTREAM_SURFACE_MANIFEST = Object.freeze({
     "tests/unit/strategies/learner-capture-contract.test.ts": true,
     "tests/unit/strategies/learnings-audit-contract.test.ts": true,
     "tests/unit/strategies/learnings-confirmation-contract.test.ts": true,
+    "tests/unit/strategies/learnings-overflow-contract.test.ts": true,
     "tests/unit/strategies/linear-access-history.test.ts": true,
     "tests/unit/strategies/merge.test.ts": true,
     "tests/unit/strategies/mld-telemetry-contract.test.ts": true,