ushman-ledger 1.1.0 → 1.2.0

package/dist/patch-resolver.js

@@ -0,0 +1,184 @@
+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.`);
+};
+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/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":"AASA,OAAO,EACH,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;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,CAMrB,CAAC"}

package/dist/record.js

@@ -1,9 +1,10 @@
 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 { LedgerSchemaVersion } from "./schema/entry.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";
@@ -20,7 +21,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 +52,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 +80,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 +112,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,3 @@
+import type { LedgerEntry } from '../schema/entry.ts';
+export declare const renderMigrationLogMarkdown: (entries: AsyncIterable<LedgerEntry>) => 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;AA2C3F,eAAO,MAAM,0BAA0B,GAAU,SAAS,aAAa,CAAC,WAAW,CAAC,KAAG,OAAO,CAAC,MAAM,CAwCpG,CAAC"}

package/dist/render/migration-log.js

@@ -0,0 +1,72 @@
+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';
+export const renderMigrationLogMarkdown = async (entries) => {
+    const changeLogEntries = [];
+    for await (const entry of entries) {
+        if (isChangeLogEntry(entry)) {
+            changeLogEntries.push(entry);
+        }
+    }
+    changeLogEntries.reverse();
+    if (changeLogEntries.length === 0) {
+        return ['# Ushman Ledger Migration Log', '', 'No change-log entries recorded.'].join('\n');
+    }
+    return [
+        '# Ushman Ledger Migration Log',
+        '',
+        ...changeLogEntries.flatMap((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');
+};

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;AAgItD,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,15 @@ 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 +46,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 +81,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 +133,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,6 @@
+import type { LedgerEntry } from '../schema/entry.ts';
+export declare const renderWorkspaceNarrativeMarkdown: ({ entries, workspaceName, }: {
+    readonly entries: AsyncIterable<LedgerEntry>;
+    readonly workspaceName: string;
+}) => 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;AAsCjE,eAAO,MAAM,gCAAgC,GAAU,6BAGpD;IACC,QAAQ,CAAC,OAAO,EAAE,aAAa,CAAC,WAAW,CAAC,CAAC;IAC7C,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;CAClC,KAAG,OAAO,CAAC,MAAM,CA+CjB,CAAC"}

package/dist/render/workspace-narrative.js

@@ -0,0 +1,69 @@
+const SECTION_TITLES = {
+    cleanupWave: '## Cleanup waves (newest first)',
+    decompositionWave: '## Decomposition waves',
+    openIssue: '## Open issues',
+    semanticCleanupSummary: '## Semantic cleanup summary',
+    semanticCleanupSummaryArchive: '## Archive — prior semantic-cleanup summaries',
+    verifiedFlow: '## Verified flows',
+};
+const NARRATIVE_SUBKINDS = [
+    'cleanup-wave',
+    'verified-flow',
+    'open-issue',
+    'decomposition-wave',
+    'semantic-cleanup-summary',
+];
+const isNarrativeNote = (entry) => entry.kind === 'note' && NARRATIVE_SUBKINDS.some((subkind) => subkind === entry.subkind);
+const byNewestFirst = (left, right) => right.ts.localeCompare(left.ts);
+const renderBulletSection = (entries) => entries.length === 0
+    ? '- None recorded.'
+    : entries.map((entry) => `- ${entry.ts} — ${entry.summary}`).join('\n');
+const renderLatestSummary = (entries) => {
+    const [latest] = entries;
+    if (!latest) {
+        return 'No entries recorded.';
+    }
+    return [`### ${latest.ts} — ${latest.summary}`, '', latest.body || 'No narrative body recorded.'].join('\n');
+};
+export const renderWorkspaceNarrativeMarkdown = async ({ entries, workspaceName, }) => {
+    const entriesBySubkind = new Map(NARRATIVE_SUBKINDS.map((subkind) => [subkind, []]));
+    for await (const entry of entries) {
+        if (!isNarrativeNote(entry)) {
+            continue;
+        }
+        entriesBySubkind.get(entry.subkind)?.push(entry);
+    }
+    for (const noteEntries of entriesBySubkind.values()) {
+        noteEntries.sort(byNewestFirst);
+    }
+    const semanticCleanupSummaries = entriesBySubkind.get('semantic-cleanup-summary') ?? [];
+    const [, ...archivedSummaries] = semanticCleanupSummaries;
+    return [
+        `# Workspace narrative — ${workspaceName}`,
+        '',
+        SECTION_TITLES.semanticCleanupSummary,
+        '',
+        renderLatestSummary(semanticCleanupSummaries),
+        '',
+        SECTION_TITLES.cleanupWave,
+        '',
+        renderBulletSection(entriesBySubkind.get('cleanup-wave') ?? []),
+        '',
+        SECTION_TITLES.verifiedFlow,
+        '',
+        renderBulletSection(entriesBySubkind.get('verified-flow') ?? []),
+        '',
+        SECTION_TITLES.openIssue,
+        '',
+        renderBulletSection(entriesBySubkind.get('open-issue') ?? []),
+        '',
+        SECTION_TITLES.decompositionWave,
+        '',
+        renderBulletSection(entriesBySubkind.get('decomposition-wave') ?? []),
+        '',
+        SECTION_TITLES.semanticCleanupSummaryArchive,
+        '',
+        renderBulletSection(archivedSummaries),
+        '',
+    ].join('\n');
+};