ushman-ledger 1.2.1 → 1.3.0

package/dist/builders.d.ts

@@ -147,6 +147,39 @@ export declare const buildChangeLogRecord: (input: BuildRecordInput<Extract<Ledg
     phase: "capture" | "intake" | "seed" | "vendor-extract" | "cleanup" | "parity" | "characterize" | "equiv" | "analyze" | "recover" | "ship" | "migration";
     summary: string;
 };
+/** Build a `stage-write` record. */
+export declare const buildStageWriteRecord: (input: BuildRecordInput<Extract<LedgerRecord, {
+    kind: "stage-write";
+}>>) => {
+    filePath: string;
+    kind: "stage-write";
+    rationale: string;
+    stage: "intake" | "seed" | "vendor-extract" | "cleanup" | "candidate-promotion";
+    details?: {
+        [x: string]: unknown;
+    } | undefined;
+    emitter: {
+        tool: string;
+        user?: string | undefined;
+        version: string;
+    };
+    idempotencyKey?: string | undefined;
+    links?: ({
+        affectedFiles?: string[] | undefined;
+        blobs?: string[] | undefined;
+        briefId?: string | undefined;
+        correctsLedgerId?: string | undefined;
+        gitRef?: string | undefined;
+        idempotencyKey?: string | undefined;
+        stripDecisionId?: string | undefined;
+        supersedesLedgerId?: string | undefined;
+        validatorVerdictId?: string | undefined;
+    } & {
+        [key: string]: unknown;
+    }) | undefined;
+    phase: "capture" | "intake" | "seed" | "vendor-extract" | "cleanup" | "parity" | "characterize" | "equiv" | "analyze" | "recover" | "ship" | "migration";
+    summary: string;
+};
 /** Build a `strip-decision-reverted` record. */
 export declare const buildStripDecisionRevertedRecord: (input: BuildRecordInput<Extract<LedgerRecord, {
     kind: "strip-decision-reverted";

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,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"}
+{"version":3,"file":"builders.d.ts","sourceRoot":"","sources":["../src/builders.ts"],"names":[],"mappings":"AACA,OAAO,EAGH,KAAK,YAAY,EAKpB,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,oCAAoC;AACpC,eAAO,MAAM,qBAAqB,GAAI,OAAO,gBAAgB,CAAC,OAAO,CAAC,YAAY,EAAE;IAAE,IAAI,EAAE,aAAa,CAAA;CAAE,CAAC,CAAC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAQvG,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/builders.js

@@ -1,5 +1,5 @@
 import * as v from 'valibot';
-import { ChangeLogRecordSchema, CorrectionRecordSchema, OperatorDecisionRecordSchema, StripDecisionRevertedRecordSchema, ValidatorResultRecordSchema, } from "./schema/entry.js";
+import { ChangeLogRecordSchema, CorrectionRecordSchema, OperatorDecisionRecordSchema, StageWriteRecordSchema, StripDecisionRevertedRecordSchema, ValidatorResultRecordSchema, } from "./schema/entry.js";
 /** Build an `operator-decision` record with a validated structured payload. */
 export const buildOperatorDecisionRecord = (input) => v.parse(OperatorDecisionRecordSchema, {
     ...input,
@@ -21,6 +21,15 @@ export const buildChangeLogRecord = (input) => v.parse(ChangeLogRecordSchema, {
     ...input,
     kind: 'change-log',
 });
+/** Build a `stage-write` record. */
+export const buildStageWriteRecord = (input) => v.parse(StageWriteRecordSchema, {
+    ...input,
+    kind: 'stage-write',
+    links: {
+        ...(input.links ?? {}),
+        affectedFiles: [...new Set([...(input.links?.affectedFiles ?? []), input.filePath])],
+    },
+});
 /** Build a `strip-decision-reverted` record. */
 export const buildStripDecisionRevertedRecord = (input) => v.parse(StripDecisionRevertedRecordSchema, {
     ...input,

package/dist/cli.d.ts.map

@@ -1 +1 @@
-{"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"}
+{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":";AA6DA,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;AAsjCF,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

@@ -6,14 +6,17 @@ import path from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { promisify } from 'node:util';
 import * as v from 'valibot';
+import { readPatchTextFromFile } from "./blobs.js";
 import { openLedger } from "./handle.js";
 import { deriveFilesChangedFromPatch } from "./patch-resolver.js";
-import { ChangeLogParityStatusSchema, ChangeLogSmokeResultSchema, ChangeLogSubkindSchema, LEDGER_KINDS, LEDGER_PHASES, parseLedgerRecord, WorkspaceRelativePathSchema, } from "./schema/entry.js";
+import { ChangeLogParityStatusSchema, ChangeLogSmokeResultSchema, ChangeLogSubkindSchema, LEDGER_KINDS, LEDGER_PHASES, STAGE_WRITE_STAGES, parseLedgerRecord, WorkspaceRelativePathSchema, } from "./schema/entry.js";
 import { NoteSubkindSchema } from "./schema/note.js";
 import { LEDGER_LIBRARY_VERSION } from "./version.js";
 const execFileAsync = promisify(execFile);
 const DEFAULT_GIT_DIFF_MAX_BUFFER_BYTES = 10 * 1024 * 1024;
 const DEFAULT_GIT_DIFF_TIMEOUT_MS = 30_000;
+const BOOLEAN_FLAG_NAMES = new Set(['from-stdin', 'help', 'json']);
+const GIT_DIFF_FORMAT_ARGS = ['--no-color', '--no-ext-diff', '--src-prefix=a/', '--dst-prefix=b/'];
 const RENDER_TARGETS = [
     'retro',
     'jsonl',
@@ -35,7 +38,8 @@ 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]`;
+const STAGE_WRITE_ONLY_FLAGS = ['file-path', 'stage'];
+const renderRecordUsage = (commandName) => `${commandName} record [--workspace=<ws>] --kind=<kind> --phase=<phase> --summary="..." [--rationale="..."] [--file-path=<path>] [--stage=<stage>] [--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 = {
@@ -51,9 +55,21 @@ const DEFAULT_CONTEXT = {
 const renderValidValues = () => `Valid values:
   kinds: ${LEDGER_KINDS.join(', ')}
   phases: ${LEDGER_PHASES.join(', ')}
+  stage-write stages: ${STAGE_WRITE_STAGES.join(', ')}
   note subkinds: ${NoteSubkindSchema.options.join(', ')}
   render targets: ${RENDER_TARGETS.join(', ')}
 `;
+const renderRuntimeTuningHelp = () => `Runtime tuning env vars:
+  USHMAN_LEDGER_SCAN_BATCH_SIZE (default: 32)
+  USHMAN_LEDGER_SCAN_CONCURRENCY (default: 16)
+  USHMAN_LEDGER_READ_INDEX_REBUILD_BATCH_SIZE (default: USHMAN_LEDGER_SCAN_BATCH_SIZE)
+  USHMAN_LEDGER_READ_INDEX_REBUILD_CONCURRENCY (default: USHMAN_LEDGER_SCAN_CONCURRENCY)
+  USHMAN_LEDGER_COVERAGE_FILE_STAT_CONCURRENCY (default: USHMAN_LEDGER_SCAN_CONCURRENCY)
+  USHMAN_LEDGER_BLOB_HASH_CONCURRENCY (default: USHMAN_LEDGER_SCAN_CONCURRENCY)
+  USHMAN_LEDGER_DOCTOR_CHECKPOINT_MAX_AGE_MS (default: 86400000)
+  USHMAN_LEDGER_DOCTOR_OPEN_ISSUE_MAX_AGE_MS (default: 2592000000)
+  USHMAN_LEDGER_MAX_PATCH_BYTES (default: 10485760)
+`;
 const renderHelp = (commandName) => `${commandName}
 
 Commands:
@@ -64,28 +80,37 @@ Commands:
   ${commandName} tail [--workspace=<ws>] [--phase=<phase>] [--limit=<n>]
   ${commandName} render [--workspace=<ws>] [--to=retro|jsonl|timeline-html|dependency-graph|migration-log-md|workspace-narrative-md] [--phase=<phase>] [--since=<iso>] [--limit=<n>] [--out=<file>]
   ${commandName} archive [--workspace=<ws>] --out=<file.tgz>
-  ${commandName} doctor [--workspace=<ws>]
+  ${commandName} doctor [--workspace=<ws>] [--json]
   ${commandName} --version
 
-${renderValidValues()}`;
+${renderValidValues()}
+${renderRuntimeTuningHelp()}`;
 const renderCommandHelp = (commandName, command) => {
     switch (command) {
         case 'record':
             return `${renderRecordUsage(commandName)}
 
-${renderValidValues()}`;
+${renderValidValues()}
+${renderRuntimeTuningHelp()}`;
         case 'note':
             return `${commandName} note <subkind> [--workspace=<ws>] --phase=<phase> --summary="..." [--body=<markdown-file>] [--from-stdin]
 
-${renderValidValues()}`;
+${renderValidValues()}
+${renderRuntimeTuningHelp()}`;
         case 'list':
             return `${commandName} list [--workspace=<ws>] [--phase=<phase>] [--kind=<kind>] [--since=<iso>] [--limit=<n>] [--json]
 
-${renderValidValues()}`;
+${renderValidValues()}
+${renderRuntimeTuningHelp()}`;
         case 'render':
             return `${commandName} render [--workspace=<ws>] [--to=<target>] [--phase=<phase>] [--since=<iso>] [--limit=<n>] [--out=<file>]
 
-${renderValidValues()}`;
+${renderValidValues()}
+${renderRuntimeTuningHelp()}`;
+        case 'doctor':
+            return `${commandName} doctor [--workspace=<ws>] [--json]
+
+${renderRuntimeTuningHelp()}`;
         default:
             return renderHelp(commandName);
     }
@@ -111,7 +136,7 @@ const parseArgv = (argv) => {
             continue;
         }
         const next = argv[index + 1];
-        if (!next || next.startsWith('--')) {
+        if (BOOLEAN_FLAG_NAMES.has(name) || !next || next.startsWith('--')) {
             flags[name] = true;
             continue;
         }
@@ -192,6 +217,18 @@ const parseWorkspaceRelativePathCsv = ({ flagName, raw }) => {
     }
     return uniquePaths;
 };
+const parseWorkspaceRelativePathFlag = ({ flagName, flags, required = false, }) => {
+    const raw = required ? getRequiredString(flags, flagName) : getFlag(flags, flagName);
+    if (!raw) {
+        return undefined;
+    }
+    try {
+        return v.parse(WorkspaceRelativePathSchema, raw);
+    }
+    catch {
+        throw new CliUsageError(`--${flagName} path is not a normalized workspace-relative path: ${raw}`);
+    }
+};
 const isGitDiffMaxBufferError = (error) => {
     const code = getErrorCode(error);
     if (code === 'ERR_CHILD_PROCESS_STDIO_MAXBUFFER') {
@@ -211,11 +248,31 @@ const isGitDiffTimeoutError = (error) => {
         error.killed === true &&
         error.signal === 'SIGTERM');
 };
+const buildGitDiffArgs = (gitOptions, gitRef) => gitOptions.scopedPaths.length === 0
+    ? ['diff', ...GIT_DIFF_FORMAT_ARGS, gitRef]
+    : ['diff', ...GIT_DIFF_FORMAT_ARGS, gitRef, '--', ...gitOptions.scopedPaths];
+const throwGitDiffFailure = ({ error, gitOptions, gitRef, }) => {
+    if (getErrorCode(error) === 'ENOENT') {
+        throw new CliUsageError('git is required for --diff-from-git and was not found in PATH. Install git or use --diff with a patch file.');
+    }
+    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.`);
+    }
+    const stderr = typeof error === 'object' && error !== null && 'stderr' in error
+        ? String(error.stderr ?? '').trim()
+        : '';
+    if (stderr.length > 0) {
+        throw new CliUsageError(`git diff ${gitRef} failed: ${stderr}`);
+    }
+    throw new CliUsageError(`git diff ${gitRef} failed. Ensure the ref exists and the workspace is a git repository.`);
+};
 const materializeGitDiff = async ({ gitOptions, gitRef, workspaceRoot, }) => {
     let tempDir;
     try {
-        const gitArgs = gitOptions.scopedPaths.length === 0 ? ['diff', gitRef] : ['diff', gitRef, '--', ...gitOptions.scopedPaths];
-        const { stdout } = await execFileAsync('git', gitArgs, {
+        const { stdout } = await execFileAsync('git', buildGitDiffArgs(gitOptions, gitRef), {
             cwd: workspaceRoot,
             maxBuffer: gitOptions.maxBufferBytes,
             timeout: gitOptions.timeoutMs,
@@ -229,16 +286,11 @@ const materializeGitDiff = async ({ gitOptions, gitRef, workspaceRoot, }) => {
         if (tempDir) {
             await rm(tempDir, { force: true, recursive: true });
         }
-        if (getErrorCode(error) === 'ENOENT') {
-            throw new CliUsageError('git is required for --diff-from-git and was not found in PATH.');
-        }
-        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;
+        return throwGitDiffFailure({
+            error,
+            gitOptions,
+            gitRef,
+        });
     }
 };
 const parseJsonInput = (text, sourceLabel) => {
@@ -252,6 +304,9 @@ const parseJsonInput = (text, sourceLabel) => {
 const print = (context, text) => {
     context.stdout.write(text.endsWith('\n') ? text : `${text}\n`);
 };
+const printJson = (context, value) => {
+    print(context, JSON.stringify(value, null, 2));
+};
 const parseLimit = (flags) => getFlag(flags, 'limit')
     ? parsePositiveIntegerFlag({
         defaultValue: 0,
@@ -311,6 +366,13 @@ const parseRenderTarget = (flags) => {
     }
     return target;
 };
+const parseRequiredStageWriteStage = (flags) => {
+    const stage = getRequiredString(flags, 'stage');
+    if (!STAGE_WRITE_STAGES.includes(stage)) {
+        throw new CliUsageError(`Invalid --stage value: ${stage}. Expected one of: ${STAGE_WRITE_STAGES.join(', ')}.`);
+    }
+    return stage;
+};
 const splitCommandLines = (value) => value
     .split(/\r?\n/u)
     .map((command) => command.trim())
@@ -397,7 +459,7 @@ const assertDiffRecordKindSupported = (kind) => {
     }
     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 readPatchText = async (diffPath) => readPatchTextFromFile(diffPath);
 const readPatchTextForRecordKind = async (kind, diffPath) => {
     if (kind === 'change-log' || kind === 'agent-patch' || kind === 'operator-patch') {
         return readPatchText(diffPath);
@@ -461,11 +523,13 @@ const validateRecordStdinFlags = (flags) => {
         'operator',
         'parity-status',
         'phase',
+        'file-path',
         'rationale',
         'rollback-plan',
         'rolls-back',
         'smoke-notes',
         'smoke-result',
+        'stage',
         'subkind',
         'summary',
     ].filter((flagName) => hasFlag(flags, flagName));
@@ -476,53 +540,87 @@ const validateRecordStdinFlags = (flags) => {
         .map((flagName) => `--${flagName}`)
         .join(', ')}. When using --from-stdin, provide all record fields in the JSON input.`);
 };
-const buildBaseRecordFromFlags = (parsed, context) => {
-    const kind = getRequiredKind(parsed.flags);
-    if (kind !== 'change-log') {
-        rejectUnsupportedFlags('change-log', parsed.flags, CHANGE_LOG_RECORD_ONLY_FLAGS);
+const applyRationaleFlag = ({ flags, kind, record, }) => {
+    const rationale = getFlag(flags, 'rationale');
+    if (!rationale) {
+        return rationale;
     }
-    const record = {
-        emitter: {
-            tool: context.defaultEmitter.tool,
-            version: context.defaultEmitter.version,
-        },
-        kind,
-        phase: getRequiredPhase(parsed.flags),
-        summary: getRequiredString(parsed.flags, 'summary'),
-    };
-    const rationale = getFlag(parsed.flags, 'rationale');
-    if (rationale) {
-        if (kind !== 'agent-patch' &&
-            kind !== 'operator-patch' &&
-            kind !== 'operator-decision' &&
-            kind !== 'correction') {
-            throw new CliUsageError('--rationale is only supported for patch, operator-decision, and correction records.');
-        }
-        if (kind !== 'operator-decision') {
-            record.rationale = rationale;
-        }
+    if (kind !== 'agent-patch' &&
+        kind !== 'operator-patch' &&
+        kind !== 'operator-decision' &&
+        kind !== 'correction' &&
+        kind !== 'stage-write') {
+        throw new CliUsageError('--rationale is only supported for patch, stage-write, operator-decision, and correction records.');
+    }
+    if (kind !== 'operator-decision') {
+        record.rationale = rationale;
     }
+    return rationale;
+};
+const applyKindSpecificRecordFields = ({ defaultTool, flags, kind, rationale, record, }) => {
     if (kind === 'agent-patch') {
         record.agent = {
-            name: getFlag(parsed.flags, 'agent') ?? context.defaultEmitter.tool,
+            name: getFlag(flags, 'agent') ?? defaultTool,
         };
+        return;
     }
     if (kind === 'operator-patch') {
         record.operator = {
-            name: getFlag(parsed.flags, 'operator') ?? context.defaultEmitter.tool,
+            name: getFlag(flags, 'operator') ?? defaultTool,
         };
+        return;
     }
     if (kind === 'operator-decision') {
-        const action = getRequiredString(parsed.flags, 'action');
         record.payload = {
-            action,
-            checkId: getFlag(parsed.flags, 'check-id'),
+            action: getRequiredString(flags, 'action'),
+            checkId: getFlag(flags, 'check-id'),
             rationale: rationale ?? '',
         };
+        return;
     }
     if (kind === 'change-log') {
-        record.subkind = parseRequiredChangeLogSubkind(parsed.flags);
+        record.subkind = parseRequiredChangeLogSubkind(flags);
+        return;
+    }
+    if (kind === 'stage-write') {
+        record.filePath = parseWorkspaceRelativePathFlag({
+            flagName: 'file-path',
+            flags,
+            required: true,
+        });
+        record.rationale = getRequiredString(flags, 'rationale');
+        record.stage = parseRequiredStageWriteStage(flags);
     }
+};
+const buildBaseRecordFromFlags = (parsed, context) => {
+    const kind = getRequiredKind(parsed.flags);
+    if (kind !== 'change-log') {
+        rejectUnsupportedFlags('change-log', parsed.flags, CHANGE_LOG_RECORD_ONLY_FLAGS);
+    }
+    if (kind !== 'stage-write') {
+        rejectUnsupportedFlags('stage-write', parsed.flags, STAGE_WRITE_ONLY_FLAGS);
+    }
+    const record = {
+        emitter: {
+            tool: context.defaultEmitter.tool,
+            version: context.defaultEmitter.version,
+        },
+        kind,
+        phase: getRequiredPhase(parsed.flags),
+        summary: getRequiredString(parsed.flags, 'summary'),
+    };
+    const rationale = applyRationaleFlag({
+        flags: parsed.flags,
+        kind,
+        record,
+    });
+    applyKindSpecificRecordFields({
+        defaultTool: context.defaultEmitter.tool,
+        flags: parsed.flags,
+        kind,
+        rationale,
+        record,
+    });
     const idempotencyKey = getFlag(parsed.flags, 'idempotency-key');
     if (idempotencyKey) {
         record.idempotencyKey = idempotencyKey;
@@ -695,16 +793,22 @@ const runNoteCli = async (parsed, context) => {
 const runListCli = async (parsed, context) => {
     const ledger = await openLedger(getWorkspaceRoot(parsed.flags));
     if (hasFlag(parsed.flags, 'json')) {
-        const entries = [];
+        let wroteEntry = false;
+        context.stdout.write('[\n');
         for await (const entry of ledger.list({
             kind: parseOptionalKind(parsed.flags),
             limit: parseLimit(parsed.flags),
             phase: parseOptionalPhase(parsed.flags),
             since: parseSince(parsed.flags),
         })) {
-            entries.push(entry);
+            if (wroteEntry) {
+                context.stdout.write(',\n');
+            }
+            const renderedEntry = JSON.stringify(entry, null, 2).replaceAll('\n', '\n  ');
+            context.stdout.write(`  ${renderedEntry}`);
+            wroteEntry = true;
         }
-        print(context, JSON.stringify(entries, null, 2));
+        context.stdout.write(wroteEntry ? '\n]\n' : ']\n');
         return 0;
     }
     for await (const entry of ledger.list({
@@ -762,16 +866,29 @@ const runArchiveCli = async (parsed, context) => {
     print(context, result.integrityHash);
     return 0;
 };
+const formatDoctorFinding = (finding) => [`[${finding.code}] ${finding.message}`, `Next step: ${finding.remediation}`].join('\n');
+const printDoctorFindings = (context, report) => {
+    context.stderr.write(`doctor found ${report.issueCount} issue${report.issueCount === 1 ? '' : 's'}.\n`);
+    for (const [index, finding] of report.findings.entries()) {
+        context.stderr.write(`\n${formatDoctorFinding(finding)}`);
+        if (index < report.findings.length - 1) {
+            context.stderr.write('\n');
+        }
+    }
+    context.stderr.write('\n');
+};
 const runDoctorCli = async (parsed, context) => {
     const ledger = await openLedger(getWorkspaceRoot(parsed.flags));
     const result = await ledger.doctor();
+    if (hasFlag(parsed.flags, 'json')) {
+        printJson(context, result);
+        return result.ok ? 0 : 1;
+    }
     if (result.ok) {
         print(context, 'ok');
         return 0;
     }
-    for (const issue of result.issues) {
-        context.stderr.write(`${issue}\n`);
-    }
+    printDoctorFindings(context, result);
     return 1;
 };
 const formatCliError = (error) => {
@@ -787,7 +904,7 @@ const formatCliError = (error) => {
         })
             .join('\n');
     }
-    return error instanceof Error ? (error.stack ?? error.message) : String(error);
+    return error instanceof Error ? error.message : String(error);
 };
 export const runLedgerCli = async (argv, context = {}) => {
     const mergedContext = { ...DEFAULT_CONTEXT, ...context };

package/dist/coverage.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"coverage.d.ts","sourceRoot":"","sources":["../src/coverage.ts"],"names":[],"mappings":"AAgGA,MAAM,MAAM,cAAc,GAAG;IACzB,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAC/B,QAAQ,CAAC,YAAY,EAAE,MAAM,EAAE,CAAC;IAChC,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,cAAc,EAAE,MAAM,EAAE,CAAC;CACrC,CAAC;AAEF,eAAO,MAAM,eAAe,GAAU,eAAe,MAAM,KAAG,OAAO,CAAC,cAAc,CAgDnF,CAAC"}
+{"version":3,"file":"coverage.d.ts","sourceRoot":"","sources":["../src/coverage.ts"],"names":[],"mappings":"AA+FA,MAAM,MAAM,cAAc,GAAG;IACzB,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAC/B,QAAQ,CAAC,YAAY,EAAE,MAAM,EAAE,CAAC;IAChC,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,cAAc,EAAE,MAAM,EAAE,CAAC;CACrC,CAAC;AAEF,eAAO,MAAM,eAAe,GAAU,eAAe,MAAM,KAAG,OAAO,CAAC,cAAc,CAiDnF,CAAC"}

package/dist/coverage.js

@@ -4,10 +4,10 @@ import { mapWithConcurrencyLimit } from "./async.js";
 import { CANDIDATE_EXCLUDE_GLOBS, CANDIDATE_FILE_GLOBS } from "./candidate-paths.js";
 import { readLabManifestMin } from "./lab-min.js";
 import { loadLedgerState } from "./recovery.js";
+import { getLedgerRuntimeConfig } from "./runtime-config.js";
 const EXCLUDED_ROOTS = new Set(CANDIDATE_EXCLUDE_GLOBS.map((glob) => glob.replace(/\/\*\*$/u, '')));
 const CANDIDATE_DIRECTORIES = CANDIDATE_FILE_GLOBS.filter((glob) => glob.endsWith('/**/*')).map((glob) => glob.slice(0, -5));
 const CANDIDATE_FILES = CANDIDATE_FILE_GLOBS.filter((glob) => !glob.endsWith('/**/*'));
-const FILE_STAT_CONCURRENCY = 16;
 const toPosix = (value) => value.replaceAll(path.sep, '/');
 const isMissingPathError = (error) => {
     const code = error.code;
@@ -85,13 +85,14 @@ const getWorkspaceInitMs = async (workspaceRoot) => {
     return labManifestStat.birthtimeMs || labManifestStat.mtimeMs;
 };
 export const computeCoverage = async (workspaceRoot) => {
+    const { coverageFileStatConcurrency } = getLedgerRuntimeConfig();
     const [{ readIndex }, candidateFiles, workspaceInitMs] = await Promise.all([
         loadLedgerState(workspaceRoot),
         collectCandidateFiles(workspaceRoot),
         getWorkspaceInitMs(workspaceRoot),
     ]);
     const coverageIndex = new Set(readIndex.coveredFiles.map((filePath) => toPosix(filePath)));
-    const candidateStats = await mapWithConcurrencyLimit(candidateFiles, FILE_STAT_CONCURRENCY, async (relativePath) => {
+    const candidateStats = await mapWithConcurrencyLimit(candidateFiles, coverageFileStatConcurrency, async (relativePath) => {
         try {
             return {
                 mtimeMs: (await stat(path.join(workspaceRoot, relativePath))).mtimeMs,

package/dist/doctor.d.ts

@@ -1,9 +1,22 @@
 import { type PreparedLedgerState } from './recovery.ts';
+export declare const DOCTOR_FINDING_CODES: readonly ["blob-corrupt", "blob-missing", "blob-unreadable", "change-log-rollback-missing-target", "change-log-smoke-failure-missing-rollback-plan", "manifest-entry-count-mismatch", "manifest-entry-location-missing", "manifest-entry-missing-on-disk", "manifest-last-sequence-mismatch", "manifest-per-phase-latest-mismatch", "manifest-phase-mismatch", "manifest-sequence-mismatch", "open-issue-stale", "pending-commit-quarantined", "phase-prev-entry-mismatch", "pre-change-checkpoint-stale", "read-failure"];
+export type DoctorFindingCode = (typeof DOCTOR_FINDING_CODES)[number];
+export type DoctorFindingMetadataValue = boolean | null | number | string;
+export type DoctorFinding = {
+    readonly code: DoctorFindingCode;
+    readonly message: string;
+    readonly metadata?: Record<string, DoctorFindingMetadataValue>;
+    readonly remediation: string;
+};
+export type DoctorReport = {
+    readonly checkedAt: string;
+    readonly findings: DoctorFinding[];
+    readonly issueCount: number;
+    readonly issues: string[];
+    readonly ok: boolean;
+};
 export declare const runLedgerDoctor: (workspaceRoot: string, options?: {
     readonly skipPrepare?: boolean;
     readonly state?: PreparedLedgerState;
-}) => Promise<{
-    issues: string[];
-    ok: boolean;
-}>;
+}) => Promise<DoctorReport>;
 //# sourceMappingURL=doctor.d.ts.map

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;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"}
+{"version":3,"file":"doctor.d.ts","sourceRoot":"","sources":["../src/doctor.ts"],"names":[],"mappings":"AAMA,OAAO,EAAiD,KAAK,mBAAmB,EAAE,MAAM,eAAe,CAAC;AAUxG,eAAO,MAAM,oBAAoB,4fAkBvB,CAAC;AAEX,MAAM,MAAM,iBAAiB,GAAG,CAAC,OAAO,oBAAoB,CAAC,CAAC,MAAM,CAAC,CAAC;AACtE,MAAM,MAAM,0BAA0B,GAAG,OAAO,GAAG,IAAI,GAAG,MAAM,GAAG,MAAM,CAAC;AAE1E,MAAM,MAAM,aAAa,GAAG;IACxB,QAAQ,CAAC,IAAI,EAAE,iBAAiB,CAAC;IACjC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,0BAA0B,CAAC,CAAC;IAC/D,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;CAChC,CAAC;AAEF,MAAM,MAAM,YAAY,GAAG;IACvB,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,QAAQ,EAAE,aAAa,EAAE,CAAC;IACnC,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,MAAM,EAAE,MAAM,EAAE,CAAC;IAC1B,QAAQ,CAAC,EAAE,EAAE,OAAO,CAAC;CACxB,CAAC;AAwlBF,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,KACvF,OAAO,CAAC,YAAY,CAsCtB,CAAC"}