ushman-ledger 0.3.0 → 1.2.0

package/dist/cli.js

@@ -5,14 +5,35 @@ import os from 'node:os';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { promisify } from 'node:util';
-import { ZodError } from 'zod';
+import * as v from 'valibot';
 import { openLedger } from "./handle.js";
-import { LEDGER_KINDS, LEDGER_PHASES, parseLedgerRecord } from "./schema/entry.js";
+import { deriveFilesChangedFromPatch } from "./patch-resolver.js";
+import { ChangeLogParityStatusSchema, ChangeLogSmokeResultSchema, ChangeLogSubkindSchema, LEDGER_KINDS, LEDGER_PHASES, parseLedgerRecord, WorkspaceRelativePathSchema, } from "./schema/entry.js";
 import { NoteSubkindSchema } from "./schema/note.js";
 import { LEDGER_LIBRARY_VERSION } from "./version.js";
 const execFileAsync = promisify(execFile);
+const GIT_DIFF_MAX_BUFFER_BYTES = 10 * 1024 * 1024;
 const GIT_DIFF_TIMEOUT_MS = 30_000;
-const RENDER_TARGETS = ['retro', 'jsonl', 'timeline-html', 'dependency-graph', 'analytics-summary'];
+const RENDER_TARGETS = [
+    'retro',
+    'jsonl',
+    'timeline-html',
+    'dependency-graph',
+    'migration-log-md',
+    'workspace-narrative-md',
+];
+const CHANGE_LOG_RECORD_ONLY_FLAGS = [
+    'commands',
+    'commands-from',
+    'files-changed',
+    'hypothesis',
+    'parity-status',
+    'rollback-plan',
+    'rolls-back',
+    'smoke-notes',
+    'smoke-result',
+    'subkind',
+];
 class CliUsageError extends Error {
 }
 const DEFAULT_CONTEXT = {
@@ -34,12 +55,12 @@ const renderValidValues = () => `Valid values:
 const renderHelp = (commandName) => `${commandName}
 
 Commands:
-  ${commandName} record [--workspace=<ws>] --kind=<kind> --phase=<phase> --summary="..." [--rationale="..."] [--action=<operator-action>] [--check-id=<check-id>] [--diff=<patch-file>] [--diff-from-git=<ref>] [--idempotency-key=<key>] [--from-stdin]
+  ${commandName} record [--workspace=<ws>] --kind=<kind> --phase=<phase> --summary="..." [--rationale="..."] [--action=<operator-action>] [--check-id=<check-id>] [--diff=<patch-file>] [--diff-from-git=<ref>] [--idempotency-key=<key>] [--subkind=<change-log-subkind>] [--files-changed=<csv>] [--hypothesis="..."] [--commands="cmd1\ncmd2" | --commands-from=<file>] [--smoke-result=<result>] [--smoke-notes="..."] [--parity-status=<status>] [--rollback-plan="..."] [--rolls-back=<entry-id>] [--from-stdin]
   ${commandName} note <subkind> [--workspace=<ws>] --phase=<phase> --summary="..." [--body=<markdown-file>] [--from-stdin]
   ${commandName} list [--workspace=<ws>] [--phase=<phase>] [--kind=<kind>] [--since=<iso>] [--limit=<n>] [--json]
   ${commandName} show [--workspace=<ws>] <entry-id>
   ${commandName} tail [--workspace=<ws>] [--phase=<phase>] [--limit=<n>]
-  ${commandName} render [--workspace=<ws>] [--to=retro|jsonl|timeline-html|dependency-graph|analytics-summary] [--phase=<phase>] [--out=<file>] [--fresh] [--json]
+  ${commandName} render [--workspace=<ws>] [--to=retro|jsonl|timeline-html|dependency-graph|migration-log-md|workspace-narrative-md] [--phase=<phase>] [--since=<iso>] [--limit=<n>] [--out=<file>]
   ${commandName} archive [--workspace=<ws>] --out=<file.tgz>
   ${commandName} doctor [--workspace=<ws>]
   ${commandName} --version
@@ -48,7 +69,7 @@ ${renderValidValues()}`;
 const renderCommandHelp = (commandName, command) => {
     switch (command) {
         case 'record':
-            return `${commandName} record [--workspace=<ws>] --kind=<kind> --phase=<phase> --summary="..." [--rationale="..."] [--action=<operator-action>] [--check-id=<check-id>] [--diff=<patch-file>] [--diff-from-git=<ref>] [--idempotency-key=<key>] [--from-stdin]
+            return `${commandName} record [--workspace=<ws>] --kind=<kind> --phase=<phase> --summary="..." [--rationale="..."] [--action=<operator-action>] [--check-id=<check-id>] [--diff=<patch-file>] [--diff-from-git=<ref>] [--idempotency-key=<key>] [--subkind=<change-log-subkind>] [--files-changed=<csv>] [--hypothesis="..."] [--commands="cmd1\ncmd2" | --commands-from=<file>] [--smoke-result=<result>] [--smoke-notes="..."] [--parity-status=<status>] [--rollback-plan="..."] [--rolls-back=<entry-id>] [--from-stdin]
 
 ${renderValidValues()}`;
         case 'note':
@@ -60,9 +81,7 @@ ${renderValidValues()}`;
 
 ${renderValidValues()}`;
         case 'render':
-            return `${commandName} render [--workspace=<ws>] [--to=<target>] [--phase=<phase>] [--out=<file>] [--fresh] [--json]
-
-Use \`--fresh\` to bypass the cached analytics summary. \`--json\` remains a compatibility alias for the same behavior.
+            return `${commandName} render [--workspace=<ws>] [--to=<target>] [--phase=<phase>] [--since=<iso>] [--limit=<n>] [--out=<file>]
 
 ${renderValidValues()}`;
         default:
@@ -101,6 +120,9 @@ const parseArgv = (argv) => {
 };
 const getFlag = (flags, name) => {
     const value = flags[name];
+    if (value === true) {
+        throw new CliUsageError(`Missing value for --${name}.`);
+    }
     return typeof value === 'string' ? value : undefined;
 };
 const hasFlag = (flags, name) => flags[name] === true || typeof flags[name] === 'string';
@@ -142,7 +164,7 @@ const materializeGitDiff = async (workspaceRoot, gitRef) => {
     try {
         const { stdout } = await execFileAsync('git', ['diff', gitRef], {
             cwd: workspaceRoot,
-            maxBuffer: 10 * 1024 * 1024,
+            maxBuffer: GIT_DIFF_MAX_BUFFER_BYTES,
             timeout: GIT_DIFF_TIMEOUT_MS,
         });
         tempDir = await mkdtemp(path.join(os.tmpdir(), 'ushman-ledger-git-diff-'));
@@ -236,18 +258,121 @@ const parseRenderTarget = (flags) => {
     }
     return target;
 };
+const splitCommandLines = (value) => value
+    .split(/\r?\n/u)
+    .map((command) => command.trim())
+    .filter((command) => command.length > 0);
+const getUsedFlags = (flags, names) => names.filter((name) => hasFlag(flags, name)).map((name) => `--${name}`);
+const rejectUnsupportedFlags = (supportedKindLabel, flags, names) => {
+    const usedFlags = getUsedFlags(flags, names);
+    if (usedFlags.length === 0) {
+        return;
+    }
+    throw new CliUsageError(`${usedFlags.join(', ')} ${usedFlags.length === 1 ? 'is' : 'are'} only supported for ${supportedKindLabel} records.`);
+};
+const parseRequiredChangeLogSubkind = (flags) => {
+    const subkind = getRequiredString(flags, 'subkind');
+    if (!ChangeLogSubkindSchema.options.includes(subkind)) {
+        throw new CliUsageError(`Invalid --subkind value: ${subkind}. Expected one of: ${ChangeLogSubkindSchema.options.join(', ')}.`);
+    }
+    return subkind;
+};
+const parseOptionalChangeLogPicklist = ({ flagName, flags, options, }) => {
+    const value = getFlag(flags, flagName);
+    if (!value) {
+        return undefined;
+    }
+    if (!options.includes(value)) {
+        throw new CliUsageError(`Invalid --${flagName} value: ${value}. Expected one of: ${options.join(', ')}.`);
+    }
+    return value;
+};
+const parseFilesChangedCsv = (raw) => {
+    const uniquePaths = [
+        ...new Set(raw
+            .split(',')
+            .map((value) => value.trim())
+            .filter((value) => value.length > 0)
+            .map((filePath) => {
+            try {
+                return v.parse(WorkspaceRelativePathSchema, filePath);
+            }
+            catch {
+                throw new CliUsageError(`--files-changed path is not a normalized workspace-relative path: ${filePath}`);
+            }
+        })),
+    ];
+    if (uniquePaths.length === 0) {
+        throw new CliUsageError('--files-changed must include at least one workspace-relative path.');
+    }
+    return uniquePaths.map((filePath) => ({ path: filePath }));
+};
+const readCommandLines = async (flags) => {
+    const inlineCommands = getFlag(flags, 'commands');
+    const commandsFrom = getFlag(flags, 'commands-from');
+    if (inlineCommands && commandsFrom) {
+        throw new CliUsageError('Use either --commands or --commands-from, not both.');
+    }
+    if (commandsFrom) {
+        const commandsPath = path.resolve(commandsFrom);
+        await ensureFileExists(commandsPath, '--commands-from');
+        return splitCommandLines(await readFile(commandsPath, 'utf8'));
+    }
+    if (inlineCommands) {
+        return splitCommandLines(inlineCommands);
+    }
+    return undefined;
+};
+const resolveDiffInput = async ({ flags, kind, workspaceRoot, }) => {
+    const diffPath = getFlag(flags, 'diff');
+    const diffFromGit = getFlag(flags, 'diff-from-git');
+    if (diffPath && diffFromGit) {
+        throw new CliUsageError('Use either --diff or --diff-from-git, not both.');
+    }
+    if (!diffPath && !diffFromGit) {
+        return {};
+    }
+    if (kind !== 'agent-patch' && kind !== 'operator-patch' && kind !== 'change-log') {
+        throw new CliUsageError('--diff and --diff-from-git are only supported for patch and change-log records.');
+    }
+    if (diffPath) {
+        const resolvedDiffPath = path.resolve(diffPath);
+        await ensureFileExists(resolvedDiffPath, '--diff');
+        return {
+            diffPath: resolvedDiffPath,
+            patchText: kind === 'change-log' ? await readFile(resolvedDiffPath, 'utf8') : undefined,
+        };
+    }
+    const materialized = await materializeGitDiff(workspaceRoot, diffFromGit ?? '');
+    return {
+        cleanupTempDir: materialized.tempDir,
+        diffPath: materialized.patchPath,
+        gitRef: diffFromGit,
+        patchText: kind === 'change-log' ? await readFile(materialized.patchPath, 'utf8') : undefined,
+    };
+};
 const validateRecordStdinFlags = (flags) => {
     const conflictingFlags = [
         'agent',
         'action',
         'check-id',
+        'commands',
+        'commands-from',
         'diff',
         'diff-from-git',
+        'files-changed',
+        'hypothesis',
         'idempotency-key',
         'kind',
         'operator',
+        'parity-status',
         'phase',
         'rationale',
+        'rollback-plan',
+        'rolls-back',
+        'smoke-notes',
+        'smoke-result',
+        'subkind',
         'summary',
     ].filter((flagName) => hasFlag(flags, flagName));
     if (conflictingFlags.length === 0) {
@@ -259,6 +384,9 @@ const validateRecordStdinFlags = (flags) => {
 };
 const buildBaseRecordFromFlags = (parsed, context) => {
     const kind = getRequiredKind(parsed.flags);
+    if (kind !== 'change-log') {
+        rejectUnsupportedFlags('change-log', parsed.flags, CHANGE_LOG_RECORD_ONLY_FLAGS);
+    }
     const record = {
         emitter: {
             tool: context.defaultEmitter.tool,
@@ -298,43 +426,68 @@ const buildBaseRecordFromFlags = (parsed, context) => {
             rationale: rationale ?? '',
         };
     }
+    if (kind === 'change-log') {
+        record.subkind = parseRequiredChangeLogSubkind(parsed.flags);
+    }
     const idempotencyKey = getFlag(parsed.flags, 'idempotency-key');
     if (idempotencyKey) {
         record.idempotencyKey = idempotencyKey;
     }
     return { kind, record };
 };
-const applyPatchInputToRecord = async ({ kind, record, workspaceRoot, parsed, }) => {
-    const diffPath = getFlag(parsed.flags, 'diff');
-    if (diffPath) {
-        if (kind !== 'agent-patch' && kind !== 'operator-patch') {
-            throw new CliUsageError('--diff is only supported for patch records.');
-        }
-        await ensureFileExists(path.resolve(diffPath), '--diff');
-        record.diffPath = diffPath;
-    }
-    const diffFromGit = getFlag(parsed.flags, 'diff-from-git');
-    if (!diffFromGit) {
-        return {};
-    }
+const applyPatchInputToRecord = async ({ kind, patchInput, record, }) => {
     if (kind !== 'agent-patch' && kind !== 'operator-patch') {
-        throw new CliUsageError('--diff-from-git is only supported for patch records.');
-    }
-    if (diffPath) {
-        throw new CliUsageError('Use either --diff or --diff-from-git, not both.');
+        return {};
     }
-    const materialized = await materializeGitDiff(workspaceRoot, diffFromGit);
     return {
-        cleanupTempDir: materialized.tempDir,
+        cleanupTempDir: patchInput.cleanupTempDir,
         record: {
             ...record,
-            diffPath: materialized.patchPath,
-            links: {
-                gitRef: diffFromGit,
-            },
+            diffPath: patchInput.diffPath,
+            links: patchInput.gitRef
+                ? {
+                    ...record.links,
+                    gitRef: patchInput.gitRef,
+                }
+                : record.links,
         },
     };
 };
+const applyChangeLogFlagsToRecord = async ({ flags, patchInput, record, }) => {
+    const filesChangedFlag = getFlag(flags, 'files-changed');
+    if (filesChangedFlag && patchInput.patchText) {
+        throw new CliUsageError('Use either --files-changed or --diff/--diff-from-git to populate change-log files.');
+    }
+    return {
+        ...record,
+        commandsRun: await readCommandLines(flags),
+        filesChanged: filesChangedFlag
+            ? parseFilesChangedCsv(filesChangedFlag)
+            : patchInput.patchText
+                ? deriveFilesChangedFromPatch(patchInput.patchText)
+                : undefined,
+        hypothesis: getFlag(flags, 'hypothesis'),
+        links: patchInput.gitRef
+            ? {
+                ...record.links,
+                gitRef: patchInput.gitRef,
+            }
+            : record.links,
+        parityStatus: parseOptionalChangeLogPicklist({
+            flagName: 'parity-status',
+            flags,
+            options: ChangeLogParityStatusSchema.options,
+        }),
+        rollbackPlan: getFlag(flags, 'rollback-plan'),
+        rollsBack: getFlag(flags, 'rolls-back'),
+        smokeNotes: getFlag(flags, 'smoke-notes'),
+        smokeResult: parseOptionalChangeLogPicklist({
+            flagName: 'smoke-result',
+            flags,
+            options: ChangeLogSmokeResultSchema.options,
+        }),
+    };
+};
 const buildRecordFromFlags = async (parsed, context) => {
     const workspaceRoot = getWorkspaceRoot(parsed.flags);
     if (hasFlag(parsed.flags, 'from-stdin')) {
@@ -346,17 +499,41 @@ const buildRecordFromFlags = async (parsed, context) => {
         };
     }
     const { kind, record } = buildBaseRecordFromFlags(parsed, context);
-    const patchInput = await applyPatchInputToRecord({
-        kind,
-        parsed,
-        record,
-        workspaceRoot,
-    });
-    return {
-        cleanupTempDir: patchInput.cleanupTempDir,
-        record: patchInput.record ?? record,
-        workspaceRoot,
-    };
+    let diffInput;
+    try {
+        diffInput = await resolveDiffInput({
+            flags: parsed.flags,
+            kind,
+            workspaceRoot,
+        });
+        if (kind === 'change-log') {
+            return {
+                cleanupTempDir: diffInput.cleanupTempDir,
+                record: await applyChangeLogFlagsToRecord({
+                    flags: parsed.flags,
+                    patchInput: diffInput,
+                    record,
+                }),
+                workspaceRoot,
+            };
+        }
+        const patchInput = await applyPatchInputToRecord({
+            kind,
+            patchInput: diffInput,
+            record,
+        });
+        return {
+            cleanupTempDir: patchInput.cleanupTempDir,
+            record: patchInput.record ?? record,
+            workspaceRoot,
+        };
+    }
+    catch (error) {
+        if (diffInput?.cleanupTempDir) {
+            await rm(diffInput.cleanupTempDir, { force: true, recursive: true });
+        }
+        throw error;
+    }
 };
 const buildNoteRecord = async (parsed, context) => {
     const [subkind] = parsed.positionals;
@@ -462,15 +639,12 @@ const runTailCli = async (parsed, context) => runListCli({
 }, context);
 const runRenderCli = async (parsed, context) => {
     const target = parseRenderTarget(parsed.flags);
-    const wantsFresh = hasFlag(parsed.flags, 'fresh') || hasFlag(parsed.flags, 'json');
-    if (wantsFresh && target !== 'analytics-summary') {
-        throw new CliUsageError('--fresh and --json are only supported for render --to=analytics-summary.');
-    }
     const ledger = await openLedger(getWorkspaceRoot(parsed.flags));
     const content = await ledger.render({
-        fresh: wantsFresh,
+        limit: parseLimit(parsed.flags),
         out: getFlag(parsed.flags, 'out'),
         phase: parseOptionalPhase(parsed.flags),
+        since: parseSince(parsed.flags),
         to: target,
     });
     if (!getFlag(parsed.flags, 'out')) {
@@ -501,10 +675,11 @@ const formatCliError = (error) => {
     if (error instanceof CliUsageError) {
         return error.message;
     }
-    if (error instanceof ZodError) {
+    if (v.isValiError(error)) {
         return error.issues
             .map((issue) => {
-            const pathLabel = issue.path.length > 0 ? issue.path.join('.') : 'input';
+            const pathSegments = issue.path?.map((segment) => String(segment.key)) ?? [];
+            const pathLabel = pathSegments.length > 0 ? pathSegments.join('.') : 'input';
             return `${pathLabel}: ${issue.message}`;
         })
             .join('\n');
@@ -557,6 +732,6 @@ if (isDirectExecution()) {
         process.exit(code);
     }, (error) => {
         process.stderr.write(`${formatCliError(error)}\n`);
-        process.exit(error instanceof CliUsageError || error instanceof ZodError ? 1 : 2);
+        process.exit(error instanceof CliUsageError || v.isValiError(error) ? 1 : 2);
     });
 }

package/dist/doctor.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"doctor.d.ts","sourceRoot":"","sources":["../src/doctor.ts"],"names":[],"mappings":"AAMA,OAAO,EAAmB,KAAK,mBAAmB,EAAE,MAAM,eAAe,CAAC;AAsL1E,eAAO,MAAM,eAAe,GACxB,eAAe,MAAM,EACrB,UAAS;IAAE,QAAQ,CAAC,WAAW,CAAC,EAAE,OAAO,CAAC;IAAC,QAAQ,CAAC,KAAK,CAAC,EAAE,mBAAmB,CAAA;CAAO;;;EAyCzF,CAAC"}
+{"version":3,"file":"doctor.d.ts","sourceRoot":"","sources":["../src/doctor.ts"],"names":[],"mappings":"AAMA,OAAO,EAAmB,KAAK,mBAAmB,EAAE,MAAM,eAAe,CAAC;AA8V1E,eAAO,MAAM,eAAe,GACxB,eAAe,MAAM,EACrB,UAAS;IAAE,QAAQ,CAAC,WAAW,CAAC,EAAE,OAAO,CAAC;IAAC,QAAQ,CAAC,KAAK,CAAC,EAAE,mBAAmB,CAAA;CAAO;;;EAyCzF,CAAC"}

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,
                 entry: resolvedEntry.entry,
+                entriesByIdempotencyKey,
                 issues,
                 latestByPhase,
                 manifest,
+                openIssueEntries,
                 previousByPhase,
+                resolvedLedgerIds,
                 unseenManifestEntryIds,
             });
         }
     }
+    checkChangeLogWarnings({
+        checkpointEntries,
+        entriesByIdempotencyKey,
+        issues,
+        nowMs,
+        openIssueEntries,
+        resolvedLedgerIds,
+    });
     return {
         blobChecks,
         entryCount,

package/dist/handle.d.ts

@@ -3,6 +3,7 @@ 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' | 'migration-log-md' | 'retro' | 'timeline-html' | 'workspace-narrative-md';
 export type LedgerHandle = {
     readonly archive: (outPath: string) => Promise<{
         integrityHash: string;
@@ -17,10 +18,11 @@ export type LedgerHandle = {
         id: string;
     }>;
     readonly render: (options: {
-        fresh?: boolean;
         out?: string;
+        limit?: number;
         phase?: LedgerPhase;
-        to: 'analytics-summary' | 'dependency-graph' | 'jsonl' | 'retro' | 'timeline-html';
+        since?: string;
+        to: RenderTarget;
     }) => Promise<string>;
     readonly show: (entryId: string) => Promise<LedgerEntry | null>;
 };

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;AAQtD,OAAO,KAAK,EAAE,WAAW,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAwDlE,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;QACvB,KAAK,CAAC,EAAE,OAAO,CAAC;QAChB,GAAG,CAAC,EAAE,MAAM,CAAC;QACb,KAAK,CAAC,EAAE,WAAW,CAAC;QACpB,EAAE,EAAE,mBAAmB,GAAG,kBAAkB,GAAG,OAAO,GAAG,OAAO,GAAG,eAAe,CAAC;KACtF,KAAK,OAAO,CAAC,MAAM,CAAC,CAAC;IACtB,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,CAsC5E,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,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAGlE,MAAM,MAAM,YAAY,GAClB,kBAAkB,GAClB,OAAO,GACP,kBAAkB,GAClB,OAAO,GACP,eAAe,GACf,wBAAwB,CAAC;AAkD/B,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;QACvB,GAAG,CAAC,EAAE,MAAM,CAAC;QACb,KAAK,CAAC,EAAE,MAAM,CAAC;QACf,KAAK,CAAC,EAAE,WAAW,CAAC;QACpB,KAAK,CAAC,EAAE,MAAM,CAAC;QACf,EAAE,EAAE,YAAY,CAAC;KACpB,KAAK,OAAO,CAAC,MAAM,CAAC,CAAC;IACtB,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,CAyC5E,CAAC"}