ushman-ledger 0.3.0

package/dist/recovery.js

@@ -0,0 +1,189 @@
+import { readdir, readFile, rm, stat } from 'node:fs/promises';
+import path from 'node:path';
+import { z } from 'zod';
+import { reconcilePendingArchivesUnderLock } from "./archive-journal.js";
+import { getNextManifestSequence, updateManifestForEntry } from "./manifest-update.js";
+import { ensureReadIndexUnderLock } from "./read-index.js";
+import { LedgerEntrySchema } from "./schema/entry.js";
+import { cleanupStaleTempFiles, ensureLedgerDirectories, readManifest, resolveLedgerPaths, saveManifest, writeAtomicJsonFile, writeEntryFile, } from "./storage/filesystem.js";
+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 }),
+    entry: LedgerEntrySchema,
+    logicalHash: z.string().min(1),
+    schemaVersion: z.literal(PendingCommitSchemaVersion),
+    sequence: z.number().int().positive(),
+});
+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 buildPendingCommitFilePath = (workspaceRoot, sequence, entryId) => path.join(resolveLedgerPaths(workspaceRoot).pendingCommitsDir, `${formatSequence(sequence)}-${entryId}.json`);
+const parsePendingCommitFileName = (name) => {
+    const match = /^(\d+)-(.+)\.json$/u.exec(name);
+    if (!match) {
+        return null;
+    }
+    return PendingCommitFileNameSchema.parse({
+        entryId: match[2],
+        sequence: Number.parseInt(match[1], 10),
+    });
+};
+const readPendingCommit = async (filePath) => {
+    try {
+        const text = await readFile(filePath, 'utf8');
+        return PendingCommitSchema.parse(JSON.parse(text));
+    }
+    catch (error) {
+        throw new Error(`Invalid pending commit at ${filePath}: ${error instanceof Error ? error.message : String(error)}`);
+    }
+};
+const readPendingCommits = async (workspaceRoot) => {
+    const paths = await ensureLedgerDirectories(workspaceRoot);
+    const entries = await readdir(paths.pendingCommitsDir, { withFileTypes: true });
+    const pendingFiles = entries
+        .filter((entry) => entry.isFile())
+        .map((entry) => {
+        if (!entry.name.endsWith('.json')) {
+            return null;
+        }
+        const parsed = parsePendingCommitFileName(entry.name);
+        if (!parsed) {
+            return null;
+        }
+        return {
+            ...parsed,
+            filePath: path.join(paths.pendingCommitsDir, entry.name),
+        };
+    })
+        .filter((pendingFile) => pendingFile !== null)
+        .sort((left, right) => left.sequence === right.sequence
+        ? left.entryId.localeCompare(right.entryId)
+        : left.sequence - right.sequence);
+    return Promise.all(pendingFiles.map(async (pendingFile) => ({
+        filePath: pendingFile.filePath,
+        pending: await readPendingCommit(pendingFile.filePath),
+    })));
+};
+const ensurePendingCommitEntryFile = async (workspaceRoot, pending) => {
+    const entryPath = path.join(resolveLedgerPaths(workspaceRoot).phaseDir(pending.entry.phase), `${pending.entry.id}.json`);
+    try {
+        await stat(entryPath);
+        return;
+    }
+    catch (error) {
+        if (error.code !== 'ENOENT') {
+            throw error;
+        }
+    }
+    await writeEntryFile(workspaceRoot, pending.entry.phase, `${pending.entry.id}.json`, pending.entry);
+};
+const checkPendingCommitConflict = (manifest, pending) => {
+    const location = manifest.entryLocations[pending.entry.id];
+    if (!location) {
+        return;
+    }
+    if (location.phase !== pending.entry.phase || location.sequence !== pending.sequence) {
+        throw new Error(`Pending commit ${pending.entry.id} conflicts with manifest location ${location.phase}/${location.sequence}.`);
+    }
+};
+const applyPendingCommit = async ({ manifest, pending, workspaceRoot, }) => {
+    checkPendingCommitConflict(manifest, pending);
+    if (manifest.entryLocations[pending.entry.id]) {
+        await ensurePendingCommitEntryFile(workspaceRoot, pending);
+        return {
+            didChangeManifest: false,
+            manifest,
+        };
+    }
+    if (manifest.lastSequence < pending.baseLastSequence) {
+        throw new Error(`Pending commit ${pending.entry.id} is waiting on earlier sequence ${pending.baseLastSequence}.`);
+    }
+    if (manifest.lastSequence > pending.baseLastSequence) {
+        throw new Error(`Pending commit ${pending.entry.id} cannot be replayed after manifest advanced to ${manifest.lastSequence}.`);
+    }
+    const expectedSequence = getNextManifestSequence(manifest.lastSequence);
+    if (expectedSequence !== pending.sequence) {
+        throw new Error(`Pending commit ${pending.entry.id} expected next sequence ${pending.sequence} but manifest would advance to ${expectedSequence}.`);
+    }
+    await writeEntryFile(workspaceRoot, pending.entry.phase, `${pending.entry.id}.json`, pending.entry);
+    const nextManifest = updateManifestForEntry({
+        entry: pending.entry,
+        logicalHash: pending.logicalHash,
+        manifest,
+    });
+    if (nextManifest.lastSequence !== pending.sequence) {
+        throw new Error(`Pending commit ${pending.entry.id} expected sequence ${pending.sequence} but resolved to ${nextManifest.lastSequence}.`);
+    }
+    return {
+        didChangeManifest: true,
+        manifest: nextManifest,
+    };
+};
+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({
+        baseLastSequence: manifest.lastSequence,
+        createdAt: new Date().toISOString(),
+        entry,
+        logicalHash,
+        schemaVersion: PendingCommitSchemaVersion,
+        sequence: nextSequence,
+    }));
+    return filePath;
+};
+export const removePendingCommit = async (filePath) => {
+    await rm(filePath, { force: true });
+};
+export const reconcilePendingCommitsUnderLock = async (workspaceRoot) => {
+    await cleanupStaleTempFiles(workspaceRoot);
+    let manifest = await readManifest(workspaceRoot);
+    const pendingCommits = await readPendingCommits(workspaceRoot);
+    const processedPendingFiles = [];
+    let manifestChanged = false;
+    for (const pendingCommit of pendingCommits) {
+        const replayed = await applyPendingCommit({
+            manifest,
+            pending: pendingCommit.pending,
+            workspaceRoot,
+        });
+        manifest = replayed.manifest;
+        manifestChanged = manifestChanged || replayed.didChangeManifest;
+        processedPendingFiles.push(pendingCommit.filePath);
+    }
+    if (manifestChanged) {
+        await saveManifest(workspaceRoot, manifest);
+    }
+    for (const filePath of processedPendingFiles) {
+        await removePendingCommit(filePath);
+    }
+    return manifest;
+};
+export const reconcileLedgerStateUnderLock = async (workspaceRoot) => {
+    const manifestAfterPendingCommits = await reconcilePendingCommitsUnderLock(workspaceRoot);
+    const readIndex = await ensureReadIndexUnderLock(workspaceRoot, manifestAfterPendingCommits);
+    const manifest = await reconcilePendingArchivesUnderLock({
+        manifest: manifestAfterPendingCommits,
+        workspaceRoot,
+    });
+    return { manifest, readIndex };
+};
+export const loadLedgerState = async (workspaceRoot) => {
+    const paths = await ensureLedgerDirectories(workspaceRoot);
+    const lock = await acquireLock(paths.manifestLockFile);
+    try {
+        return await reconcileLedgerStateUnderLock(workspaceRoot);
+    }
+    finally {
+        await lock.release();
+    }
+};
+export const prepareLedgerState = async (workspaceRoot) => {
+    await loadLedgerState(workspaceRoot);
+};

package/dist/render/analytics-summary.d.ts

@@ -0,0 +1,58 @@
+import { z } from 'zod';
+import type { LedgerReadIndex } from '../read-index.ts';
+import { type LedgerEntry } from '../schema/entry.ts';
+import type { LedgerManifest } from '../schema/manifest.ts';
+export declare const AnalyticsSummarySchema: z.ZodObject<{
+    agentPatchCount: z.ZodNumber;
+    entriesByKind: z.ZodRecord<z.ZodEnum<{
+        "tool-invocation": "tool-invocation";
+        "agent-patch": "agent-patch";
+        "operator-patch": "operator-patch";
+        "stage-transition": "stage-transition";
+        "operator-decision": "operator-decision";
+        "validator-result": "validator-result";
+        "runtime-event": "runtime-event";
+        note: "note";
+        correction: "correction";
+        "strip-decision-reverted": "strip-decision-reverted";
+        "descope-brief": "descope-brief";
+        "merge-return": "merge-return";
+        "merge-return-rejected": "merge-return-rejected";
+        revert: "revert";
+        rollback: "rollback";
+        "rework.test_retired": "rework.test_retired";
+    }>, z.ZodNumber>;
+    entryCount: z.ZodNumber;
+    filesTouchedCount: z.ZodNumber;
+    filterHash: z.ZodString;
+    legacyEntryCount: z.ZodNumber;
+    operatorDecisionActionCounts: z.ZodRecord<z.ZodEnum<{
+        "bypass-doctor": "bypass-doctor";
+        "skip-check": "skip-check";
+        "override-strip-decision": "override-strip-decision";
+        "override-ship-state": "override-ship-state";
+        "manual-parity-assertion": "manual-parity-assertion";
+        "ledger-hand-edit": "ledger-hand-edit";
+        escalation: "escalation";
+    }>, z.ZodNumber>;
+    operatorPatchCount: z.ZodNumber;
+    reworkTestRetiredCount: z.ZodNumber;
+    schemaVersion: z.ZodLiteral<"ushman-ledger-analytics-summary/v1">;
+    stageTransitionCount: z.ZodNumber;
+    tipHash: z.ZodString;
+    validatorPassFailCounts: z.ZodObject<{
+        green: z.ZodNumber;
+        red: z.ZodNumber;
+        yellow: z.ZodNumber;
+    }, z.core.$strip>;
+}, z.core.$strip>;
+export type AnalyticsSummary = z.infer<typeof AnalyticsSummarySchema>;
+export declare const renderAnalyticsSummary: ({ cachePath, entries, filter, manifest, readIndex, useCache, }: {
+    readonly cachePath: string;
+    readonly entries: AsyncIterable<LedgerEntry>;
+    readonly filter: unknown;
+    readonly manifest: LedgerManifest;
+    readonly readIndex: LedgerReadIndex;
+    readonly useCache: boolean;
+}) => Promise<string>;
+//# sourceMappingURL=analytics-summary.d.ts.map

package/dist/render/analytics-summary.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"analytics-summary.d.ts","sourceRoot":"","sources":["../../src/render/analytics-summary.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,kBAAkB,CAAC;AACxD,OAAO,EAEH,KAAK,WAAW,EAInB,MAAM,oBAAoB,CAAC;AAC5B,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC;AAY5D,eAAO,MAAM,sBAAsB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAcjC,CAAC;AAEH,MAAM,MAAM,gBAAgB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,sBAAsB,CAAC,CAAC;AAgKtE,eAAO,MAAM,sBAAsB,GAAU,gEAO1C;IACC,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,OAAO,EAAE,aAAa,CAAC,WAAW,CAAC,CAAC;IAC7C,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAC;IACzB,QAAQ,CAAC,QAAQ,EAAE,cAAc,CAAC;IAClC,QAAQ,CAAC,SAAS,EAAE,eAAe,CAAC;IACpC,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAC;CAC9B,oBAqBA,CAAC"}

package/dist/render/analytics-summary.js

@@ -0,0 +1,151 @@
+import { readFile } from 'node:fs/promises';
+import { z } from 'zod';
+import { sha256Hex, stableStringify } from "../json.js";
+import { LEDGER_KINDS, OPERATOR_DECISION_ACTIONS, } from "../schema/entry.js";
+import { writeAtomicJsonFile } from "../storage/filesystem.js";
+const ANALYTICS_SUMMARY_SCHEMA_VERSION = 'ushman-ledger-analytics-summary/v1';
+const EntriesByKindSchema = z.record(z.enum(LEDGER_KINDS), z.number().int().nonnegative());
+const OperatorDecisionActionCountsSchema = z.record(z.enum(OPERATOR_DECISION_ACTIONS), z.number().int().nonnegative());
+const ValidatorPassFailCountsSchema = z.object({
+    green: z.number().int().nonnegative(),
+    red: z.number().int().nonnegative(),
+    yellow: z.number().int().nonnegative(),
+});
+export const AnalyticsSummarySchema = z.object({
+    agentPatchCount: z.number().int().nonnegative(),
+    entriesByKind: EntriesByKindSchema,
+    entryCount: z.number().int().nonnegative(),
+    filesTouchedCount: z.number().int().nonnegative(),
+    filterHash: z.string().min(1),
+    legacyEntryCount: z.number().int().nonnegative(),
+    operatorDecisionActionCounts: OperatorDecisionActionCountsSchema,
+    operatorPatchCount: z.number().int().nonnegative(),
+    reworkTestRetiredCount: z.number().int().nonnegative(),
+    schemaVersion: z.literal(ANALYTICS_SUMMARY_SCHEMA_VERSION),
+    stageTransitionCount: z.number().int().nonnegative(),
+    tipHash: z.string().min(1),
+    validatorPassFailCounts: ValidatorPassFailCountsSchema,
+});
+const buildEntriesByKind = () => Object.fromEntries(LEDGER_KINDS.map((kind) => [kind, 0]));
+const buildOperatorDecisionActionCounts = () => Object.fromEntries(OPERATOR_DECISION_ACTIONS.map((action) => [action, 0]));
+const computeLedgerTipHash = ({ manifest, readIndex, }) => sha256Hex(stableStringify({
+    lastEntryId: readIndex.lastEntryId,
+    lastSequence: manifest.lastSequence,
+}));
+const computeFilterHash = (filter) => sha256Hex(stableStringify(filter));
+const increment = (record, key) => {
+    record[key] += 1;
+};
+const createSummaryAccumulator = () => ({
+    agentPatchCount: 0,
+    entriesByKind: buildEntriesByKind(),
+    entryCount: 0,
+    legacyEntryCount: 0,
+    operatorDecisionActionCounts: buildOperatorDecisionActionCounts(),
+    operatorPatchCount: 0,
+    reworkTestRetiredCount: 0,
+    stageTransitionCount: 0,
+    touchedPaths: new Set(),
+    validatorPassFailCounts: {
+        green: 0,
+        red: 0,
+        yellow: 0,
+    },
+});
+const addTouchedPaths = (state, touchedPaths) => {
+    for (const touchedPath of touchedPaths) {
+        state.touchedPaths.add(touchedPath);
+    }
+};
+const accumulateEntry = (state, entry) => {
+    state.entryCount += 1;
+    increment(state.entriesByKind, entry.kind);
+    if (entry._legacy) {
+        state.legacyEntryCount += 1;
+    }
+    switch (entry.kind) {
+        case 'agent-patch':
+            state.agentPatchCount += 1;
+            addTouchedPaths(state, entry.payload.touchedPaths);
+            return;
+        case 'operator-patch':
+            state.operatorPatchCount += 1;
+            addTouchedPaths(state, entry.payload.touchedPaths);
+            return;
+        case 'operator-decision':
+            increment(state.operatorDecisionActionCounts, entry.payload.action);
+            return;
+        case 'validator-result':
+            increment(state.validatorPassFailCounts, entry.verdict);
+            return;
+        case 'stage-transition':
+            state.stageTransitionCount += 1;
+            return;
+        case 'rework.test_retired':
+            state.reworkTestRetiredCount += 1;
+            return;
+        default:
+            return;
+    }
+};
+const summarizeEntries = async ({ entries, filterHash, tipHash, }) => {
+    const state = createSummaryAccumulator();
+    for await (const entry of entries) {
+        accumulateEntry(state, entry);
+    }
+    return AnalyticsSummarySchema.parse({
+        agentPatchCount: state.agentPatchCount,
+        entriesByKind: state.entriesByKind,
+        entryCount: state.entryCount,
+        filesTouchedCount: state.touchedPaths.size,
+        filterHash,
+        legacyEntryCount: state.legacyEntryCount,
+        operatorDecisionActionCounts: state.operatorDecisionActionCounts,
+        operatorPatchCount: state.operatorPatchCount,
+        reworkTestRetiredCount: state.reworkTestRetiredCount,
+        schemaVersion: ANALYTICS_SUMMARY_SCHEMA_VERSION,
+        stageTransitionCount: state.stageTransitionCount,
+        tipHash,
+        validatorPassFailCounts: state.validatorPassFailCounts,
+    });
+};
+const formatAnalyticsSummary = (summary) => `${stableStringify(summary, true)}\n`;
+const debugLog = (message, error) => {
+    if (process.env.NODE_ENV === 'test') {
+        return;
+    }
+    const details = error instanceof Error ? error.message : String(error);
+    console.debug(`[ushman-ledger] ${message}: ${details}`);
+};
+const readCachedSummary = async (cachePath) => {
+    try {
+        const text = await readFile(cachePath, 'utf8');
+        return AnalyticsSummarySchema.parse(JSON.parse(text));
+    }
+    catch (error) {
+        if (error.code === 'ENOENT') {
+            return null;
+        }
+        debugLog(`Ignoring analytics summary cache at ${cachePath}`, error);
+        return null;
+    }
+};
+export const renderAnalyticsSummary = async ({ cachePath, entries, filter, manifest, readIndex, useCache, }) => {
+    const filterHash = computeFilterHash(filter);
+    const tipHash = computeLedgerTipHash({ manifest, readIndex });
+    if (useCache) {
+        const cached = await readCachedSummary(cachePath);
+        if (cached?.tipHash === tipHash && cached.filterHash === filterHash) {
+            return formatAnalyticsSummary(cached);
+        }
+    }
+    const summary = await summarizeEntries({
+        entries,
+        filterHash,
+        tipHash,
+    });
+    if (useCache) {
+        await writeAtomicJsonFile(cachePath, summary);
+    }
+    return formatAnalyticsSummary(summary);
+};

package/dist/render/dependency-graph.d.ts

@@ -0,0 +1,3 @@
+import type { LedgerEntry } from '../schema/entry.ts';
+export declare const renderDependencyGraph: (entries: AsyncIterable<LedgerEntry>) => Promise<string>;
+//# sourceMappingURL=dependency-graph.d.ts.map

package/dist/render/dependency-graph.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"dependency-graph.d.ts","sourceRoot":"","sources":["../../src/render/dependency-graph.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AAKtD,eAAO,MAAM,qBAAqB,GAAU,SAAS,aAAa,CAAC,WAAW,CAAC,KAAG,OAAO,CAAC,MAAM,CAoB/F,CAAC"}

package/dist/render/dependency-graph.js

@@ -0,0 +1,18 @@
+const escapeMermaid = (value) => value.replaceAll('\\', '\\\\').replaceAll('"', '\\"').replaceAll(/\s+/gu, ' ').trim();
+export const renderDependencyGraph = async (entries) => {
+    const lines = ['graph TD'];
+    for await (const entry of entries) {
+        const nodeLabel = escapeMermaid(`${entry.phase}:${entry.kind}`);
+        lines.push(`  "${escapeMermaid(entry.id)}"["${nodeLabel}\\n${escapeMermaid(entry.summary)}"]`);
+        if (entry.prevEntryId) {
+            lines.push(`  "${escapeMermaid(entry.prevEntryId)}" --> "${escapeMermaid(entry.id)}"`);
+        }
+        if (entry.links.correctsLedgerId) {
+            lines.push(`  "${escapeMermaid(entry.links.correctsLedgerId)}" -. corrects .-> "${escapeMermaid(entry.id)}"`);
+        }
+        if (entry.links.supersedesLedgerId) {
+            lines.push(`  "${escapeMermaid(entry.links.supersedesLedgerId)}" -. supersedes .-> "${escapeMermaid(entry.id)}"`);
+        }
+    }
+    return lines.join('\n');
+};

package/dist/render/jsonl.d.ts

@@ -0,0 +1,3 @@
+import type { LedgerEntry } from '../schema/entry.ts';
+export declare const renderJsonl: (entries: AsyncIterable<LedgerEntry>) => Promise<string>;
+//# sourceMappingURL=jsonl.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"jsonl.d.ts","sourceRoot":"","sources":["../../src/render/jsonl.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AAEtD,eAAO,MAAM,WAAW,GAAU,SAAS,aAAa,CAAC,WAAW,CAAC,KAAG,OAAO,CAAC,MAAM,CAMrF,CAAC"}

package/dist/render/jsonl.js

@@ -0,0 +1,8 @@
+import { stableStringify } from "../json.js";
+export const renderJsonl = async (entries) => {
+    const lines = [];
+    for await (const entry of entries) {
+        lines.push(stableStringify(entry));
+    }
+    return `${lines.join('\n')}${lines.length > 0 ? '\n' : ''}`;
+};

package/dist/render/retro.d.ts

@@ -0,0 +1,6 @@
+import type { LedgerEntry } from '../schema/entry.ts';
+export declare const renderRetroMarkdown: ({ entries, manifest, }: {
+    readonly entries: AsyncIterable<LedgerEntry>;
+    readonly manifest: unknown;
+}) => Promise<string>;
+//# sourceMappingURL=retro.d.ts.map

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

@@ -0,0 +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"}

package/dist/render/retro.js

@@ -0,0 +1,124 @@
+import { sha256Hex, stableStringify } from "../json.js";
+const renderList = (items) => items.length === 0 ? '- None recorded.' : items.map((item) => `- ${item}`).join('\n');
+const toSingleLine = (value) => value.replaceAll(/\s+/gu, ' ').trim();
+const formatEntry = (entry) => `${entry.ts} [${entry.phase}] ${toSingleLine(entry.summary)}`;
+const createRetroBuckets = () => ({
+    correctionEntries: [],
+    operatorEntries: [],
+    problemEntries: [],
+    retroEntries: [],
+    toolEntries: [],
+    toolingEntries: [],
+    validatorEntries: [],
+});
+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 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 resolveRenderedAt = (entryCount, lastEntryTimestamp, manifest) => {
+    if (entryCount > 0) {
+        return lastEntryTimestamp ?? 'n/a';
+    }
+    if (typeof manifest === 'object' && manifest && 'createdAt' in manifest) {
+        const createdAt = manifest.createdAt;
+        if (typeof createdAt === 'string') {
+            return createdAt;
+        }
+    }
+    return 'n/a';
+};
+const normalizeManifestForHash = (manifest) => typeof manifest === 'object' && manifest
+    ? { ...manifest, updatedAt: undefined }
+    : manifest;
+const formatValidatorEntry = (entry) => entry.kind === 'validator-result'
+    ? `${entry.ts} [${entry.validator}/${entry.verdict}] ${entry.summary}`
+    : formatEntry(entry);
+const collectRetroState = async (entries) => {
+    const buckets = createRetroBuckets();
+    const tools = new Set();
+    let entryCount = 0;
+    let lastEntryTimestamp = null;
+    for await (const entry of 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));
+        }
+    }
+    return {
+        buckets,
+        entryCount,
+        lastEntryTimestamp,
+        tools: [...tools].sort((left, right) => left.localeCompare(right)),
+    };
+};
+export const renderRetroMarkdown = async ({ entries, manifest, }) => {
+    const { buckets, entryCount, lastEntryTimestamp, tools } = await collectRetroState(entries);
+    const renderedAt = resolveRenderedAt(entryCount, lastEntryTimestamp, manifest);
+    const manifestSha = sha256Hex(stableStringify(normalizeManifestForHash(manifest)));
+    return [
+        '<!-- LEDGER_SCHEMA_VERSION: ushman-ledger-entry/v1 -->',
+        '<!-- DO_NOT_EDIT: Auto-generated. Use `ushman-ledger record` / `ushman-ledger note`. -->',
+        `<!-- LAST_RENDERED: ${renderedAt} -->`,
+        `<!-- LAST_RENDERED_AT_ENTRY_COUNT: ${entryCount} -->`,
+        `<!-- LAST_RENDERED_MANIFEST_SHA: ${manifestSha} -->`,
+        '',
+        '# Ushman Ledger Retro',
+        '',
+        '## 1. Donor classification',
+        renderList(['Recorded through the workspace ledger.']),
+        '',
+        '## 2. Migration scope',
+        renderList(['See operator decisions and note entries for phase-specific scope.']),
+        '',
+        '## 3. Step-by-step migration log',
+        renderList(buckets.toolEntries),
+        '',
+        '## 4. Problems hit',
+        renderList(buckets.problemEntries),
+        '',
+        '## 5. Tools used',
+        renderList(tools),
+        '',
+        '## 6. Where dedicated tooling would have helped',
+        renderList(buckets.toolingEntries),
+        '',
+        '## 7. Where tooling was overkill',
+        renderList(buckets.retroEntries),
+        '',
+        '## 8. Corrections and revisions',
+        renderList(buckets.correctionEntries),
+        '',
+        '## 9. Operator notes',
+        renderList(buckets.operatorEntries),
+        '',
+        '## 10. Triage signals',
+        renderList(buckets.validatorEntries),
+        '',
+    ].join('\n');
+};

package/dist/render/timeline-html.d.ts

@@ -0,0 +1,3 @@
+import type { LedgerEntry } from '../schema/entry.ts';
+export declare const renderTimelineHtml: (entries: AsyncIterable<LedgerEntry>) => Promise<string>;
+//# sourceMappingURL=timeline-html.d.ts.map

package/dist/render/timeline-html.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"timeline-html.d.ts","sourceRoot":"","sources":["../../src/render/timeline-html.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AAUtD,eAAO,MAAM,kBAAkB,GAAU,SAAS,aAAa,CAAC,WAAW,CAAC,KAAG,OAAO,CAAC,MAAM,CAmC5F,CAAC"}

package/dist/render/timeline-html.js

@@ -0,0 +1,37 @@
+const escapeHtml = (value) => value
+    .replaceAll('&', '&')
+    .replaceAll('<', '&lt;')
+    .replaceAll('>', '&gt;')
+    .replaceAll('"', '&quot;')
+    .replaceAll("'", '&#39;');
+export const renderTimelineHtml = async (entries) => {
+    const rows = [];
+    for await (const entry of entries) {
+        rows.push(`<tr><td>${escapeHtml(entry.ts)}</td><td>${escapeHtml(entry.phase)}</td><td>${escapeHtml(entry.kind)}</td><td>${escapeHtml(entry.summary)}</td></tr>`);
+    }
+    return `<!doctype html>
+<html lang="en">
+<head>
+  <meta charset="utf-8" />
+  <title>Ushman Ledger Timeline</title>
+  <style>
+    body { font-family: sans-serif; margin: 2rem; }
+    table { border-collapse: collapse; width: 100%; }
+    th, td { border: 1px solid #ddd; padding: 0.5rem; text-align: left; }
+    th { background: #f5f5f5; }
+  </style>
+</head>
+<body>
+  <h1>Ushman Ledger Timeline</h1>
+  <table>
+    <thead>
+      <tr><th>Timestamp</th><th>Phase</th><th>Kind</th><th>Summary</th></tr>
+    </thead>
+    <tbody>
+${rows.join('\n')}
+    </tbody>
+  </table>
+</body>
+</html>
+`;
+};