@codyswann/lisa 2.297.5 → 2.298.0

package/all/copy-contents/.gitattributes

@@ -0,0 +1,9 @@
+# BEGIN: AI GUARDRAILS
+
+# 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
+# command is machine-local — run `lisa install-merge-driver` to register it.
+.lisa/PROJECT_LEARNINGS.md merge=lisa-learnings
+
+# END: AI GUARDRAILS

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

@@ -1,13 +1,32 @@
 /** Registrars for non-project gate commands shipped to host projects. */
 import type { Command } from "commander";
 import type { FileUpstreamOptions } from "./file-upstream-cmd.js";
-/** Gate runners kept structural to avoid importing the whole CLI dependency record. */
+/**
+ * Gate runners kept structural to avoid importing the whole CLI dependency
+ * record.
+ *
+ * `merge-learnings` and `install-merge-driver` are deliberately NOT members.
+ * They are invoked by git and by an operator repairing a repository, never
+ * substituted by the root CLI, and both mutate real state — the merge driver
+ * overwrites the file git hands it, and the installer writes local git config.
+ * An optional, defaulted field would be the worst shape here: a caller that
+ * believed it had stubbed every gate command would silently run the real driver
+ * against real files. Leaving them off the record makes non-injectability
+ * explicit; they are covered directly by unit tests and by end-to-end tests
+ * that drive real `git merge`.
+ */
 export interface GateCommandDependencies {
     runCheckLearningsBudget: (path: string | undefined) => Promise<number>;
     runFileUpstream: (options: FileUpstreamOptions) => Promise<number>;
 }
-/** Gate commands skip the root npm update check. */
-export declare const GATE_COMMAND_NAMES: readonly ["check-learnings-budget", "file-upstream"];
+/**
+ * Gate commands skip the root npm update check.
+ *
+ * `merge-learnings` especially: git runs it inline during every merge of the
+ * ledger, so a network update check would stall the merge and pollute the
+ * driver's output.
+ */
+export declare const GATE_COMMAND_NAMES: readonly ["check-learnings-budget", "file-upstream", "merge-learnings", "install-merge-driver"];
 /**
  * Register all non-project gate commands.
  * @param program - Commander program

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

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

package/dist/cli/gate-commands.js

@@ -1,7 +1,17 @@
-/** Gate commands skip the root npm update check. */
+import { runInstallMergeDriver } from "./install-merge-driver-cmd.js";
+import { runMergeLearnings, } from "./merge-learnings-cmd.js";
+/**
+ * Gate commands skip the root npm update check.
+ *
+ * `merge-learnings` especially: git runs it inline during every merge of the
+ * ledger, so a network update check would stall the merge and pollute the
+ * driver's output.
+ */
 export const GATE_COMMAND_NAMES = [
     "check-learnings-budget",
     "file-upstream",
+    "merge-learnings",
+    "install-merge-driver",
 ];
 /**
  * Register the bounded learnings-budget check.
@@ -35,6 +45,42 @@ function addFileUpstreamCommand(program, dependencies) {
             process.exitCode = code;
     });
 }
+/**
+ * Register the project-learnings union merge driver.
+ *
+ * Invoked by git, not by humans: the argument names map to git's `%O %A %B %P`
+ * placeholders and the exit code carries the merge verdict.
+ * @param program - Commander program
+ */
+function addMergeLearningsCommand(program) {
+    program
+        .command("merge-learnings")
+        .description("Git merge driver: union the project learnings ledger by entry id")
+        .option("--base <file>", "Merge-base version (git %O)")
+        .option("--ours <file>", "Our version; receives the result (git %A)")
+        .option("--theirs <file>", "Their version (git %B)")
+        .option("--path <path>", "Real pathname for diagnostics (git %P)")
+        .action(async (options) => {
+        const code = await runMergeLearnings(options);
+        if (code !== 0)
+            process.exitCode = code;
+    });
+}
+/**
+ * Register the machine-local merge-driver installer.
+ * @param program - Commander program
+ */
+function addInstallMergeDriverCommand(program) {
+    program
+        .command("install-merge-driver")
+        .description("Register the project learnings union merge driver in local git config")
+        .argument("[path]", "Project directory (default: current directory)")
+        .action(async (targetPath) => {
+        const code = await runInstallMergeDriver(targetPath);
+        if (code !== 0)
+            process.exitCode = code;
+    });
+}
 /**
  * Register all non-project gate commands.
  * @param program - Commander program
@@ -43,5 +89,7 @@ function addFileUpstreamCommand(program, dependencies) {
 export function addGateCommands(program, dependencies) {
     addCheckLearningsBudgetCommand(program, dependencies);
     addFileUpstreamCommand(program, dependencies);
+    addMergeLearningsCommand(program);
+    addInstallMergeDriverCommand(program);
 }
 //# sourceMappingURL=gate-commands.js.map

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

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

package/dist/cli/install-merge-driver-cmd.d.ts

@@ -0,0 +1,21 @@
+/** Injectable collaborators for {@link runInstallMergeDriver}. */
+export interface InstallMergeDriverDependencies {
+    /** Working directory used to resolve a relative project path. */
+    readonly cwd?: string;
+    /** Sink for the outcome line (defaults to stdout). */
+    readonly log?: (message: string) => void;
+    /** Sink for a real registration failure (defaults to stderr). */
+    readonly error?: (message: string) => void;
+}
+/**
+ * Register the merge driver for one project.
+ * Exit code distinguishes a benign non-event from a real failure: a directory
+ * that is not a git repository passes (nothing to register), but a git-config
+ * write that failed exits non-zero. Reporting success there would tell an
+ * operator the ledger is protected when it is not.
+ * @param targetPath - Optional project directory (default: current directory)
+ * @param dependencies - Injectable collaborators for tests
+ * @returns Process exit code: 0 registered/unchanged/not-a-repo, 1 failed
+ */
+export declare function runInstallMergeDriver(targetPath: string | undefined, dependencies?: InstallMergeDriverDependencies): Promise<number>;
+//# sourceMappingURL=install-merge-driver-cmd.d.ts.map

package/dist/cli/install-merge-driver-cmd.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"install-merge-driver-cmd.d.ts","sourceRoot":"","sources":["../../src/cli/install-merge-driver-cmd.ts"],"names":[],"mappings":"AAcA,kEAAkE;AAClE,MAAM,WAAW,8BAA8B;IAC7C,iEAAiE;IACjE,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,CAAC;IACtB,sDAAsD;IACtD,QAAQ,CAAC,GAAG,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,IAAI,CAAC;IACzC,iEAAiE;IACjE,QAAQ,CAAC,KAAK,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,IAAI,CAAC;CAC5C;AAED;;;;;;;;;GASG;AACH,wBAAsB,qBAAqB,CACzC,UAAU,EAAE,MAAM,GAAG,SAAS,EAC9B,YAAY,GAAE,8BAAmC,GAChD,OAAO,CAAC,MAAM,CAAC,CAajB"}

package/dist/cli/install-merge-driver-cmd.js

@@ -0,0 +1,37 @@
+/**
+ * `lisa install-merge-driver` — register the project-learnings union merge
+ * driver in the current repository's local git config.
+ *
+ * `lisa apply` already does this through the `EnsureLearningsMergeDriver`
+ * migration, so this command exists for the cases apply does not cover: a fresh
+ * clone or worktree that has not been applied yet, and CI-like environments
+ * where the bootstrap guard suppresses apply. It is also the command the
+ * learnings budget gate names when it detects a conflict-corrupted ledger.
+ * @module cli/install-merge-driver-cmd
+ */
+import * as path from "node:path";
+import { installLearningsMergeDriver } from "../core/learnings-merge-driver-install.js";
+/**
+ * Register the merge driver for one project.
+ * Exit code distinguishes a benign non-event from a real failure: a directory
+ * that is not a git repository passes (nothing to register), but a git-config
+ * write that failed exits non-zero. Reporting success there would tell an
+ * operator the ledger is protected when it is not.
+ * @param targetPath - Optional project directory (default: current directory)
+ * @param dependencies - Injectable collaborators for tests
+ * @returns Process exit code: 0 registered/unchanged/not-a-repo, 1 failed
+ */
+export async function runInstallMergeDriver(targetPath, dependencies = {}) {
+    const cwd = dependencies.cwd ?? process.cwd();
+    const log = dependencies.log ?? ((message) => console.log(message));
+    const error = dependencies.error ?? ((message) => console.error(message));
+    const projectRoot = path.resolve(cwd, targetPath ?? ".");
+    const result = await installLearningsMergeDriver(projectRoot);
+    if (result.kind === "failed") {
+        error(`install-merge-driver: ${result.detail}`);
+        return 1;
+    }
+    log(`install-merge-driver: ${result.detail}`);
+    return 0;
+}
+//# sourceMappingURL=install-merge-driver-cmd.js.map

package/dist/cli/install-merge-driver-cmd.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"install-merge-driver-cmd.js","sourceRoot":"","sources":["../../src/cli/install-merge-driver-cmd.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AACH,OAAO,KAAK,IAAI,MAAM,WAAW,CAAC;AAClC,OAAO,EAAE,2BAA2B,EAAE,MAAM,2CAA2C,CAAC;AAYxF;;;;;;;;;GASG;AACH,MAAM,CAAC,KAAK,UAAU,qBAAqB,CACzC,UAA8B,EAC9B,eAA+C,EAAE;IAEjD,MAAM,GAAG,GAAG,YAAY,CAAC,GAAG,IAAI,OAAO,CAAC,GAAG,EAAE,CAAC;IAC9C,MAAM,GAAG,GAAG,YAAY,CAAC,GAAG,IAAI,CAAC,CAAC,OAAe,EAAE,EAAE,CAAC,OAAO,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC;IAC5E,MAAM,KAAK,GACT,YAAY,CAAC,KAAK,IAAI,CAAC,CAAC,OAAe,EAAE,EAAE,CAAC,OAAO,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC;IACtE,MAAM,WAAW,GAAG,IAAI,CAAC,OAAO,CAAC,GAAG,EAAE,UAAU,IAAI,GAAG,CAAC,CAAC;IACzD,MAAM,MAAM,GAAG,MAAM,2BAA2B,CAAC,WAAW,CAAC,CAAC;IAC9D,IAAI,MAAM,CAAC,IAAI,KAAK,QAAQ,EAAE,CAAC;QAC7B,KAAK,CAAC,yBAAyB,MAAM,CAAC,MAAM,EAAE,CAAC,CAAC;QAChD,OAAO,CAAC,CAAC;IACX,CAAC;IACD,GAAG,CAAC,yBAAyB,MAAM,CAAC,MAAM,EAAE,CAAC,CAAC;IAC9C,OAAO,CAAC,CAAC;AACX,CAAC"}

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

@@ -0,0 +1,24 @@
+/** Git-supplied merge sides, mapped from `%O %A %B %P`. */
+export interface MergeLearningsOptions {
+    /** `%O` — merge-base version; an empty file when the ledger is new. */
+    readonly base?: string;
+    /** `%A` — our version, and the file the result must be written to. */
+    readonly ours?: string;
+    /** `%B` — their (incoming) version. */
+    readonly theirs?: string;
+    /** `%P` — the real pathname, used only in diagnostics. */
+    readonly path?: string;
+}
+/** Injectable collaborators for {@link runMergeLearnings}. */
+export interface MergeLearningsDependencies {
+    /** Sink for the conflict diagnostic (defaults to stderr). */
+    readonly error?: (message: string) => void;
+}
+/**
+ * Run the union merge and publish the result.
+ * @param options - Git-supplied merge sides
+ * @param dependencies - Injectable collaborators for tests
+ * @returns Process exit code: 0 merged, 1 conflict
+ */
+export declare function runMergeLearnings(options: MergeLearningsOptions, dependencies?: MergeLearningsDependencies): Promise<number>;
+//# sourceMappingURL=merge-learnings-cmd.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"merge-learnings-cmd.d.ts","sourceRoot":"","sources":["../../src/cli/merge-learnings-cmd.ts"],"names":[],"mappings":"AAsBA,2DAA2D;AAC3D,MAAM,WAAW,qBAAqB;IACpC,uEAAuE;IACvE,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IACvB,sEAAsE;IACtE,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IACvB,uCAAuC;IACvC,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IACzB,0DAA0D;IAC1D,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;CACxB;AAED,8DAA8D;AAC9D,MAAM,WAAW,0BAA0B;IACzC,6DAA6D;IAC7D,QAAQ,CAAC,KAAK,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,IAAI,CAAC;CAC5C;AA2BD;;;;;GAKG;AACH,wBAAsB,iBAAiB,CACrC,OAAO,EAAE,qBAAqB,EAC9B,YAAY,GAAE,0BAA+B,GAC5C,OAAO,CAAC,MAAM,CAAC,CA2CjB"}

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

@@ -0,0 +1,82 @@
+/**
+ * `lisa merge-learnings` — the git merge driver for the project-learnings
+ * ledger.
+ *
+ * Git invokes this with the three sides of a merge and expects the result to be
+ * written over the "ours" file, exiting zero for a clean merge and non-zero to
+ * record a conflict. The union itself lives in `core/learnings-merge.ts`; this
+ * module is only the process boundary — argument plumbing, file IO, and the
+ * exit-code contract.
+ *
+ * On conflict the "ours" file is deliberately left untouched rather than filled
+ * with conflict markers: git still records the conflict from the non-zero exit,
+ * and leaving a parseable ledger in the working tree means the recovering agent
+ * reads a real document plus a precise reason on stderr, instead of a corrupted
+ * one. The marker guard in `core/learnings-document.ts` remains the backstop for
+ * ledgers corrupted while this driver was NOT registered.
+ * @module cli/merge-learnings-cmd
+ */
+import { readFile } from "node:fs/promises";
+import { mergeLearningsDocuments } from "../core/learnings-merge.js";
+import { writeFileAtomically } from "../utils/atomic-file-write.js";
+/**
+ * Read one merge side that was definitely supplied.
+ *
+ * Never conflates "unreadable" with "empty". Collapsing the two is what made
+ * this driver fail OPEN: an unreadable merge base silently became "no base",
+ * the union degraded to two-way, and a superseded entry was resurrected into a
+ * CLEAN, committed merge. Real triggers include ERR_STRING_TOO_LONG on an
+ * oversized base, EACCES, ENOMEM, and EMFILE/ENFILE exhaustion under exactly
+ * the parallel worktree merges this driver serves.
+ * @param file - Path supplied by git
+ * @returns The contents, or an explicit read failure
+ */
+async function readSide(file) {
+    try {
+        return { ok: true, content: await readFile(file, "utf8") };
+    }
+    catch {
+        return { ok: false };
+    }
+}
+/**
+ * Run the union merge and publish the result.
+ * @param options - Git-supplied merge sides
+ * @param dependencies - Injectable collaborators for tests
+ * @returns Process exit code: 0 merged, 1 conflict
+ */
+export async function runMergeLearnings(options, dependencies = {}) {
+    const error = dependencies.error ?? ((message) => console.error(message));
+    const label = options.path ?? "project learnings";
+    if (options.ours === undefined || options.theirs === undefined) {
+        error("merge-learnings: --ours and --theirs are required (git supplies %A and %B)");
+        return 1;
+    }
+    const oursPath = options.ours;
+    const ours = await readSide(oursPath);
+    const theirs = await readSide(options.theirs);
+    if (!ours.ok || !theirs.ok) {
+        error(`merge-learnings: ${label}: could not read both merge sides`);
+        return 1;
+    }
+    // An OMITTED --base legitimately means "new on both sides". A base that was
+    // supplied and cannot be read is a different thing entirely, and must never
+    // be silently downgraded into the first case — exit 0 makes git record a
+    // clean merge, so failing open here publishes data loss with no marker, no
+    // diagnostic, and no second chance.
+    const base = options.base === undefined
+        ? { ok: true, content: "" }
+        : await readSide(options.base);
+    if (!base.ok) {
+        error(`merge-learnings: ${label}: merge base could not be read — refusing to merge without it, because a two-way union silently resurrects superseded entries`);
+        return 1;
+    }
+    const result = mergeLearningsDocuments(base.content, ours.content, theirs.content);
+    if (result.kind === "conflict") {
+        error(`merge-learnings: ${label}: ${result.reason}`);
+        return 1;
+    }
+    await writeFileAtomically(oursPath, result.content);
+    return 0;
+}
+//# sourceMappingURL=merge-learnings-cmd.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"merge-learnings-cmd.js","sourceRoot":"","sources":["../../src/cli/merge-learnings-cmd.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AACH,OAAO,EAAE,QAAQ,EAAE,MAAM,kBAAkB,CAAC;AAC5C,OAAO,EAAE,uBAAuB,EAAE,MAAM,4BAA4B,CAAC;AACrE,OAAO,EAAE,mBAAmB,EAAE,MAAM,+BAA+B,CAAC;AAyBpE;;;;;;;;;;;GAWG;AACH,KAAK,UAAU,QAAQ,CAAC,IAAY;IAClC,IAAI,CAAC;QACH,OAAO,EAAE,EAAE,EAAE,IAAI,EAAE,OAAO,EAAE,MAAM,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC,EAAE,CAAC;IAC7D,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,CAAC;IACvB,CAAC;AACH,CAAC;AAED;;;;;GAKG;AACH,MAAM,CAAC,KAAK,UAAU,iBAAiB,CACrC,OAA8B,EAC9B,eAA2C,EAAE;IAE7C,MAAM,KAAK,GACT,YAAY,CAAC,KAAK,IAAI,CAAC,CAAC,OAAe,EAAE,EAAE,CAAC,OAAO,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC;IACtE,MAAM,KAAK,GAAG,OAAO,CAAC,IAAI,IAAI,mBAAmB,CAAC;IAClD,IAAI,OAAO,CAAC,IAAI,KAAK,SAAS,IAAI,OAAO,CAAC,MAAM,KAAK,SAAS,EAAE,CAAC;QAC/D,KAAK,CACH,4EAA4E,CAC7E,CAAC;QACF,OAAO,CAAC,CAAC;IACX,CAAC;IACD,MAAM,QAAQ,GAAG,OAAO,CAAC,IAAI,CAAC;IAC9B,MAAM,IAAI,GAAG,MAAM,QAAQ,CAAC,QAAQ,CAAC,CAAC;IACtC,MAAM,MAAM,GAAG,MAAM,QAAQ,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC;IAC9C,IAAI,CAAC,IAAI,CAAC,EAAE,IAAI,CAAC,MAAM,CAAC,EAAE,EAAE,CAAC;QAC3B,KAAK,CAAC,oBAAoB,KAAK,mCAAmC,CAAC,CAAC;QACpE,OAAO,CAAC,CAAC;IACX,CAAC;IACD,4EAA4E;IAC5E,4EAA4E;IAC5E,yEAAyE;IACzE,2EAA2E;IAC3E,oCAAoC;IACpC,MAAM,IAAI,GACR,OAAO,CAAC,IAAI,KAAK,SAAS;QACxB,CAAC,CAAC,EAAE,EAAE,EAAE,IAAI,EAAE,OAAO,EAAE,EAAE,EAAE;QAC3B,CAAC,CAAC,MAAM,QAAQ,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC;IACnC,IAAI,CAAC,IAAI,CAAC,EAAE,EAAE,CAAC;QACb,KAAK,CACH,oBAAoB,KAAK,+HAA+H,CACzJ,CAAC;QACF,OAAO,CAAC,CAAC;IACX,CAAC;IACD,MAAM,MAAM,GAAG,uBAAuB,CACpC,IAAI,CAAC,OAAO,EACZ,IAAI,CAAC,OAAO,EACZ,MAAM,CAAC,OAAO,CACf,CAAC;IACF,IAAI,MAAM,CAAC,IAAI,KAAK,UAAU,EAAE,CAAC;QAC/B,KAAK,CAAC,oBAAoB,KAAK,KAAK,MAAM,CAAC,MAAM,EAAE,CAAC,CAAC;QACrD,OAAO,CAAC,CAAC;IACX,CAAC;IACD,MAAM,mBAAmB,CAAC,QAAQ,EAAE,MAAM,CAAC,OAAO,CAAC,CAAC;IACpD,OAAO,CAAC,CAAC;AACX,CAAC"}

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":"AA4BA,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;CAC5B;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,CAgChC;AA2CD;;;;;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;CAC5B;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,CAgChC;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, estimateLearningTokens, } from "./learnings-contract.js";
-import { parseLearningsFile, renderLearningsFile, } from "./learnings-document.js";
+import { CONFLICT_MARKER_DIAGNOSIS, conflictMarkerError, findConflictMarkerInBytes, parseLearningsFile, renderLearningsFile, } from "./learnings-document.js";
 import { validateLearningEntry } from "./learnings-entry.js";
 /**
  * Check one already-resolved absolute learnings path against the shared hard
@@ -70,6 +70,12 @@ function withRemediation(detail, file) {
         return detail;
     }
     const target = formatDiagnosticPath(file);
+    // Checked before the budget clauses: a conflicted merge duplicates the JSONL
+    // block, so this failure often ALSO breaches a budget, and "shorten entries"
+    // is the wrong instruction for it.
+    if (detail.includes(CONFLICT_MARKER_DIAGNOSIS)) {
+        return `${detail} — recompact ${target} from both conflicting versions, then register the union merge driver (\`lisa install-merge-driver\`) so concurrent learning branches merge instead of conflicting`;
+    }
     if (detail.includes("maxEntries")) {
         return `${detail} — consolidate or remove entries in ${target} to fit the learnings budget`;
     }
@@ -164,11 +170,20 @@ async function readBoundedRegularFile(file, maximumBytes) {
         if (!before.isFile()) {
             throw new Error("unsafe input: expected a regular file");
         }
+        // Read the bounded prefix BEFORE judging size. A git-conflicted ledger is
+        // roughly double size, so the size guard used to win this race and report
+        // "shorten or remove entries" for a file whose problem is duplication —
+        // advice that has an operator deleting good learnings. The read is capped
+        // by the buffer either way, so an oversized file is still never slurped.
+        const buffer = Buffer.allocUnsafe(maximumBytes + 1);
+        const bytesRead = await fillBuffer(handle, buffer, 0);
+        const conflictLine = findConflictMarkerInBytes(buffer.subarray(0, bytesRead));
+        if (conflictLine !== undefined) {
+            throw conflictMarkerError(conflictLine);
+        }
         if (before.size > BigInt(maximumBytes)) {
             throw new Error(`maxTokens exceeded: measured ${before.size}, allowed ${maximumBytes}`);
         }
-        const buffer = Buffer.allocUnsafe(maximumBytes + 1);
-        const bytesRead = await fillBuffer(handle, buffer, 0);
         if (bytesRead > maximumBytes) {
             throw new Error(`maxTokens exceeded: measured at least ${bytesRead}, allowed ${maximumBytes}`);
         }

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-document.d.ts

@@ -1,5 +1,10 @@
 /** Pure parsing and rendering for the canonical project-learnings document. */
 import { type LearningEntry } from "./learnings-contract.js";
+/**
+ * Stable diagnosis prefix. Shared so the CI gate can recognize this specific
+ * failure and attach merge-driver remediation without re-implementing the scan.
+ */
+export declare const CONFLICT_MARKER_DIAGNOSIS = "Project learnings file contains a git conflict marker";
 /**
  * Render the complete file in one stable, machine-readable Markdown form.
  * @param entries - Validated entries to serialize
@@ -19,4 +24,45 @@ export declare function parseLearningsFile(content: string): LearningEntry[];
  * @param context - Error-message prefix
  */
 export declare function assertDocumentBudget(content: string, entryCount: number, context: string): void;
+/**
+ * Locate the first line git left a conflict marker on.
+ *
+ * The fs-level write lock cannot prevent this corruption: each learner pass
+ * runs on its own `learning/<fingerprint>` branch in its own worktree, so a
+ * path-scoped lock never sees the other writer and the collision surfaces at
+ * merge time.
+ *
+ * Detection is exact because of the render contract: entries are serialized one
+ * `JSON.stringify` object per line and that escapes every newline, so no stored
+ * field value can ever begin a line. Every line of a canonical document starts
+ * with `#`, `<!--`, a backtick fence, `{`, or is empty — so a line STARTING
+ * with a seven-character git marker is unambiguously foreign to the format and
+ * cannot be legitimate content.
+ * @param content - Untrusted learnings document
+ * @returns One-based line number of the first marker, or undefined when clean
+ */
+export declare function findConflictMarkerLine(content: string): number | undefined;
+/**
+ * Build the one canonical conflict diagnosis every reader throws.
+ *
+ * Shared because the readers each apply a file-SIZE guard before handing bytes
+ * to the parser, and a real conflicted ledger is roughly double size — so the
+ * size guard would otherwise win the race and tell an operator to "shorten or
+ * remove entries" on a file whose actual problem is duplication. Each reader
+ * scans its bounded prefix and throws THIS error instead.
+ * @param line - One-based line number of the first marker
+ * @returns Error carrying the shared diagnosis and remediation
+ */
+export declare function conflictMarkerError(line: number): Error;
+/**
+ * Scan a possibly-truncated UTF-8 prefix for a conflict marker.
+ *
+ * Decoded leniently on purpose: the buffer is cut at a fixed byte ceiling and
+ * may split a multi-byte character, which a strict decoder would reject. A
+ * replacement character cannot forge or hide a marker, since markers are ASCII
+ * anchored at line start.
+ * @param prefix - Bounded bytes read from the head of a candidate ledger
+ * @returns One-based line number of the first marker, or undefined when clean
+ */
+export declare function findConflictMarkerInBytes(prefix: Uint8Array): number | undefined;
 //# sourceMappingURL=learnings-document.d.ts.map

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

package/dist/core/learnings-document.js

@@ -8,7 +8,30 @@ const FILE_HEADER = `# Project Learnings
 `;
 const JSON_FENCE_START = "```jsonl\n";
 const JSON_FENCE_END = "\n```\n";
-const CONFLICT_MARKER_PATTERN = /^(<<<<<<<|=======|>>>>>>>)(?: .*)?$/mu;
+/**
+ * Git's conflict markers, anchored to the start of a line.
+ *
+ * Seven characters is only the DEFAULT width. Git's `conflict-marker-size`
+ * attribute is real and widens every marker, and a `.gitattributes` setting it
+ * survives `lisa apply` because copy-contents preserves host lines outside the
+ * managed block — so a fixed `{7}` quantifier silently stops recognizing
+ * corruption in exactly the repositories that configured it. `{7,}` matches any
+ * legal width. The trailing class also admits `\r` so a CRLF checkout's
+ * `>>>>>>>\r` is still seen.
+ *
+ * Only the opener (`<<<<<<<`), the diff3 base separator (`|||||||`), and the
+ * closer (`>>>>>>>`) are matched. A bare `=======` is deliberately NOT a signal
+ * on its own: a row of equals signs is ordinary prose punctuation, so matching
+ * it would make a legitimate document undiagnosable. Every real git conflict
+ * emits an opener and a closer around it, so anchoring on those loses no
+ * detection power while removing the ambiguity.
+ */
+const CONFLICT_MARKER = /^(?:<{7,}|\|{7,}|>{7,})(?:[ \t\r]|$)/u;
+/**
+ * Stable diagnosis prefix. Shared so the CI gate can recognize this specific
+ * failure and attach merge-driver remediation without re-implementing the scan.
+ */
+export const CONFLICT_MARKER_DIAGNOSIS = "Project learnings file contains a git conflict marker";
 /**
  * Render the complete file in one stable, machine-readable Markdown form.
  * @param entries - Validated entries to serialize
@@ -24,12 +47,17 @@ export function renderLearningsFile(entries) {
  * @returns Revalidated entries from the document
  */
 export function parseLearningsFile(content) {
+    // Diagnose concurrent-write corruption BEFORE the byte budget. A conflicted
+    // merge duplicates the whole JSONL block, so a nearly-full ledger lands over
+    // budget and would otherwise report "exceeds maxTokens" — advice that sends
+    // an operator off deleting good learnings when the real fix is recompaction.
+    const conflictLine = findConflictMarkerLine(content);
+    if (conflictLine !== undefined) {
+        throw conflictMarkerError(conflictLine);
+    }
     if (estimateLearningTokens(content) > LEARNINGS_CONTRACT.maxTokens) {
         throw new Error(`Project learnings payload exceeds maxTokens ${LEARNINGS_CONTRACT.maxTokens}`);
     }
-    if (CONFLICT_MARKER_PATTERN.test(content)) {
-        throw new Error("Project learnings ledger corrupted by concurrent write: embedded conflict markers found; restore or recompact the ledger before writing");
-    }
     if (!content.startsWith(`${FILE_HEADER}${JSON_FENCE_START}`) ||
         !content.endsWith(JSON_FENCE_END)) {
         throw new Error("Invalid project learnings file format");
@@ -58,6 +86,56 @@ export function assertDocumentBudget(content, entryCount, context) {
         throw new Error(`${context} exceeds maxTokens ${LEARNINGS_CONTRACT.maxTokens} (measured ${estimatedTokens})`);
     }
 }
+/**
+ * Locate the first line git left a conflict marker on.
+ *
+ * The fs-level write lock cannot prevent this corruption: each learner pass
+ * runs on its own `learning/<fingerprint>` branch in its own worktree, so a
+ * path-scoped lock never sees the other writer and the collision surfaces at
+ * merge time.
+ *
+ * Detection is exact because of the render contract: entries are serialized one
+ * `JSON.stringify` object per line and that escapes every newline, so no stored
+ * field value can ever begin a line. Every line of a canonical document starts
+ * with `#`, `<!--`, a backtick fence, `{`, or is empty — so a line STARTING
+ * with a seven-character git marker is unambiguously foreign to the format and
+ * cannot be legitimate content.
+ * @param content - Untrusted learnings document
+ * @returns One-based line number of the first marker, or undefined when clean
+ */
+export function findConflictMarkerLine(content) {
+    const index = content
+        .split("\n")
+        .findIndex(line => CONFLICT_MARKER.test(line));
+    return index === -1 ? undefined : index + 1;
+}
+/**
+ * Build the one canonical conflict diagnosis every reader throws.
+ *
+ * Shared because the readers each apply a file-SIZE guard before handing bytes
+ * to the parser, and a real conflicted ledger is roughly double size — so the
+ * size guard would otherwise win the race and tell an operator to "shorten or
+ * remove entries" on a file whose actual problem is duplication. Each reader
+ * scans its bounded prefix and throws THIS error instead.
+ * @param line - One-based line number of the first marker
+ * @returns Error carrying the shared diagnosis and remediation
+ */
+export function conflictMarkerError(line) {
+    return new Error(`${CONFLICT_MARKER_DIAGNOSIS} on line ${line}: the ledger was corrupted by concurrent writers merging separate learning branches. Recompact it by keeping every distinct entry id from both sides, then re-run.`);
+}
+/**
+ * Scan a possibly-truncated UTF-8 prefix for a conflict marker.
+ *
+ * Decoded leniently on purpose: the buffer is cut at a fixed byte ceiling and
+ * may split a multi-byte character, which a strict decoder would reject. A
+ * replacement character cannot forge or hide a marker, since markers are ASCII
+ * anchored at line start.
+ * @param prefix - Bounded bytes read from the head of a candidate ledger
+ * @returns One-based line number of the first marker, or undefined when clean
+ */
+export function findConflictMarkerInBytes(prefix) {
+    return findConflictMarkerLine(new TextDecoder("utf-8").decode(prefix));
+}
 /**
  * Add a stable entry identifier to validation failures.
  * @param candidate - Parsed JSONL value

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

@@ -1 +1 @@
-{"version":3,"file":"learnings-document.js","sourceRoot":"","sources":["../../src/core/learnings-document.ts"],"names":[],"mappings":"AAAA,+EAA+E;AAC/E,OAAO,EACL,kBAAkB,EAClB,sBAAsB,GAEvB,MAAM,yBAAyB,CAAC;AACjC,OAAO,EAAE,qBAAqB,EAAE,MAAM,sBAAsB,CAAC;AAE7D,MAAM,WAAW,GAAG;;gCAEY,kBAAkB,CAAC,OAAO;;CAEzD,CAAC;AACF,MAAM,gBAAgB,GAAG,YAAY,CAAC;AACtC,MAAM,cAAc,GAAG,SAAS,CAAC;AACjC,MAAM,uBAAuB,GAAG,uCAAuC,CAAC;AAExE;;;;GAIG;AACH,MAAM,UAAU,mBAAmB,CAAC,OAAiC;IACnE,MAAM,KAAK,GAAG,OAAO,CAAC,GAAG,CAAC,KAAK,CAAC,EAAE,CAAC,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IACrE,OAAO,GAAG,WAAW,GAAG,gBAAgB,GAAG,KAAK,GAAG,cAAc,EAAE,CAAC;AACtE,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,kBAAkB,CAAC,OAAe;IAChD,IAAI,sBAAsB,CAAC,OAAO,CAAC,GAAG,kBAAkB,CAAC,SAAS,EAAE,CAAC;QACnE,MAAM,IAAI,KAAK,CACb,+CAA+C,kBAAkB,CAAC,SAAS,EAAE,CAC9E,CAAC;IACJ,CAAC;IACD,IAAI,uBAAuB,CAAC,IAAI,CAAC,OAAO,CAAC,EAAE,CAAC;QAC1C,MAAM,IAAI,KAAK,CACb,yIAAyI,CAC1I,CAAC;IACJ,CAAC;IACD,IACE,CAAC,OAAO,CAAC,UAAU,CAAC,GAAG,WAAW,GAAG,gBAAgB,EAAE,CAAC;QACxD,CAAC,OAAO,CAAC,QAAQ,CAAC,cAAc,CAAC,EACjC,CAAC;QACD,MAAM,IAAI,KAAK,CAAC,uCAAuC,CAAC,CAAC;IAC3D,CAAC;IACD,MAAM,SAAS,GAAG,WAAW,CAAC,MAAM,GAAG,gBAAgB,CAAC,MAAM,CAAC;IAC/D,MAAM,OAAO,GAAG,OAAO,CAAC,MAAM,GAAG,cAAc,CAAC,MAAM,CAAC;IACvD,MAAM,OAAO,GAAG,cAAc,CAAC,OAAO,CAAC,KAAK,CAAC,SAAS,EAAE,OAAO,CAAC,CAAC,CAAC,GAAG,CACnE,2BAA2B,CAC5B,CAAC;IACF,IAAI,IAAI,GAAG,CAAC,OAAO,CAAC,GAAG,CAAC,KAAK,CAAC,EAAE,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC,CAAC,IAAI,KAAK,OAAO,CAAC,MAAM,EAAE,CAAC;QACpE,MAAM,IAAI,KAAK,CAAC,kDAAkD,CAAC,CAAC;IACtE,CAAC;IACD,oBAAoB,CAAC,OAAO,EAAE,OAAO,CAAC,MAAM,EAAE,2BAA2B,CAAC,CAAC;IAC3E,OAAO,OAAO,CAAC;AACjB,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,oBAAoB,CAClC,OAAe,EACf,UAAkB,EAClB,OAAe;IAEf,IAAI,UAAU,GAAG,kBAAkB,CAAC,UAAU,EAAE,CAAC;QAC/C,MAAM,IAAI,KAAK,CACb,GAAG,OAAO,iCAAiC,UAAU,aAAa,kBAAkB,CAAC,UAAU,EAAE,CAClG,CAAC;IACJ,CAAC;IACD,MAAM,eAAe,GAAG,sBAAsB,CAAC,OAAO,CAAC,CAAC;IACxD,IAAI,eAAe,GAAG,kBAAkB,CAAC,SAAS,EAAE,CAAC;QACnD,MAAM,IAAI,KAAK,CACb,GAAG,OAAO,sBAAsB,kBAAkB,CAAC,SAAS,cAAc,eAAe,GAAG,CAC7F,CAAC;IACJ,CAAC;AACH,CAAC;AAED;;;;;GAKG;AACH,SAAS,2BAA2B,CAClC,SAAkB,EAClB,KAAa;IAEb,IAAI,CAAC;QACH,OAAO,qBAAqB,CAAC,SAAS,CAAC,CAAC;IAC1C,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,MAAM,EAAE,GAAG,qBAAqB,CAAC,SAAS,CAAC,CAAC;QAC5C,0EAA0E;QAC1E,wEAAwE;QACxE,yEAAyE;QACzE,yEAAyE;QACzE,4BAA4B;QAC5B,MAAM,KAAK,GAAG,EAAE,KAAK,SAAS,CAAC,CAAC,CAAC,SAAS,KAAK,GAAG,CAAC,EAAE,CAAC,CAAC,CAAC,UAAU,EAAE,GAAG,CAAC;QACxE,MAAM,MAAM,GAAG,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;QACtE,MAAM,IAAI,KAAK,CAAC,oBAAoB,KAAK,KAAK,MAAM,EAAE,CAAC,CAAC;IAC1D,CAAC;AACH,CAAC;AAED;;;;GAIG;AACH,SAAS,qBAAqB,CAAC,SAAkB;IAC/C,IAAI,SAAS,KAAK,IAAI,IAAI,OAAO,SAAS,KAAK,QAAQ,EAAE,CAAC;QACxD,OAAO,SAAS,CAAC;IACnB,CAAC;IACD,MAAM,UAAU,GAAG,MAAM,CAAC,wBAAwB,CAAC,SAAS,EAAE,IAAI,CAAC,CAAC;IACpE,OAAO,UAAU,KAAK,SAAS;QAC7B,OAAO,IAAI,UAAU;QACrB,OAAO,UAAU,CAAC,KAAK,KAAK,QAAQ;QACpC,CAAC,CAAC,UAAU,CAAC,KAAK;QAClB,CAAC,CAAC,SAAS,CAAC;AAChB,CAAC;AAED;;;;GAIG;AACH,SAAS,cAAc,CAAC,OAAe;IACrC,IAAI,OAAO,KAAK,EAAE,EAAE,CAAC;QACnB,OAAO,EAAE,CAAC;IACZ,CAAC;IACD,IAAI,CAAC;QACH,OAAO,OAAO,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,GAAG,CAAC,IAAI,CAAC,EAAE,CAAC,IAAI,CAAC,KAAK,CAAC,IAAI,CAAY,CAAC,CAAC;IACtE,CAAC;IAAC,MAAM,CAAC;QACP,MAAM,IAAI,KAAK,CAAC,yCAAyC,CAAC,CAAC;IAC7D,CAAC;AACH,CAAC"}
+{"version":3,"file":"learnings-document.js","sourceRoot":"","sources":["../../src/core/learnings-document.ts"],"names":[],"mappings":"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"}

package/dist/core/learnings-file-safety.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"learnings-file-safety.d.ts","sourceRoot":"","sources":["../../src/core/learnings-file-safety.ts"],"names":[],"mappings":"AAMA;;;;;GAKG;AACH,wBAAgB,yBAAyB,CACvC,WAAW,EAAE,MAAM,EACnB,YAAY,EAAE,MAAM,GACnB;IAAE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CASpD;AAED;;;;GAIG;AACH,wBAAsB,qBAAqB,CACzC,MAAM,EAAE,MAAM,GACb,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CAmC7B;AAED;;;;GAIG;AACH,wBAAsB,yBAAyB,CAC7C,IAAI,EAAE,MAAM,EACZ,MAAM,EAAE,MAAM,GACb,OAAO,CAAC,IAAI,CAAC,CAYf"}
+{"version":3,"file":"learnings-file-safety.d.ts","sourceRoot":"","sources":["../../src/core/learnings-file-safety.ts"],"names":[],"mappings":"AAUA;;;;;GAKG;AACH,wBAAgB,yBAAyB,CACvC,WAAW,EAAE,MAAM,EACnB,YAAY,EAAE,MAAM,GACnB;IAAE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CASpD;AAED;;;;GAIG;AACH,wBAAsB,qBAAqB,CACzC,MAAM,EAAE,MAAM,GACb,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CAyC7B;AAkBD;;;;GAIG;AACH,wBAAsB,yBAAyB,CAC7C,IAAI,EAAE,MAAM,EACZ,MAAM,EAAE,MAAM,GACb,OAAO,CAAC,IAAI,CAAC,CAYf"}