ushman-ledger 1.1.0 → 1.2.1

package/dist/doctor.js

@@ -7,7 +7,9 @@ import { isReadIndexCurrent, readReadIndex } from "./read-index.js";
 import { loadLedgerState } from "./recovery.js";
 import { readManifest } from "./storage/filesystem.js";
 const BLOB_HASH_CONCURRENCY = 16;
+const CHECKPOINT_MAX_AGE_MS = 24 * 60 * 60 * 1_000;
 const ENTRY_READ_BATCH_SIZE = 32;
+const OPEN_ISSUE_MAX_AGE_MS = 30 * 24 * 60 * 60 * 1_000;
 const checkPrevChain = (entry, previousByPhase, issues) => {
     const expectedPrev = previousByPhase.get(entry.phase) ?? null;
     if (entry.prevEntryId !== expectedPrev) {
@@ -66,13 +68,51 @@ const buildReadFailure = (error) => ({
     issues: [`Failed to read ledger state: ${error instanceof Error ? (error.message ?? error.name) : String(error)}.`],
     ok: false,
 });
-const inspectDoctorEntry = ({ blobChecks, entry, issues, latestByPhase, manifest, previousByPhase, unseenManifestEntryIds, }) => {
-    unseenManifestEntryIds.delete(entry.id);
-    checkPrevChain(entry, previousByPhase, issues);
+const isChangeLogEntry = (entry) => entry.kind === 'change-log';
+const isOpenIssueNote = (entry) => entry.kind === 'note' && entry.subkind === 'open-issue';
+const trackResolutionLinks = (entry, resolvedLedgerIds) => {
+    if (entry.links.correctsLedgerId) {
+        resolvedLedgerIds.add(entry.links.correctsLedgerId);
+    }
+    if (entry.links.supersedesLedgerId) {
+        resolvedLedgerIds.add(entry.links.supersedesLedgerId);
+    }
+};
+const trackIdempotencyEntry = (entry, entriesByIdempotencyKey) => {
+    const idempotencyKey = entry.links.idempotencyKey;
+    if (!idempotencyKey) {
+        return;
+    }
+    const existingEntries = entriesByIdempotencyKey.get(idempotencyKey) ?? [];
+    existingEntries.push({ id: entry.id, ts: entry.ts });
+    entriesByIdempotencyKey.set(idempotencyKey, existingEntries);
+};
+const checkChangeLogWarnings = ({ checkpointEntries, entriesByIdempotencyKey, issues, nowMs, openIssueEntries, resolvedLedgerIds, }) => {
+    for (const checkpointEntry of checkpointEntries) {
+        const ageMs = nowMs - Date.parse(checkpointEntry.ts);
+        if (ageMs <= CHECKPOINT_MAX_AGE_MS) {
+            continue;
+        }
+        const idempotencyKey = checkpointEntry.links.idempotencyKey;
+        const hasFollowUp = typeof idempotencyKey === 'string' &&
+            (entriesByIdempotencyKey.get(idempotencyKey) ?? []).some((candidate) => candidate.id !== checkpointEntry.id && candidate.ts >= checkpointEntry.ts);
+        if (!hasFollowUp) {
+            issues.push(`Pre-change checkpoint ${checkpointEntry.id} is older than 24h and has no follow-up entry with matching idempotencyKey.`);
+        }
+    }
+    for (const openIssueEntry of openIssueEntries) {
+        const ageMs = nowMs - Date.parse(openIssueEntry.ts);
+        if (ageMs <= OPEN_ISSUE_MAX_AGE_MS || resolvedLedgerIds.has(openIssueEntry.id)) {
+            continue;
+        }
+        issues.push(`Open issue note ${openIssueEntry.id} is older than 30 days and has no resolution link.`);
+    }
+};
+const inspectManifestLocation = ({ entry, issues, latestByPhase, manifest, }) => {
     const manifestLocation = manifest.entryLocations[entry.id];
     if (!manifestLocation) {
         issues.push(`Manifest is missing entry location for ${entry.id}.`);
-        return;
+        return null;
     }
     if (manifestLocation.phase !== entry.phase) {
         issues.push(`Manifest phase mismatch for ${entry.id}: expected ${entry.phase}, found ${manifestLocation.phase}.`);
@@ -81,6 +121,25 @@ const inspectDoctorEntry = ({ blobChecks, entry, issues, latestByPhase, manifest
     if (!currentLatest || manifestLocation.sequence > currentLatest.sequence) {
         latestByPhase.set(entry.phase, { entryId: entry.id, sequence: manifestLocation.sequence });
     }
+    return manifestLocation;
+};
+const inspectNarrativeEntry = ({ checkpointEntries, entry, issues, openIssueEntries, }) => {
+    if (isChangeLogEntry(entry)) {
+        if (entry.subkind === 'pre-change-checkpoint') {
+            checkpointEntries.push(entry);
+        }
+        if (entry.smokeResult === 'fail' && !entry.rollbackPlan) {
+            issues.push(`Change-log entry ${entry.id} has smokeResult=fail but no rollbackPlan.`);
+        }
+        if (entry.subkind === 'rollback' && !entry.rollsBack) {
+            issues.push(`Change-log rollback entry ${entry.id} is missing rollsBack.`);
+        }
+    }
+    if (isOpenIssueNote(entry)) {
+        openIssueEntries.push(entry);
+    }
+};
+const inspectPatchEntry = ({ blobChecks, entry, }) => {
     if (entry.kind !== 'agent-patch' && entry.kind !== 'operator-patch') {
         return;
     }
@@ -88,13 +147,42 @@ const inspectDoctorEntry = ({ blobChecks, entry, issues, latestByPhase, manifest
         blobChecks.push({ blobHash, entryId: entry.id });
     }
 };
+const inspectDoctorEntry = ({ blobChecks, checkpointEntries, entry, entriesByIdempotencyKey, issues, latestByPhase, manifest, openIssueEntries, previousByPhase, resolvedLedgerIds, unseenManifestEntryIds, }) => {
+    unseenManifestEntryIds.delete(entry.id);
+    checkPrevChain(entry, previousByPhase, issues);
+    trackIdempotencyEntry(entry, entriesByIdempotencyKey);
+    trackResolutionLinks(entry, resolvedLedgerIds);
+    if (!inspectManifestLocation({
+        entry,
+        issues,
+        latestByPhase,
+        manifest,
+    })) {
+        return;
+    }
+    inspectNarrativeEntry({
+        checkpointEntries,
+        entry,
+        issues,
+        openIssueEntries,
+    });
+    inspectPatchEntry({
+        blobChecks,
+        entry,
+    });
+};
 const collectDoctorState = async (workspaceRoot, manifest, readIndex) => {
     const issues = [];
     const previousByPhase = new Map();
     const latestByPhase = new Map();
     const unseenManifestEntryIds = new Set(Object.keys(manifest.entryLocations));
     const blobChecks = [];
+    const checkpointEntries = [];
+    const entriesByIdempotencyKey = new Map();
+    const openIssueEntries = [];
+    const resolvedLedgerIds = new Set();
     let entryCount = 0;
+    const nowMs = Date.now();
     const orderedEntries = getOrderedEntryLocations(manifest, readIndex, {});
     checkManifestSequenceOrder(orderedEntries, issues);
     for (let index = 0; index < orderedEntries.length; index += ENTRY_READ_BATCH_SIZE) {
@@ -111,15 +199,27 @@ const collectDoctorState = async (workspaceRoot, manifest, readIndex) => {
             entryCount += 1;
             inspectDoctorEntry({
                 blobChecks,
+                checkpointEntries,
+                entriesByIdempotencyKey,
                 entry: resolvedEntry.entry,
                 issues,
                 latestByPhase,
                 manifest,
+                openIssueEntries,
                 previousByPhase,
+                resolvedLedgerIds,
                 unseenManifestEntryIds,
             });
         }
     }
+    checkChangeLogWarnings({
+        checkpointEntries,
+        entriesByIdempotencyKey,
+        issues,
+        nowMs,
+        openIssueEntries,
+        resolvedLedgerIds,
+    });
     return {
         blobChecks,
         entryCount,

package/dist/handle.d.ts

@@ -3,7 +3,31 @@ import { runLedgerDoctor } from './doctor.ts';
 import { type LedgerFilter } from './list.ts';
 import { appendNote, type NoteBody } from './note.ts';
 import type { LedgerEntry, LedgerPhase } from './schema/entry.ts';
-export type RenderTarget = 'dependency-graph' | 'jsonl' | 'retro' | 'timeline-html';
+export type RenderTarget = 'dependency-graph' | 'jsonl' | 'migration-log-md' | 'retro' | 'timeline-html' | 'workspace-narrative-md';
+/**
+ * Chunk writer used by `renderTo()` for bounded render emission.
+ *
+ * Writers may complete synchronously or asynchronously. Throwing rejects the render and causes any in-progress
+ * atomic output file to be aborted.
+ */
+export type RenderWriter = (chunk: string) => Promise<void> | void;
+/** Options for `render()`, which returns the rendered text and optionally mirrors it to disk. */
+export type LedgerRenderOptions = {
+    readonly limit?: number;
+    readonly out?: string;
+    readonly phase?: LedgerPhase;
+    readonly since?: string;
+    readonly to: RenderTarget;
+};
+/** Options for `renderTo()`, which writes to a callback and/or canonical render file without buffering the full output. */
+export type LedgerRenderToOptions = {
+    readonly limit?: number;
+    readonly out?: string;
+    readonly phase?: LedgerPhase;
+    readonly since?: string;
+    readonly to: RenderTarget;
+    readonly write?: RenderWriter;
+};
 export type LedgerHandle = {
     readonly archive: (outPath: string) => Promise<{
         integrityHash: string;
@@ -17,12 +41,10 @@ export type LedgerHandle = {
     readonly record: (entry: unknown) => Promise<{
         id: string;
     }>;
-    readonly render: (options: {
-        out?: string;
-        phase?: LedgerPhase;
-        to: RenderTarget;
-    }) => Promise<string>;
+    readonly render: (options: LedgerRenderOptions) => Promise<string>;
+    readonly renderTo: (options: LedgerRenderToOptions) => Promise<void>;
     readonly show: (entryId: string) => Promise<LedgerEntry | null>;
 };
+/** Open a workspace ledger handle after reconciling any pending crash-recovery state. */
 export declare const openLedger: (workspaceRoot: string) => Promise<LedgerHandle>;
 //# sourceMappingURL=handle.d.ts.map

package/dist/handle.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"handle.d.ts","sourceRoot":"","sources":["../src/handle.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,eAAe,EAAE,MAAM,eAAe,CAAC;AAChD,OAAO,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAE9C,OAAO,EAA8B,KAAK,YAAY,EAAe,MAAM,WAAW,CAAC;AACvF,OAAO,EAAE,UAAU,EAAE,KAAK,QAAQ,EAAE,MAAM,WAAW,CAAC;AAOtD,OAAO,KAAK,EAAE,WAAW,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAGlE,MAAM,MAAM,YAAY,GAAG,kBAAkB,GAAG,OAAO,GAAG,OAAO,GAAG,eAAe,CAAC;AAuCpF,MAAM,MAAM,YAAY,GAAG;IACvB,QAAQ,CAAC,OAAO,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,OAAO,CAAC;QAAE,aAAa,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IAC1E,QAAQ,CAAC,eAAe,EAAE,MAAM,OAAO,CAAC,OAAO,CAAC,UAAU,CAAC,OAAO,eAAe,CAAC,CAAC,CAAC,CAAC;IACrF,QAAQ,CAAC,MAAM,EAAE,MAAM,OAAO,CAAC,OAAO,CAAC,UAAU,CAAC,OAAO,eAAe,CAAC,CAAC,CAAC,CAAC;IAC5E,QAAQ,CAAC,IAAI,EAAE,CAAC,MAAM,CAAC,EAAE,YAAY,KAAK,aAAa,CAAC,WAAW,CAAC,CAAC;IACrE,QAAQ,CAAC,IAAI,EAAE,CAAC,OAAO,EAAE,UAAU,CAAC,OAAO,UAAU,CAAC,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,QAAQ,KAAK,OAAO,CAAC;QAAE,EAAE,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IACtG,QAAQ,CAAC,MAAM,EAAE,CAAC,KAAK,EAAE,OAAO,KAAK,OAAO,CAAC;QAAE,EAAE,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IAC7D,QAAQ,CAAC,MAAM,EAAE,CAAC,OAAO,EAAE;QAAE,GAAG,CAAC,EAAE,MAAM,CAAC;QAAC,KAAK,CAAC,EAAE,WAAW,CAAC;QAAC,EAAE,EAAE,YAAY,CAAA;KAAE,KAAK,OAAO,CAAC,MAAM,CAAC,CAAC;IACvG,QAAQ,CAAC,IAAI,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,OAAO,CAAC,WAAW,GAAG,IAAI,CAAC,CAAC;CACnE,CAAC;AAEF,eAAO,MAAM,UAAU,GAAU,eAAe,MAAM,KAAG,OAAO,CAAC,YAAY,CAqC5E,CAAC"}
+{"version":3,"file":"handle.d.ts","sourceRoot":"","sources":["../src/handle.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,eAAe,EAAE,MAAM,eAAe,CAAC;AAChD,OAAO,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAE9C,OAAO,EAA8B,KAAK,YAAY,EAAe,MAAM,WAAW,CAAC;AACvF,OAAO,EAAE,UAAU,EAAE,KAAK,QAAQ,EAAE,MAAM,WAAW,CAAC;AAStD,OAAO,KAAK,EAAE,WAAW,EAAc,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAG9E,MAAM,MAAM,YAAY,GAClB,kBAAkB,GAClB,OAAO,GACP,kBAAkB,GAClB,OAAO,GACP,eAAe,GACf,wBAAwB,CAAC;AAE/B;;;;;GAKG;AACH,MAAM,MAAM,YAAY,GAAG,CAAC,KAAK,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC;AAEnE,iGAAiG;AACjG,MAAM,MAAM,mBAAmB,GAAG;IAC9B,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,KAAK,CAAC,EAAE,WAAW,CAAC;IAC7B,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,EAAE,EAAE,YAAY,CAAC;CAC7B,CAAC;AAEF,2HAA2H;AAC3H,MAAM,MAAM,qBAAqB,GAAG;IAChC,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,KAAK,CAAC,EAAE,WAAW,CAAC;IAC7B,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,EAAE,EAAE,YAAY,CAAC;IAC1B,QAAQ,CAAC,KAAK,CAAC,EAAE,YAAY,CAAC;CACjC,CAAC;AA4GF,MAAM,MAAM,YAAY,GAAG;IACvB,QAAQ,CAAC,OAAO,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,OAAO,CAAC;QAAE,aAAa,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IAC1E,QAAQ,CAAC,eAAe,EAAE,MAAM,OAAO,CAAC,OAAO,CAAC,UAAU,CAAC,OAAO,eAAe,CAAC,CAAC,CAAC,CAAC;IACrF,QAAQ,CAAC,MAAM,EAAE,MAAM,OAAO,CAAC,OAAO,CAAC,UAAU,CAAC,OAAO,eAAe,CAAC,CAAC,CAAC,CAAC;IAC5E,QAAQ,CAAC,IAAI,EAAE,CAAC,MAAM,CAAC,EAAE,YAAY,KAAK,aAAa,CAAC,WAAW,CAAC,CAAC;IACrE,QAAQ,CAAC,IAAI,EAAE,CAAC,OAAO,EAAE,UAAU,CAAC,OAAO,UAAU,CAAC,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,QAAQ,KAAK,OAAO,CAAC;QAAE,EAAE,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IACtG,QAAQ,CAAC,MAAM,EAAE,CAAC,KAAK,EAAE,OAAO,KAAK,OAAO,CAAC;QAAE,EAAE,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IAC7D,QAAQ,CAAC,MAAM,EAAE,CAAC,OAAO,EAAE,mBAAmB,KAAK,OAAO,CAAC,MAAM,CAAC,CAAC;IACnE,QAAQ,CAAC,QAAQ,EAAE,CAAC,OAAO,EAAE,qBAAqB,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IACrE,QAAQ,CAAC,IAAI,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,OAAO,CAAC,WAAW,GAAG,IAAI,CAAC,CAAC;CACnE,CAAC;AAEF,yFAAyF;AACzF,eAAO,MAAM,UAAU,GAAU,eAAe,MAAM,KAAG,OAAO,CAAC,YAAY,CAyF5E,CAAC"}

package/dist/handle.js

@@ -1,3 +1,4 @@
+import path from 'node:path';
 import { archiveLedger } from "./archive.js";
 import { computeCoverage } from "./coverage.js";
 import { runLedgerDoctor } from "./doctor.js";
@@ -8,23 +9,62 @@ import { appendRecord, readEntryById } from "./record.js";
 import { loadLedgerState, prepareLedgerState } from "./recovery.js";
 import { renderDependencyGraph } from "./render/dependency-graph.js";
 import { renderJsonl } from "./render/jsonl.js";
+import { renderMigrationLogMarkdown } from "./render/migration-log.js";
 import { renderRetroMarkdown } from "./render/retro.js";
 import { renderTimelineHtml } from "./render/timeline-html.js";
-import { resolveLedgerPaths, writeAtomicTextFile } from "./storage/filesystem.js";
-const renderEntries = async ({ filter, target, workspaceRoot, }) => {
-    const { manifest, readIndex } = await loadLedgerState(workspaceRoot);
+import { renderWorkspaceNarrativeMarkdown } from "./render/workspace-narrative.js";
+import { createAtomicTextFileWriter, resolveLedgerPaths, writeAtomicTextFile } from "./storage/filesystem.js";
+const createEntryIteratorFactory = ({ filter, state, workspaceRoot, }) => {
+    return (entryOptions = {}) => iterateEntriesFromManifest(workspaceRoot, state.manifest, state.readIndex, {
+        kind: entryOptions.kind,
+        limit: filter.limit,
+        phase: filter.phase,
+        since: filter.since,
+    }, entryOptions.direction);
+};
+const collectRenderedText = async (emit) => {
+    const chunks = [];
+    await emit((chunk) => {
+        chunks.push(chunk);
+    });
+    return chunks.join('');
+};
+const emitRenderedTarget = async ({ createEntries, manifest, target, write, workspaceName, }) => {
     switch (target) {
         case 'dependency-graph':
-            return renderDependencyGraph(iterateEntriesFromManifest(workspaceRoot, manifest, readIndex, filter));
+            await write(await renderDependencyGraph(createEntries()));
+            return;
         case 'jsonl':
-            return renderJsonl(iterateEntriesFromManifest(workspaceRoot, manifest, readIndex, filter));
+            await write(await renderJsonl(createEntries()));
+            return;
+        case 'migration-log-md':
+            await renderMigrationLogMarkdown({
+                entries: createEntries({
+                    direction: 'desc',
+                    kind: 'change-log',
+                }),
+                write,
+            });
+            return;
         case 'timeline-html':
-            return renderTimelineHtml(iterateEntriesFromManifest(workspaceRoot, manifest, readIndex, filter));
+            await write(await renderTimelineHtml(createEntries()));
+            return;
         case 'retro':
-            return renderRetroMarkdown({
-                entries: iterateEntriesFromManifest(workspaceRoot, manifest, readIndex, filter),
+            await write(await renderRetroMarkdown({
+                entries: createEntries(),
                 manifest,
+            }));
+            return;
+        case 'workspace-narrative-md':
+            await renderWorkspaceNarrativeMarkdown({
+                entries: createEntries({
+                    direction: 'desc',
+                    kind: 'note',
+                }),
+                workspaceName,
+                write,
             });
+            return;
     }
 };
 const resolveRenderOutputPath = (workspaceRoot, target) => {
@@ -32,12 +72,17 @@ const resolveRenderOutputPath = (workspaceRoot, target) => {
     switch (target) {
         case 'retro':
             return paths.renderFile;
+        case 'migration-log-md':
+            return paths.renderMigrationLogFile;
         case 'timeline-html':
             return paths.renderTimelineFile;
+        case 'workspace-narrative-md':
+            return paths.renderWorkspaceNarrativeFile;
         default:
             return null;
     }
 };
+/** Open a workspace ledger handle after reconciling any pending crash-recovery state. */
 export const openLedger = async (workspaceRoot) => {
     await readLabManifestMin(workspaceRoot);
     await prepareLedgerState(workspaceRoot);
@@ -55,17 +100,66 @@ export const openLedger = async (workspaceRoot) => {
             return { id: result.id };
         },
         render: async (options) => {
-            const content = await renderEntries({
-                filter: { phase: options.phase },
-                target: options.to,
+            const state = await loadLedgerState(workspaceRoot);
+            const createEntries = createEntryIteratorFactory({
+                filter: options,
+                state,
                 workspaceRoot,
             });
+            const content = await collectRenderedText((write) => emitRenderedTarget({
+                createEntries,
+                manifest: state.manifest,
+                target: options.to,
+                workspaceName: path.basename(workspaceRoot),
+                write,
+            }));
             const outputPath = options.out ?? resolveRenderOutputPath(workspaceRoot, options.to);
             if (outputPath) {
                 await writeAtomicTextFile(outputPath, `${content}${content.endsWith('\n') ? '' : '\n'}`);
             }
             return content;
         },
+        renderTo: async (options) => {
+            const state = await loadLedgerState(workspaceRoot);
+            const createEntries = createEntryIteratorFactory({
+                filter: options,
+                state,
+                workspaceRoot,
+            });
+            const outputPath = options.out ?? resolveRenderOutputPath(workspaceRoot, options.to);
+            const atomicWriter = outputPath ? await createAtomicTextFileWriter(outputPath) : null;
+            const writer = options.write;
+            let hasWrittenContent = false;
+            let endsWithNewline = false;
+            if (!atomicWriter && !writer) {
+                throw new Error(`Render target ${options.to} requires either a writer callback or an output path.`);
+            }
+            try {
+                await emitRenderedTarget({
+                    createEntries,
+                    manifest: state.manifest,
+                    target: options.to,
+                    workspaceName: path.basename(workspaceRoot),
+                    write: async (chunk) => {
+                        if (chunk.length > 0) {
+                            hasWrittenContent = true;
+                            endsWithNewline = chunk.endsWith('\n');
+                        }
+                        await writer?.(chunk);
+                        await atomicWriter?.write(chunk);
+                    },
+                });
+                if (!hasWrittenContent || !endsWithNewline) {
+                    await writer?.('\n');
+                    await atomicWriter?.write('\n');
+                }
+                await atomicWriter?.close();
+            }
+            catch (error) {
+                await atomicWriter?.abort();
+                throw error;
+            }
+        },
         show: async (entryId) => {
             const { manifest } = await loadLedgerState(workspaceRoot);
             if (!manifest.entryLocations[entryId]) {

package/dist/helpers.d.ts

@@ -0,0 +1,7 @@
+export declare const createWorkspaceFixture: () => Promise<{
+    cleanup: () => Promise<void>;
+    workspaceRoot: string;
+}>;
+export declare const ageFile: (filePath: string, ageMs?: number) => Promise<void>;
+export declare const waitForFile: (filePath: string, timeoutMs?: number) => Promise<void>;
+//# sourceMappingURL=helpers.d.ts.map

package/dist/helpers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"helpers.d.ts","sourceRoot":"","sources":["../src/helpers.ts"],"names":[],"mappings":"AAIA,eAAO,MAAM,sBAAsB;;;EAuBlC,CAAC;AAEF,eAAO,MAAM,OAAO,GAAU,UAAU,MAAM,EAAE,cAAc,kBAG7D,CAAC;AAEF,eAAO,MAAM,WAAW,GAAU,UAAU,MAAM,EAAE,kBAAiB,kBAcpE,CAAC"}

package/dist/helpers.js

@@ -0,0 +1,38 @@
+import { mkdir, mkdtemp, rm, stat, utimes, writeFile } from 'node:fs/promises';
+import os from 'node:os';
+import path from 'node:path';
+export const createWorkspaceFixture = async () => {
+    const workspaceRoot = await mkdtemp(path.join(os.tmpdir(), 'ushman-ledger-'));
+    await mkdir(path.join(workspaceRoot, '.lab'), { recursive: true });
+    await mkdir(path.join(workspaceRoot, 'src'), { recursive: true });
+    await writeFile(path.join(workspaceRoot, '.lab', 'lab.json'), `${JSON.stringify({
+        schemaVersion: 'ushman-lab/v4.0',
+        workspaceId: '3d71d4fb-dca0-4d63-9ad6-69d59a2395f4',
+    }, null, 2)}\n`, 'utf8');
+    return {
+        cleanup: async () => {
+            await rm(workspaceRoot, { force: true, recursive: true });
+        },
+        workspaceRoot,
+    };
+};
+export const ageFile = async (filePath, ageMs = 61_000) => {
+    const staleTime = new Date(Date.now() - ageMs);
+    await utimes(filePath, staleTime, staleTime);
+};
+export const waitForFile = async (filePath, timeoutMs = 1_000) => {
+    const deadline = Date.now() + timeoutMs;
+    while (Date.now() <= deadline) {
+        try {
+            await stat(filePath);
+            return;
+        }
+        catch (error) {
+            if (error.code !== 'ENOENT') {
+                throw error;
+            }
+        }
+        await new Promise((resolve) => setTimeout(resolve, 10));
+    }
+    throw new Error(`Timed out waiting for file: ${filePath}`);
+};

package/dist/index.d.ts

@@ -1,9 +1,11 @@
-export { buildCorrectionRecord, buildOperatorDecisionRecord, buildStripDecisionRevertedRecord, buildValidatorResultRecord, } from './builders.ts';
+export { type BuildRecordInput, buildChangeLogRecord, buildCorrectionRecord, buildOperatorDecisionRecord, buildStripDecisionRevertedRecord, buildValidatorResultRecord, } from './builders.ts';
 export { runLedgerCli } from './cli.ts';
 export { type CoverageReport, computeCoverage } from './coverage.ts';
-export { type LedgerHandle, type RenderTarget, openLedger } from './handle.ts';
+export { type LedgerHandle, type LedgerRenderOptions, type LedgerRenderToOptions, openLedger, type RenderTarget, type RenderWriter, } from './handle.ts';
 export type { LedgerFilter } from './list.ts';
-export { type AgentPatchDiff, AgentPatchDiffSchema, AgentPatchEntrySchema, AgentPatchRecordSchema, CorrectionEntrySchema, CorrectionRecordSchema, EmitterSchema, type LedgerEntry, LedgerEntrySchema, type LedgerKind, LedgerLinksSchema, type LedgerPhase, LedgerPhaseSchema, type LedgerRecord, LedgerRecordSchema, NoteEntrySchema, type OperatorDecisionAction, OperatorDecisionActionSchema, OperatorDecisionEntrySchema, type OperatorDecisionPayload, OperatorDecisionPayloadSchema, OperatorDecisionRecordSchema, OperatorPatchEntrySchema, OperatorPatchRecordSchema, parseLedgerEntry, parseLedgerRecord, RuntimeEventEntrySchema, StripDecisionRevertedEntrySchema, type StripDecisionRevertedPayload, StripDecisionRevertedPayloadSchema, StripDecisionRevertedRecordSchema, ToolInvocationEntrySchema, ToolInvocationRecordSchema, ValidatorResultEntrySchema, ValidatorResultRecordSchema, } from './schema/entry.ts';
+export { appendCleanupWaveNote, appendDecompositionWaveNote, appendNote, appendOpenIssueNote, appendSemanticCleanupSummaryNote, appendVerifiedFlowNote, type NoteBody, } from './note.ts';
+export { deriveFilesChangedFromPatch } from './patch-resolver.ts';
+export { type AgentPatchDiff, AgentPatchDiffSchema, AgentPatchEntrySchema, AgentPatchRecordSchema, type ChangeLogEntry, ChangeLogEntrySchema, type ChangeLogFileChange, ChangeLogFileChangeSchema, type ChangeLogParityStatus, ChangeLogParityStatusSchema, type ChangeLogRecord, ChangeLogRecordSchema, type ChangeLogSmokeResult, ChangeLogSmokeResultSchema, type ChangeLogSubkind, ChangeLogSubkindSchema, CorrectionEntrySchema, CorrectionRecordSchema, EmitterSchema, type LedgerEntry, LedgerEntrySchema, type LedgerKind, type LedgerLinks, LedgerLinksSchema, type LedgerPhase, LedgerPhaseSchema, type LedgerRecord, LedgerRecordSchema, type NoteEntry, NoteEntrySchema, type OperatorDecisionAction, OperatorDecisionActionSchema, OperatorDecisionEntrySchema, type OperatorDecisionPayload, OperatorDecisionPayloadSchema, OperatorDecisionRecordSchema, OperatorPatchEntrySchema, OperatorPatchRecordSchema, parseLedgerEntry, parseLedgerRecord, RuntimeEventEntrySchema, StripDecisionRevertedEntrySchema, type StripDecisionRevertedPayload, StripDecisionRevertedPayloadSchema, StripDecisionRevertedRecordSchema, ToolInvocationEntrySchema, ToolInvocationRecordSchema, ValidatorResultEntrySchema, ValidatorResultRecordSchema, } from './schema/entry.ts';
 export { type NoteSubkind, NoteSubkindSchema } from './schema/note.ts';
 export { resolveLedgerPaths } from './storage/filesystem.ts';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACH,qBAAqB,EACrB,2BAA2B,EAC3B,gCAAgC,EAChC,0BAA0B,GAC7B,MAAM,eAAe,CAAC;AACvB,OAAO,EAAE,YAAY,EAAE,MAAM,UAAU,CAAC;AACxC,OAAO,EAAE,KAAK,cAAc,EAAE,eAAe,EAAE,MAAM,eAAe,CAAC;AACrE,OAAO,EAAE,KAAK,YAAY,EAAE,KAAK,YAAY,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAC/E,YAAY,EAAE,YAAY,EAAE,MAAM,WAAW,CAAC;AAC9C,OAAO,EACH,KAAK,cAAc,EACnB,oBAAoB,EACpB,qBAAqB,EACrB,sBAAsB,EACtB,qBAAqB,EACrB,sBAAsB,EACtB,aAAa,EACb,KAAK,WAAW,EAChB,iBAAiB,EACjB,KAAK,UAAU,EACf,iBAAiB,EACjB,KAAK,WAAW,EAChB,iBAAiB,EACjB,KAAK,YAAY,EACjB,kBAAkB,EAClB,eAAe,EACf,KAAK,sBAAsB,EAC3B,4BAA4B,EAC5B,2BAA2B,EAC3B,KAAK,uBAAuB,EAC5B,6BAA6B,EAC7B,4BAA4B,EAC5B,wBAAwB,EACxB,yBAAyB,EACzB,gBAAgB,EAChB,iBAAiB,EACjB,uBAAuB,EACvB,gCAAgC,EAChC,KAAK,4BAA4B,EACjC,kCAAkC,EAClC,iCAAiC,EACjC,yBAAyB,EACzB,0BAA0B,EAC1B,0BAA0B,EAC1B,2BAA2B,GAC9B,MAAM,mBAAmB,CAAC;AAC3B,OAAO,EAAE,KAAK,WAAW,EAAE,iBAAiB,EAAE,MAAM,kBAAkB,CAAC;AACvE,OAAO,EAAE,kBAAkB,EAAE,MAAM,yBAAyB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACH,KAAK,gBAAgB,EACrB,oBAAoB,EACpB,qBAAqB,EACrB,2BAA2B,EAC3B,gCAAgC,EAChC,0BAA0B,GAC7B,MAAM,eAAe,CAAC;AACvB,OAAO,EAAE,YAAY,EAAE,MAAM,UAAU,CAAC;AACxC,OAAO,EAAE,KAAK,cAAc,EAAE,eAAe,EAAE,MAAM,eAAe,CAAC;AACrE,OAAO,EACH,KAAK,YAAY,EACjB,KAAK,mBAAmB,EACxB,KAAK,qBAAqB,EAC1B,UAAU,EACV,KAAK,YAAY,EACjB,KAAK,YAAY,GACpB,MAAM,aAAa,CAAC;AACrB,YAAY,EAAE,YAAY,EAAE,MAAM,WAAW,CAAC;AAC9C,OAAO,EACH,qBAAqB,EACrB,2BAA2B,EAC3B,UAAU,EACV,mBAAmB,EACnB,gCAAgC,EAChC,sBAAsB,EACtB,KAAK,QAAQ,GAChB,MAAM,WAAW,CAAC;AACnB,OAAO,EAAE,2BAA2B,EAAE,MAAM,qBAAqB,CAAC;AAClE,OAAO,EACH,KAAK,cAAc,EACnB,oBAAoB,EACpB,qBAAqB,EACrB,sBAAsB,EACtB,KAAK,cAAc,EACnB,oBAAoB,EACpB,KAAK,mBAAmB,EACxB,yBAAyB,EACzB,KAAK,qBAAqB,EAC1B,2BAA2B,EAC3B,KAAK,eAAe,EACpB,qBAAqB,EACrB,KAAK,oBAAoB,EACzB,0BAA0B,EAC1B,KAAK,gBAAgB,EACrB,sBAAsB,EACtB,qBAAqB,EACrB,sBAAsB,EACtB,aAAa,EACb,KAAK,WAAW,EAChB,iBAAiB,EACjB,KAAK,UAAU,EACf,KAAK,WAAW,EAChB,iBAAiB,EACjB,KAAK,WAAW,EAChB,iBAAiB,EACjB,KAAK,YAAY,EACjB,kBAAkB,EAClB,KAAK,SAAS,EACd,eAAe,EACf,KAAK,sBAAsB,EAC3B,4BAA4B,EAC5B,2BAA2B,EAC3B,KAAK,uBAAuB,EAC5B,6BAA6B,EAC7B,4BAA4B,EAC5B,wBAAwB,EACxB,yBAAyB,EACzB,gBAAgB,EAChB,iBAAiB,EACjB,uBAAuB,EACvB,gCAAgC,EAChC,KAAK,4BAA4B,EACjC,kCAAkC,EAClC,iCAAiC,EACjC,yBAAyB,EACzB,0BAA0B,EAC1B,0BAA0B,EAC1B,2BAA2B,GAC9B,MAAM,mBAAmB,CAAC;AAC3B,OAAO,EAAE,KAAK,WAAW,EAAE,iBAAiB,EAAE,MAAM,kBAAkB,CAAC;AACvE,OAAO,EAAE,kBAAkB,EAAE,MAAM,yBAAyB,CAAC"}

package/dist/index.js

@@ -1,7 +1,9 @@
-export { buildCorrectionRecord, buildOperatorDecisionRecord, buildStripDecisionRevertedRecord, buildValidatorResultRecord, } from "./builders.js";
+export { buildChangeLogRecord, buildCorrectionRecord, buildOperatorDecisionRecord, buildStripDecisionRevertedRecord, buildValidatorResultRecord, } from "./builders.js";
 export { runLedgerCli } from "./cli.js";
 export { computeCoverage } from "./coverage.js";
-export { openLedger } from "./handle.js";
-export { AgentPatchDiffSchema, AgentPatchEntrySchema, AgentPatchRecordSchema, CorrectionEntrySchema, CorrectionRecordSchema, EmitterSchema, LedgerEntrySchema, LedgerLinksSchema, LedgerPhaseSchema, LedgerRecordSchema, NoteEntrySchema, OperatorDecisionActionSchema, OperatorDecisionEntrySchema, OperatorDecisionPayloadSchema, OperatorDecisionRecordSchema, OperatorPatchEntrySchema, OperatorPatchRecordSchema, parseLedgerEntry, parseLedgerRecord, RuntimeEventEntrySchema, StripDecisionRevertedEntrySchema, StripDecisionRevertedPayloadSchema, StripDecisionRevertedRecordSchema, ToolInvocationEntrySchema, ToolInvocationRecordSchema, ValidatorResultEntrySchema, ValidatorResultRecordSchema, } from "./schema/entry.js";
+export { openLedger, } from "./handle.js";
+export { appendCleanupWaveNote, appendDecompositionWaveNote, appendNote, appendOpenIssueNote, appendSemanticCleanupSummaryNote, appendVerifiedFlowNote, } from "./note.js";
+export { deriveFilesChangedFromPatch } from "./patch-resolver.js";
+export { AgentPatchDiffSchema, AgentPatchEntrySchema, AgentPatchRecordSchema, ChangeLogEntrySchema, ChangeLogFileChangeSchema, ChangeLogParityStatusSchema, ChangeLogRecordSchema, ChangeLogSmokeResultSchema, ChangeLogSubkindSchema, CorrectionEntrySchema, CorrectionRecordSchema, EmitterSchema, LedgerEntrySchema, LedgerLinksSchema, LedgerPhaseSchema, LedgerRecordSchema, NoteEntrySchema, OperatorDecisionActionSchema, OperatorDecisionEntrySchema, OperatorDecisionPayloadSchema, OperatorDecisionRecordSchema, OperatorPatchEntrySchema, OperatorPatchRecordSchema, parseLedgerEntry, parseLedgerRecord, RuntimeEventEntrySchema, StripDecisionRevertedEntrySchema, StripDecisionRevertedPayloadSchema, StripDecisionRevertedRecordSchema, ToolInvocationEntrySchema, ToolInvocationRecordSchema, ValidatorResultEntrySchema, ValidatorResultRecordSchema, } from "./schema/entry.js";
 export { NoteSubkindSchema } from "./schema/note.js";
 export { resolveLedgerPaths } from "./storage/filesystem.js";

package/dist/list.d.ts

@@ -259,7 +259,7 @@ export declare const readManifestEntryBatch: ({ allowMissing, entryLocations, wo
     } | {
         body: string;
         kind: "note";
-        subkind: "regression" | "automation" | "retro" | "operator" | "tooling-gap";
+        subkind: "regression" | "automation" | "retro" | "operator" | "tooling-gap" | "cleanup-wave" | "verified-flow" | "open-issue" | "decomposition-wave" | "semantic-cleanup-summary";
         details?: {
             [x: string]: unknown;
         } | undefined;
@@ -321,6 +321,48 @@ export declare const readManifestEntryBatch: ({ allowMissing, entryLocations, wo
         schemaVersion: "ushman-ledger-entry/v1";
         summary: string;
         ts: string;
+    } | {
+        commandsRun?: string[] | undefined;
+        filesChanged: {
+            added?: number | undefined;
+            path: string;
+            removed?: number | undefined;
+        }[];
+        hypothesis?: string | undefined;
+        kind: "change-log";
+        parityStatus?: "not-run" | "green" | "yellow" | "red" | undefined;
+        rollbackPlan?: string | undefined;
+        rollsBack?: string | undefined;
+        smokeNotes?: string | undefined;
+        smokeResult?: "pass" | "fail" | "partial" | "not-run" | undefined;
+        subkind: "vendor-extract" | "pre-change-checkpoint" | "semantic-cleanup" | "decomposition" | "rollback" | "hotfix" | "smoke";
+        details?: {
+            [x: string]: unknown;
+        } | undefined;
+        emitter: {
+            tool: string;
+            user?: string | undefined;
+            version: string;
+        };
+        id: string;
+        links: {
+            affectedFiles?: string[] | undefined;
+            blobs?: string[] | undefined;
+            briefId?: string | undefined;
+            correctsLedgerId?: string | undefined;
+            gitRef?: string | undefined;
+            idempotencyKey?: string | undefined;
+            stripDecisionId?: string | undefined;
+            supersedesLedgerId?: string | undefined;
+            validatorVerdictId?: string | undefined;
+        } & {
+            [key: string]: unknown;
+        };
+        phase: "capture" | "intake" | "seed" | "vendor-extract" | "cleanup" | "parity" | "characterize" | "equiv" | "analyze" | "recover" | "ship" | "migration";
+        prevEntryId: string | null;
+        schemaVersion: "ushman-ledger-entry/v1";
+        summary: string;
+        ts: string;
     };
     entryId: string;
     location: {
@@ -335,7 +377,7 @@ export declare const readManifestEntryBatch: ({ allowMissing, entryLocations, wo
         sequence: number;
     };
 })[]>;
-export declare const iterateEntriesFromManifest: (workspaceRoot: string, manifest: LedgerManifest, readIndex: LedgerReadIndex, filter?: LedgerFilter) => AsyncIterable<LedgerEntry>;
+export declare const iterateEntriesFromManifest: (workspaceRoot: string, manifest: LedgerManifest, readIndex: LedgerReadIndex, filter?: LedgerFilter, direction?: "asc" | "desc") => AsyncIterable<LedgerEntry>;
 export declare const listEntries: (workspaceRoot: string, filter?: LedgerFilter) => AsyncIterable<LedgerEntry>;
 export declare const readAllEntries: (workspaceRoot: string, filter?: LedgerFilter) => Promise<LedgerEntry[]>;
 //# sourceMappingURL=list.d.ts.map

package/dist/list.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"list.d.ts","sourceRoot":"","sources":["../src/list.ts"],"names":[],"mappings":"AACA,OAAO,EACH,KAAK,eAAe,EACpB,KAAK,qBAAqB,EAG7B,MAAM,iBAAiB,CAAC;AAEzB,OAAO,EAAE,KAAK,WAAW,EAAE,KAAK,UAAU,EAAE,KAAK,WAAW,EAAoB,MAAM,mBAAmB,CAAC;AAC1G,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AAG3D,MAAM,MAAM,YAAY,GAAG;IACvB,QAAQ,CAAC,IAAI,CAAC,EAAE,UAAU,CAAC;IAC3B,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,KAAK,CAAC,EAAE,WAAW,CAAC;IAC7B,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;CAC3B,CAAC;AAmDF,eAAO,MAAM,wBAAwB,GACjC,UAAU,cAAc,EACxB,WAAW,eAAe,EAC1B,QAAQ,YAAY,EACpB,YAAW,KAAK,GAAG,MAAc,4BAgBpC,CAAC;AAgCF,eAAO,MAAM,sBAAsB,GAAU,kDAI1C;IACC,QAAQ,CAAC,YAAY,CAAC,EAAE,OAAO,CAAC;IAChC,QAAQ,CAAC,cAAc,EAAE,SAAS,qBAAqB,EAAE,CAAC;IAC1D,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;CAClC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;KAQI,CAAC;AA6CN,eAAO,MAAM,0BAA0B,GACnC,eAAe,MAAM,EACrB,UAAU,cAAc,EACxB,WAAW,eAAe,EAC1B,SAAQ,YAAiB,KAC1B,aAAa,CAAC,WAAW,CAwB3B,CAAC;AAEF,eAAO,MAAM,WAAW,GACpB,eAAe,MAAM,EACrB,SAAQ,YAAiB,KAC1B,aAAa,CAAC,WAAW,CAG3B,CAAC;AAEF,eAAO,MAAM,cAAc,GAAU,eAAe,MAAM,EAAE,SAAQ,YAAiB,KAAG,OAAO,CAAC,WAAW,EAAE,CAM5G,CAAC"}
+{"version":3,"file":"list.d.ts","sourceRoot":"","sources":["../src/list.ts"],"names":[],"mappings":"AACA,OAAO,EACH,KAAK,eAAe,EACpB,KAAK,qBAAqB,EAG7B,MAAM,iBAAiB,CAAC;AAEzB,OAAO,EAAE,KAAK,WAAW,EAAE,KAAK,UAAU,EAAE,KAAK,WAAW,EAAoB,MAAM,mBAAmB,CAAC;AAC1G,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AAG3D,MAAM,MAAM,YAAY,GAAG;IACvB,QAAQ,CAAC,IAAI,CAAC,EAAE,UAAU,CAAC;IAC3B,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,KAAK,CAAC,EAAE,WAAW,CAAC;IAC7B,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;CAC3B,CAAC;AAmDF,eAAO,MAAM,wBAAwB,GACjC,UAAU,cAAc,EACxB,WAAW,eAAe,EAC1B,QAAQ,YAAY,EACpB,YAAW,KAAK,GAAG,MAAc,4BAgBpC,CAAC;AAgCF,eAAO,MAAM,sBAAsB,GAAU,kDAI1C;IACC,QAAQ,CAAC,YAAY,CAAC,EAAE,OAAO,CAAC;IAChC,QAAQ,CAAC,cAAc,EAAE,SAAS,qBAAqB,EAAE,CAAC;IAC1D,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;CAClC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;KAQI,CAAC;AAiDN,eAAO,MAAM,0BAA0B,GACnC,eAAe,MAAM,EACrB,UAAU,cAAc,EACxB,WAAW,eAAe,EAC1B,SAAQ,YAAiB,EACzB,YAAW,KAAK,GAAG,MAAc,KAClC,aAAa,CAAC,WAAW,CAwB3B,CAAC;AAEF,eAAO,MAAM,WAAW,GACpB,eAAe,MAAM,EACrB,SAAQ,YAAiB,KAC1B,aAAa,CAAC,WAAW,CAG3B,CAAC;AAEF,eAAO,MAAM,cAAc,GAAU,eAAe,MAAM,EAAE,SAAQ,YAAiB,KAAG,OAAO,CAAC,WAAW,EAAE,CAM5G,CAAC"}

package/dist/list.js

@@ -77,7 +77,7 @@ export const readManifestEntryBatch = async ({ allowMissing = false, entryLocati
     location,
     workspaceRoot,
 }));
-const collectLimitedEntries = async ({ filter, manifest, readIndex, workspaceRoot, }) => {
+const collectLimitedEntries = async ({ direction, filter, manifest, readIndex, workspaceRoot, }) => {
     const collectedEntries = [];
     const orderedEntries = getOrderedEntryLocations(manifest, readIndex, filter, 'desc');
     const limit = filter.limit ?? 0;
@@ -99,17 +99,19 @@ const collectLimitedEntries = async ({ filter, manifest, readIndex, workspaceRoo
             }
         }
     }
-    collectedEntries.reverse();
+    if (direction === 'asc') {
+        collectedEntries.reverse();
+    }
     return collectedEntries;
 };
-export const iterateEntriesFromManifest = async function* (workspaceRoot, manifest, readIndex, filter = {}) {
+export const iterateEntriesFromManifest = async function* (workspaceRoot, manifest, readIndex, filter = {}, direction = 'asc') {
     if (filter.limit) {
-        for (const entry of await collectLimitedEntries({ filter, manifest, readIndex, workspaceRoot })) {
+        for (const entry of await collectLimitedEntries({ direction, filter, manifest, readIndex, workspaceRoot })) {
             yield entry;
         }
         return;
     }
-    const orderedEntries = getOrderedEntryLocations(manifest, readIndex, filter);
+    const orderedEntries = getOrderedEntryLocations(manifest, readIndex, filter, direction);
     for (let index = 0; index < orderedEntries.length; index += ENTRY_READ_BATCH_SIZE) {
         const batch = orderedEntries.slice(index, index + ENTRY_READ_BATCH_SIZE);
         const resolvedEntries = await readManifestEntryBatch({

package/dist/note.d.ts

@@ -1,13 +1,40 @@
 import { appendRecord } from './record.ts';
 import type { LedgerPhase } from './schema/entry.ts';
 import type { NoteSubkind } from './schema/note.ts';
+/** Input shared by the narrative and note helper wrappers. */
 export type NoteBody = {
     readonly body: string;
     readonly phase: LedgerPhase;
     readonly summary: string;
 };
+/** Append a typed note entry using the library emitter metadata. */
 export declare const appendNote: (workspaceRoot: string, subkind: NoteSubkind, noteBody: NoteBody) => Promise<{
     entry: Awaited<ReturnType<typeof appendRecord>>["entry"];
     id: string;
 }>;
+/** Append a `cleanup-wave` narrative note. */
+export declare const appendCleanupWaveNote: (workspaceRoot: string, noteBody: NoteBody) => Promise<{
+    entry: Awaited<ReturnType<typeof appendRecord>>["entry"];
+    id: string;
+}>;
+/** Append a `verified-flow` narrative note. */
+export declare const appendVerifiedFlowNote: (workspaceRoot: string, noteBody: NoteBody) => Promise<{
+    entry: Awaited<ReturnType<typeof appendRecord>>["entry"];
+    id: string;
+}>;
+/** Append an `open-issue` narrative note. */
+export declare const appendOpenIssueNote: (workspaceRoot: string, noteBody: NoteBody) => Promise<{
+    entry: Awaited<ReturnType<typeof appendRecord>>["entry"];
+    id: string;
+}>;
+/** Append a `decomposition-wave` narrative note. */
+export declare const appendDecompositionWaveNote: (workspaceRoot: string, noteBody: NoteBody) => Promise<{
+    entry: Awaited<ReturnType<typeof appendRecord>>["entry"];
+    id: string;
+}>;
+/** Append the current `semantic-cleanup-summary` note for workspace narrative rendering. */
+export declare const appendSemanticCleanupSummaryNote: (workspaceRoot: string, noteBody: NoteBody) => Promise<{
+    entry: Awaited<ReturnType<typeof appendRecord>>["entry"];
+    id: string;
+}>;
 //# sourceMappingURL=note.d.ts.map

package/dist/note.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"note.d.ts","sourceRoot":"","sources":["../src/note.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAC3C,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AACrD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AAGpD,MAAM,MAAM,QAAQ,GAAG;IACnB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,KAAK,EAAE,WAAW,CAAC;IAC5B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;CAC5B,CAAC;AAEF,eAAO,MAAM,UAAU,GACnB,eAAe,MAAM,EACrB,SAAS,WAAW,EACpB,UAAU,QAAQ,KACnB,OAAO,CAAC;IAAE,KAAK,EAAE,OAAO,CAAC,UAAU,CAAC,OAAO,YAAY,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC;IAAC,EAAE,EAAE,MAAM,CAAA;CAAE,CAYlF,CAAC"}
+{"version":3,"file":"note.d.ts","sourceRoot":"","sources":["../src/note.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAC3C,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AACrD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AAGpD,8DAA8D;AAC9D,MAAM,MAAM,QAAQ,GAAG;IACnB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,KAAK,EAAE,WAAW,CAAC;IAC5B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;CAC5B,CAAC;AAEF,oEAAoE;AACpE,eAAO,MAAM,UAAU,GACnB,eAAe,MAAM,EACrB,SAAS,WAAW,EACpB,UAAU,QAAQ,KACnB,OAAO,CAAC;IAAE,KAAK,EAAE,OAAO,CAAC,UAAU,CAAC,OAAO,YAAY,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC;IAAC,EAAE,EAAE,MAAM,CAAA;CAAE,CAYlF,CAAC;AAEF,8CAA8C;AAC9C,eAAO,MAAM,qBAAqB,GAAI,eAAe,MAAM,EAAE,UAAU,QAAQ;WAf3D,OAAO,CAAC,UAAU,CAAC,OAAO,YAAY,CAAC,CAAC,CAAC,OAAO,CAAC;QAAM,MAAM;EAgB1B,CAAC;AAExD,+CAA+C;AAC/C,eAAO,MAAM,sBAAsB,GAAI,eAAe,MAAM,EAAE,UAAU,QAAQ;WAnB5D,OAAO,CAAC,UAAU,CAAC,OAAO,YAAY,CAAC,CAAC,CAAC,OAAO,CAAC;QAAM,MAAM;EAoBzB,CAAC;AAEzD,6CAA6C;AAC7C,eAAO,MAAM,mBAAmB,GAAI,eAAe,MAAM,EAAE,UAAU,QAAQ;WAvBzD,OAAO,CAAC,UAAU,CAAC,OAAO,YAAY,CAAC,CAAC,CAAC,OAAO,CAAC;QAAM,MAAM;EAwB5B,CAAC;AAEtD,oDAAoD;AACpD,eAAO,MAAM,2BAA2B,GAAI,eAAe,MAAM,EAAE,UAAU,QAAQ;WA3BjE,OAAO,CAAC,UAAU,CAAC,OAAO,YAAY,CAAC,CAAC,CAAC,OAAO,CAAC;QAAM,MAAM;EA4BpB,CAAC;AAE9D,4FAA4F;AAC5F,eAAO,MAAM,gCAAgC,GAAI,eAAe,MAAM,EAAE,UAAU,QAAQ;WA/BtE,OAAO,CAAC,UAAU,CAAC,OAAO,YAAY,CAAC,CAAC,CAAC,OAAO,CAAC;QAAM,MAAM;EAgCd,CAAC"}