ushman-ledger 1.1.0 → 1.2.1

package/AGENTS.md

@@ -23,13 +23,17 @@ An append-only ledger library and CLI for ushman v4 workspaces. It owns ledger s
 ## Read order
 
 1. `README.md`
-2. `src/schema/entry.ts`
-3. `src/storage/filesystem.ts`
-4. `src/record.ts`
-5. `src/handle.ts`
-6. `src/coverage.ts`
-7. `src/doctor.ts`
-8. `src/cli.ts`
+2. `src/schema/entry-core.ts`
+3. `src/schema/entry-read.ts`
+4. `src/schema/entry-write.ts`
+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`
 
 ## Commands
 

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # Changelog
 
+## [1.1.0] - 2026-05-23
+
+- Added `change-log` records, narrative note subkinds, and `migration-log-md` / `workspace-narrative-md` render targets.
+- Split entry schema parsing into focused read/write/core modules and moved compatibility coercions behind dedicated parse migrations.
+- Extracted patch-source resolution behind a dedicated resolver with focused tests and more actionable hash mismatch failures.
+
 ## [1.0.1] - 2026-05-16
 
 - Tightened the schema surface to the ledger primitives the v4 orchestrator actively uses.

package/README.md

@@ -9,6 +9,7 @@ Append-only workspace ledger library and CLI for ushman v4 workspaces.
 - Content-hash idempotency
 - Patch blob storage
 - Retro / JSONL / timeline / dependency-graph rendering
+- Change-log / workspace narrative markdown rendering
 - Archive integrity output
 - Doctor and coverage helpers
 
@@ -26,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' },
@@ -47,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' },
@@ -57,32 +84,72 @@ 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
+ushman-ledger note cleanup-wave --workspace=<ws> --phase=cleanup --summary="wave 1" --body=/tmp/narrative.md
 ushman-ledger list --workspace=<ws> --json
 ushman-ledger render --workspace=<ws> --to=retro
+ushman-ledger render --workspace=<ws> --to=migration-log-md
+ushman-ledger render --workspace=<ws> --to=workspace-narrative-md
 ushman-ledger render --workspace=<ws> --to=jsonl --out=/tmp/ledger.jsonl
 ushman-ledger render --workspace=<ws> --to=dependency-graph --out=/tmp/ledger.mmd
 ushman-ledger archive --workspace=<ws> --out=/tmp/ledger.tgz
 ushman-ledger doctor --workspace=<ws>
 ```
 
-Valid record kinds: `tool-invocation`, `agent-patch`, `operator-patch`, `operator-decision`, `validator-result`, `runtime-event`, `note`, `correction`, `strip-decision-reverted`
+Valid record kinds: `tool-invocation`, `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 note subkinds: `regression`, `automation`, `retro`, `operator`, `tooling-gap`
+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`
+
+## Change-log records
+
+`change-log` entries are append-only structured narrative records for migration and cleanup work. They accept:
+
+- `subkind`: `pre-change-checkpoint`, `semantic-cleanup`, `vendor-extract`, `decomposition`, `rollback`, `hotfix`, `smoke`
+- `filesChanged`: explicit CSV paths via `--files-changed`, or automatic diffstat-style derivation from `--diff` / `--diff-from-git`
+- 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.
 
-Valid render targets: `retro`, `jsonl`, `timeline-html`, `dependency-graph`
+`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
 
@@ -150,7 +217,9 @@ Valid render targets: `retro`, `jsonl`, `timeline-html`, `dependency-graph`
 ## 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
@@ -164,7 +233,9 @@ Valid render targets: `retro`, `jsonl`, `timeline-html`, `dependency-graph`
   pending-archives/
   blobs/
   render.md
+  render.migration-log.md
   render.timeline.html
+  render.workspace-narrative.md
   <phase>/
     <timestamp>-<sequence>-<hash>.json
 ```
@@ -181,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/blobs.js

@@ -1,4 +1,4 @@
-import { mkdir, readFile, stat } from 'node:fs/promises';
+import { mkdir, readFile } from 'node:fs/promises';
 import path from 'node:path';
 import { sha256File, sha256Hex } from "./json.js";
 import { resolveLedgerPaths, writeAtomicTextFile } from "./storage/filesystem.js";
@@ -34,11 +34,11 @@ export const storePatchBlob = async (workspaceRoot, patchText) => {
     const blobPath = buildBlobPath(workspaceRoot, blobSha256);
     let shouldWrite = true;
     try {
-        await stat(blobPath);
         shouldWrite = (await sha256File(blobPath)) !== blobSha256;
     }
     catch (error) {
-        if (error.code !== 'ENOENT') {
+        const code = error.code;
+        if (code !== 'ENOENT') {
             throw error;
         }
     }

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. */
@@ -104,6 +104,49 @@ export declare const buildCorrectionRecord: (input: BuildRecordInput<Extract<Led
     phase: "capture" | "intake" | "seed" | "vendor-extract" | "cleanup" | "parity" | "characterize" | "equiv" | "analyze" | "recover" | "ship" | "migration";
     summary: string;
 };
+/** Build a `change-log` record. */
+export declare const buildChangeLogRecord: (input: BuildRecordInput<Extract<LedgerRecord, {
+    kind: "change-log";
+}>>) => {
+    commandsRun?: string[] | undefined;
+    filesChanged: {
+        added?: number | undefined;
+        path: string;
+        removed?: number | undefined;
+    }[];
+    hypothesis?: string | undefined;
+    kind: "change-log";
+    parityStatus?: "not-run" | "green" | "yellow" | "red" | undefined;
+    rollbackPlan?: string | undefined;
+    rollsBack?: string | undefined;
+    smokeNotes?: string | undefined;
+    smokeResult?: "pass" | "fail" | "partial" | "not-run" | undefined;
+    subkind: "vendor-extract" | "pre-change-checkpoint" | "semantic-cleanup" | "decomposition" | "rollback" | "hotfix" | "smoke";
+    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";
@@ -139,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,EAEH,KAAK,YAAY,EAKpB,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,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/builders.js

@@ -1,10 +1,10 @@
 import * as v from 'valibot';
-import { CorrectionRecordSchema, OperatorDecisionPayloadSchema, OperatorDecisionRecordSchema, StripDecisionRevertedRecordSchema, ValidatorResultRecordSchema, } from "./schema/entry.js";
+import { ChangeLogRecordSchema, CorrectionRecordSchema, OperatorDecisionRecordSchema, StripDecisionRevertedRecordSchema, ValidatorResultRecordSchema, } from "./schema/entry.js";
 /** Build an `operator-decision` record with a validated structured payload. */
 export const buildOperatorDecisionRecord = (input) => v.parse(OperatorDecisionRecordSchema, {
     ...input,
     kind: 'operator-decision',
-    payload: v.parse(OperatorDecisionPayloadSchema, input.payload),
+    payload: input.payload,
 });
 /** Build a `validator-result` record. */
 export const buildValidatorResultRecord = (input) => v.parse(ValidatorResultRecordSchema, {
@@ -16,6 +16,11 @@ export const buildCorrectionRecord = (input) => v.parse(CorrectionRecordSchema,
     ...input,
     kind: 'correction',
 });
+/** Build a `change-log` record. */
+export const buildChangeLogRecord = (input) => v.parse(ChangeLogRecordSchema, {
+    ...input,
+    kind: 'change-log',
+});
 /** 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":";AAoBA,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;AAqjBF,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"}