ushman-ledger 1.2.0 → 1.2.2

package/dist/doctor.js

@@ -5,71 +5,202 @@ import { sha256File } from "./json.js";
 import { getOrderedEntryLocations, readManifestEntryBatch } from "./list.js";
 import { isReadIndexCurrent, readReadIndex } from "./read-index.js";
 import { loadLedgerState } from "./recovery.js";
+import { getLedgerRuntimeConfig } from "./runtime-config.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) => {
+export const DOCTOR_FINDING_CODES = [
+    'blob-corrupt',
+    'blob-missing',
+    'blob-unreadable',
+    'change-log-rollback-missing-target',
+    'change-log-smoke-failure-missing-rollback-plan',
+    'manifest-entry-count-mismatch',
+    'manifest-entry-location-missing',
+    'manifest-entry-missing-on-disk',
+    'manifest-last-sequence-mismatch',
+    'manifest-per-phase-latest-mismatch',
+    'manifest-phase-mismatch',
+    'manifest-sequence-mismatch',
+    'open-issue-stale',
+    'phase-prev-entry-mismatch',
+    'pre-change-checkpoint-stale',
+    'read-failure',
+];
+const createFinding = ({ code, message, metadata, remediation, }) => ({
+    code,
+    message,
+    metadata,
+    remediation,
+});
+const buildDoctorReport = (findings) => ({
+    checkedAt: new Date().toISOString(),
+    findings: [...findings],
+    issueCount: findings.length,
+    issues: findings.map((finding) => finding.message),
+    ok: findings.length === 0,
+});
+const pushFinding = (findings, finding) => {
+    findings.push(finding);
+};
+const isMissingPathError = (error) => {
+    const code = error.code;
+    return code === 'ENOENT' || code === 'ENOTDIR';
+};
+const buildReadFailure = (error) => buildDoctorReport([
+    createFinding({
+        code: 'read-failure',
+        message: `Failed to read ledger state: ${error instanceof Error ? error.message ?? error.name : String(error)}.`,
+        remediation: 'Re-open the ledger or rerun the command first so recovery can reconcile pending state. If the error persists, repair or restore the invalid manifest/read-index JSON before archiving.',
+    }),
+]);
+const isChangeLogEntry = (entry) => entry.kind === 'change-log';
+const isOpenIssueNote = (entry) => entry.kind === 'note' && entry.subkind === 'open-issue';
+const checkPrevChain = (entry, findings, previousByPhase) => {
     const expectedPrev = previousByPhase.get(entry.phase) ?? null;
     if (entry.prevEntryId !== expectedPrev) {
-        issues.push(`Phase ${entry.phase} has broken prevEntryId chain at ${entry.id}: expected ${expectedPrev ?? 'null'}, found ${entry.prevEntryId ?? 'null'}.`);
+        pushFinding(findings, createFinding({
+            code: 'phase-prev-entry-mismatch',
+            message: `Phase ${entry.phase} has broken prevEntryId chain at ${entry.id}: expected ${expectedPrev ?? 'null'}, found ${entry.prevEntryId ?? 'null'}.`,
+            metadata: {
+                entryId: entry.id,
+                expectedPrevEntryId: expectedPrev,
+                foundPrevEntryId: entry.prevEntryId,
+                phase: entry.phase,
+            },
+            remediation: 'Restore the edited entry or repair the phase chain so prevEntryId matches append order. Use a correction entry for content fixes instead of hand-editing ledger history.',
+        }));
     }
     previousByPhase.set(entry.phase, entry.id);
 };
 const checkBlobPresence = async (workspaceRoot, blobChecks) => {
-    const results = await mapWithConcurrencyLimit(blobChecks, BLOB_HASH_CONCURRENCY, async ({ blobHash, entryId }) => {
+    const { blobHashConcurrency } = getLedgerRuntimeConfig();
+    const groupedBlobChecks = new Map();
+    for (const { blobHash, entryId } of blobChecks) {
+        const entryIds = groupedBlobChecks.get(blobHash) ?? [];
+        entryIds.push(entryId);
+        groupedBlobChecks.set(blobHash, entryIds);
+    }
+    const results = await mapWithConcurrencyLimit([...groupedBlobChecks.entries()], blobHashConcurrency, async ([blobHash, entryIds]) => {
+        const blobPath = resolveBlobPath(workspaceRoot, blobHash);
         try {
-            const blobPath = resolveBlobPath(workspaceRoot, blobHash);
             await stat(blobPath);
+        }
+        catch (error) {
+            if (!isMissingPathError(error)) {
+                throw error;
+            }
+            return entryIds.map((entryId) => createFinding({
+                code: 'blob-missing',
+                message: `Missing blob ${blobHash} for ${entryId}.`,
+                metadata: {
+                    blobSha256: blobHash,
+                    entryId,
+                },
+                remediation: 'Restore the missing blob file under .lab/ledger/blobs/ or recreate the patch entry from the original diff before archiving.',
+            }));
+        }
+        try {
             const actualHash = await sha256File(blobPath);
             if (actualHash !== blobHash) {
-                return `Blob ${blobHash} for ${entryId} is corrupted (found ${actualHash}).`;
+                return entryIds.map((entryId) => createFinding({
+                    code: 'blob-corrupt',
+                    message: `Blob ${blobHash} for ${entryId} is corrupted (found ${actualHash}).`,
+                    metadata: {
+                        actualSha256: actualHash,
+                        blobSha256: blobHash,
+                        entryId,
+                    },
+                    remediation: 'Restore the original blob content under .lab/ledger/blobs/ or recreate the patch entry from the original diff before archiving.',
+                }));
             }
-            return null;
+            return [];
         }
-        catch {
-            return `Missing blob ${blobHash} for ${entryId}.`;
+        catch (error) {
+            return entryIds.map((entryId) => createFinding({
+                code: 'blob-unreadable',
+                message: `Blob ${blobHash} for ${entryId} could not be read: ${error instanceof Error ? error.message : String(error)}.`,
+                metadata: {
+                    blobSha256: blobHash,
+                    entryId,
+                },
+                remediation: 'Fix the filesystem permission or read error first, then rerun doctor so blob integrity can be verified before archiving.',
+            }));
         }
     });
-    return results.filter((issue) => issue !== null);
+    return results.flat();
 };
-const checkManifestCounts = (manifest, entryCount) => {
-    const issues = [];
+const checkManifestCounts = (findings, manifest, entryCount) => {
     if (manifest.entryCount !== entryCount) {
-        issues.push(`Manifest entryCount ${manifest.entryCount} does not match disk entries ${entryCount}.`);
+        pushFinding(findings, createFinding({
+            code: 'manifest-entry-count-mismatch',
+            message: `Manifest entryCount ${manifest.entryCount} does not match disk entries ${entryCount}.`,
+            metadata: {
+                diskEntryCount: entryCount,
+                manifestEntryCount: manifest.entryCount,
+            },
+            remediation: 'Rerun the command or reopen the ledger so recovery can replay pending commits. If the mismatch persists, compare manifest.json with the on-disk phase entries and repair the missing location or file.',
+        }));
     }
     if (manifest.lastSequence !== entryCount) {
-        issues.push(`Manifest lastSequence ${manifest.lastSequence} does not match disk entries ${entryCount}.`);
+        pushFinding(findings, createFinding({
+            code: 'manifest-last-sequence-mismatch',
+            message: `Manifest lastSequence ${manifest.lastSequence} does not match disk entries ${entryCount}.`,
+            metadata: {
+                diskEntryCount: entryCount,
+                manifestLastSequence: manifest.lastSequence,
+            },
+            remediation: 'Repair manifest.json so lastSequence matches the highest durable append sequence after recovery completes.',
+        }));
     }
-    return issues;
 };
-const finalizeManifestChecks = ({ entryCount, issues, latestByPhase, manifest, unseenManifestEntryIds, }) => {
-    issues.push(...checkManifestCounts(manifest, entryCount));
+const finalizeManifestChecks = ({ entryCount, findings, latestByPhase, manifest, unseenManifestEntryIds, }) => {
+    checkManifestCounts(findings, manifest, entryCount);
     for (const entryId of unseenManifestEntryIds) {
-        issues.push(`Manifest entry location points to missing disk entry ${entryId}.`);
+        pushFinding(findings, createFinding({
+            code: 'manifest-entry-missing-on-disk',
+            message: `Manifest entry location points to missing disk entry ${entryId}.`,
+            metadata: { entryId },
+            remediation: 'Restore the missing entry file or repair manifest.entryLocations so every referenced entry id exists on disk before archiving.',
+        }));
     }
-    for (const [phase, latest] of latestByPhase.entries()) {
-        if (manifest.perPhaseLatest[phase] !== latest.entryId) {
-            issues.push(`Manifest perPhaseLatest mismatch for ${phase}: expected ${latest.entryId}, found ${manifest.perPhaseLatest[phase] ?? 'missing'}.`);
+    const phasesToCheck = new Set([...Object.keys(manifest.perPhaseLatest), ...latestByPhase.keys()]);
+    for (const phase of phasesToCheck) {
+        const latest = latestByPhase.get(phase);
+        const expectedEntryId = latest?.entryId ?? null;
+        const foundEntryId = manifest.perPhaseLatest[phase] ?? null;
+        if (foundEntryId !== expectedEntryId) {
+            pushFinding(findings, createFinding({
+                code: 'manifest-per-phase-latest-mismatch',
+                message: `Manifest perPhaseLatest mismatch for ${phase}: expected ${expectedEntryId ?? 'missing'}, found ${foundEntryId ?? 'missing'}.`,
+                metadata: {
+                    expectedEntryId,
+                    foundEntryId,
+                    phase,
+                },
+                remediation: 'Repair perPhaseLatest so each phase points at the newest durable entry in that phase.',
+            }));
         }
     }
 };
-const checkManifestSequenceOrder = (entryLocations, issues) => {
+const checkManifestSequenceOrder = (entryLocations, findings) => {
     for (let index = 0; index < entryLocations.length; index += 1) {
         const [entryId, location] = entryLocations[index];
         const expectedSequence = index + 1;
         if (location.sequence !== expectedSequence) {
-            issues.push(`Manifest sequence mismatch for ${entryId}: expected ${expectedSequence}, found ${location.sequence}.`);
+            pushFinding(findings, createFinding({
+                code: 'manifest-sequence-mismatch',
+                message: `Manifest sequence mismatch for ${entryId}: expected ${expectedSequence}, found ${location.sequence}.`,
+                metadata: {
+                    entryId,
+                    expectedSequence,
+                    foundSequence: location.sequence,
+                },
+                remediation: 'Repair manifest.entryLocations so sequences remain contiguous and match append order.',
+            }));
         }
     }
 };
-const buildReadFailure = (error) => ({
-    issues: [`Failed to read ledger state: ${error instanceof Error ? (error.message ?? error.name) : String(error)}.`],
-    ok: false,
-});
-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);
@@ -87,7 +218,7 @@ const trackIdempotencyEntry = (entry, entriesByIdempotencyKey) => {
     existingEntries.push({ id: entry.id, ts: entry.ts });
     entriesByIdempotencyKey.set(idempotencyKey, existingEntries);
 };
-const checkChangeLogWarnings = ({ checkpointEntries, entriesByIdempotencyKey, issues, nowMs, openIssueEntries, resolvedLedgerIds, }) => {
+const checkChangeLogWarnings = ({ checkpointEntries, entriesByIdempotencyKey, findings, nowMs, openIssueEntries, resolvedLedgerIds, }) => {
     for (const checkpointEntry of checkpointEntries) {
         const ageMs = nowMs - Date.parse(checkpointEntry.ts);
         if (ageMs <= CHECKPOINT_MAX_AGE_MS) {
@@ -97,7 +228,15 @@ const checkChangeLogWarnings = ({ checkpointEntries, entriesByIdempotencyKey, is
         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.`);
+            pushFinding(findings, createFinding({
+                code: 'pre-change-checkpoint-stale',
+                message: `Pre-change checkpoint ${checkpointEntry.id} is older than 24h and has no follow-up entry with matching idempotencyKey.`,
+                metadata: {
+                    entryId: checkpointEntry.id,
+                    idempotencyKey: idempotencyKey ?? null,
+                },
+                remediation: 'Append a follow-up change-log entry with the same idempotency key, or close the stale checkpoint with a correction entry explaining the abandoned work.',
+            }));
         }
     }
     for (const openIssueEntry of openIssueEntries) {
@@ -105,17 +244,36 @@ const checkChangeLogWarnings = ({ checkpointEntries, entriesByIdempotencyKey, is
         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.`);
+        pushFinding(findings, createFinding({
+            code: 'open-issue-stale',
+            message: `Open issue note ${openIssueEntry.id} is older than 30 days and has no resolution link.`,
+            metadata: { entryId: openIssueEntry.id },
+            remediation: 'Append a correction or superseding note that links back to the open issue once the follow-up is complete.',
+        }));
     }
 };
-const inspectManifestLocation = ({ entry, issues, latestByPhase, manifest, }) => {
+const inspectManifestLocation = ({ entry, findings, latestByPhase, manifest, }) => {
     const manifestLocation = manifest.entryLocations[entry.id];
     if (!manifestLocation) {
-        issues.push(`Manifest is missing entry location for ${entry.id}.`);
+        pushFinding(findings, createFinding({
+            code: 'manifest-entry-location-missing',
+            message: `Manifest is missing entry location for ${entry.id}.`,
+            metadata: { entryId: entry.id },
+            remediation: 'Repair manifest.entryLocations so every durable entry has a phase/sequence location before archiving.',
+        }));
         return null;
     }
     if (manifestLocation.phase !== entry.phase) {
-        issues.push(`Manifest phase mismatch for ${entry.id}: expected ${entry.phase}, found ${manifestLocation.phase}.`);
+        pushFinding(findings, createFinding({
+            code: 'manifest-phase-mismatch',
+            message: `Manifest phase mismatch for ${entry.id}: expected ${entry.phase}, found ${manifestLocation.phase}.`,
+            metadata: {
+                entryId: entry.id,
+                expectedPhase: entry.phase,
+                foundPhase: manifestLocation.phase,
+            },
+            remediation: 'Move the entry back to the correct phase directory or repair manifest.entryLocations so the recorded phase matches the stored entry.',
+        }));
     }
     const currentLatest = latestByPhase.get(entry.phase);
     if (!currentLatest || manifestLocation.sequence > currentLatest.sequence) {
@@ -123,16 +281,26 @@ const inspectManifestLocation = ({ entry, issues, latestByPhase, manifest, }) =>
     }
     return manifestLocation;
 };
-const inspectNarrativeEntry = ({ checkpointEntries, entry, issues, openIssueEntries, }) => {
+const inspectNarrativeEntry = ({ checkpointEntries, entry, findings, 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.`);
+            pushFinding(findings, createFinding({
+                code: 'change-log-smoke-failure-missing-rollback-plan',
+                message: `Change-log entry ${entry.id} has smokeResult=fail but no rollbackPlan.`,
+                metadata: { entryId: entry.id },
+                remediation: 'Append a correction or follow-up change-log entry documenting the rollback plan before treating the failure as closed.',
+            }));
         }
         if (entry.subkind === 'rollback' && !entry.rollsBack) {
-            issues.push(`Change-log rollback entry ${entry.id} is missing rollsBack.`);
+            pushFinding(findings, createFinding({
+                code: 'change-log-rollback-missing-target',
+                message: `Change-log rollback entry ${entry.id} is missing rollsBack.`,
+                metadata: { entryId: entry.id },
+                remediation: 'Append a correction or replacement rollback entry with rollsBack pointing at the reverted ledger entry id.',
+            }));
         }
     }
     if (isOpenIssueNote(entry)) {
@@ -147,14 +315,14 @@ const inspectPatchEntry = ({ blobChecks, entry, }) => {
         blobChecks.push({ blobHash, entryId: entry.id });
     }
 };
-const inspectDoctorEntry = ({ blobChecks, checkpointEntries, entry, entriesByIdempotencyKey, issues, latestByPhase, manifest, openIssueEntries, previousByPhase, resolvedLedgerIds, unseenManifestEntryIds, }) => {
+const inspectDoctorEntry = ({ blobChecks, checkpointEntries, entriesByIdempotencyKey, entry, findings, latestByPhase, manifest, openIssueEntries, previousByPhase, resolvedLedgerIds, unseenManifestEntryIds, }) => {
     unseenManifestEntryIds.delete(entry.id);
-    checkPrevChain(entry, previousByPhase, issues);
+    checkPrevChain(entry, findings, previousByPhase);
     trackIdempotencyEntry(entry, entriesByIdempotencyKey);
     trackResolutionLinks(entry, resolvedLedgerIds);
     if (!inspectManifestLocation({
         entry,
-        issues,
+        findings,
         latestByPhase,
         manifest,
     })) {
@@ -163,7 +331,7 @@ const inspectDoctorEntry = ({ blobChecks, checkpointEntries, entry, entriesByIde
     inspectNarrativeEntry({
         checkpointEntries,
         entry,
-        issues,
+        findings,
         openIssueEntries,
     });
     inspectPatchEntry({
@@ -172,7 +340,7 @@ const inspectDoctorEntry = ({ blobChecks, checkpointEntries, entry, entriesByIde
     });
 };
 const collectDoctorState = async (workspaceRoot, manifest, readIndex) => {
-    const issues = [];
+    const findings = [];
     const previousByPhase = new Map();
     const latestByPhase = new Map();
     const unseenManifestEntryIds = new Set(Object.keys(manifest.entryLocations));
@@ -183,13 +351,15 @@ const collectDoctorState = async (workspaceRoot, manifest, readIndex) => {
     const resolvedLedgerIds = new Set();
     let entryCount = 0;
     const nowMs = Date.now();
+    const { scanBatchSize, scanConcurrency } = getLedgerRuntimeConfig();
     const orderedEntries = getOrderedEntryLocations(manifest, readIndex, {});
-    checkManifestSequenceOrder(orderedEntries, issues);
-    for (let index = 0; index < orderedEntries.length; index += ENTRY_READ_BATCH_SIZE) {
-        const batch = orderedEntries.slice(index, index + ENTRY_READ_BATCH_SIZE);
+    checkManifestSequenceOrder(orderedEntries, findings);
+    for (let index = 0; index < orderedEntries.length; index += scanBatchSize) {
+        const batch = orderedEntries.slice(index, index + scanBatchSize);
         const resolvedEntries = await readManifestEntryBatch({
             allowMissing: true,
             entryLocations: batch,
+            entryReadConcurrency: scanConcurrency,
             workspaceRoot,
         });
         for (const resolvedEntry of resolvedEntries) {
@@ -200,9 +370,9 @@ const collectDoctorState = async (workspaceRoot, manifest, readIndex) => {
             inspectDoctorEntry({
                 blobChecks,
                 checkpointEntries,
-                entry: resolvedEntry.entry,
                 entriesByIdempotencyKey,
-                issues,
+                entry: resolvedEntry.entry,
+                findings,
                 latestByPhase,
                 manifest,
                 openIssueEntries,
@@ -215,7 +385,7 @@ const collectDoctorState = async (workspaceRoot, manifest, readIndex) => {
     checkChangeLogWarnings({
         checkpointEntries,
         entriesByIdempotencyKey,
-        issues,
+        findings,
         nowMs,
         openIssueEntries,
         resolvedLedgerIds,
@@ -223,7 +393,7 @@ const collectDoctorState = async (workspaceRoot, manifest, readIndex) => {
     return {
         blobChecks,
         entryCount,
-        issues,
+        findings,
         latestByPhase,
         unseenManifestEntryIds,
     };
@@ -256,17 +426,14 @@ export const runLedgerDoctor = async (workspaceRoot, options = {}) => {
     catch (error) {
         return buildReadFailure(error);
     }
-    const { blobChecks, entryCount, issues, latestByPhase, unseenManifestEntryIds } = doctorState;
-    issues.push(...(await checkBlobPresence(workspaceRoot, blobChecks)));
+    const { blobChecks, entryCount, findings, latestByPhase, unseenManifestEntryIds } = doctorState;
+    findings.push(...(await checkBlobPresence(workspaceRoot, blobChecks)));
     finalizeManifestChecks({
         entryCount,
-        issues,
+        findings,
         latestByPhase,
         manifest: preparedState.manifest,
         unseenManifestEntryIds,
     });
-    return {
-        issues,
-        ok: issues.length === 0,
-    };
+    return buildDoctorReport(findings);
 };

package/dist/handle.d.ts

@@ -4,6 +4,30 @@ 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';
+/**
+ * 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,14 +41,10 @@ export type LedgerHandle = {
     readonly record: (entry: unknown) => Promise<{
         id: string;
     }>;
-    readonly render: (options: {
-        out?: string;
-        limit?: number;
-        phase?: LedgerPhase;
-        since?: string;
-        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":"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"}
+{"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

@@ -13,28 +13,58 @@ import { renderMigrationLogMarkdown } from "./render/migration-log.js";
 import { renderRetroMarkdown } from "./render/retro.js";
 import { renderTimelineHtml } from "./render/timeline-html.js";
 import { renderWorkspaceNarrativeMarkdown } from "./render/workspace-narrative.js";
-import { resolveLedgerPaths, writeAtomicTextFile } from "./storage/filesystem.js";
-const renderEntries = async ({ filter, target, workspaceRoot, }) => {
-    const { manifest, readIndex } = await loadLedgerState(workspaceRoot);
+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':
-            return renderMigrationLogMarkdown(iterateEntriesFromManifest(workspaceRoot, manifest, readIndex, filter));
+            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':
-            return renderWorkspaceNarrativeMarkdown({
-                entries: iterateEntriesFromManifest(workspaceRoot, manifest, readIndex, filter),
-                workspaceName: path.basename(workspaceRoot),
+            await renderWorkspaceNarrativeMarkdown({
+                entries: createEntries({
+                    direction: 'desc',
+                    kind: 'note',
+                }),
+                workspaceName,
+                write,
             });
+            return;
     }
 };
 const resolveRenderOutputPath = (workspaceRoot, target) => {
@@ -52,6 +82,7 @@ const resolveRenderOutputPath = (workspaceRoot, target) => {
             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);
@@ -69,21 +100,66 @@ export const openLedger = async (workspaceRoot) => {
             return { id: result.id };
         },
         render: async (options) => {
-            const content = await renderEntries({
-                filter: {
-                    limit: options.limit,
-                    phase: options.phase,
-                    since: options.since,
-                },
-                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

@@ -4,4 +4,5 @@ export declare const createWorkspaceFixture: () => Promise<{
 }>;
 export declare const ageFile: (filePath: string, ageMs?: number) => Promise<void>;
 export declare const waitForFile: (filePath: string, timeoutMs?: number) => Promise<void>;
+export declare const withEnvOverrides: <Value>(overrides: Record<string, string | undefined>, action: () => Promise<Value>) => Promise<Value>;
 //# sourceMappingURL=helpers.d.ts.map

package/dist/helpers.d.ts.map

@@ -1 +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"}
+{"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;AAEF,eAAO,MAAM,gBAAgB,GAAU,KAAK,EACxC,WAAW,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,EAC7C,QAAQ,MAAM,OAAO,CAAC,KAAK,CAAC,mBAuB/B,CAAC"}