ushman-ledger 1.1.0 → 1.2.1

package/dist/note.js

@@ -1,5 +1,6 @@
 import { appendRecord } from "./record.js";
 import { LEDGER_LIBRARY_VERSION } from "./version.js";
+/** Append a typed note entry using the library emitter metadata. */
 export const appendNote = async (workspaceRoot, subkind, noteBody) => {
     return appendRecord(workspaceRoot, {
         body: noteBody.body,
@@ -13,3 +14,13 @@ export const appendNote = async (workspaceRoot, subkind, noteBody) => {
         summary: noteBody.summary,
     });
 };
+/** Append a `cleanup-wave` narrative note. */
+export const appendCleanupWaveNote = (workspaceRoot, noteBody) => appendNote(workspaceRoot, 'cleanup-wave', noteBody);
+/** Append a `verified-flow` narrative note. */
+export const appendVerifiedFlowNote = (workspaceRoot, noteBody) => appendNote(workspaceRoot, 'verified-flow', noteBody);
+/** Append an `open-issue` narrative note. */
+export const appendOpenIssueNote = (workspaceRoot, noteBody) => appendNote(workspaceRoot, 'open-issue', noteBody);
+/** Append a `decomposition-wave` narrative note. */
+export const appendDecompositionWaveNote = (workspaceRoot, noteBody) => appendNote(workspaceRoot, 'decomposition-wave', noteBody);
+/** Append the current `semantic-cleanup-summary` note for workspace narrative rendering. */
+export const appendSemanticCleanupSummaryNote = (workspaceRoot, noteBody) => appendNote(workspaceRoot, 'semantic-cleanup-summary', noteBody);

package/dist/patch-resolver.d.ts

@@ -0,0 +1,39 @@
+import { type AgentPatchDiff, type ChangeLogFileChange, type LedgerLinks, type LedgerRecord } from './schema/entry.ts';
+type AgentPatchRecord = Extract<LedgerRecord, {
+    kind: 'agent-patch';
+}>;
+type OperatorPatchRecord = Extract<LedgerRecord, {
+    kind: 'operator-patch';
+}>;
+type ResolvedAgentPatchRecord = Omit<AgentPatchRecord, 'diffPath' | 'diffText' | 'links'> & {
+    readonly diff: AgentPatchDiff;
+    readonly links: LedgerLinks;
+};
+type ResolvedOperatorPatchRecord = Omit<OperatorPatchRecord, 'diffPath' | 'diffText' | 'links'> & {
+    readonly diff: AgentPatchDiff;
+    readonly links: LedgerLinks;
+};
+export type ResolvedPatchRecord = ResolvedAgentPatchRecord | ResolvedOperatorPatchRecord;
+/**
+ * Derive `change-log.filesChanged` metadata from a git-style unified diff.
+ *
+ * Example:
+ * `deriveFilesChangedFromPatch(await readFile('/tmp/change.patch', 'utf8'))`
+ *
+ * Known limits:
+ * - Requires `diff --git` headers to identify file boundaries.
+ * - Counts only textual hunk `+` and `-` lines, so binary or mode-only diffs can yield zero line counts.
+ * - Uses the post-image path when available and rejects diff blocks that cannot be mapped to a normalized
+ *   workspace-relative path.
+ */
+export declare const deriveFilesChangedFromPatch: (patchText: string) => ChangeLogFileChange[];
+export declare function resolvePatchRecord(args: {
+    readonly record: AgentPatchRecord;
+    readonly workspaceRoot: string;
+}): Promise<ResolvedAgentPatchRecord>;
+export declare function resolvePatchRecord(args: {
+    readonly record: OperatorPatchRecord;
+    readonly workspaceRoot: string;
+}): Promise<ResolvedOperatorPatchRecord>;
+export {};
+//# sourceMappingURL=patch-resolver.d.ts.map

package/dist/patch-resolver.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"patch-resolver.d.ts","sourceRoot":"","sources":["../src/patch-resolver.ts"],"names":[],"mappings":"AAIA,OAAO,EACH,KAAK,cAAc,EACnB,KAAK,mBAAmB,EACxB,KAAK,WAAW,EAChB,KAAK,YAAY,EAEpB,MAAM,mBAAmB,CAAC;AAI3B,KAAK,gBAAgB,GAAG,OAAO,CAAC,YAAY,EAAE;IAAE,IAAI,EAAE,aAAa,CAAA;CAAE,CAAC,CAAC;AACvE,KAAK,mBAAmB,GAAG,OAAO,CAAC,YAAY,EAAE;IAAE,IAAI,EAAE,gBAAgB,CAAA;CAAE,CAAC,CAAC;AAQ7E,KAAK,wBAAwB,GAAG,IAAI,CAAC,gBAAgB,EAAE,UAAU,GAAG,UAAU,GAAG,OAAO,CAAC,GAAG;IACxF,QAAQ,CAAC,IAAI,EAAE,cAAc,CAAC;IAC9B,QAAQ,CAAC,KAAK,EAAE,WAAW,CAAC;CAC/B,CAAC;AACF,KAAK,2BAA2B,GAAG,IAAI,CAAC,mBAAmB,EAAE,UAAU,GAAG,UAAU,GAAG,OAAO,CAAC,GAAG;IAC9F,QAAQ,CAAC,IAAI,EAAE,cAAc,CAAC;IAC9B,QAAQ,CAAC,KAAK,EAAE,WAAW,CAAC;CAC/B,CAAC;AAEF,MAAM,MAAM,mBAAmB,GAAG,wBAAwB,GAAG,2BAA2B,CAAC;AAqKzF;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,2BAA2B,GAAI,WAAW,MAAM,KAAG,mBAAmB,EAuClF,CAAC;AAmBF,wBAAgB,kBAAkB,CAAC,IAAI,EAAE;IACrC,QAAQ,CAAC,MAAM,EAAE,gBAAgB,CAAC;IAClC,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;CAClC,GAAG,OAAO,CAAC,wBAAwB,CAAC,CAAC;AACtC,wBAAgB,kBAAkB,CAAC,IAAI,EAAE;IACrC,QAAQ,CAAC,MAAM,EAAE,mBAAmB,CAAC;IACrC,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;CAClC,GAAG,OAAO,CAAC,2BAA2B,CAAC,CAAC"}

package/dist/patch-resolver.js

@@ -0,0 +1,196 @@
+import { readFile } from 'node:fs/promises';
+import path from 'node:path';
+import * as v from 'valibot';
+import { resolveBlobPath, storePatchBlob } from "./blobs.js";
+import { WorkspaceRelativePathSchema, } from "./schema/entry.js";
+const readBlobText = async (workspaceRoot, blobSha256) => readFile(resolveBlobPath(workspaceRoot, blobSha256), 'utf8');
+const formatRecordContext = (record) => `${record.kind} "${record.summary}" [${record.phase}]`;
+const normalizeWorkspaceRelativePath = (value) => v.parse(WorkspaceRelativePathSchema, value.replaceAll('\\', '/'));
+const stripGitPathPrefix = (value) => {
+    const normalized = value.trim().replace(/^"([^"]*)"$/u, '$1');
+    if (normalized === '/dev/null') {
+        return null;
+    }
+    if (normalized.startsWith('a/') || normalized.startsWith('b/')) {
+        return normalized.slice(2);
+    }
+    return normalized;
+};
+const inferHeaderPath = (line) => {
+    const match = /^diff --git (?:"a\/([^"]+)"|a\/(\S+)) (?:"b\/([^"]+)"|b\/(\S+))$/u.exec(line.trim());
+    if (!match) {
+        return null;
+    }
+    const rightPath = match[3] ?? match[4];
+    return rightPath ? stripGitPathPrefix(`b/${rightPath}`) : null;
+};
+const finalizeFileChange = (current, filesChanged) => {
+    if (!current) {
+        return;
+    }
+    const resolvedPath = current.plusPath ?? current.minusPath ?? current.headerPath;
+    if (!resolvedPath) {
+        throw new Error('Unable to derive a workspace-relative path from a diff block.');
+    }
+    filesChanged.push({
+        added: current.added > 0 ? current.added : undefined,
+        path: normalizeWorkspaceRelativePath(resolvedPath),
+        removed: current.removed > 0 ? current.removed : undefined,
+    });
+};
+const createDiffFileAccumulator = (line) => ({
+    added: 0,
+    headerPath: inferHeaderPath(line),
+    minusPath: null,
+    plusPath: null,
+    removed: 0,
+});
+const applyPatchMetadataLine = (current, line) => {
+    if (line.startsWith('+++ ')) {
+        return {
+            next: {
+                ...current,
+                plusPath: stripGitPathPrefix(line.slice(4)),
+            },
+        };
+    }
+    if (line.startsWith('--- ')) {
+        return {
+            next: {
+                ...current,
+                minusPath: stripGitPathPrefix(line.slice(4)),
+            },
+        };
+    }
+    if (line.startsWith('@@')) {
+        return {
+            next: current,
+            startHunk: true,
+        };
+    }
+    return {
+        next: current,
+    };
+};
+const applyPatchHunkLine = (current, line) => {
+    if (line.startsWith('+')) {
+        return {
+            ...current,
+            added: current.added + 1,
+        };
+    }
+    if (line.startsWith('-')) {
+        return {
+            ...current,
+            removed: current.removed + 1,
+        };
+    }
+    return current;
+};
+const mergeBlobLink = (links, blobSha256) => ({
+    ...links,
+    blobs: [...new Set([...(links?.blobs ?? []), blobSha256])],
+});
+const resolvePatchSource = async ({ record, workspaceRoot, }) => {
+    if (record.diffPath) {
+        const resolvedPath = path.resolve(workspaceRoot, record.diffPath);
+        return {
+            patchText: await readFile(resolvedPath, 'utf8'),
+            source: 'file',
+            sourceLabel: resolvedPath,
+        };
+    }
+    if (record.diffText) {
+        return {
+            patchText: record.diffText,
+            source: 'inline',
+            sourceLabel: 'inline diff text',
+        };
+    }
+    if (record.diff) {
+        try {
+            return {
+                patchText: await readBlobText(workspaceRoot, record.diff.blobSha256),
+                source: 'blob',
+                sourceLabel: `blob ${record.diff.blobSha256}`,
+            };
+        }
+        catch (error) {
+            if (error.code === 'ENOENT') {
+                throw new Error(`Patch blob ${record.diff.blobSha256} was not found for ${formatRecordContext(record)}. Store it first or use diffPath.`);
+            }
+            throw error;
+        }
+    }
+    throw new Error(`${record.kind} records require diff, diffPath, or diffText.`);
+};
+/**
+ * Derive `change-log.filesChanged` metadata from a git-style unified diff.
+ *
+ * Example:
+ * `deriveFilesChangedFromPatch(await readFile('/tmp/change.patch', 'utf8'))`
+ *
+ * Known limits:
+ * - Requires `diff --git` headers to identify file boundaries.
+ * - Counts only textual hunk `+` and `-` lines, so binary or mode-only diffs can yield zero line counts.
+ * - Uses the post-image path when available and rejects diff blocks that cannot be mapped to a normalized
+ *   workspace-relative path.
+ */
+export const deriveFilesChangedFromPatch = (patchText) => {
+    const filesChanged = [];
+    let current;
+    let insideHunk = false;
+    for (const line of patchText.split(/\r?\n/u)) {
+        if (line.startsWith('diff --git ')) {
+            finalizeFileChange(current, filesChanged);
+            current = createDiffFileAccumulator(line);
+            insideHunk = false;
+            continue;
+        }
+        if (!current) {
+            continue;
+        }
+        if (insideHunk) {
+            if (line.startsWith('@@')) {
+                continue;
+            }
+            current = applyPatchHunkLine(current, line);
+            continue;
+        }
+        const metadataUpdate = applyPatchMetadataLine(current, line);
+        current = metadataUpdate.next;
+        if (metadataUpdate.startHunk) {
+            insideHunk = true;
+            continue;
+        }
+        if (!insideHunk) {
+            continue;
+        }
+        current = applyPatchHunkLine(current, line);
+    }
+    finalizeFileChange(current, filesChanged);
+    return filesChanged;
+};
+const buildResolvedPatchRecord = ({ links, record, storedDiff, }) => {
+    const { diffPath: _diffPath, diffText: _diffText, ...rest } = record;
+    return {
+        ...rest,
+        diff: storedDiff,
+        links,
+    };
+};
+export async function resolvePatchRecord({ record, workspaceRoot, }) {
+    const { patchText, sourceLabel } = await resolvePatchSource({
+        record,
+        workspaceRoot,
+    });
+    const storedDiff = await storePatchBlob(workspaceRoot, patchText);
+    if (record.diff && record.diff.blobSha256 !== storedDiff.blobSha256) {
+        throw new Error(`Provided diff blob ${record.diff.blobSha256} from ${sourceLabel} does not match patch text hash ${storedDiff.blobSha256} for ${formatRecordContext(record)}.`);
+    }
+    return buildResolvedPatchRecord({
+        links: mergeBlobLink(record.links, storedDiff.blobSha256),
+        record,
+        storedDiff,
+    });
+}

package/dist/read-index.d.ts

@@ -3,14 +3,14 @@ import { type LedgerEntry, type LedgerKind, type LedgerPhase } from './schema/en
 import type { LedgerManifest } from './schema/manifest.ts';
 declare const ReadIndexEntrySchema: v.ObjectSchema<{
     readonly id: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.MinLengthAction<string, 1, undefined>]>;
-    readonly kind: v.PicklistSchema<readonly ["tool-invocation", "agent-patch", "operator-patch", "operator-decision", "validator-result", "runtime-event", "note", "correction", "strip-decision-reverted"], undefined>;
+    readonly kind: v.PicklistSchema<readonly ["tool-invocation", "agent-patch", "operator-patch", "operator-decision", "validator-result", "runtime-event", "note", "correction", "strip-decision-reverted", "change-log"], undefined>;
     readonly ts: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.IsoTimestampAction<string, undefined>]>;
 }, undefined>;
 declare const LedgerReadIndexSchema: v.SchemaWithPipe<readonly [v.ObjectSchema<{
     readonly coveredFiles: v.OptionalSchema<v.ArraySchema<v.StringSchema<undefined>, undefined>, readonly []>;
     readonly entries: v.OptionalSchema<v.ArraySchema<v.ObjectSchema<{
         readonly id: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.MinLengthAction<string, 1, undefined>]>;
-        readonly kind: v.PicklistSchema<readonly ["tool-invocation", "agent-patch", "operator-patch", "operator-decision", "validator-result", "runtime-event", "note", "correction", "strip-decision-reverted"], undefined>;
+        readonly kind: v.PicklistSchema<readonly ["tool-invocation", "agent-patch", "operator-patch", "operator-decision", "validator-result", "runtime-event", "note", "correction", "strip-decision-reverted", "change-log"], undefined>;
         readonly ts: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.IsoTimestampAction<string, undefined>]>;
     }, undefined>, undefined>, readonly []>;
     readonly entryCount: v.SchemaWithPipe<readonly [v.NumberSchema<undefined>, v.IntegerAction<number, undefined>, v.MinValueAction<number, 0, undefined>]>;
@@ -21,7 +21,7 @@ declare const LedgerReadIndexSchema: v.SchemaWithPipe<readonly [v.ObjectSchema<{
     coveredFiles: string[];
     entries: {
         id: string;
-        kind: "tool-invocation" | "agent-patch" | "operator-patch" | "operator-decision" | "validator-result" | "runtime-event" | "note" | "correction" | "strip-decision-reverted";
+        kind: "operator-decision" | "validator-result" | "change-log" | "tool-invocation" | "agent-patch" | "operator-patch" | "runtime-event" | "note" | "correction" | "strip-decision-reverted";
         ts: string;
     }[];
     entryCount: number;
@@ -32,7 +32,7 @@ declare const LedgerReadIndexSchema: v.SchemaWithPipe<readonly [v.ObjectSchema<{
     coveredFiles: string[];
     entries: {
         id: string;
-        kind: "tool-invocation" | "agent-patch" | "operator-patch" | "operator-decision" | "validator-result" | "runtime-event" | "note" | "correction" | "strip-decision-reverted";
+        kind: "operator-decision" | "validator-result" | "change-log" | "tool-invocation" | "agent-patch" | "operator-patch" | "runtime-event" | "note" | "correction" | "strip-decision-reverted";
         ts: string;
     }[];
     entryCount: number;
@@ -50,7 +50,7 @@ export declare const buildReadIndexFromManifest: (workspaceRoot: string, manifes
     coveredFiles: string[];
     entries: {
         id: string;
-        kind: "tool-invocation" | "agent-patch" | "operator-patch" | "operator-decision" | "validator-result" | "runtime-event" | "note" | "correction" | "strip-decision-reverted";
+        kind: "operator-decision" | "validator-result" | "change-log" | "tool-invocation" | "agent-patch" | "operator-patch" | "runtime-event" | "note" | "correction" | "strip-decision-reverted";
         ts: string;
     }[];
     entryCount: number;
@@ -65,7 +65,7 @@ export declare const ensureReadIndexUnderLock: (workspaceRoot: string, manifest:
     coveredFiles: string[];
     entries: {
         id: string;
-        kind: "tool-invocation" | "agent-patch" | "operator-patch" | "operator-decision" | "validator-result" | "runtime-event" | "note" | "correction" | "strip-decision-reverted";
+        kind: "operator-decision" | "validator-result" | "change-log" | "tool-invocation" | "agent-patch" | "operator-patch" | "runtime-event" | "note" | "correction" | "strip-decision-reverted";
         ts: string;
     }[];
     entryCount: number;
@@ -81,7 +81,7 @@ export declare const appendEntryToReadIndex: ({ entry, readIndex, sequence, }: {
     coveredFiles: string[];
     entries: {
         id: string;
-        kind: "tool-invocation" | "agent-patch" | "operator-patch" | "operator-decision" | "validator-result" | "runtime-event" | "note" | "correction" | "strip-decision-reverted";
+        kind: "operator-decision" | "validator-result" | "change-log" | "tool-invocation" | "agent-patch" | "operator-patch" | "runtime-event" | "note" | "correction" | "strip-decision-reverted";
         ts: string;
     }[];
     entryCount: number;

package/dist/read-index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"read-index.d.ts","sourceRoot":"","sources":["../src/read-index.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,CAAC,MAAM,SAAS,CAAC;AAG7B,OAAO,EAAgB,KAAK,WAAW,EAAE,KAAK,UAAU,EAAE,KAAK,WAAW,EAAoB,MAAM,mBAAmB,CAAC;AACxH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AAO3D,QAAA,MAAM,oBAAoB;;;;aAIxB,CAAC;AAEH,QAAA,MAAM,qBAAqB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;sDAiB1B,CAAC;AAEF,MAAM,MAAM,eAAe,GAAG,CAAC,CAAC,WAAW,CAAC,OAAO,qBAAqB,CAAC,CAAC;AAC1E,MAAM,MAAM,cAAc,GAAG,CAAC,CAAC,WAAW,CAAC,OAAO,oBAAoB,CAAC,CAAC;AACxE,MAAM,MAAM,qBAAqB,GAAG,SAAS,CAAC,MAAM,EAAE;IAAE,KAAK,EAAE,WAAW,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAA;CAAE,CAAC,CAAC;AA0HhG,eAAO,MAAM,0BAA0B,GAAU,eAAe,MAAM,EAAE,UAAU,cAAc;;;;;;;;;;;EAuB/F,CAAC;AAYF,eAAO,MAAM,kBAAkB,GAAI,OAAO,eAAe,EAAE,UAAU,cAAc,YAG1C,CAAC;AAE1C,eAAO,MAAM,aAAa,GAAU,eAAe,MAAM,KAAG,OAAO,CAAC,eAAe,GAAG,IAAI,CAWzF,CAAC;AAEF,eAAO,MAAM,aAAa,GAAU,eAAe,MAAM,EAAE,WAAW,eAAe,kBAGpF,CAAC;AAEF,eAAO,MAAM,wBAAwB,GAAU,eAAe,MAAM,EAAE,UAAU,cAAc;;;;;;;;;;;EAiB7F,CAAC;AAEF,eAAO,MAAM,sBAAsB,GAAI,iCAIpC;IACC,QAAQ,CAAC,KAAK,EAAE,WAAW,CAAC;IAC5B,QAAQ,CAAC,SAAS,EAAE,eAAe,CAAC;IACpC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;CAC7B;;;;;;;;;;;CAYA,CAAC;AAEF,eAAO,MAAM,sBAAsB,GAAI,uCAIpC;IACC,QAAQ,CAAC,MAAM,EAAE;QACb,QAAQ,CAAC,IAAI,CAAC,EAAE,UAAU,CAAC;QAC3B,QAAQ,CAAC,KAAK,CAAC,EAAE,WAAW,CAAC;QAC7B,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;KAC3B,CAAC;IACF,QAAQ,CAAC,QAAQ,EAAE,cAAc,CAAC;IAClC,QAAQ,CAAC,cAAc,EAAE,cAAc,CAAC;CAC3C,YAeA,CAAC"}
+{"version":3,"file":"read-index.d.ts","sourceRoot":"","sources":["../src/read-index.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,CAAC,MAAM,SAAS,CAAC;AAG7B,OAAO,EAAgB,KAAK,WAAW,EAAE,KAAK,UAAU,EAAE,KAAK,WAAW,EAAoB,MAAM,mBAAmB,CAAC;AACxH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AAO3D,QAAA,MAAM,oBAAoB;;;;aAIxB,CAAC;AAEH,QAAA,MAAM,qBAAqB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;sDAc1B,CAAC;AAEF,MAAM,MAAM,eAAe,GAAG,CAAC,CAAC,WAAW,CAAC,OAAO,qBAAqB,CAAC,CAAC;AAC1E,MAAM,MAAM,cAAc,GAAG,CAAC,CAAC,WAAW,CAAC,OAAO,oBAAoB,CAAC,CAAC;AACxE,MAAM,MAAM,qBAAqB,GAAG,SAAS,CAAC,MAAM,EAAE;IAAE,KAAK,EAAE,WAAW,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAA;CAAE,CAAC,CAAC;AA0HhG,eAAO,MAAM,0BAA0B,GAAU,eAAe,MAAM,EAAE,UAAU,cAAc;;;;;;;;;;;EAuB/F,CAAC;AAYF,eAAO,MAAM,kBAAkB,GAAI,OAAO,eAAe,EAAE,UAAU,cAAc,YAG1C,CAAC;AAE1C,eAAO,MAAM,aAAa,GAAU,eAAe,MAAM,KAAG,OAAO,CAAC,eAAe,GAAG,IAAI,CAWzF,CAAC;AAEF,eAAO,MAAM,aAAa,GAAU,eAAe,MAAM,EAAE,WAAW,eAAe,kBAGpF,CAAC;AAEF,eAAO,MAAM,wBAAwB,GAAU,eAAe,MAAM,EAAE,UAAU,cAAc;;;;;;;;;;;EAiB7F,CAAC;AAEF,eAAO,MAAM,sBAAsB,GAAI,iCAIpC;IACC,QAAQ,CAAC,KAAK,EAAE,WAAW,CAAC;IAC5B,QAAQ,CAAC,SAAS,EAAE,eAAe,CAAC;IACpC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;CAC7B;;;;;;;;;;;CAYA,CAAC;AAEF,eAAO,MAAM,sBAAsB,GAAI,uCAIpC;IACC,QAAQ,CAAC,MAAM,EAAE;QACb,QAAQ,CAAC,IAAI,CAAC,EAAE,UAAU,CAAC;QAC3B,QAAQ,CAAC,KAAK,CAAC,EAAE,WAAW,CAAC;QAC7B,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;KAC3B,CAAC;IACF,QAAQ,CAAC,QAAQ,EAAE,cAAc,CAAC;IAClC,QAAQ,CAAC,cAAc,EAAE,cAAc,CAAC;CAC3C,YAeA,CAAC"}

package/dist/record.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"record.d.ts","sourceRoot":"","sources":["../src/record.ts"],"names":[],"mappings":"AAQA,OAAO,EAEH,KAAK,WAAW,EAKnB,MAAM,mBAAmB,CAAC;AAC3B,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AAU3D,KAAK,qBAAqB,GAAG;IACzB,QAAQ,CAAC,eAAe,CAAC,EAAE,CAAC,OAAO,EAAE;QAAE,KAAK,EAAE,WAAW,CAAA;KAAE,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IAC9E,QAAQ,CAAC,iBAAiB,CAAC,EAAE,CAAC,OAAO,EAAE;QAAE,KAAK,EAAE,WAAW,CAAA;KAAE,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IAChF,QAAQ,CAAC,uBAAuB,CAAC,EAAE,CAAC,OAAO,EAAE;QAAE,KAAK,EAAE,WAAW,CAAC;QAAC,iBAAiB,EAAE,MAAM,CAAA;KAAE,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IACjH,QAAQ,CAAC,kBAAkB,CAAC,EAAE,CAAC,OAAO,EAAE;QAAE,KAAK,EAAE,WAAW,CAAA;KAAE,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;CACpF,CAAC;AAUF,eAAO,MAAM,wBAAwB,GAAI,eAAe,MAAM,EAAE,OAAO,qBAAqB,GAAG,IAAI,SAOlG,CAAC;AAoHF,eAAO,MAAM,YAAY,GACrB,eAAe,MAAM,EACrB,OAAO,OAAO,KACf,OAAO,CAAC;IAAE,KAAK,EAAE,WAAW,CAAC;IAAC,EAAE,EAAE,MAAM,CAAA;CAAE,CAqF5C,CAAC;AAEF,eAAO,MAAM,aAAa,GACtB,eAAe,MAAM,EACrB,UAAU,cAAc,EACxB,SAAS,MAAM,KAChB,OAAO,CAAC,WAAW,CAMrB,CAAC"}
+{"version":3,"file":"record.d.ts","sourceRoot":"","sources":["../src/record.ts"],"names":[],"mappings":"AAQA,OAAO,EACH,KAAK,WAAW,EAMnB,MAAM,mBAAmB,CAAC;AAC3B,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AAU3D,KAAK,qBAAqB,GAAG;IACzB,QAAQ,CAAC,eAAe,CAAC,EAAE,CAAC,OAAO,EAAE;QAAE,KAAK,EAAE,WAAW,CAAA;KAAE,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IAC9E,QAAQ,CAAC,iBAAiB,CAAC,EAAE,CAAC,OAAO,EAAE;QAAE,KAAK,EAAE,WAAW,CAAA;KAAE,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IAChF,QAAQ,CAAC,uBAAuB,CAAC,EAAE,CAAC,OAAO,EAAE;QAAE,KAAK,EAAE,WAAW,CAAC;QAAC,iBAAiB,EAAE,MAAM,CAAA;KAAE,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IACjH,QAAQ,CAAC,kBAAkB,CAAC,EAAE,CAAC,OAAO,EAAE;QAAE,KAAK,EAAE,WAAW,CAAA;KAAE,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;CACpF,CAAC;AAOF,eAAO,MAAM,wBAAwB,GAAI,eAAe,MAAM,EAAE,OAAO,qBAAqB,GAAG,IAAI,SAOlG,CAAC;AA0EF,eAAO,MAAM,YAAY,GACrB,eAAe,MAAM,EACrB,OAAO,OAAO,KACf,OAAO,CAAC;IAAE,KAAK,EAAE,WAAW,CAAC;IAAC,EAAE,EAAE,MAAM,CAAA;CAAE,CAsF5C,CAAC;AAEF,eAAO,MAAM,aAAa,GACtB,eAAe,MAAM,EACrB,UAAU,cAAc,EACxB,SAAS,MAAM,KAChB,OAAO,CAAC,WAAW,CASrB,CAAC"}

package/dist/record.js

@@ -1,12 +1,12 @@
 import { readFile } from 'node:fs/promises';
 import path from 'node:path';
 import * as v from 'valibot';
-import { resolveBlobPath, storePatchBlob } from "./blobs.js";
 import { sha256Hex, stableStringify } from "./json.js";
 import { updateManifestForEntry } from "./manifest-update.js";
+import { resolvePatchRecord } from "./patch-resolver.js";
 import { appendEntryToReadIndex, saveReadIndex } from "./read-index.js";
 import { reconcileLedgerStateUnderLock, removePendingCommit, writePendingCommit } from "./recovery.js";
-import { LedgerEntrySchema, parseLedgerEntry, parseLedgerRecord, } from "./schema/entry.js";
+import { LedgerEntrySchema, LedgerSchemaVersion, parseLedgerEntry, parseLedgerRecord, } from "./schema/entry.js";
 import { ensureLedgerDirectories, readManifest, resolveLedgerPaths, saveManifest, writeEntryFile, } from "./storage/filesystem.js";
 import { acquireLock } from "./storage/lock.js";
 const appendRecordTestHooks = new Map();
@@ -20,7 +20,6 @@ export const setAppendRecordTestHooks = (workspaceRoot, hooks) => {
     }
     appendRecordTestHooks.set(key, hooks);
 };
-const readBlobText = async (workspaceRoot, diff) => readFile(resolveBlobPath(workspaceRoot, diff.blobSha256), 'utf8');
 const addIdempotencyMetadata = (record) => {
     if (!record.idempotencyKey) {
         return record;
@@ -52,47 +51,22 @@ const buildEntryId = (entryWithoutId, sequence) => {
     const bodyHash = sha256Hex(stableStringify(entryWithoutId));
     return `${toEntryIdTimestamp(entryWithoutId.ts)}-${sequence.toString().padStart(8, '0')}-${bodyHash.slice(0, 12)}`;
 };
-const loadPatchText = async ({ record, workspaceRoot, }) => {
-    if (record.diffPath) {
-        return readFile(path.resolve(record.diffPath), 'utf8');
-    }
-    if (record.diffText) {
-        return record.diffText;
+const normalizeRecord = async ({ record, workspaceRoot, }) => {
+    if (record.kind === 'agent-patch') {
+        return resolvePatchRecord({ record, workspaceRoot });
     }
-    if (record.diff) {
-        try {
-            return await readBlobText(workspaceRoot, record.diff);
-        }
-        catch (error) {
-            if (error.code === 'ENOENT') {
-                throw new Error(`Patch blob ${record.diff.blobSha256} was not found. Store it first or use diffPath.`);
-            }
-            throw error;
-        }
+    if (record.kind === 'operator-patch') {
+        return resolvePatchRecord({ record, workspaceRoot });
     }
-    throw new Error(`${record.kind} records require diff, diffPath, or diffText.`);
+    return record;
 };
-const resolvePatchRecord = async ({ record, workspaceRoot, }) => {
-    const patchText = await loadPatchText({ record, workspaceRoot });
-    const storedDiff = await storePatchBlob(workspaceRoot, patchText);
-    if (record.diff && record.diff.blobSha256 !== storedDiff.blobSha256) {
-        throw new Error(`Provided diff blob ${record.diff.blobSha256} does not match patch text hash ${storedDiff.blobSha256}.`);
+const assertRollbackTargetExists = (record, manifest) => {
+    if (record.kind !== 'change-log' || record.subkind !== 'rollback' || !record.rollsBack) {
+        return;
     }
-    const { diffPath: _diffPath, diffText: _diffText, ...rest } = record;
-    return {
-        ...rest,
-        diff: storedDiff,
-        links: {
-            ...record.links,
-            blobs: [...new Set([...(record.links?.blobs ?? []), storedDiff.blobSha256])],
-        },
-    };
-};
-const normalizeRecord = async ({ record, workspaceRoot, }) => {
-    if (record.kind === 'agent-patch' || record.kind === 'operator-patch') {
-        return resolvePatchRecord({ record, workspaceRoot });
+    if (!manifest.entryLocations[record.rollsBack]) {
+        throw new Error(`change-log rollback target was not found in the ledger: ${record.rollsBack}`);
     }
-    return record;
 };
 export const appendRecord = async (workspaceRoot, input) => {
     const parsed = parseLedgerRecord(input);
@@ -105,6 +79,7 @@ export const appendRecord = async (workspaceRoot, input) => {
     const lock = await acquireLock(paths.manifestLockFile);
     try {
         const { manifest, readIndex } = await reconcileLedgerStateUnderLock(workspaceRoot);
+        assertRollbackTargetExists(recordWithMetadata, manifest);
         const manifestFingerprint = fingerprintManifest(manifest);
         const keyedLogicalHash = parsed.idempotencyKey ? buildLogicalHash(recordWithMetadata) : null;
         if (keyedLogicalHash) {
@@ -136,7 +111,7 @@ export const appendRecord = async (workspaceRoot, input) => {
             ...recordWithoutIdempotencyKey,
             links: recordWithoutIdempotencyKey.links ?? {},
             prevEntryId: manifest.perPhaseLatest[normalizedRecord.phase] ?? null,
-            schemaVersion: 'ushman-ledger-entry/v1',
+            schemaVersion: LedgerSchemaVersion,
             ts: new Date().toISOString(),
         };
         const entry = v.parse(LedgerEntrySchema, {

package/dist/render/migration-log.d.ts

@@ -0,0 +1,10 @@
+import type { LedgerEntry } from '../schema/entry.ts';
+export declare const writeMigrationLogMarkdown: ({ entries, write, }: {
+    readonly entries: AsyncIterable<LedgerEntry>;
+    readonly write: (chunk: string) => Promise<void> | void;
+}) => Promise<void>;
+export declare const renderMigrationLogMarkdown: ({ entries, write, }: {
+    readonly entries: AsyncIterable<LedgerEntry>;
+    readonly write?: (chunk: string) => Promise<void> | void;
+}) => Promise<string>;
+//# sourceMappingURL=migration-log.d.ts.map

package/dist/render/migration-log.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"migration-log.d.ts","sourceRoot":"","sources":["../../src/render/migration-log.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAuC,WAAW,EAAE,MAAM,oBAAoB,CAAC;AAmE3F,eAAO,MAAM,yBAAyB,GAAU,qBAG7C;IACC,QAAQ,CAAC,OAAO,EAAE,aAAa,CAAC,WAAW,CAAC,CAAC;IAC7C,QAAQ,CAAC,KAAK,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC;CAC3D,kBAaA,CAAC;AAEF,eAAO,MAAM,0BAA0B,GAAU,qBAG9C;IACC,QAAQ,CAAC,OAAO,EAAE,aAAa,CAAC,WAAW,CAAC,CAAC;IAC7C,QAAQ,CAAC,KAAK,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC;CAC5D,KAAG,OAAO,CAAC,MAAM,CASjB,CAAC"}

package/dist/render/migration-log.js

@@ -0,0 +1,79 @@
+const getFence = (lines) => {
+    const longestBacktickRun = lines.reduce((longest, line) => {
+        const matches = line.match(/`+/gu) ?? [];
+        return Math.max(longest, ...matches.map((match) => match.length), 3);
+    }, 3);
+    return '`'.repeat(longestBacktickRun + 1);
+};
+const toCodeBlock = (commandsRun) => {
+    const lines = commandsRun && commandsRun.length > 0 ? commandsRun : ['# None recorded'];
+    const fence = getFence(lines);
+    return [fence + 'bash', ...lines, fence].join('\n');
+};
+const renderFilesChanged = (filesChanged) => filesChanged.length === 0
+    ? '- None recorded.'
+    : filesChanged
+        .map((fileChange) => {
+        const stats = [`+${fileChange.added ?? 0}`, `-${fileChange.removed ?? 0}`].join(' ');
+        return `- \`${fileChange.path}\` (${stats})`;
+    })
+        .join('\n');
+const renderOptionalLine = (label, value) => `**${label}**: ${value ?? 'Not recorded.'}`;
+const renderSmokeLine = (entry) => {
+    if (entry.smokeResult && entry.smokeNotes) {
+        return `**Smoke result**: ${entry.smokeResult} - ${entry.smokeNotes}`;
+    }
+    if (entry.smokeResult) {
+        return `**Smoke result**: ${entry.smokeResult}`;
+    }
+    if (entry.smokeNotes) {
+        return ['**Smoke result**: Not recorded.', '', `**Smoke notes**: ${entry.smokeNotes}`].join('\n');
+    }
+    return '**Smoke result**: Not recorded.';
+};
+const isChangeLogEntry = (entry) => entry.kind === 'change-log';
+const renderChangeLogSection = (entry) => [
+    `## ${entry.ts} - ${entry.summary}`,
+    '',
+    `**Type**: ${entry.subkind}`,
+    '',
+    '**Files changed**:',
+    renderFilesChanged(entry.filesChanged),
+    '',
+    renderOptionalLine('Hypothesis', entry.hypothesis),
+    '',
+    '**Commands run**:',
+    toCodeBlock(entry.commandsRun),
+    '',
+    renderSmokeLine(entry),
+    '',
+    renderOptionalLine('Parity status', entry.parityStatus),
+    '',
+    renderOptionalLine('Rollback plan', entry.rollbackPlan),
+    '',
+    '---',
+    '',
+].join('\n');
+export const writeMigrationLogMarkdown = async ({ entries, write, }) => {
+    await write('# Ushman Ledger Migration Log\n\n');
+    let hasEntries = false;
+    for await (const entry of entries) {
+        if (!isChangeLogEntry(entry)) {
+            continue;
+        }
+        hasEntries = true;
+        await write(renderChangeLogSection(entry));
+    }
+    if (!hasEntries) {
+        await write('No change-log entries recorded.');
+    }
+};
+export const renderMigrationLogMarkdown = async ({ entries, write, }) => {
+    const chunks = [];
+    const resolvedWriter = write ??
+        ((chunk) => {
+            chunks.push(chunk);
+        });
+    await writeMigrationLogMarkdown({ entries, write: resolvedWriter });
+    return chunks.join('');
+};

package/dist/render/retro.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"retro.d.ts","sourceRoot":"","sources":["../../src/render/retro.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AA6GtD,eAAO,MAAM,mBAAmB,GAAU,wBAGvC;IACC,QAAQ,CAAC,OAAO,EAAE,aAAa,CAAC,WAAW,CAAC,CAAC;IAC7C,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAC;CAC9B,KAAG,OAAO,CAAC,MAAM,CA6CjB,CAAC"}
+{"version":3,"file":"retro.d.ts","sourceRoot":"","sources":["../../src/render/retro.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AA4HtD,eAAO,MAAM,mBAAmB,GAAU,wBAGvC;IACC,QAAQ,CAAC,OAAO,EAAE,aAAa,CAAC,WAAW,CAAC,CAAC;IAC7C,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAC;CAC9B,KAAG,OAAO,CAAC,MAAM,CAgDjB,CAAC"}

package/dist/render/retro.js

@@ -4,6 +4,7 @@ const toSingleLine = (value) => value.replaceAll(/\s+/gu, ' ').trim();
 const formatEntry = (entry) => `${entry.ts} [${entry.phase}] ${toSingleLine(entry.summary)}`;
 const createRetroBuckets = () => ({
     correctionEntries: [],
+    dedicatedNarrativeEntries: [],
     operatorEntries: [],
     problemEntries: [],
     retroEntries: [],
@@ -18,6 +19,9 @@ const isToolingEntry = (entry) => (entry.kind === 'note' && entry.subkind === 'a
     (entry.kind === 'note' && entry.subkind === 'tooling-gap');
 const isRetroNote = (entry) => entry.kind === 'note' && entry.subkind === 'retro';
 const isOperatorNote = (entry) => entry.kind === 'note' && entry.subkind === 'operator';
+const isDedicatedNarrativeEntry = (entry) => entry.kind === 'change-log' ||
+    (entry.kind === 'note' &&
+        ['cleanup-wave', 'verified-flow', 'open-issue', 'decomposition-wave', 'semantic-cleanup-summary'].includes(entry.subkind));
 const resolveRenderedAt = (entryCount, lastEntryTimestamp, manifest) => {
     if (entryCount > 0) {
         return lastEntryTimestamp ?? 'n/a';
@@ -36,6 +40,32 @@ const normalizeManifestForHash = (manifest) => typeof manifest === 'object' && m
 const formatValidatorEntry = (entry) => entry.kind === 'validator-result'
     ? `${entry.ts} [${entry.validator}/${entry.verdict}] ${entry.summary}`
     : formatEntry(entry);
+const bucketRetroEntry = (buckets, entry) => {
+    if (isToolEntry(entry)) {
+        buckets.toolEntries.push(formatEntry(entry));
+    }
+    if (isProblemEntry(entry)) {
+        buckets.problemEntries.push(formatEntry(entry));
+    }
+    if (isToolingEntry(entry)) {
+        buckets.toolingEntries.push(formatEntry(entry));
+    }
+    if (isRetroNote(entry)) {
+        buckets.retroEntries.push(formatEntry(entry));
+    }
+    if (entry.kind === 'validator-result') {
+        buckets.validatorEntries.push(formatValidatorEntry(entry));
+    }
+    if (entry.kind === 'correction') {
+        buckets.correctionEntries.push(formatEntry(entry));
+    }
+    if (isOperatorNote(entry)) {
+        buckets.operatorEntries.push(formatEntry(entry));
+    }
+    if (isDedicatedNarrativeEntry(entry)) {
+        buckets.dedicatedNarrativeEntries.push(formatEntry(entry));
+    }
+};
 const collectRetroState = async (entries) => {
     const buckets = createRetroBuckets();
     const tools = new Set();
@@ -45,27 +75,7 @@ const collectRetroState = async (entries) => {
         entryCount += 1;
         lastEntryTimestamp = entry.ts;
         tools.add(entry.emitter.tool);
-        if (isToolEntry(entry)) {
-            buckets.toolEntries.push(formatEntry(entry));
-        }
-        if (isProblemEntry(entry)) {
-            buckets.problemEntries.push(formatEntry(entry));
-        }
-        if (isToolingEntry(entry)) {
-            buckets.toolingEntries.push(formatEntry(entry));
-        }
-        if (isRetroNote(entry)) {
-            buckets.retroEntries.push(formatEntry(entry));
-        }
-        if (entry.kind === 'validator-result') {
-            buckets.validatorEntries.push(formatValidatorEntry(entry));
-        }
-        if (entry.kind === 'correction') {
-            buckets.correctionEntries.push(formatEntry(entry));
-        }
-        if (isOperatorNote(entry)) {
-            buckets.operatorEntries.push(formatEntry(entry));
-        }
+        bucketRetroEntry(buckets, entry);
     }
     return {
         buckets,
@@ -117,5 +127,8 @@ export const renderRetroMarkdown = async ({ entries, manifest, }) => {
         '## 10. Triage signals',
         renderList(buckets.validatorEntries),
         '',
+        '## 11. Dedicated narrative/change-log entries',
+        renderList(buckets.dedicatedNarrativeEntries),
+        '',
     ].join('\n');
 };

package/dist/render/workspace-narrative.d.ts

@@ -0,0 +1,12 @@
+import type { LedgerEntry } from '../schema/entry.ts';
+export declare const writeWorkspaceNarrativeMarkdown: ({ entries, workspaceName, write, }: {
+    readonly entries: AsyncIterable<LedgerEntry>;
+    readonly workspaceName: string;
+    readonly write: (chunk: string) => Promise<void> | void;
+}) => Promise<void>;
+export declare const renderWorkspaceNarrativeMarkdown: ({ entries, workspaceName, write, }: {
+    readonly entries: AsyncIterable<LedgerEntry>;
+    readonly workspaceName: string;
+    readonly write?: (chunk: string) => Promise<void> | void;
+}) => Promise<string>;
+//# sourceMappingURL=workspace-narrative.d.ts.map

package/dist/render/workspace-narrative.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"workspace-narrative.d.ts","sourceRoot":"","sources":["../../src/render/workspace-narrative.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAa,MAAM,oBAAoB,CAAC;AAuIjE,eAAO,MAAM,+BAA+B,GAAU,oCAInD;IACC,QAAQ,CAAC,OAAO,EAAE,aAAa,CAAC,WAAW,CAAC,CAAC;IAC7C,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAC/B,QAAQ,CAAC,KAAK,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC;CAC3D,kBA+BA,CAAC;AAEF,eAAO,MAAM,gCAAgC,GAAU,oCAIpD;IACC,QAAQ,CAAC,OAAO,EAAE,aAAa,CAAC,WAAW,CAAC,CAAC;IAC7C,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAC/B,QAAQ,CAAC,KAAK,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC;CAC5D,KAAG,OAAO,CAAC,MAAM,CAajB,CAAC"}