ushman-ledger 1.2.2 → 1.3.0

package/AGENTS.md

@@ -29,11 +29,13 @@ An append-only ledger library and CLI for ushman v4 workspaces. It owns ledger s
 5. `src/schema/entry-migrations.ts`
 6. `src/schema/entry.ts`
 7. `src/storage/filesystem.ts`
-8. `src/record.ts`
-9. `src/handle.ts`
-10. `src/coverage.ts`
-11. `src/doctor.ts`
-12. `src/cli.ts`
+8. `src/recovery.ts`
+9. `src/record.ts`
+10. `src/handle.ts`
+11. `src/runtime-config.ts`
+12. `src/coverage.ts`
+13. `src/doctor.ts`
+14. `src/cli.ts`
 
 ## Commands
 

package/ARCHITECTURE.md

@@ -20,7 +20,9 @@ The same reconciliation path is used by reads, writes, coverage, doctor, render,
 
 - `manifest.json`: append-order metadata, per-phase pointers, idempotency index, and archive metadata.
 - `read-index.json`: durable lightweight scan index used by list/render/coverage/doctor.
+- `external-temp-files/`: journals for custom render temp files created outside `.lab/ledger`.
 - `pending/`: append journals used to replay incomplete commits.
+- `pending-quarantine/`: unreplayable pending commit journals plus quarantine metadata.
 - `pending-archives/`: archive journals used to adopt or discard incomplete archive writes.
 - `blobs/`: content-addressed patch payloads keyed by SHA-256.
 - `<phase>/`: append-only entry files per ledger phase.
@@ -30,6 +32,7 @@ The same reconciliation path is used by reads, writes, coverage, doctor, render,
 - Entries are immutable once written. Corrections use `correction` records linked to the original entry.
 - Each phase maintains its own `prevEntryId` chain so local append history is explicit and auditable.
 - Idempotency is logical-content based by default and can be overridden with an explicit `idempotencyKey`.
+- `stage-write` records treat `filePath` as the required primary covered artifact and may extend coverage with extra normalized `links.affectedFiles`.
 - Patch payloads are de-duplicated by SHA-256 and stored once under `blobs/`.
 
 ## Read path
@@ -43,8 +46,8 @@ The same reconciliation path is used by reads, writes, coverage, doctor, render,
 
 - Atomic writes use temp files and rename.
 - Pending commit journals record the target sequence before the entry file and manifest can drift.
-- Startup reconciliation replays pending commits in manifest order, rebuilds missing or stale read indexes, adopts verified archives, and cleans stale temp files.
-- Manifest locks are reclaimed only after stale-owner checks, so a newer owner is not deleted during handoff.
+- Startup reconciliation replays pending commits in manifest order, quarantines unreplayable pending commits, rebuilds missing or stale read indexes, adopts verified archives, and cleans stale temp files.
+- Manifest locks are reclaimed after stale-owner or dead-owner checks, so a newer owner is not deleted during handoff.
 - Re-opening the ledger or rerunning any CLI command triggers the same recovery path; there is no separate manual recovery subcommand.
 
 ## Scale and tuning
@@ -57,6 +60,8 @@ The default scan contract is intentionally conservative and can be tuned with en
 - `USHMAN_LEDGER_READ_INDEX_REBUILD_CONCURRENCY`
 - `USHMAN_LEDGER_COVERAGE_FILE_STAT_CONCURRENCY`
 - `USHMAN_LEDGER_BLOB_HASH_CONCURRENCY`
+- `USHMAN_LEDGER_DOCTOR_CHECKPOINT_MAX_AGE_MS`
+- `USHMAN_LEDGER_DOCTOR_OPEN_ISSUE_MAX_AGE_MS`
 - `USHMAN_LEDGER_MAX_PATCH_BYTES`
 
 The benchmark entrypoint, `bun run bench:scale`, prints the active runtime config so measurements can be compared across different knob settings.
@@ -70,6 +75,7 @@ The benchmark entrypoint, `bun run bench:scale`, prints the active runtime confi
 ## Contributor map
 
 - `src/blobs.ts`: patch blob storage, size limits, and digest/path validation.
+- `src/storage/lock.ts`: manifest lock acquisition, stale-owner reclaim, and reclaim-marker turnover.
 - `src/record.ts`: append pipeline and idempotency behavior.
 - `src/recovery.ts`: pending journal replay, read-index rebuild, and temp cleanup.
 - `src/read-index.ts`: durable scan index construction and maintenance.

package/CHANGELOG.md

@@ -1,5 +1,16 @@
 # Changelog
 
+## [1.2.0] - 2026-05-28
+
+- Added `stage-write` ledger records for deterministic pipeline-owned candidate writes.
+- `stage-write` now accepts `intake` alongside the later candidate-mutating stage ids so intake-owned writes such as auto-stubs and workspace runbooks can be recorded without falling back to patch semantics.
+- Read-index coverage now treats `stage-write.filePath` the same as patch `affectedFiles`, so downstream coverage checks can distinguish stage output from operator edits without losing coverage accounting.
+- Retro rendering now includes `stage-write` entries in the tool/action stream.
+- Custom render outputs now journal their external temp files so startup recovery can clean stale crash leftovers outside `.lab/ledger`.
+- Lock recovery now reclaims locks immediately when the recorded owner PID is no longer alive.
+- Pending commit recovery now quarantines unreplayable journals and reports them through `doctor` instead of failing the whole reconciliation pass.
+- Doctor stale-age windows for pre-change checkpoints and open issues are configurable through runtime environment variables.
+
 ## [1.1.0] - 2026-05-23
 
 - Added `change-log` records, narrative note subkinds, and `migration-log-md` / `workspace-narrative-md` render targets.

package/README.md

@@ -33,6 +33,7 @@ import {
   appendSemanticCleanupSummaryNote,
   type BuildRecordInput,
   buildChangeLogRecord,
+  buildStageWriteRecord,
   buildValidatorResultRecord,
   deriveFilesChangedFromPatch,
   getLedgerRuntimeConfig,
@@ -75,6 +76,17 @@ await ledger.record(
   }),
 );
 
+await ledger.record(
+  buildStageWriteRecord({
+    emitter: { tool: 'ushman-seed', version: '1.0.0' },
+    filePath: 'src/generated/candidate.ts',
+    phase: 'seed',
+    rationale: 'Seed stage wrote the initial candidate artifact.',
+    stage: 'seed',
+    summary: 'seed candidate output',
+  }),
+);
+
 await ledger.record(
   buildValidatorResultRecord({
     emitter: { tool: 'ushman-doctor', version: '1.0.0' },
@@ -126,6 +138,7 @@ const buildRuntimeEventRecord = (input: RuntimeEventInput) => ({
 ```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=stage-write --phase=seed --summary="seed output" --rationale="pipeline wrote candidate" --file-path=src/generated/candidate.ts --stage=seed
 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"
@@ -142,10 +155,12 @@ ushman-ledger doctor --workspace=<ws>
 ushman-ledger doctor --workspace=<ws> --json
 ```
 
-Valid record kinds: `tool-invocation`, `agent-patch`, `operator-patch`, `operator-decision`, `validator-result`, `runtime-event`, `note`, `correction`, `strip-decision-reverted`, `change-log`
+Valid record kinds: `tool-invocation`, `stage-write`, `agent-patch`, `operator-patch`, `operator-decision`, `validator-result`, `runtime-event`, `note`, `correction`, `strip-decision-reverted`, `change-log`
 
 Valid phases: `capture`, `intake`, `seed`, `vendor-extract`, `cleanup`, `parity`, `characterize`, `equiv`, `analyze`, `recover`, `ship`, `migration`
 
+Valid `stage-write` stages: `seed`, `vendor-extract`, `cleanup`, `candidate-promotion`
+
 Valid note subkinds: `regression`, `automation`, `retro`, `operator`, `tooling-gap`, `cleanup-wave`, `verified-flow`, `open-issue`, `decomposition-wave`, `semantic-cleanup-summary`
 
 Valid render targets: `retro`, `jsonl`, `timeline-html`, `dependency-graph`, `migration-log-md`, `workspace-narrative-md`
@@ -184,14 +199,16 @@ Valid render targets: `retro`, `jsonl`, `timeline-html`, `dependency-graph`, `mi
 - `operator-decision` entries capture `{ action, checkId?, rationale }` in `payload`. `action` is one of `bypass-doctor`, `skip-check`, `override-strip-decision`, `override-ship-state`, `manual-parity-assertion`, `ledger-hand-edit`, `escalation`.
 - `strip-decision-reverted` entries capture `{ stripDecisionId, rationale, invalidatedStages? }`.
 - `correction` entries require `links.correctsLedgerId` pointing at the entry they correct.
+- `stage-write` entries capture `{ filePath, rationale, stage }` for deterministic pipeline-owned writes. `phase` records where the ledger event happened; `stage` records the pipeline stage that produced the artifact.
 - Patch entries (`agent-patch`, `operator-patch`) store a `diff` blob reference and a `rationale`. Patch text is stored once under `.lab/ledger/blobs/` and shared by hash.
 
 ## Links and coverage
 
 - `links.affectedFiles` should contain normalized workspace-relative paths for files changed by an `agent-patch` or `operator-patch`.
+- `stage-write.filePath` is always treated as covered output. If one stage write should cover additional normalized paths, include them in `links.affectedFiles`; coverage merges both sources.
 - Use forward slashes, do not prefix paths with `./`, and do not include trailing slashes or `..` segments.
 - Coverage only considers candidate workspace files modified after workspace initialization.
-- A modified file is considered covered when any patch entry lists it in `links.affectedFiles`.
+- A modified file is considered covered when a patch entry lists it in `links.affectedFiles` or a `stage-write` entry names it through `filePath`/`links.affectedFiles`.
 - Coverage is backed by a durable read index so repeated coverage runs do not rescan every patch entry.
 
 ## Append chain and concurrency
@@ -200,21 +217,22 @@ Valid render targets: `retro`, `jsonl`, `timeline-html`, `dependency-graph`, `mi
 - Manifest updates are serialized through a global ledger lock.
 - Appends use a pending-commit journal so entry files, the manifest, and the durable read index can be replayed after crashes.
 - Open, read, and append paths reconcile unfinished commits before serving ledger data.
-- Corrupt or stale manifest locks are reclaimed automatically with compare-and-swap style quarantine semantics.
+- Corrupt, stale, or dead-owner manifest locks are reclaimed automatically with compare-and-swap style quarantine semantics.
 
 ## Crash recovery
 
 - Pending commit journals live under `.lab/ledger/pending/`.
+- Pending commit journals that cannot be replayed are moved to `.lab/ledger/pending-quarantine/` and surfaced by `doctor`.
 - Pending archive journals live under `.lab/ledger/pending-archives/`.
 - Startup reconciliation replays journaled appends in manifest sequence order.
 - Startup reconciliation also rebuilds a missing or stale `read-index.json` from manifest sequence order.
 - Verified pending archives are adopted into the manifest on startup; corrupt or partial pending archives are deleted.
-- Stale temp files are cleaned for phase entries, the manifest, blobs, the read index, and render outputs.
+- Stale temp files are cleaned for phase entries, the manifest, blobs, the read index, canonical render outputs, and tracked custom render outputs.
 
 ## Recovery & Troubleshooting
 
 - `.lab/ledger/pending/` contains append journals that let the ledger recover incomplete writes after crashes. Do not edit these files by hand.
-- If startup or `doctor` reports a pending commit mismatch, re-open the ledger or rerun the command first so reconciliation can replay or discard the journal safely.
+- If startup moves a pending commit to `.lab/ledger/pending-quarantine/`, inspect the `doctor` finding and restore the journal only when its entry, sequence, and manifest base are known to be safe.
 - If `doctor` reports manifest or blob corruption, fix the underlying entry/blob mismatch first and rerun `doctor` before attempting `archive`.
 
 ## Scan behavior
@@ -249,7 +267,9 @@ Valid render targets: `retro`, `jsonl`, `timeline-html`, `dependency-graph`, `mi
   .manifest.lock
   manifest.json
   read-index.json
+  external-temp-files/
   pending/
+  pending-quarantine/
   pending-archives/
   blobs/
   render.md
@@ -290,6 +310,8 @@ bun run bench:scale
 - `USHMAN_LEDGER_READ_INDEX_REBUILD_CONCURRENCY`: concurrent entry reads used while rebuilding `read-index.json`. Defaults to `USHMAN_LEDGER_SCAN_CONCURRENCY`.
 - `USHMAN_LEDGER_COVERAGE_FILE_STAT_CONCURRENCY`: concurrent `stat()` calls during coverage scans. Defaults to `USHMAN_LEDGER_SCAN_CONCURRENCY`.
 - `USHMAN_LEDGER_BLOB_HASH_CONCURRENCY`: concurrent blob integrity hashes during `doctor`. Defaults to `USHMAN_LEDGER_SCAN_CONCURRENCY`.
+- `USHMAN_LEDGER_DOCTOR_CHECKPOINT_MAX_AGE_MS`: stale window for `pre-change-checkpoint` follow-up findings. Default `86400000`.
+- `USHMAN_LEDGER_DOCTOR_OPEN_ISSUE_MAX_AGE_MS`: stale window for unresolved `open-issue` note findings. Default `2592000000`.
 - `USHMAN_LEDGER_MAX_PATCH_BYTES`: maximum accepted patch/blob input size in bytes. Default `10485760`.
 
 All runtime tuning values must be positive integers. Invalid values fail fast with an explicit error so automation does not silently run with an unexpected fallback.

package/TROUBLESHOOTING.md

@@ -127,18 +127,28 @@ Action:
 
 ### `pre-change-checkpoint-stale`
 
-Meaning: a pre-change checkpoint aged past 24 hours without a follow-up entry using the same `idempotencyKey`.
+Meaning: a pre-change checkpoint aged past the configured stale window without a follow-up entry using the same `idempotencyKey`. The default window is 24 hours.
 
 Action:
 - Append the follow-up change-log entry, or close the stale checkpoint with a correction entry explaining the abandoned work.
 
 ### `open-issue-stale`
 
-Meaning: an `open-issue` note is older than 30 days and has no correction/supersession link.
+Meaning: an `open-issue` note is older than the configured stale window and has no correction/supersession link. The default window is 30 days.
 
 Action:
 - Append a correction or superseding note linking back to the old issue once the follow-up is complete.
 
+### `pending-commit-quarantined`
+
+Meaning: startup recovery found a pending commit journal that could not be parsed, replayed, or reconciled with the current manifest, so it moved the journal to `.lab/ledger/pending-quarantine/` and continued reconciling the rest of the ledger.
+
+Action:
+- Inspect the finding metadata and matching quarantine files.
+- Start with `ushman-ledger doctor --workspace="$WS" --json` so the finding metadata shows the quarantined file path and recorded reason.
+- Restore the journal to `.lab/ledger/pending/` only if its entry, sequence, and manifest base are known to be safe.
+- Otherwise keep or remove the quarantined file after recording an operator decision for the recovery outcome.
+
 ### `read-failure`
 
 Meaning: the ledger could not be parsed or reconciled cleanly before checks started.
@@ -159,12 +169,16 @@ Action:
 
 ### Ledger lock held by a dead process
 
-Rerun the original ledger command first. Lock reclamation happens during normal startup and append flows, so you usually do not need to delete lock files by hand.
+Rerun the original ledger command first. Lock reclamation checks the recorded owner PID and stale age during normal startup and append flows, so you usually do not need to delete lock files by hand.
 
 ### Manifest and disk disagree after a crash
 
 Re-open the ledger first so pending commits can be replayed. If `doctor` still reports `manifest-entry-missing-on-disk` or `manifest-entry-location-missing`, repair the missing entry file or manifest location before archiving.
 
+### Custom doctor stale windows
+
+Use `USHMAN_LEDGER_DOCTOR_CHECKPOINT_MAX_AGE_MS` to tune `pre-change-checkpoint-stale` and `USHMAN_LEDGER_DOCTOR_OPEN_ISSUE_MAX_AGE_MS` to tune `open-issue-stale`. Both values are positive integer millisecond windows and keep the default behavior when unset.
+
 ### Manual ledger edits
 
 Prefer appending `correction` or `operator-decision` records instead of editing historical entry files directly. If historical files were edited already, use `doctor` to identify the damaged chain or manifest pointers before appending new records.

package/dist/blobs.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"blobs.d.ts","sourceRoot":"","sources":["../src/blobs.ts"],"names":[],"mappings":"AA8CA,MAAM,MAAM,eAAe,GAAG;IAC1B,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;CACjC,CAAC;AAEF,eAAO,MAAM,qBAAqB,GAAI,QAAQ,MAAM,WAKnD,CAAC;AAEF,eAAO,MAAM,0BAA0B,GAAI,WAAW,MAAM,EAAE,aAAa,MAAM,WAOhF,CAAC;AAEF,eAAO,MAAM,qBAAqB,GAAU,WAAW,MAAM,oBAO5D,CAAC;AAEF,eAAO,MAAM,cAAc,GAAU,eAAe,MAAM,EAAE,WAAW,MAAM,KAAG,OAAO,CAAC,eAAe,CAmBtG,CAAC;AAEF,eAAO,MAAM,sBAAsB,GAAU,eAAe,MAAM,EAAE,WAAW,MAAM,KAAG,OAAO,CAAC,eAAe,CAE9G,CAAC;AAEF,eAAO,MAAM,eAAe,GAAI,eAAe,MAAM,EAAE,QAAQ,MAAM,WACN,CAAC"}
+{"version":3,"file":"blobs.d.ts","sourceRoot":"","sources":["../src/blobs.ts"],"names":[],"mappings":"AAsDA,MAAM,MAAM,eAAe,GAAG;IAC1B,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;CACjC,CAAC;AAEF,eAAO,MAAM,qBAAqB,GAAI,QAAQ,MAAM,WAKnD,CAAC;AAEF,eAAO,MAAM,0BAA0B,GAAI,WAAW,MAAM,EAAE,aAAa,MAAM,WAOhF,CAAC;AAEF,eAAO,MAAM,qBAAqB,GAAU,WAAW,MAAM,oBAO5D,CAAC;AAEF,eAAO,MAAM,cAAc,GAAU,eAAe,MAAM,EAAE,WAAW,MAAM,KAAG,OAAO,CAAC,eAAe,CAmBtG,CAAC;AAEF,eAAO,MAAM,sBAAsB,GAAU,eAAe,MAAM,EAAE,WAAW,MAAM,KAAG,OAAO,CAAC,eAAe,CAE9G,CAAC;AAEF,eAAO,MAAM,eAAe,GAAI,eAAe,MAAM,EAAE,QAAQ,MAAM,WACN,CAAC"}

package/dist/blobs.js

@@ -31,7 +31,7 @@ const countPatchLines = (patchText) => {
     });
     return { addedLines, removedLines };
 };
-const formatPatchLimitError = ({ bytes, limitBytes, sourceLabel }) => `Patch input from ${sourceLabel} is ${bytes} bytes, exceeding the configured limit of ${limitBytes} bytes. Reduce the diff size or increase USHMAN_LEDGER_MAX_PATCH_BYTES.`;
+const formatPatchLimitError = ({ bytes, limitBytes, sourceLabel, }) => `Patch input from ${sourceLabel} is ${bytes} bytes, exceeding the configured limit of ${limitBytes} bytes. Reduce the diff size or increase USHMAN_LEDGER_MAX_PATCH_BYTES.`;
 const buildBlobPath = (workspaceRoot, sha256) => {
     const paths = resolveLedgerPaths(workspaceRoot);
     return path.join(paths.blobsDir, sha256.slice(0, 2), `${sha256}.patch`);

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":";AA2DA,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;AA29BF,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

@@ -9,7 +9,7 @@ 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);
@@ -38,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 = {
@@ -54,6 +55,7 @@ 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(', ')}
 `;
@@ -64,6 +66,8 @@ const renderRuntimeTuningHelp = () => `Runtime tuning env vars:
   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}
@@ -213,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') {
@@ -350,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())
@@ -500,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));
@@ -515,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;

package/dist/doctor.d.ts

@@ -1,5 +1,5 @@
 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", "phase-prev-entry-mismatch", "pre-change-checkpoint-stale", "read-failure"];
+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 = {

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;AAS1E,eAAO,MAAM,oBAAoB,8dAiBvB,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;AAqjBF,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,CAqCtB,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"}