ushman-ledger 1.2.1 → 1.3.0

package/dist/doctor.js

@@ -4,72 +4,232 @@ import { resolveBlobPath } from "./blobs.js";
 import { sha256File } from "./json.js";
 import { getOrderedEntryLocations, readManifestEntryBatch } from "./list.js";
 import { isReadIndexCurrent, readReadIndex } from "./read-index.js";
-import { loadLedgerState } from "./recovery.js";
+import { listPendingCommitQuarantines, 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) => {
+const HOUR_MS = 60 * 60 * 1_000;
+const DAY_MS = 24 * HOUR_MS;
+const MINUTE_MS = 60 * 1_000;
+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',
+    'pending-commit-quarantined',
+    '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 formatAgeThreshold = (ageMs) => {
+    if (ageMs >= DAY_MS && ageMs % DAY_MS === 0) {
+        const days = ageMs / DAY_MS;
+        return `${days} day${days === 1 ? '' : 's'}`;
+    }
+    if (ageMs >= HOUR_MS && ageMs % HOUR_MS === 0) {
+        return `${ageMs / HOUR_MS}h`;
+    }
+    if (ageMs >= MINUTE_MS && ageMs % MINUTE_MS === 0) {
+        return `${ageMs / MINUTE_MS}m`;
+    }
+    return `${ageMs}ms`;
+};
+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 checkPendingCommitQuarantines = async (workspaceRoot) => {
+    const quarantines = await listPendingCommitQuarantines(workspaceRoot);
+    return quarantines.map((quarantine) => createFinding({
+        code: 'pending-commit-quarantined',
+        message: `Pending commit journal ${quarantine.originalFileName} is quarantined: ${quarantine.reason}`,
+        metadata: {
+            commitPath: quarantine.commitPath,
+            metadataPath: quarantine.metadataPath,
+            originalFileName: quarantine.originalFileName,
+            quarantinedAt: quarantine.quarantinedAt,
+        },
+        remediation: 'Inspect the quarantined journal under .lab/ledger/pending-quarantine/. Restore it to .lab/ledger/pending/ only if its entry, sequence, and manifest base are known to be safe; otherwise keep or remove it after recording an operator decision.',
+    }));
 };
-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,35 +247,64 @@ 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, checkpointMaxAgeMs, entriesByIdempotencyKey, findings, nowMs, openIssueMaxAgeMs, openIssueEntries, resolvedLedgerIds, }) => {
+    const checkpointMaxAgeLabel = formatAgeThreshold(checkpointMaxAgeMs);
     for (const checkpointEntry of checkpointEntries) {
         const ageMs = nowMs - Date.parse(checkpointEntry.ts);
-        if (ageMs <= CHECKPOINT_MAX_AGE_MS) {
+        if (ageMs <= checkpointMaxAgeMs) {
             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.`);
+            pushFinding(findings, createFinding({
+                code: 'pre-change-checkpoint-stale',
+                message: `Pre-change checkpoint ${checkpointEntry.id} is older than ${checkpointMaxAgeLabel} 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.',
+            }));
         }
     }
+    const openIssueMaxAgeLabel = formatAgeThreshold(openIssueMaxAgeMs);
     for (const openIssueEntry of openIssueEntries) {
         const ageMs = nowMs - Date.parse(openIssueEntry.ts);
-        if (ageMs <= OPEN_ISSUE_MAX_AGE_MS || resolvedLedgerIds.has(openIssueEntry.id)) {
+        if (ageMs <= openIssueMaxAgeMs || 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 ${openIssueMaxAgeLabel} 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 +312,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 +346,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 +362,7 @@ const inspectDoctorEntry = ({ blobChecks, checkpointEntries, entry, entriesByIde
     inspectNarrativeEntry({
         checkpointEntries,
         entry,
-        issues,
+        findings,
         openIssueEntries,
     });
     inspectPatchEntry({
@@ -172,7 +371,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 +382,15 @@ const collectDoctorState = async (workspaceRoot, manifest, readIndex) => {
     const resolvedLedgerIds = new Set();
     let entryCount = 0;
     const nowMs = Date.now();
+    const { doctorCheckpointMaxAgeMs, doctorOpenIssueMaxAgeMs, 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) {
@@ -202,7 +403,7 @@ const collectDoctorState = async (workspaceRoot, manifest, readIndex) => {
                 checkpointEntries,
                 entriesByIdempotencyKey,
                 entry: resolvedEntry.entry,
-                issues,
+                findings,
                 latestByPhase,
                 manifest,
                 openIssueEntries,
@@ -214,16 +415,18 @@ const collectDoctorState = async (workspaceRoot, manifest, readIndex) => {
     }
     checkChangeLogWarnings({
         checkpointEntries,
+        checkpointMaxAgeMs: doctorCheckpointMaxAgeMs,
         entriesByIdempotencyKey,
-        issues,
+        findings,
         nowMs,
+        openIssueMaxAgeMs: doctorOpenIssueMaxAgeMs,
         openIssueEntries,
         resolvedLedgerIds,
     });
     return {
         blobChecks,
         entryCount,
-        issues,
+        findings,
         latestByPhase,
         unseenManifestEntryIds,
     };
@@ -256,17 +459,15 @@ 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 checkPendingCommitQuarantines(workspaceRoot)));
+    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.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,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"}
+{"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;AAQ9E,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;AA+KF,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,CA6E5E,CAAC"}

package/dist/handle.js

@@ -13,7 +13,7 @@ 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 { createAtomicTextFileWriter, resolveLedgerPaths, writeAtomicTextFile } from "./storage/filesystem.js";
+import { createAtomicTextFileWriter, createExternalTempFileRegistrar, resolveLedgerPaths, writeAtomicTextFile, } from "./storage/filesystem.js";
 const createEntryIteratorFactory = ({ filter, state, workspaceRoot, }) => {
     return (entryOptions = {}) => iterateEntriesFromManifest(workspaceRoot, state.manifest, state.readIndex, {
         kind: entryOptions.kind,
@@ -29,6 +29,22 @@ const collectRenderedText = async (emit) => {
     });
     return chunks.join('');
 };
+const attachCleanupCause = (error, cleanupError) => {
+    if (error instanceof Error) {
+        const errorWithCause = error;
+        if (errorWithCause.cause === undefined) {
+            Object.defineProperty(errorWithCause, 'cause', {
+                configurable: true,
+                enumerable: false,
+                value: cleanupError,
+                writable: true,
+            });
+        }
+        return error;
+    }
+    return new Error(String(error), { cause: cleanupError });
+};
+const getExternalTempRegistrar = (workspaceRoot, outPath) => outPath ? createExternalTempFileRegistrar(workspaceRoot) : undefined;
 const emitRenderedTarget = async ({ createEntries, manifest, target, write, workspaceName, }) => {
     switch (target) {
         case 'dependency-graph':
@@ -82,6 +98,40 @@ const resolveRenderOutputPath = (workspaceRoot, target) => {
             return null;
     }
 };
+const runRenderToWriters = async ({ atomicWriter, createEntries, manifest, target, workspaceName, writer, }) => {
+    let hasWrittenContent = false;
+    let endsWithNewline = false;
+    try {
+        await emitRenderedTarget({
+            createEntries,
+            manifest,
+            target,
+            workspaceName,
+            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) {
+        try {
+            await atomicWriter?.abort();
+        }
+        catch (cleanupError) {
+            throw attachCleanupCause(error, cleanupError);
+        }
+        throw error;
+    }
+};
 /** Open a workspace ledger handle after reconciling any pending crash-recovery state. */
 export const openLedger = async (workspaceRoot) => {
     await readLabManifestMin(workspaceRoot);
@@ -115,7 +165,9 @@ export const openLedger = async (workspaceRoot) => {
             }));
             const outputPath = options.out ?? resolveRenderOutputPath(workspaceRoot, options.to);
             if (outputPath) {
-                await writeAtomicTextFile(outputPath, `${content}${content.endsWith('\n') ? '' : '\n'}`);
+                await writeAtomicTextFile(outputPath, `${content}${content.endsWith('\n') ? '' : '\n'}`, {
+                    registerTempFile: getExternalTempRegistrar(workspaceRoot, options.out),
+                });
             }
             return content;
         },
@@ -127,38 +179,23 @@ export const openLedger = async (workspaceRoot) => {
                 workspaceRoot,
             });
             const outputPath = options.out ?? resolveRenderOutputPath(workspaceRoot, options.to);
-            const atomicWriter = outputPath ? await createAtomicTextFileWriter(outputPath) : null;
+            const atomicWriter = outputPath
+                ? await createAtomicTextFileWriter(outputPath, {
+                    registerTempFile: getExternalTempRegistrar(workspaceRoot, options.out),
+                })
+                : 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;
-            }
+            await runRenderToWriters({
+                atomicWriter,
+                createEntries,
+                manifest: state.manifest,
+                target: options.to,
+                workspaceName: path.basename(workspaceRoot),
+                writer,
+            });
         },
         show: async (entryId) => {
             const { manifest } = await loadLedgerState(workspaceRoot);

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"}

package/dist/helpers.js

@@ -36,3 +36,26 @@ export const waitForFile = async (filePath, timeoutMs = 1_000) => {
     }
     throw new Error(`Timed out waiting for file: ${filePath}`);
 };
+export const withEnvOverrides = async (overrides, action) => {
+    const previousValues = new Map();
+    for (const [key, value] of Object.entries(overrides)) {
+        previousValues.set(key, process.env[key]);
+        if (value === undefined) {
+            delete process.env[key];
+            continue;
+        }
+        process.env[key] = value;
+    }
+    try {
+        return await action();
+    }
+    finally {
+        for (const [key, value] of previousValues.entries()) {
+            if (value === undefined) {
+                delete process.env[key];
+                continue;
+            }
+            process.env[key] = value;
+        }
+    }
+};