ushman-ledger 1.2.0 → 1.2.1

package/README.md

@@ -27,9 +27,20 @@ bun link ushman-ledger
 ## Library API
 
 ```ts
-import { buildValidatorResultRecord, openLedger } from 'ushman-ledger';
-
-const ledger = await openLedger('/path/to/workspace');
+import { readFile } from 'node:fs/promises';
+import {
+  appendCleanupWaveNote,
+  appendSemanticCleanupSummaryNote,
+  type BuildRecordInput,
+  buildChangeLogRecord,
+  buildValidatorResultRecord,
+  deriveFilesChangedFromPatch,
+  openLedger,
+} from 'ushman-ledger';
+
+const workspaceRoot = '/path/to/workspace';
+const ledger = await openLedger(workspaceRoot);
+const patchText = await readFile('/tmp/change.patch', 'utf8');
 
 await ledger.record({
   emitter: { tool: 'ushman-cli', version: '1.0.0' },
@@ -48,6 +59,21 @@ await ledger.record({
   summary: 'Apply websocket shim',
 });
 
+await ledger.record(
+  buildChangeLogRecord({
+    emitter: { tool: 'ushman-cli', version: '1.0.0' },
+    filesChanged: deriveFilesChangedFromPatch(patchText),
+    hypothesis: 'Smaller schema modules keep the public API stable.',
+    kind: 'change-log',
+    parityStatus: 'green',
+    phase: 'cleanup',
+    rollbackPlan: 'Revert the schema split.',
+    smokeResult: 'pass',
+    subkind: 'semantic-cleanup',
+    summary: 'Split schema modules',
+  }),
+);
+
 await ledger.record(
   buildValidatorResultRecord({
     emitter: { tool: 'ushman-doctor', version: '1.0.0' },
@@ -58,16 +84,32 @@ await ledger.record(
   }),
 );
 
+await appendCleanupWaveNote(workspaceRoot, {
+  body: 'Split schema definitions out of the monolithic entry module.',
+  phase: 'cleanup',
+  summary: 'Wave 1',
+});
+
+await appendSemanticCleanupSummaryNote(workspaceRoot, {
+  body: 'The latest semantic cleanup summary shown in workspace-narrative-md.',
+  phase: 'migration',
+  summary: 'Latest summary',
+});
+
 await ledger.render({ to: 'retro' });
 await ledger.render({ to: 'migration-log-md' });
+await ledger.renderTo({ to: 'migration-log-md', out: '/tmp/migration-log.md' });
 await ledger.archive('/tmp/ledger.tgz');
 ```
 
+Advanced builder wrappers can reuse the exported `BuildRecordInput<T>` helper type when they want the same input contract the built-in builders accept.
+
 ## CLI
 
 ```bash
 ushman-ledger record --workspace=<ws> --kind=tool-invocation --phase=capture --summary="capture started"
 ushman-ledger record --workspace=<ws> --kind=agent-patch --phase=cleanup --summary="capture git diff" --rationale="track working tree change" --diff-from-git=HEAD
+ushman-ledger record --workspace=<ws> --kind=change-log --subkind=smoke --phase=cleanup --summary="scope git diff" --diff-from-git=HEAD --git-paths=src/main.ts,src/cli.ts --git-diff-timeout-ms=10000 --git-diff-max-buffer-bytes=20971520
 ushman-ledger record --workspace=<ws> --kind=operator-decision --phase=cleanup --summary="manual override" --action=ledger-hand-edit --check-id=manual-review --rationale="operator edited the ledger after audit"
 ushman-ledger record --workspace=<ws> --kind=change-log --subkind=semantic-cleanup --phase=cleanup --summary="split schema modules" --diff=/tmp/change.patch --hypothesis="smaller schema modules keep the public API stable" --commands=$'bun test\nbun run typecheck' --smoke-result=pass --parity-status=green --rollback-plan="revert the schema split"
 ushman-ledger note regression --workspace=<ws> --phase=cleanup --summary="runtime drift" --body=/tmp/note.md
@@ -99,7 +141,15 @@ Valid render targets: `retro`, `jsonl`, `timeline-html`, `dependency-graph`, `mi
 - optional narrative fields: `hypothesis`, `commandsRun`, `smokeResult`, `smokeNotes`, `parityStatus`, `rollbackPlan`
 - `rollsBack`: required when `subkind=rollback`
 
+`deriveFilesChangedFromPatch()` is exported for library callers that want the same diff-to-file summary behavior as the CLI. Known limits:
+
+- It expects `diff --git` headers to delimit files.
+- It counts only textual hunk `+`/`-` lines, so binary or mode-only diffs can report zero line counts.
+- It keeps the post-image path when available and rejects diff blocks that cannot be mapped to normalized workspace-relative paths.
+
 `migration-log-md` renders only `change-log` entries. `workspace-narrative-md` renders only the dedicated narrative note subkinds.
+`render()` still returns a string for in-memory callers. `renderTo()` is the bounded-output alternative for large ledgers and can write to a callback or the canonical render file on disk.
+`renderTo()` writers receive sequential chunks, can return synchronously or asynchronously, and should throw only when the render should abort.
 
 ## Workspace prerequisite
 
@@ -167,7 +217,9 @@ Valid render targets: `retro`, `jsonl`, `timeline-html`, `dependency-graph`, `mi
 ## Git diff capture
 
 - `--diff-from-git=<ref>` runs `git diff <ref>` against the workspace working tree.
-- The CLI times out `git diff` after 30 seconds and reports a usage error instead of hanging indefinitely.
+- `--git-paths=<csv>` safely scopes `git diff` to literal normalized workspace-relative paths. The CLI passes them after `--`, so pathspec magic and shell token splitting are intentionally not supported here.
+- `--git-diff-timeout-ms=<ms>` and `--git-diff-max-buffer-bytes=<bytes>` override the default 30 second timeout and 10 MiB stdout buffer for the git diff helper.
+- The CLI reports usage errors for missing `git`, timed out git diffs, invalid scoped paths, and buffer overflows instead of surfacing raw child-process failures.
 - This is the only CLI feature that depends on an external binary. `git` must be available in `PATH`.
 
 ## Storage shape
@@ -200,5 +252,5 @@ bun run bench:scale
 
 ## Scale benchmark
 
-- `bun run bench:scale` creates a temporary workspace and benchmarks large-ledger paths for population, limited reads, repeated coverage, and repeated doctor runs.
+- `bun run bench:scale` creates a temporary workspace and benchmarks large-ledger paths for population, limited reads, repeated coverage, repeated doctor runs, and markdown render paths.
 - Override the defaults with environment variables such as `LEDGER_BENCH_ENTRY_COUNT=100000` and `LEDGER_BENCH_CANDIDATE_FILE_COUNT=10000`.

package/dist/builders.d.ts

@@ -1,5 +1,5 @@
 import { type LedgerRecord } from './schema/entry.ts';
-type BuildRecordInput<TRecord extends LedgerRecord> = Omit<TRecord, 'kind'> & {
+export type BuildRecordInput<TRecord extends LedgerRecord> = Omit<TRecord, 'kind'> & {
     readonly kind?: TRecord['kind'];
 };
 /** Build an `operator-decision` record with a validated structured payload. */
@@ -182,5 +182,4 @@ export declare const buildStripDecisionRevertedRecord: (input: BuildRecordInput<
     phase: "capture" | "intake" | "seed" | "vendor-extract" | "cleanup" | "parity" | "characterize" | "equiv" | "analyze" | "recover" | "ship" | "migration";
     summary: string;
 };
-export {};
 //# sourceMappingURL=builders.d.ts.map

package/dist/builders.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"builders.d.ts","sourceRoot":"","sources":["../src/builders.ts"],"names":[],"mappings":"AACA,OAAO,EAGH,KAAK,YAAY,EAIpB,MAAM,mBAAmB,CAAC;AAE3B,KAAK,gBAAgB,CAAC,OAAO,SAAS,YAAY,IAAI,IAAI,CAAC,OAAO,EAAE,MAAM,CAAC,GAAG;IAC1E,QAAQ,CAAC,IAAI,CAAC,EAAE,OAAO,CAAC,MAAM,CAAC,CAAC;CACnC,CAAC;AAEF,+EAA+E;AAC/E,eAAO,MAAM,2BAA2B,GACpC,OAAO,gBAAgB,CAAC,OAAO,CAAC,YAAY,EAAE;IAAE,IAAI,EAAE,mBAAmB,CAAA;CAAE,CAAC,CAAC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAM3E,CAAC;AAEP,yCAAyC;AACzC,eAAO,MAAM,0BAA0B,GACnC,OAAO,gBAAgB,CAAC,OAAO,CAAC,YAAY,EAAE;IAAE,IAAI,EAAE,kBAAkB,CAAA;CAAE,CAAC,CAAC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAK1E,CAAC;AAEP,sEAAsE;AACtE,eAAO,MAAM,qBAAqB,GAAI,OAAO,gBAAgB,CAAC,OAAO,CAAC,YAAY,EAAE;IAAE,IAAI,EAAE,YAAY,CAAA;CAAE,CAAC,CAAC;;;;;;;;;;;;;;;;;;;;;;;;;;;CAItG,CAAC;AAEP,mCAAmC;AACnC,eAAO,MAAM,oBAAoB,GAAI,OAAO,gBAAgB,CAAC,OAAO,CAAC,YAAY,EAAE;IAAE,IAAI,EAAE,YAAY,CAAA;CAAE,CAAC,CAAC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAIrG,CAAC;AAEP,gDAAgD;AAChD,eAAO,MAAM,gCAAgC,GACzC,OAAO,gBAAgB,CAAC,OAAO,CAAC,YAAY,EAAE;IAAE,IAAI,EAAE,yBAAyB,CAAA;CAAE,CAAC,CAAC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAKjF,CAAC"}
+{"version":3,"file":"builders.d.ts","sourceRoot":"","sources":["../src/builders.ts"],"names":[],"mappings":"AACA,OAAO,EAGH,KAAK,YAAY,EAIpB,MAAM,mBAAmB,CAAC;AAE3B,MAAM,MAAM,gBAAgB,CAAC,OAAO,SAAS,YAAY,IAAI,IAAI,CAAC,OAAO,EAAE,MAAM,CAAC,GAAG;IACjF,QAAQ,CAAC,IAAI,CAAC,EAAE,OAAO,CAAC,MAAM,CAAC,CAAC;CACnC,CAAC;AAEF,+EAA+E;AAC/E,eAAO,MAAM,2BAA2B,GACpC,OAAO,gBAAgB,CAAC,OAAO,CAAC,YAAY,EAAE;IAAE,IAAI,EAAE,mBAAmB,CAAA;CAAE,CAAC,CAAC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAM3E,CAAC;AAEP,yCAAyC;AACzC,eAAO,MAAM,0BAA0B,GACnC,OAAO,gBAAgB,CAAC,OAAO,CAAC,YAAY,EAAE;IAAE,IAAI,EAAE,kBAAkB,CAAA;CAAE,CAAC,CAAC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAK1E,CAAC;AAEP,sEAAsE;AACtE,eAAO,MAAM,qBAAqB,GAAI,OAAO,gBAAgB,CAAC,OAAO,CAAC,YAAY,EAAE;IAAE,IAAI,EAAE,YAAY,CAAA;CAAE,CAAC,CAAC;;;;;;;;;;;;;;;;;;;;;;;;;;;CAItG,CAAC;AAEP,mCAAmC;AACnC,eAAO,MAAM,oBAAoB,GAAI,OAAO,gBAAgB,CAAC,OAAO,CAAC,YAAY,EAAE;IAAE,IAAI,EAAE,YAAY,CAAA;CAAE,CAAC,CAAC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAIrG,CAAC;AAEP,gDAAgD;AAChD,eAAO,MAAM,gCAAgC,GACzC,OAAO,gBAAgB,CAAC,OAAO,CAAC,YAAY,EAAE;IAAE,IAAI,EAAE,yBAAyB,CAAA;CAAE,CAAC,CAAC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAKjF,CAAC"}

package/dist/cli.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":";AAmDA,KAAK,UAAU,GAAG;IACd,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,cAAc,EAAE;QACrB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;QACtB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;KAC5B,CAAC;IACF,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC,cAAc,GAAG,aAAa,CAAC,UAAU,GAAG,MAAM,CAAC,CAAC;IAC3E,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC,cAAc,CAAC;IACvC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC,cAAc,CAAC;CAC1C,CAAC;AAiwBF,eAAO,MAAM,YAAY,GAAU,MAAM,SAAS,MAAM,EAAE,EAAE,UAAS,OAAO,CAAC,UAAU,CAAM,KAAG,OAAO,CAAC,MAAM,CAqC7G,CAAC;AAEF,eAAO,MAAM,IAAI,GAAU,OAAM,SAAS,MAAM,EAA0B,KAAG,OAAO,CAAC,MAAM,CAE1F,CAAC"}
+{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":";AAuDA,KAAK,UAAU,GAAG;IACd,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,cAAc,EAAE;QACrB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;QACtB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;KAC5B,CAAC;IACF,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC,cAAc,GAAG,aAAa,CAAC,UAAU,GAAG,MAAM,CAAC,CAAC;IAC3E,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC,cAAc,CAAC;IACvC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC,cAAc,CAAC;CAC1C,CAAC;AAi5BF,eAAO,MAAM,YAAY,GAAU,MAAM,SAAS,MAAM,EAAE,EAAE,UAAS,OAAO,CAAC,UAAU,CAAM,KAAG,OAAO,CAAC,MAAM,CAqC7G,CAAC;AAEF,eAAO,MAAM,IAAI,GAAU,OAAM,SAAS,MAAM,EAA0B,KAAG,OAAO,CAAC,MAAM,CAE1F,CAAC"}

package/dist/cli.js

@@ -12,8 +12,8 @@ import { ChangeLogParityStatusSchema, ChangeLogSmokeResultSchema, ChangeLogSubki
 import { NoteSubkindSchema } from "./schema/note.js";
 import { LEDGER_LIBRARY_VERSION } from "./version.js";
 const execFileAsync = promisify(execFile);
-const GIT_DIFF_MAX_BUFFER_BYTES = 10 * 1024 * 1024;
-const GIT_DIFF_TIMEOUT_MS = 30_000;
+const DEFAULT_GIT_DIFF_MAX_BUFFER_BYTES = 10 * 1024 * 1024;
+const DEFAULT_GIT_DIFF_TIMEOUT_MS = 30_000;
 const RENDER_TARGETS = [
     'retro',
     'jsonl',
@@ -22,6 +22,7 @@ const RENDER_TARGETS = [
     'migration-log-md',
     'workspace-narrative-md',
 ];
+const GIT_DIFF_FLAG_NAMES = ['git-diff-max-buffer-bytes', 'git-diff-timeout-ms', 'git-paths'];
 const CHANGE_LOG_RECORD_ONLY_FLAGS = [
     'commands',
     'commands-from',
@@ -34,6 +35,7 @@ const CHANGE_LOG_RECORD_ONLY_FLAGS = [
     'smoke-result',
     'subkind',
 ];
+const renderRecordUsage = (commandName) => `${commandName} record [--workspace=<ws>] --kind=<kind> --phase=<phase> --summary="..." [--rationale="..."] [--action=<operator-action>] [--check-id=<check-id>] [--diff=<patch-file>] [--diff-from-git=<ref>] [--git-paths=<csv>] [--git-diff-timeout-ms=<ms>] [--git-diff-max-buffer-bytes=<bytes>] [--idempotency-key=<key>] [--subkind=<change-log-subkind>] [--files-changed=<csv>] [--hypothesis="..."] [--commands="cmd1\ncmd2" | --commands-from=<file>] [--smoke-result=<result>] [--smoke-notes="..."] [--parity-status=<status>] [--rollback-plan="..."] [--rolls-back=<entry-id>] [--from-stdin]`;
 class CliUsageError extends Error {
 }
 const DEFAULT_CONTEXT = {
@@ -55,7 +57,7 @@ const renderValidValues = () => `Valid values:
 const renderHelp = (commandName) => `${commandName}
 
 Commands:
-  ${commandName} record [--workspace=<ws>] --kind=<kind> --phase=<phase> --summary="..." [--rationale="..."] [--action=<operator-action>] [--check-id=<check-id>] [--diff=<patch-file>] [--diff-from-git=<ref>] [--idempotency-key=<key>] [--subkind=<change-log-subkind>] [--files-changed=<csv>] [--hypothesis="..."] [--commands="cmd1\ncmd2" | --commands-from=<file>] [--smoke-result=<result>] [--smoke-notes="..."] [--parity-status=<status>] [--rollback-plan="..."] [--rolls-back=<entry-id>] [--from-stdin]
+  ${renderRecordUsage(commandName)}
   ${commandName} note <subkind> [--workspace=<ws>] --phase=<phase> --summary="..." [--body=<markdown-file>] [--from-stdin]
   ${commandName} list [--workspace=<ws>] [--phase=<phase>] [--kind=<kind>] [--since=<iso>] [--limit=<n>] [--json]
   ${commandName} show [--workspace=<ws>] <entry-id>
@@ -69,7 +71,7 @@ ${renderValidValues()}`;
 const renderCommandHelp = (commandName, command) => {
     switch (command) {
         case 'record':
-            return `${commandName} record [--workspace=<ws>] --kind=<kind> --phase=<phase> --summary="..." [--rationale="..."] [--action=<operator-action>] [--check-id=<check-id>] [--diff=<patch-file>] [--diff-from-git=<ref>] [--idempotency-key=<key>] [--subkind=<change-log-subkind>] [--files-changed=<csv>] [--hypothesis="..."] [--commands="cmd1\ncmd2" | --commands-from=<file>] [--smoke-result=<result>] [--smoke-notes="..."] [--parity-status=<status>] [--rollback-plan="..."] [--rolls-back=<entry-id>] [--from-stdin]
+            return `${renderRecordUsage(commandName)}
 
 ${renderValidValues()}`;
         case 'note':
@@ -159,13 +161,64 @@ const ensureFileExists = async (filePath, flagName) => {
         throw error;
     }
 };
-const materializeGitDiff = async (workspaceRoot, gitRef) => {
+const getErrorCode = (error) => typeof error === 'object' && error !== null && 'code' in error ? error.code : undefined;
+const parsePositiveIntegerFlag = ({ defaultValue, flagName, flags, }) => {
+    const raw = getFlag(flags, flagName);
+    if (!raw) {
+        return defaultValue;
+    }
+    if (!/^[1-9]\d*$/u.test(raw)) {
+        throw new CliUsageError(`Invalid --${flagName} value: ${raw}. Expected a positive integer.`);
+    }
+    return Number.parseInt(raw, 10);
+};
+const parseWorkspaceRelativePathCsv = ({ flagName, raw }) => {
+    const uniquePaths = [
+        ...new Set(raw
+            .split(',')
+            .map((value) => value.trim())
+            .filter((value) => value.length > 0)
+            .map((filePath) => {
+            try {
+                return v.parse(WorkspaceRelativePathSchema, filePath);
+            }
+            catch {
+                throw new CliUsageError(`--${flagName} path is not a normalized workspace-relative path: ${filePath}`);
+            }
+        })),
+    ];
+    if (uniquePaths.length === 0) {
+        throw new CliUsageError(`--${flagName} must include at least one workspace-relative path.`);
+    }
+    return uniquePaths;
+};
+const isGitDiffMaxBufferError = (error) => {
+    const code = getErrorCode(error);
+    if (code === 'ERR_CHILD_PROCESS_STDIO_MAXBUFFER') {
+        return true;
+    }
+    return error instanceof RangeError && error.message.includes('maxBuffer');
+};
+const isGitDiffTimeoutError = (error) => {
+    const code = getErrorCode(error);
+    if (code === 'ETIMEDOUT') {
+        return true;
+    }
+    return (typeof error === 'object' &&
+        error !== null &&
+        'killed' in error &&
+        'signal' in error &&
+        error.killed === true &&
+        error.signal === 'SIGTERM');
+};
+const materializeGitDiff = async ({ gitOptions, gitRef, workspaceRoot, }) => {
     let tempDir;
     try {
-        const { stdout } = await execFileAsync('git', ['diff', gitRef], {
+        const gitArgs = gitOptions.scopedPaths.length === 0 ? ['diff', gitRef] : ['diff', gitRef, '--', ...gitOptions.scopedPaths];
+        const { stdout } = await execFileAsync('git', gitArgs, {
             cwd: workspaceRoot,
-            maxBuffer: GIT_DIFF_MAX_BUFFER_BYTES,
-            timeout: GIT_DIFF_TIMEOUT_MS,
+            maxBuffer: gitOptions.maxBufferBytes,
+            timeout: gitOptions.timeoutMs,
         });
         tempDir = await mkdtemp(path.join(os.tmpdir(), 'ushman-ledger-git-diff-'));
         const patchPath = path.join(tempDir, 'patch.diff');
@@ -176,11 +229,14 @@ const materializeGitDiff = async (workspaceRoot, gitRef) => {
         if (tempDir) {
             await rm(tempDir, { force: true, recursive: true });
         }
-        if (error.code === 'ENOENT') {
+        if (getErrorCode(error) === 'ENOENT') {
             throw new CliUsageError('git is required for --diff-from-git and was not found in PATH.');
         }
-        if (error.code === 'ETIMEDOUT') {
-            throw new CliUsageError(`git diff ${gitRef} timed out after ${GIT_DIFF_TIMEOUT_MS}ms. Narrow the diff or run git manually.`);
+        if (isGitDiffTimeoutError(error)) {
+            throw new CliUsageError(`git diff ${gitRef} timed out after ${gitOptions.timeoutMs}ms. Narrow the diff or increase --git-diff-timeout-ms.`);
+        }
+        if (isGitDiffMaxBufferError(error)) {
+            throw new CliUsageError(`git diff ${gitRef} exceeded the configured stdout buffer (${gitOptions.maxBufferBytes} bytes). Narrow the diff or increase --git-diff-max-buffer-bytes.`);
         }
         throw error;
     }
@@ -196,16 +252,13 @@ const parseJsonInput = (text, sourceLabel) => {
 const print = (context, text) => {
     context.stdout.write(text.endsWith('\n') ? text : `${text}\n`);
 };
-const parseLimit = (flags) => {
-    const raw = getFlag(flags, 'limit');
-    if (!raw) {
-        return undefined;
-    }
-    if (!/^[1-9]\d*$/u.test(raw)) {
-        throw new CliUsageError(`Invalid --limit value: ${raw}`);
-    }
-    return Number.parseInt(raw, 10);
-};
+const parseLimit = (flags) => getFlag(flags, 'limit')
+    ? parsePositiveIntegerFlag({
+        defaultValue: 0,
+        flagName: 'limit',
+        flags,
+    })
+    : undefined;
 const parseOptionalKind = (flags) => {
     const kind = getFlag(flags, 'kind');
     if (!kind) {
@@ -287,25 +340,30 @@ const parseOptionalChangeLogPicklist = ({ flagName, flags, options, }) => {
     }
     return value;
 };
-const parseFilesChangedCsv = (raw) => {
-    const uniquePaths = [
-        ...new Set(raw
-            .split(',')
-            .map((value) => value.trim())
-            .filter((value) => value.length > 0)
-            .map((filePath) => {
-            try {
-                return v.parse(WorkspaceRelativePathSchema, filePath);
-            }
-            catch {
-                throw new CliUsageError(`--files-changed path is not a normalized workspace-relative path: ${filePath}`);
-            }
-        })),
-    ];
-    if (uniquePaths.length === 0) {
-        throw new CliUsageError('--files-changed must include at least one workspace-relative path.');
-    }
-    return uniquePaths.map((filePath) => ({ path: filePath }));
+const parseFilesChangedCsv = (raw) => parseWorkspaceRelativePathCsv({
+    flagName: 'files-changed',
+    raw,
+}).map((filePath) => ({ path: filePath }));
+const parseGitDiffOptions = (flags) => {
+    const gitPaths = getFlag(flags, 'git-paths');
+    return {
+        maxBufferBytes: parsePositiveIntegerFlag({
+            defaultValue: DEFAULT_GIT_DIFF_MAX_BUFFER_BYTES,
+            flagName: 'git-diff-max-buffer-bytes',
+            flags,
+        }),
+        scopedPaths: gitPaths
+            ? parseWorkspaceRelativePathCsv({
+                flagName: 'git-paths',
+                raw: gitPaths,
+            })
+            : [],
+        timeoutMs: parsePositiveIntegerFlag({
+            defaultValue: DEFAULT_GIT_DIFF_TIMEOUT_MS,
+            flagName: 'git-diff-timeout-ms',
+            flags,
+        }),
+    };
 };
 const readCommandLines = async (flags) => {
     const inlineCommands = getFlag(flags, 'commands');
@@ -323,32 +381,65 @@ const readCommandLines = async (flags) => {
     }
     return undefined;
 };
+const validateGitDiffFlagUsage = (flags, diffFromGitProvided) => {
+    if (diffFromGitProvided) {
+        return;
+    }
+    const usedGitFlags = getUsedFlags(flags, GIT_DIFF_FLAG_NAMES);
+    if (usedGitFlags.length === 0) {
+        return;
+    }
+    throw new CliUsageError(`${usedGitFlags.join(', ')} ${usedGitFlags.length === 1 ? 'is' : 'are'} only supported with --diff-from-git.`);
+};
+const assertDiffRecordKindSupported = (kind) => {
+    if (kind === 'agent-patch' || kind === 'operator-patch' || kind === 'change-log') {
+        return;
+    }
+    throw new CliUsageError('--diff and --diff-from-git are only supported for patch and change-log records.');
+};
+const readPatchText = async (diffPath) => readFile(diffPath, 'utf8');
+const readPatchTextForRecordKind = async (kind, diffPath) => {
+    if (kind === 'change-log' || kind === 'agent-patch' || kind === 'operator-patch') {
+        return readPatchText(diffPath);
+    }
+    return undefined;
+};
+const deriveAffectedFiles = (patchText) => [
+    ...new Set(deriveFilesChangedFromPatch(patchText).map((fileChange) => fileChange.path)),
+];
 const resolveDiffInput = async ({ flags, kind, workspaceRoot, }) => {
     const diffPath = getFlag(flags, 'diff');
     const diffFromGit = getFlag(flags, 'diff-from-git');
-    if (diffPath && diffFromGit) {
+    const diffFromGitProvided = hasFlag(flags, 'diff-from-git');
+    if (diffPath && diffFromGitProvided) {
         throw new CliUsageError('Use either --diff or --diff-from-git, not both.');
     }
-    if (!diffPath && !diffFromGit) {
-        return {};
+    if (diffFromGitProvided && diffFromGit === '') {
+        throw new CliUsageError('--diff-from-git must not be empty.');
     }
-    if (kind !== 'agent-patch' && kind !== 'operator-patch' && kind !== 'change-log') {
-        throw new CliUsageError('--diff and --diff-from-git are only supported for patch and change-log records.');
+    validateGitDiffFlagUsage(flags, diffFromGitProvided);
+    if (!diffPath && !diffFromGitProvided) {
+        return {};
     }
+    assertDiffRecordKindSupported(kind);
     if (diffPath) {
         const resolvedDiffPath = path.resolve(diffPath);
         await ensureFileExists(resolvedDiffPath, '--diff');
         return {
             diffPath: resolvedDiffPath,
-            patchText: kind === 'change-log' ? await readFile(resolvedDiffPath, 'utf8') : undefined,
+            patchText: await readPatchTextForRecordKind(kind, resolvedDiffPath),
         };
     }
-    const materialized = await materializeGitDiff(workspaceRoot, diffFromGit ?? '');
+    const materialized = await materializeGitDiff({
+        gitOptions: parseGitDiffOptions(flags),
+        gitRef: diffFromGit ?? '',
+        workspaceRoot,
+    });
     return {
         cleanupTempDir: materialized.tempDir,
         diffPath: materialized.patchPath,
         gitRef: diffFromGit,
-        patchText: kind === 'change-log' ? await readFile(materialized.patchPath, 'utf8') : undefined,
+        patchText: await readPatchTextForRecordKind(kind, materialized.patchPath),
     };
 };
 const validateRecordStdinFlags = (flags) => {
@@ -361,6 +452,9 @@ const validateRecordStdinFlags = (flags) => {
         'diff',
         'diff-from-git',
         'files-changed',
+        'git-diff-max-buffer-bytes',
+        'git-diff-timeout-ms',
+        'git-paths',
         'hypothesis',
         'idempotency-key',
         'kind',
@@ -446,10 +540,16 @@ const applyPatchInputToRecord = async ({ kind, patchInput, record, }) => {
             diffPath: patchInput.diffPath,
             links: patchInput.gitRef
                 ? {
+                    affectedFiles: patchInput.patchText ? deriveAffectedFiles(patchInput.patchText) : undefined,
                     ...record.links,
                     gitRef: patchInput.gitRef,
                 }
-                : record.links,
+                : patchInput.patchText
+                    ? {
+                        affectedFiles: deriveAffectedFiles(patchInput.patchText),
+                        ...record.links,
+                    }
+                    : record.links,
         },
     };
 };
@@ -640,16 +740,19 @@ const runTailCli = async (parsed, context) => runListCli({
 const runRenderCli = async (parsed, context) => {
     const target = parseRenderTarget(parsed.flags);
     const ledger = await openLedger(getWorkspaceRoot(parsed.flags));
-    const content = await ledger.render({
+    const renderOptions = {
         limit: parseLimit(parsed.flags),
         out: getFlag(parsed.flags, 'out'),
         phase: parseOptionalPhase(parsed.flags),
         since: parseSince(parsed.flags),
         to: target,
-    });
-    if (!getFlag(parsed.flags, 'out')) {
-        print(context, content);
+    };
+    if (renderOptions.out) {
+        await ledger.renderTo(renderOptions);
+        return 0;
     }
+    const content = await ledger.render(renderOptions);
+    print(context, content);
     return 0;
 };
 const runArchiveCli = async (parsed, context) => {

package/dist/doctor.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"doctor.d.ts","sourceRoot":"","sources":["../src/doctor.ts"],"names":[],"mappings":"AAMA,OAAO,EAAmB,KAAK,mBAAmB,EAAE,MAAM,eAAe,CAAC;AA8V1E,eAAO,MAAM,eAAe,GACxB,eAAe,MAAM,EACrB,UAAS;IAAE,QAAQ,CAAC,WAAW,CAAC,EAAE,OAAO,CAAC;IAAC,QAAQ,CAAC,KAAK,CAAC,EAAE,mBAAmB,CAAA;CAAO;;;EAyCzF,CAAC"}
+{"version":3,"file":"doctor.d.ts","sourceRoot":"","sources":["../src/doctor.ts"],"names":[],"mappings":"AAMA,OAAO,EAAmB,KAAK,mBAAmB,EAAE,MAAM,eAAe,CAAC;AA+V1E,eAAO,MAAM,eAAe,GACxB,eAAe,MAAM,EACrB,UAAS;IAAE,QAAQ,CAAC,WAAW,CAAC,EAAE,OAAO,CAAC;IAAC,QAAQ,CAAC,KAAK,CAAC,EAAE,mBAAmB,CAAA;CAAO;;;EAyCzF,CAAC"}

package/dist/doctor.js

@@ -200,8 +200,8 @@ const collectDoctorState = async (workspaceRoot, manifest, readIndex) => {
             inspectDoctorEntry({
                 blobChecks,
                 checkpointEntries,
-                entry: resolvedEntry.entry,
                 entriesByIdempotencyKey,
+                entry: resolvedEntry.entry,
                 issues,
                 latestByPhase,
                 manifest,

package/dist/handle.d.ts

@@ -4,6 +4,30 @@ import { type LedgerFilter } from './list.ts';
 import { appendNote, type NoteBody } from './note.ts';
 import type { LedgerEntry, LedgerPhase } from './schema/entry.ts';
 export type RenderTarget = 'dependency-graph' | 'jsonl' | 'migration-log-md' | 'retro' | 'timeline-html' | 'workspace-narrative-md';
+/**
+ * Chunk writer used by `renderTo()` for bounded render emission.
+ *
+ * Writers may complete synchronously or asynchronously. Throwing rejects the render and causes any in-progress
+ * atomic output file to be aborted.
+ */
+export type RenderWriter = (chunk: string) => Promise<void> | void;
+/** Options for `render()`, which returns the rendered text and optionally mirrors it to disk. */
+export type LedgerRenderOptions = {
+    readonly limit?: number;
+    readonly out?: string;
+    readonly phase?: LedgerPhase;
+    readonly since?: string;
+    readonly to: RenderTarget;
+};
+/** Options for `renderTo()`, which writes to a callback and/or canonical render file without buffering the full output. */
+export type LedgerRenderToOptions = {
+    readonly limit?: number;
+    readonly out?: string;
+    readonly phase?: LedgerPhase;
+    readonly since?: string;
+    readonly to: RenderTarget;
+    readonly write?: RenderWriter;
+};
 export type LedgerHandle = {
     readonly archive: (outPath: string) => Promise<{
         integrityHash: string;
@@ -17,14 +41,10 @@ export type LedgerHandle = {
     readonly record: (entry: unknown) => Promise<{
         id: string;
     }>;
-    readonly render: (options: {
-        out?: string;
-        limit?: number;
-        phase?: LedgerPhase;
-        since?: string;
-        to: RenderTarget;
-    }) => Promise<string>;
+    readonly render: (options: LedgerRenderOptions) => Promise<string>;
+    readonly renderTo: (options: LedgerRenderToOptions) => Promise<void>;
     readonly show: (entryId: string) => Promise<LedgerEntry | null>;
 };
+/** Open a workspace ledger handle after reconciling any pending crash-recovery state. */
 export declare const openLedger: (workspaceRoot: string) => Promise<LedgerHandle>;
 //# sourceMappingURL=handle.d.ts.map

package/dist/handle.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"handle.d.ts","sourceRoot":"","sources":["../src/handle.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,eAAe,EAAE,MAAM,eAAe,CAAC;AAChD,OAAO,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAE9C,OAAO,EAA8B,KAAK,YAAY,EAAe,MAAM,WAAW,CAAC;AACvF,OAAO,EAAE,UAAU,EAAE,KAAK,QAAQ,EAAE,MAAM,WAAW,CAAC;AAStD,OAAO,KAAK,EAAE,WAAW,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAGlE,MAAM,MAAM,YAAY,GAClB,kBAAkB,GAClB,OAAO,GACP,kBAAkB,GAClB,OAAO,GACP,eAAe,GACf,wBAAwB,CAAC;AAkD/B,MAAM,MAAM,YAAY,GAAG;IACvB,QAAQ,CAAC,OAAO,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,OAAO,CAAC;QAAE,aAAa,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IAC1E,QAAQ,CAAC,eAAe,EAAE,MAAM,OAAO,CAAC,OAAO,CAAC,UAAU,CAAC,OAAO,eAAe,CAAC,CAAC,CAAC,CAAC;IACrF,QAAQ,CAAC,MAAM,EAAE,MAAM,OAAO,CAAC,OAAO,CAAC,UAAU,CAAC,OAAO,eAAe,CAAC,CAAC,CAAC,CAAC;IAC5E,QAAQ,CAAC,IAAI,EAAE,CAAC,MAAM,CAAC,EAAE,YAAY,KAAK,aAAa,CAAC,WAAW,CAAC,CAAC;IACrE,QAAQ,CAAC,IAAI,EAAE,CAAC,OAAO,EAAE,UAAU,CAAC,OAAO,UAAU,CAAC,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,QAAQ,KAAK,OAAO,CAAC;QAAE,EAAE,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IACtG,QAAQ,CAAC,MAAM,EAAE,CAAC,KAAK,EAAE,OAAO,KAAK,OAAO,CAAC;QAAE,EAAE,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IAC7D,QAAQ,CAAC,MAAM,EAAE,CAAC,OAAO,EAAE;QACvB,GAAG,CAAC,EAAE,MAAM,CAAC;QACb,KAAK,CAAC,EAAE,MAAM,CAAC;QACf,KAAK,CAAC,EAAE,WAAW,CAAC;QACpB,KAAK,CAAC,EAAE,MAAM,CAAC;QACf,EAAE,EAAE,YAAY,CAAC;KACpB,KAAK,OAAO,CAAC,MAAM,CAAC,CAAC;IACtB,QAAQ,CAAC,IAAI,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,OAAO,CAAC,WAAW,GAAG,IAAI,CAAC,CAAC;CACnE,CAAC;AAEF,eAAO,MAAM,UAAU,GAAU,eAAe,MAAM,KAAG,OAAO,CAAC,YAAY,CAyC5E,CAAC"}
+{"version":3,"file":"handle.d.ts","sourceRoot":"","sources":["../src/handle.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,eAAe,EAAE,MAAM,eAAe,CAAC;AAChD,OAAO,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAE9C,OAAO,EAA8B,KAAK,YAAY,EAAe,MAAM,WAAW,CAAC;AACvF,OAAO,EAAE,UAAU,EAAE,KAAK,QAAQ,EAAE,MAAM,WAAW,CAAC;AAStD,OAAO,KAAK,EAAE,WAAW,EAAc,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAG9E,MAAM,MAAM,YAAY,GAClB,kBAAkB,GAClB,OAAO,GACP,kBAAkB,GAClB,OAAO,GACP,eAAe,GACf,wBAAwB,CAAC;AAE/B;;;;;GAKG;AACH,MAAM,MAAM,YAAY,GAAG,CAAC,KAAK,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC;AAEnE,iGAAiG;AACjG,MAAM,MAAM,mBAAmB,GAAG;IAC9B,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,KAAK,CAAC,EAAE,WAAW,CAAC;IAC7B,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,EAAE,EAAE,YAAY,CAAC;CAC7B,CAAC;AAEF,2HAA2H;AAC3H,MAAM,MAAM,qBAAqB,GAAG;IAChC,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,KAAK,CAAC,EAAE,WAAW,CAAC;IAC7B,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,EAAE,EAAE,YAAY,CAAC;IAC1B,QAAQ,CAAC,KAAK,CAAC,EAAE,YAAY,CAAC;CACjC,CAAC;AA4GF,MAAM,MAAM,YAAY,GAAG;IACvB,QAAQ,CAAC,OAAO,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,OAAO,CAAC;QAAE,aAAa,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IAC1E,QAAQ,CAAC,eAAe,EAAE,MAAM,OAAO,CAAC,OAAO,CAAC,UAAU,CAAC,OAAO,eAAe,CAAC,CAAC,CAAC,CAAC;IACrF,QAAQ,CAAC,MAAM,EAAE,MAAM,OAAO,CAAC,OAAO,CAAC,UAAU,CAAC,OAAO,eAAe,CAAC,CAAC,CAAC,CAAC;IAC5E,QAAQ,CAAC,IAAI,EAAE,CAAC,MAAM,CAAC,EAAE,YAAY,KAAK,aAAa,CAAC,WAAW,CAAC,CAAC;IACrE,QAAQ,CAAC,IAAI,EAAE,CAAC,OAAO,EAAE,UAAU,CAAC,OAAO,UAAU,CAAC,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,QAAQ,KAAK,OAAO,CAAC;QAAE,EAAE,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IACtG,QAAQ,CAAC,MAAM,EAAE,CAAC,KAAK,EAAE,OAAO,KAAK,OAAO,CAAC;QAAE,EAAE,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IAC7D,QAAQ,CAAC,MAAM,EAAE,CAAC,OAAO,EAAE,mBAAmB,KAAK,OAAO,CAAC,MAAM,CAAC,CAAC;IACnE,QAAQ,CAAC,QAAQ,EAAE,CAAC,OAAO,EAAE,qBAAqB,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IACrE,QAAQ,CAAC,IAAI,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,OAAO,CAAC,WAAW,GAAG,IAAI,CAAC,CAAC;CACnE,CAAC;AAEF,yFAAyF;AACzF,eAAO,MAAM,UAAU,GAAU,eAAe,MAAM,KAAG,OAAO,CAAC,YAAY,CAyF5E,CAAC"}