ushman-ledger 0.3.0 → 1.2.0

package/dist/record.js

@@ -1,29 +1,18 @@
 import { readFile } from 'node:fs/promises';
 import path from 'node:path';
-import { resolveBlobPath, storePatchBlob } from "./blobs.js";
+import * as v from 'valibot';
 import { sha256Hex, stableStringify } from "./json.js";
 import { updateManifestForEntry } from "./manifest-update.js";
-import { derivePatchPayloadFromDiffText } from "./patch-metadata.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, OperatorDecisionPayloadSchema, PatchPayloadWriteSchema, parseLedgerEntry, parseLedgerRecord, ValidatorResultPayloadSchema, } from "./schema/entry.js";
+import { LedgerEntrySchema, parseLedgerEntry, parseLedgerRecord, } from "./schema/entry.js";
 import { ensureLedgerDirectories, readManifest, resolveLedgerPaths, saveManifest, writeEntryFile, } from "./storage/filesystem.js";
 import { acquireLock } from "./storage/lock.js";
-import { createDeterministicUuidV7 } from "./uuid.js";
 const appendRecordTestHooks = new Map();
 const resolveWorkspaceKey = (workspaceRoot) => path.resolve(workspaceRoot);
 const getAppendRecordTestHooks = (workspaceRoot) => appendRecordTestHooks.get(resolveWorkspaceKey(workspaceRoot));
-const warnedDeprecations = new Set();
-const warnOnce = (key, message) => {
-    if (warnedDeprecations.has(key)) {
-        return;
-    }
-    warnedDeprecations.add(key);
-    process.emitWarning(message, {
-        code: key,
-        type: 'DeprecationWarning',
-    });
-};
 export const setAppendRecordTestHooks = (workspaceRoot, hooks) => {
     const key = resolveWorkspaceKey(workspaceRoot);
     if (!hooks) {
@@ -32,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;
@@ -64,118 +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 normalizeValidatorResultRecord = (record) => {
-    if (record.kind !== 'validator-result') {
-        return record;
-    }
-    const payloadId = record.payload?.id;
-    if (payloadId) {
-        return {
-            ...record,
-            payload: ValidatorResultPayloadSchema.parse(record.payload),
-        };
-    }
-    warnOnce('USHMAN_LEDGER_VALIDATOR_ID_COMPAT', 'validator-result records should provide payload.id. A compatibility UUIDv7 was synthesized for this append.');
-    return {
-        ...record,
-        payload: {
-            id: createDeterministicUuidV7({
-                seed: stableStringify(record),
-                timestamp: 0,
-            }),
-        },
-    };
-};
-const resolvePatchTextAndBlob = async ({ record, workspaceRoot, }) => {
-    if (record.diffPath) {
-        const patchText = await readFile(path.resolve(record.diffPath), 'utf8');
-        return {
-            patchText,
-            storedDiff: await storePatchBlob(workspaceRoot, patchText),
-        };
-    }
-    if (record.payload?.diff) {
-        const storedDiff = await storePatchBlob(workspaceRoot, record.payload.diff);
-        if (record.diff && record.diff.blobSha256 !== storedDiff.blobSha256) {
-            throw new Error(`Provided diff blob ${record.diff.blobSha256} does not match payload.diff hash ${storedDiff.blobSha256}.`);
-        }
-        return {
-            patchText: record.payload.diff,
-            storedDiff,
-        };
-    }
-    if (!record.diff) {
-        throw new Error(`${record.kind} records require payload.diff, diffPath, or diff metadata.`);
-    }
-    try {
-        const patchText = await readBlobText(workspaceRoot, record.diff);
-        return {
-            patchText,
-            storedDiff: record.diff,
-        };
+const normalizeRecord = async ({ record, workspaceRoot, }) => {
+    if (record.kind === 'agent-patch') {
+        return resolvePatchRecord({ record, workspaceRoot });
     }
-    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 });
     }
+    return record;
 };
-const resolvePatchPayload = async ({ patchText, record, workspaceRoot, }) => {
-    const derivedPayload = await derivePatchPayloadFromDiffText({
-        patchText,
-        workspaceRoot,
-    });
-    const mergedPayload = PatchPayloadWriteSchema.parse({
-        ...derivedPayload,
-        ...record.payload,
-        diff: record.payload?.diff ?? patchText,
-        diffSha256: record.payload?.diffSha256 ?? derivedPayload.diffSha256,
-        fileSha256After: record.payload?.fileSha256After ?? derivedPayload.fileSha256After,
-        fileSha256Before: record.payload?.fileSha256Before ?? derivedPayload.fileSha256Before,
-        hunks: record.payload?.hunks ?? derivedPayload.hunks,
-        touchedPaths: record.payload?.touchedPaths ?? derivedPayload.touchedPaths,
-    });
-    return mergedPayload;
-};
-const resolvePatchRecord = async ({ record, workspaceRoot, }) => {
-    const { patchText, storedDiff } = await resolvePatchTextAndBlob({
-        record,
-        workspaceRoot,
-    });
-    const payload = await resolvePatchPayload({
-        patchText,
-        record,
-        workspaceRoot,
-    });
-    if (payload.diffSha256 !== storedDiff.blobSha256) {
-        throw new Error(`Patch payload hash ${payload.diffSha256} does not match stored blob hash ${storedDiff.blobSha256}.`);
+const assertRollbackTargetExists = (record, manifest) => {
+    if (record.kind !== 'change-log' || record.subkind !== 'rollback' || !record.rollsBack) {
+        return;
     }
-    return {
-        ...record,
-        diff: storedDiff,
-        links: {
-            ...record.links,
-            affectedFiles: [...new Set([...(record.links?.affectedFiles ?? []), ...payload.touchedPaths])],
-            blobs: [...new Set([...(record.links?.blobs ?? []), storedDiff.blobSha256])],
-        },
-        payload,
-    };
-};
-const normalizeRecord = async ({ record, workspaceRoot, }) => {
-    const normalizedRecord = normalizeValidatorResultRecord(record);
-    if (normalizedRecord.kind === 'agent-patch' || normalizedRecord.kind === 'operator-patch') {
-        return resolvePatchRecord({
-            record: normalizedRecord,
-            workspaceRoot,
-        });
+    if (!manifest.entryLocations[record.rollsBack]) {
+        throw new Error(`change-log rollback target was not found in the ledger: ${record.rollsBack}`);
     }
-    return normalizedRecord.kind === 'operator-decision'
-        ? {
-            ...normalizedRecord,
-            payload: OperatorDecisionPayloadSchema.parse(normalizedRecord.payload),
-        }
-        : normalizedRecord;
 };
 export const appendRecord = async (workspaceRoot, input) => {
     const parsed = parseLedgerRecord(input);
@@ -188,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) {
@@ -219,10 +112,10 @@ 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 = LedgerEntrySchema.parse({
+        const entry = v.parse(LedgerEntrySchema, {
             ...entryWithoutId,
             id: buildEntryId(entryWithoutId, nextSequence),
         });
@@ -259,10 +152,6 @@ export const appendRecord = async (workspaceRoot, input) => {
     }
 };
 export const readEntryById = async (workspaceRoot, manifest, entryId) => {
-    const location = manifest.entryLocations[entryId];
-    if (!location) {
-        throw new Error(`Ledger entry not found: ${entryId}`);
-    }
-    const text = await readFile(path.join(resolveLedgerPaths(workspaceRoot).phaseDir(location.phase), `${entryId}.json`), 'utf8');
+    const text = await readFile(path.join(resolveLedgerPaths(workspaceRoot).phaseDir(manifest.entryLocations[entryId].phase), `${entryId}.json`), 'utf8');
     return parseLedgerEntry(JSON.parse(text));
 };

package/dist/recovery.d.ts

@@ -13,7 +13,6 @@ export declare const writePendingCommit: ({ entry, logicalHash, manifest, worksp
 }) => Promise<string>;
 export declare const removePendingCommit: (filePath: string) => Promise<void>;
 export declare const reconcilePendingCommitsUnderLock: (workspaceRoot: string) => Promise<{
-    [x: string]: unknown;
     archives: {
         createdAt: string;
         integrityHash: string;
@@ -21,17 +20,29 @@ export declare const reconcilePendingCommitsUnderLock: (workspaceRoot: string) =
     }[];
     createdAt: string;
     entryCount: number;
-    entryLocations: Record<string, {
-        phase: "seed" | "capture" | "intake" | "vendor-extract" | "cleanup" | "parity" | "characterize" | "equiv" | "analyze" | "recover" | "ship" | "migration";
-        sequence: number;
-    }>;
-    idempotencyIndex: Record<string, Record<string, string>>;
+    entryLocations: {
+        [x: string]: {
+            phase: "capture" | "intake" | "seed" | "vendor-extract" | "cleanup" | "parity" | "characterize" | "equiv" | "analyze" | "recover" | "ship" | "migration";
+            sequence: number;
+        };
+    };
+    idempotencyIndex: {
+        [x: string]: {
+            [x: string]: string;
+        };
+    };
     lastSequence: number;
-    perPhaseCounts: Record<string, number>;
-    perPhaseLatest: Record<string, string>;
+    perPhaseCounts: {
+        [x: string]: number;
+    };
+    perPhaseLatest: {
+        [x: string]: string;
+    };
     schemaVersion: "ushman-ledger-manifest/v1";
     updatedAt: string;
     workspaceId: string;
+} & {
+    [key: string]: unknown;
 }>;
 export declare const reconcileLedgerStateUnderLock: (workspaceRoot: string) => Promise<PreparedLedgerState>;
 export declare const loadLedgerState: (workspaceRoot: string) => Promise<PreparedLedgerState>;

package/dist/recovery.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"recovery.d.ts","sourceRoot":"","sources":["../src/recovery.ts"],"names":[],"mappings":"AAKA,OAAO,EAA4B,KAAK,eAAe,EAAE,MAAM,iBAAiB,CAAC;AACjF,OAAO,EAAE,KAAK,WAAW,EAAqB,MAAM,mBAAmB,CAAC;AACxE,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AA0B3D,MAAM,MAAM,mBAAmB,GAAG;IAC9B,QAAQ,CAAC,QAAQ,EAAE,cAAc,CAAC;IAClC,QAAQ,CAAC,SAAS,EAAE,eAAe,CAAC;CACvC,CAAC;AA0JF,eAAO,MAAM,kBAAkB,GAAU,kDAKtC;IACC,QAAQ,CAAC,KAAK,EAAE,WAAW,CAAC;IAC5B,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,QAAQ,EAAE,cAAc,CAAC;IAClC,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;CAClC,oBAeA,CAAC;AAEF,eAAO,MAAM,mBAAmB,GAAU,UAAU,MAAM,kBAEzD,CAAC;AAEF,eAAO,MAAM,gCAAgC,GAAU,eAAe,MAAM;;;;;;;;;;;;;;;;;;;;EAyB3E,CAAC;AAEF,eAAO,MAAM,6BAA6B,GAAU,eAAe,MAAM,KAAG,OAAO,CAAC,mBAAmB,CAQtG,CAAC;AAEF,eAAO,MAAM,eAAe,GAAU,eAAe,MAAM,KAAG,OAAO,CAAC,mBAAmB,CAQxF,CAAC;AAEF,eAAO,MAAM,kBAAkB,GAAU,eAAe,MAAM,kBAE7D,CAAC"}
+{"version":3,"file":"recovery.d.ts","sourceRoot":"","sources":["../src/recovery.ts"],"names":[],"mappings":"AAKA,OAAO,EAA4B,KAAK,eAAe,EAAE,MAAM,iBAAiB,CAAC;AACjF,OAAO,EAAE,KAAK,WAAW,EAAqB,MAAM,mBAAmB,CAAC;AACxE,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AA0B3D,MAAM,MAAM,mBAAmB,GAAG;IAC9B,QAAQ,CAAC,QAAQ,EAAE,cAAc,CAAC;IAClC,QAAQ,CAAC,SAAS,EAAE,eAAe,CAAC;CACvC,CAAC;AA0JF,eAAO,MAAM,kBAAkB,GAAU,kDAKtC;IACC,QAAQ,CAAC,KAAK,EAAE,WAAW,CAAC;IAC5B,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,QAAQ,EAAE,cAAc,CAAC;IAClC,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;CAClC,oBAeA,CAAC;AAEF,eAAO,MAAM,mBAAmB,GAAU,UAAU,MAAM,kBAEzD,CAAC;AAEF,eAAO,MAAM,gCAAgC,GAAU,eAAe,MAAM;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAyB3E,CAAC;AAEF,eAAO,MAAM,6BAA6B,GAAU,eAAe,MAAM,KAAG,OAAO,CAAC,mBAAmB,CAQtG,CAAC;AAEF,eAAO,MAAM,eAAe,GAAU,eAAe,MAAM,KAAG,OAAO,CAAC,mBAAmB,CAQxF,CAAC;AAEF,eAAO,MAAM,kBAAkB,GAAU,eAAe,MAAM,kBAE7D,CAAC"}

package/dist/recovery.js

@@ -1,6 +1,6 @@
 import { readdir, readFile, rm, stat } from 'node:fs/promises';
 import path from 'node:path';
-import { z } from 'zod';
+import * as v from 'valibot';
 import { reconcilePendingArchivesUnderLock } from "./archive-journal.js";
 import { getNextManifestSequence, updateManifestForEntry } from "./manifest-update.js";
 import { ensureReadIndexUnderLock } from "./read-index.js";
@@ -10,18 +10,18 @@ import { acquireLock } from "./storage/lock.js";
 const PendingCommitSchemaVersion = 'ushman-ledger-pending-commit/v1';
 // Pending commits capture the intended sequence and logical hash before the
 // entry file and manifest update diverge, so recovery can replay safely.
-const PendingCommitSchema = z.object({
-    baseLastSequence: z.number().int().nonnegative(),
-    createdAt: z.string().datetime({ offset: true }),
+const PendingCommitSchema = v.object({
+    baseLastSequence: v.pipe(v.number(), v.integer(), v.minValue(0)),
+    createdAt: v.pipe(v.string(), v.isoTimestamp()),
     entry: LedgerEntrySchema,
-    logicalHash: z.string().min(1),
-    schemaVersion: z.literal(PendingCommitSchemaVersion),
-    sequence: z.number().int().positive(),
+    logicalHash: v.pipe(v.string(), v.minLength(1)),
+    schemaVersion: v.literal(PendingCommitSchemaVersion),
+    sequence: v.pipe(v.number(), v.integer(), v.minValue(1)),
 });
 const formatSequence = (sequence) => sequence.toString().padStart(8, '0');
-const PendingCommitFileNameSchema = z.object({
-    entryId: z.string().min(1),
-    sequence: z.number().int().positive().max(Number.MAX_SAFE_INTEGER),
+const PendingCommitFileNameSchema = v.object({
+    entryId: v.pipe(v.string(), v.minLength(1)),
+    sequence: v.pipe(v.number(), v.integer(), v.minValue(1), v.maxValue(Number.MAX_SAFE_INTEGER)),
 });
 const buildPendingCommitFilePath = (workspaceRoot, sequence, entryId) => path.join(resolveLedgerPaths(workspaceRoot).pendingCommitsDir, `${formatSequence(sequence)}-${entryId}.json`);
 const parsePendingCommitFileName = (name) => {
@@ -29,7 +29,7 @@ const parsePendingCommitFileName = (name) => {
     if (!match) {
         return null;
     }
-    return PendingCommitFileNameSchema.parse({
+    return v.parse(PendingCommitFileNameSchema, {
         entryId: match[2],
         sequence: Number.parseInt(match[1], 10),
     });
@@ -37,7 +37,7 @@ const parsePendingCommitFileName = (name) => {
 const readPendingCommit = async (filePath) => {
     try {
         const text = await readFile(filePath, 'utf8');
-        return PendingCommitSchema.parse(JSON.parse(text));
+        return v.parse(PendingCommitSchema, JSON.parse(text));
     }
     catch (error) {
         throw new Error(`Invalid pending commit at ${filePath}: ${error instanceof Error ? error.message : String(error)}`);
@@ -128,7 +128,7 @@ const applyPendingCommit = async ({ manifest, pending, workspaceRoot, }) => {
 export const writePendingCommit = async ({ entry, logicalHash, manifest, workspaceRoot, }) => {
     const nextSequence = getNextManifestSequence(manifest.lastSequence);
     const filePath = buildPendingCommitFilePath(workspaceRoot, nextSequence, entry.id);
-    await writeAtomicJsonFile(filePath, PendingCommitSchema.parse({
+    await writeAtomicJsonFile(filePath, v.parse(PendingCommitSchema, {
         baseLastSequence: manifest.lastSequence,
         createdAt: new Date().toISOString(),
         entry,

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;AAgHtD,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: [],
@@ -13,14 +14,20 @@ const createRetroBuckets = () => ({
 });
 const isProblemEntry = (entry) => (entry.kind === 'note' && entry.subkind === 'regression') ||
     (entry.kind === 'runtime-event' && entry.level === 'error');
-const isToolEntry = (entry) => entry.kind === 'tool-invocation' ||
-    entry.kind === 'agent-patch' ||
-    entry.kind === 'operator-patch' ||
-    entry.kind === 'stage-transition';
+const isToolEntry = (entry) => entry.kind === 'tool-invocation' || entry.kind === 'agent-patch' || entry.kind === 'operator-patch';
 const isToolingEntry = (entry) => (entry.kind === 'note' && entry.subkind === 'automation') ||
     (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';
@@ -39,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();
@@ -48,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,
@@ -120,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');
+};