ushman-ledger 1.2.2 → 1.3.1

package/dist/recovery.js

@@ -1,13 +1,17 @@
-import { readdir, readFile, rm, stat } from 'node:fs/promises';
+import { randomUUID } from 'node:crypto';
+import { readdir, readFile, rename, rm, stat } from 'node:fs/promises';
 import path from 'node:path';
 import * as v from 'valibot';
+import { mapWithConcurrencyLimit } from "./async.js";
 import { reconcilePendingArchivesUnderLock } from "./archive-journal.js";
 import { getNextManifestSequence, updateManifestForEntry } from "./manifest-update.js";
 import { ensureReadIndexUnderLock } from "./read-index.js";
+import { getLedgerRuntimeConfig } from "./runtime-config.js";
 import { LedgerEntrySchema } from "./schema/entry.js";
 import { cleanupStaleTempFiles, ensureLedgerDirectories, readManifest, resolveLedgerPaths, saveManifest, writeAtomicJsonFile, writeEntryFile, } from "./storage/filesystem.js";
 import { acquireLock } from "./storage/lock.js";
 const PendingCommitSchemaVersion = 'ushman-ledger-pending-commit/v1';
+const PendingCommitQuarantineSchemaVersion = 'ushman-ledger-pending-commit-quarantine/v1';
 // Pending commits capture the intended sequence and logical hash before the
 // entry file and manifest update diverge, so recovery can replay safely.
 const PendingCommitSchema = v.object({
@@ -18,6 +22,12 @@ const PendingCommitSchema = v.object({
     schemaVersion: v.literal(PendingCommitSchemaVersion),
     sequence: v.pipe(v.number(), v.integer(), v.minValue(1)),
 });
+const PendingCommitQuarantineMetadataSchema = v.object({
+    originalFileName: v.pipe(v.string(), v.minLength(1)),
+    quarantinedAt: v.pipe(v.string(), v.isoTimestamp()),
+    reason: v.pipe(v.string(), v.minLength(1)),
+    schemaVersion: v.literal(PendingCommitQuarantineSchemaVersion),
+});
 const formatSequence = (sequence) => sequence.toString().padStart(8, '0');
 const PendingCommitFileNameSchema = v.object({
     entryId: v.pipe(v.string(), v.minLength(1)),
@@ -29,10 +39,15 @@ const parsePendingCommitFileName = (name) => {
     if (!match) {
         return null;
     }
-    return v.parse(PendingCommitFileNameSchema, {
-        entryId: match[2],
-        sequence: Number.parseInt(match[1], 10),
-    });
+    try {
+        return v.parse(PendingCommitFileNameSchema, {
+            entryId: match[2],
+            sequence: Number.parseInt(match[1], 10),
+        });
+    }
+    catch {
+        return null;
+    }
 };
 const readPendingCommit = async (filePath) => {
     try {
@@ -43,32 +58,68 @@ const readPendingCommit = async (filePath) => {
         throw new Error(`Invalid pending commit at ${filePath}: ${error instanceof Error ? error.message : String(error)}`);
     }
 };
-const readPendingCommits = async (workspaceRoot) => {
+const listPendingCommitFiles = async (workspaceRoot) => {
     const paths = await ensureLedgerDirectories(workspaceRoot);
     const entries = await readdir(paths.pendingCommitsDir, { withFileTypes: true });
-    const pendingFiles = entries
-        .filter((entry) => entry.isFile())
-        .map((entry) => {
-        if (!entry.name.endsWith('.json')) {
-            return null;
+    const listing = {
+        invalidFiles: [],
+        pendingFiles: [],
+    };
+    for (const entry of entries) {
+        if (!entry.isFile() || !entry.name.endsWith('.json')) {
+            continue;
         }
+        const filePath = path.join(paths.pendingCommitsDir, entry.name);
         const parsed = parsePendingCommitFileName(entry.name);
         if (!parsed) {
-            return null;
+            listing.invalidFiles.push({
+                filePath,
+                reason: `Invalid pending commit file name: ${entry.name}`,
+            });
+            continue;
         }
-        return {
+        listing.pendingFiles.push({
             ...parsed,
-            filePath: path.join(paths.pendingCommitsDir, entry.name),
-        };
-    })
-        .filter((pendingFile) => pendingFile !== null)
-        .sort((left, right) => left.sequence === right.sequence
-        ? left.entryId.localeCompare(right.entryId)
-        : left.sequence - right.sequence);
-    return Promise.all(pendingFiles.map(async (pendingFile) => ({
-        filePath: pendingFile.filePath,
-        pending: await readPendingCommit(pendingFile.filePath),
-    })));
+            filePath,
+        });
+    }
+    listing.pendingFiles.sort((left, right) => left.sequence === right.sequence ? left.entryId.localeCompare(right.entryId) : left.sequence - right.sequence);
+    return listing;
+};
+const formatRecoveryError = (error) => (error instanceof Error ? error.message : String(error));
+const writeQuarantineMetadata = async ({ metadataPath, originalFileName, reason, }) => {
+    try {
+        await writeAtomicJsonFile(metadataPath, v.parse(PendingCommitQuarantineMetadataSchema, {
+            originalFileName,
+            quarantinedAt: new Date().toISOString(),
+            reason,
+            schemaVersion: PendingCommitQuarantineSchemaVersion,
+        }));
+    }
+    catch {
+        // The journal is already quarantined; metadata loss should not block recovery.
+    }
+};
+const quarantinePendingCommit = async ({ filePath, reason, workspaceRoot, }) => {
+    const paths = await ensureLedgerDirectories(workspaceRoot);
+    const originalFileName = path.basename(filePath);
+    const quarantineBaseName = `${path.basename(filePath, '.json')}.quarantined.${Date.now()}.${randomUUID()}`;
+    const quarantinePath = path.join(paths.pendingCommitQuarantineDir, `${quarantineBaseName}.json`);
+    const metadataPath = path.join(paths.pendingCommitQuarantineDir, `${quarantineBaseName}.meta.json`);
+    try {
+        await rename(filePath, quarantinePath);
+    }
+    catch (error) {
+        if (error.code === 'ENOENT') {
+            return;
+        }
+        throw error;
+    }
+    await writeQuarantineMetadata({
+        metadataPath,
+        originalFileName,
+        reason,
+    });
 };
 const ensurePendingCommitEntryFile = async (workspaceRoot, pending) => {
     const entryPath = path.join(resolveLedgerPaths(workspaceRoot).phaseDir(pending.entry.phase), `${pending.entry.id}.json`);
@@ -141,21 +192,82 @@ export const writePendingCommit = async ({ entry, logicalHash, manifest, workspa
 export const removePendingCommit = async (filePath) => {
     await rm(filePath, { force: true });
 };
+const readQuarantineMetadata = async (metadataPath) => {
+    try {
+        const text = await readFile(metadataPath, 'utf8');
+        return v.parse(PendingCommitQuarantineMetadataSchema, JSON.parse(text));
+    }
+    catch {
+        return null;
+    }
+};
+export const listPendingCommitQuarantines = async (workspaceRoot) => {
+    const paths = await ensureLedgerDirectories(workspaceRoot);
+    const { scanConcurrency } = getLedgerRuntimeConfig();
+    const entries = await readdir(paths.pendingCommitQuarantineDir, { withFileTypes: true });
+    const quarantinedCommitFiles = entries
+        .filter((entry) => entry.isFile() && entry.name.endsWith('.json') && !entry.name.endsWith('.meta.json'))
+        .map((entry) => entry.name)
+        .sort((left, right) => left.localeCompare(right));
+    return mapWithConcurrencyLimit(quarantinedCommitFiles, scanConcurrency, async (fileName) => {
+        const baseName = fileName.slice(0, -'.json'.length);
+        const commitPath = path.join(paths.pendingCommitQuarantineDir, fileName);
+        const metadataPath = path.join(paths.pendingCommitQuarantineDir, `${baseName}.meta.json`);
+        const metadata = await readQuarantineMetadata(metadataPath);
+        return {
+            commitPath,
+            metadataPath: metadata ? metadataPath : null,
+            originalFileName: metadata?.originalFileName ?? fileName,
+            quarantinedAt: metadata?.quarantinedAt ?? null,
+            reason: metadata?.reason ?? 'Missing or invalid pending commit quarantine metadata.',
+        };
+    });
+};
 export const reconcilePendingCommitsUnderLock = async (workspaceRoot) => {
     await cleanupStaleTempFiles(workspaceRoot);
     let manifest = await readManifest(workspaceRoot);
-    const pendingCommits = await readPendingCommits(workspaceRoot);
+    const { invalidFiles, pendingFiles } = await listPendingCommitFiles(workspaceRoot);
     const processedPendingFiles = [];
     let manifestChanged = false;
-    for (const pendingCommit of pendingCommits) {
-        const replayed = await applyPendingCommit({
-            manifest,
-            pending: pendingCommit.pending,
+    for (const invalidFile of invalidFiles) {
+        await quarantinePendingCommit({
+            filePath: invalidFile.filePath,
+            reason: invalidFile.reason,
             workspaceRoot,
         });
+    }
+    for (const pendingCommitFile of pendingFiles) {
+        let pending;
+        try {
+            pending = await readPendingCommit(pendingCommitFile.filePath);
+        }
+        catch (error) {
+            await quarantinePendingCommit({
+                filePath: pendingCommitFile.filePath,
+                reason: formatRecoveryError(error),
+                workspaceRoot,
+            });
+            continue;
+        }
+        let replayed;
+        try {
+            replayed = await applyPendingCommit({
+                manifest,
+                pending,
+                workspaceRoot,
+            });
+        }
+        catch (error) {
+            await quarantinePendingCommit({
+                filePath: pendingCommitFile.filePath,
+                reason: formatRecoveryError(error),
+                workspaceRoot,
+            });
+            continue;
+        }
         manifest = replayed.manifest;
         manifestChanged = manifestChanged || replayed.didChangeManifest;
-        processedPendingFiles.push(pendingCommit.filePath);
+        processedPendingFiles.push(pendingCommitFile.filePath);
     }
     if (manifestChanged) {
         await saveManifest(workspaceRoot, manifest);

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

@@ -1 +1 @@
-{"version":3,"file":"retro.d.ts","sourceRoot":"","sources":["../../src/render/retro.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AA4HtD,eAAO,MAAM,mBAAmB,GAAU,wBAGvC;IACC,QAAQ,CAAC,OAAO,EAAE,aAAa,CAAC,WAAW,CAAC,CAAC;IAC7C,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAC;CAC9B,KAAG,OAAO,CAAC,MAAM,CAgDjB,CAAC"}
+{"version":3,"file":"retro.d.ts","sourceRoot":"","sources":["../../src/render/retro.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AA+HtD,eAAO,MAAM,mBAAmB,GAAU,wBAGvC;IACC,QAAQ,CAAC,OAAO,EAAE,aAAa,CAAC,WAAW,CAAC,CAAC;IAC7C,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAC;CAC9B,KAAG,OAAO,CAAC,MAAM,CAgDjB,CAAC"}

package/dist/render/retro.js

@@ -14,7 +14,10 @@ const createRetroBuckets = () => ({
 });
 const isProblemEntry = (entry) => (entry.kind === 'note' && entry.subkind === 'regression') ||
     (entry.kind === 'runtime-event' && entry.level === 'error');
-const isToolEntry = (entry) => entry.kind === 'tool-invocation' || entry.kind === 'agent-patch' || entry.kind === 'operator-patch';
+const isToolEntry = (entry) => entry.kind === 'tool-invocation' ||
+    entry.kind === 'stage-write' ||
+    entry.kind === 'agent-patch' ||
+    entry.kind === 'operator-patch';
 const isToolingEntry = (entry) => (entry.kind === 'note' && entry.subkind === 'automation') ||
     (entry.kind === 'note' && entry.subkind === 'tooling-gap');
 const isRetroNote = (entry) => entry.kind === 'note' && entry.subkind === 'retro';

package/dist/runtime-config.d.ts

@@ -1,6 +1,8 @@
 export type LedgerRuntimeConfig = {
     readonly blobHashConcurrency: number;
     readonly coverageFileStatConcurrency: number;
+    readonly doctorCheckpointMaxAgeMs: number;
+    readonly doctorOpenIssueMaxAgeMs: number;
     readonly maxPatchBytes: number;
     readonly readIndexRebuildBatchSize: number;
     readonly readIndexRebuildConcurrency: number;

package/dist/runtime-config.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"runtime-config.d.ts","sourceRoot":"","sources":["../src/runtime-config.ts"],"names":[],"mappings":"AAgCA,MAAM,MAAM,mBAAmB,GAAG;IAC9B,QAAQ,CAAC,mBAAmB,EAAE,MAAM,CAAC;IACrC,QAAQ,CAAC,2BAA2B,EAAE,MAAM,CAAC;IAC7C,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAC/B,QAAQ,CAAC,yBAAyB,EAAE,MAAM,CAAC;IAC3C,QAAQ,CAAC,2BAA2B,EAAE,MAAM,CAAC;IAC7C,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAC/B,QAAQ,CAAC,eAAe,EAAE,MAAM,CAAC;CACpC,CAAC;AAuDF,eAAO,MAAM,2BAA2B,GAAI,MAAK,MAAM,CAAC,UAAwB,SAE/E,CAAC;AAEF,eAAO,MAAM,sBAAsB,GAAI,MAAK,MAAM,CAAC,UAAwB,KAAG,mBAgB7E,CAAC"}
+{"version":3,"file":"runtime-config.d.ts","sourceRoot":"","sources":["../src/runtime-config.ts"],"names":[],"mappings":"AAoCA,MAAM,MAAM,mBAAmB,GAAG;IAC9B,QAAQ,CAAC,mBAAmB,EAAE,MAAM,CAAC;IACrC,QAAQ,CAAC,2BAA2B,EAAE,MAAM,CAAC;IAC7C,QAAQ,CAAC,wBAAwB,EAAE,MAAM,CAAC;IAC1C,QAAQ,CAAC,uBAAuB,EAAE,MAAM,CAAC;IACzC,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAC/B,QAAQ,CAAC,yBAAyB,EAAE,MAAM,CAAC;IAC3C,QAAQ,CAAC,2BAA2B,EAAE,MAAM,CAAC;IAC7C,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAC/B,QAAQ,CAAC,eAAe,EAAE,MAAM,CAAC;CACpC,CAAC;AAiEF,eAAO,MAAM,2BAA2B,GAAI,MAAK,MAAM,CAAC,UAAwB,SAE/E,CAAC;AAEF,eAAO,MAAM,sBAAsB,GAAI,MAAK,MAAM,CAAC,UAAwB,KAAG,mBAgB7E,CAAC"}

package/dist/runtime-config.js

@@ -1,9 +1,13 @@
 const DEFAULT_SCAN_BATCH_SIZE = 32;
 const DEFAULT_SCAN_CONCURRENCY = 16;
 const DEFAULT_MAX_PATCH_BYTES = 10 * 1024 * 1024;
+const DEFAULT_DOCTOR_CHECKPOINT_MAX_AGE_MS = 24 * 60 * 60 * 1_000;
+const DEFAULT_DOCTOR_OPEN_ISSUE_MAX_AGE_MS = 30 * 24 * 60 * 60 * 1_000;
 const RUNTIME_CONFIG_ENV_VARS = [
     'USHMAN_LEDGER_BLOB_HASH_CONCURRENCY',
     'USHMAN_LEDGER_COVERAGE_FILE_STAT_CONCURRENCY',
+    'USHMAN_LEDGER_DOCTOR_CHECKPOINT_MAX_AGE_MS',
+    'USHMAN_LEDGER_DOCTOR_OPEN_ISSUE_MAX_AGE_MS',
     'USHMAN_LEDGER_MAX_PATCH_BYTES',
     'USHMAN_LEDGER_READ_INDEX_REBUILD_BATCH_SIZE',
     'USHMAN_LEDGER_READ_INDEX_REBUILD_CONCURRENCY',
@@ -44,6 +48,16 @@ const buildLedgerRuntimeConfig = (env) => {
             env,
             envVar: 'USHMAN_LEDGER_COVERAGE_FILE_STAT_CONCURRENCY',
         }),
+        doctorCheckpointMaxAgeMs: parsePositiveIntegerEnv({
+            defaultValue: DEFAULT_DOCTOR_CHECKPOINT_MAX_AGE_MS,
+            env,
+            envVar: 'USHMAN_LEDGER_DOCTOR_CHECKPOINT_MAX_AGE_MS',
+        }),
+        doctorOpenIssueMaxAgeMs: parsePositiveIntegerEnv({
+            defaultValue: DEFAULT_DOCTOR_OPEN_ISSUE_MAX_AGE_MS,
+            env,
+            envVar: 'USHMAN_LEDGER_DOCTOR_OPEN_ISSUE_MAX_AGE_MS',
+        }),
         maxPatchBytes: parsePositiveIntegerEnv({
             defaultValue: DEFAULT_MAX_PATCH_BYTES,
             env,

package/dist/schema/entry-core.d.ts

@@ -1,12 +1,14 @@
 import * as v from 'valibot';
 export declare const LedgerSchemaVersion: "ushman-ledger-entry/v1";
 export declare const LEDGER_PHASES: readonly ["capture", "intake", "seed", "vendor-extract", "cleanup", "parity", "characterize", "equiv", "analyze", "recover", "ship", "migration"];
-export declare const LEDGER_KINDS: readonly ["tool-invocation", "agent-patch", "operator-patch", "operator-decision", "validator-result", "runtime-event", "note", "correction", "strip-decision-reverted", "change-log"];
+export declare const LEDGER_KINDS: readonly ["tool-invocation", "stage-write", "agent-patch", "operator-patch", "operator-decision", "validator-result", "runtime-event", "note", "correction", "strip-decision-reverted", "change-log"];
+export declare const STAGE_WRITE_STAGES: readonly ["intake", "seed", "vendor-extract", "cleanup", "candidate-promotion"];
 export declare const OPERATOR_DECISION_ACTIONS: readonly ["bypass-doctor", "skip-check", "override-strip-decision", "override-ship-state", "manual-parity-assertion", "ledger-hand-edit", "escalation"];
 export declare const NonEmptyTrimmedStringSchema: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.TrimAction, v.MinLengthAction<string, 1, undefined>]>;
 export declare const WorkspaceRelativePathSchema: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.MinLengthAction<string, 1, undefined>, v.CheckAction<string, "Expected a normalized workspace-relative path.">]>;
 export declare const LedgerPhaseSchema: v.PicklistSchema<readonly ["capture", "intake", "seed", "vendor-extract", "cleanup", "parity", "characterize", "equiv", "analyze", "recover", "ship", "migration"], undefined>;
-export declare const LedgerKindSchema: v.PicklistSchema<readonly ["tool-invocation", "agent-patch", "operator-patch", "operator-decision", "validator-result", "runtime-event", "note", "correction", "strip-decision-reverted", "change-log"], undefined>;
+export declare const LedgerKindSchema: v.PicklistSchema<readonly ["tool-invocation", "stage-write", "agent-patch", "operator-patch", "operator-decision", "validator-result", "runtime-event", "note", "correction", "strip-decision-reverted", "change-log"], undefined>;
+export declare const StageWriteStageSchema: v.PicklistSchema<readonly ["intake", "seed", "vendor-extract", "cleanup", "candidate-promotion"], undefined>;
 export declare const OperatorDecisionActionSchema: v.PicklistSchema<readonly ["bypass-doctor", "skip-check", "override-strip-decision", "override-ship-state", "manual-parity-assertion", "ledger-hand-edit", "escalation"], undefined>;
 export declare const ChangeLogSubkindSchema: v.PicklistSchema<readonly ["pre-change-checkpoint", "semantic-cleanup", "vendor-extract", "decomposition", "rollback", "hotfix", "smoke"], undefined>;
 export declare const ChangeLogSmokeResultSchema: v.PicklistSchema<readonly ["pass", "fail", "partial", "not-run"], undefined>;
@@ -105,6 +107,7 @@ export type LedgerLinks = v.InferOutput<typeof LedgerLinksSchema>;
 export type LedgerPhase = v.InferOutput<typeof LedgerPhaseSchema>;
 export type OperatorDecisionAction = v.InferOutput<typeof OperatorDecisionActionSchema>;
 export type OperatorDecisionPayload = v.InferOutput<typeof OperatorDecisionPayloadSchema>;
+export type StageWriteStage = v.InferOutput<typeof StageWriteStageSchema>;
 export type StripDecisionRevertedPayload = v.InferOutput<typeof StripDecisionRevertedPayloadSchema>;
 export type WorkspaceRelativePath = v.InferOutput<typeof WorkspaceRelativePathSchema>;
 //# sourceMappingURL=entry-core.d.ts.map

package/dist/schema/entry-core.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"entry-core.d.ts","sourceRoot":"","sources":["../../src/schema/entry-core.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,CAAC,MAAM,SAAS,CAAC;AAE7B,eAAO,MAAM,mBAAmB,EAAG,wBAAiC,CAAC;AAErE,eAAO,MAAM,aAAa,mJAahB,CAAC;AAEX,eAAO,MAAM,YAAY,wLAWf,CAAC;AAEX,eAAO,MAAM,yBAAyB,yJAQ5B,CAAC;AAiDX,eAAO,MAAM,2BAA2B,+GAA+C,CAAC;AAExF,eAAO,MAAM,2BAA2B,0KAIvC,CAAC;AAIF,eAAO,MAAM,iBAAiB,gLAA4B,CAAC;AAC3D,eAAO,MAAM,gBAAgB,qNAA2B,CAAC;AACzD,eAAO,MAAM,4BAA4B,sLAAwC,CAAC;AAElF,eAAO,MAAM,sBAAsB,uJAAkC,CAAC;AACtE,eAAO,MAAM,0BAA0B,8EAAuC,CAAC;AAC/E,eAAO,MAAM,2BAA2B,6EAAyC,CAAC;AAElF,eAAO,MAAM,aAAa;;;;aAIxB,CAAC;AAEH,eAAO,MAAM,iBAAiB;;;;;;;;;;8BAa7B,CAAC;AAEF,eAAO,MAAM,sBAAsB;;;;;;;;;;;;;;;;;;;;;;;;CAUlC,CAAC;AAEF,eAAO,MAAM,sBAAsB;;;;;;;;;;;;;;;;;;;;;CAOlC,CAAC;AAEF,eAAO,MAAM,oBAAoB;;;;;aAK/B,CAAC;AAEH,eAAO,MAAM,6BAA6B;;;;aAIxC,CAAC;AAEH,eAAO,MAAM,kCAAkC;;;;aAI7C,CAAC;AAEH,eAAO,MAAM,yBAAyB;;;;aAIpC,CAAC;AAEH,MAAM,MAAM,cAAc,GAAG,CAAC,CAAC,WAAW,CAAC,OAAO,oBAAoB,CAAC,CAAC;AACxE,MAAM,MAAM,mBAAmB,GAAG,CAAC,CAAC,WAAW,CAAC,OAAO,yBAAyB,CAAC,CAAC;AAClF,MAAM,MAAM,qBAAqB,GAAG,CAAC,CAAC,WAAW,CAAC,OAAO,2BAA2B,CAAC,CAAC;AACtF,MAAM,MAAM,oBAAoB,GAAG,CAAC,CAAC,WAAW,CAAC,OAAO,0BAA0B,CAAC,CAAC;AACpF,MAAM,MAAM,gBAAgB,GAAG,CAAC,CAAC,WAAW,CAAC,OAAO,sBAAsB,CAAC,CAAC;AAC5E,MAAM,MAAM,UAAU,GAAG,CAAC,CAAC,WAAW,CAAC,OAAO,gBAAgB,CAAC,CAAC;AAChE,MAAM,MAAM,WAAW,GAAG,CAAC,CAAC,WAAW,CAAC,OAAO,iBAAiB,CAAC,CAAC;AAClE,MAAM,MAAM,WAAW,GAAG,CAAC,CAAC,WAAW,CAAC,OAAO,iBAAiB,CAAC,CAAC;AAClE,MAAM,MAAM,sBAAsB,GAAG,CAAC,CAAC,WAAW,CAAC,OAAO,4BAA4B,CAAC,CAAC;AACxF,MAAM,MAAM,uBAAuB,GAAG,CAAC,CAAC,WAAW,CAAC,OAAO,6BAA6B,CAAC,CAAC;AAC1F,MAAM,MAAM,4BAA4B,GAAG,CAAC,CAAC,WAAW,CAAC,OAAO,kCAAkC,CAAC,CAAC;AACpG,MAAM,MAAM,qBAAqB,GAAG,CAAC,CAAC,WAAW,CAAC,OAAO,2BAA2B,CAAC,CAAC"}
+{"version":3,"file":"entry-core.d.ts","sourceRoot":"","sources":["../../src/schema/entry-core.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,CAAC,MAAM,SAAS,CAAC;AAE7B,eAAO,MAAM,mBAAmB,EAAG,wBAAiC,CAAC;AAErE,eAAO,MAAM,aAAa,mJAahB,CAAC;AAEX,eAAO,MAAM,YAAY,uMAYf,CAAC;AAEX,eAAO,MAAM,kBAAkB,iFAAkF,CAAC;AAElH,eAAO,MAAM,yBAAyB,yJAQ5B,CAAC;AAiDX,eAAO,MAAM,2BAA2B,+GAA+C,CAAC;AAExF,eAAO,MAAM,2BAA2B,0KAIvC,CAAC;AAIF,eAAO,MAAM,iBAAiB,gLAA4B,CAAC;AAC3D,eAAO,MAAM,gBAAgB,oOAA2B,CAAC;AACzD,eAAO,MAAM,qBAAqB,8GAAiC,CAAC;AACpE,eAAO,MAAM,4BAA4B,sLAAwC,CAAC;AAElF,eAAO,MAAM,sBAAsB,uJAAkC,CAAC;AACtE,eAAO,MAAM,0BAA0B,8EAAuC,CAAC;AAC/E,eAAO,MAAM,2BAA2B,6EAAyC,CAAC;AAElF,eAAO,MAAM,aAAa;;;;aAIxB,CAAC;AAEH,eAAO,MAAM,iBAAiB;;;;;;;;;;8BAa7B,CAAC;AAEF,eAAO,MAAM,sBAAsB;;;;;;;;;;;;;;;;;;;;;;;;CAUlC,CAAC;AAEF,eAAO,MAAM,sBAAsB;;;;;;;;;;;;;;;;;;;;;CAOlC,CAAC;AAEF,eAAO,MAAM,oBAAoB;;;;;aAK/B,CAAC;AAEH,eAAO,MAAM,6BAA6B;;;;aAIxC,CAAC;AAEH,eAAO,MAAM,kCAAkC;;;;aAI7C,CAAC;AAEH,eAAO,MAAM,yBAAyB;;;;aAIpC,CAAC;AAEH,MAAM,MAAM,cAAc,GAAG,CAAC,CAAC,WAAW,CAAC,OAAO,oBAAoB,CAAC,CAAC;AACxE,MAAM,MAAM,mBAAmB,GAAG,CAAC,CAAC,WAAW,CAAC,OAAO,yBAAyB,CAAC,CAAC;AAClF,MAAM,MAAM,qBAAqB,GAAG,CAAC,CAAC,WAAW,CAAC,OAAO,2BAA2B,CAAC,CAAC;AACtF,MAAM,MAAM,oBAAoB,GAAG,CAAC,CAAC,WAAW,CAAC,OAAO,0BAA0B,CAAC,CAAC;AACpF,MAAM,MAAM,gBAAgB,GAAG,CAAC,CAAC,WAAW,CAAC,OAAO,sBAAsB,CAAC,CAAC;AAC5E,MAAM,MAAM,UAAU,GAAG,CAAC,CAAC,WAAW,CAAC,OAAO,gBAAgB,CAAC,CAAC;AAChE,MAAM,MAAM,WAAW,GAAG,CAAC,CAAC,WAAW,CAAC,OAAO,iBAAiB,CAAC,CAAC;AAClE,MAAM,MAAM,WAAW,GAAG,CAAC,CAAC,WAAW,CAAC,OAAO,iBAAiB,CAAC,CAAC;AAClE,MAAM,MAAM,sBAAsB,GAAG,CAAC,CAAC,WAAW,CAAC,OAAO,4BAA4B,CAAC,CAAC;AACxF,MAAM,MAAM,uBAAuB,GAAG,CAAC,CAAC,WAAW,CAAC,OAAO,6BAA6B,CAAC,CAAC;AAC1F,MAAM,MAAM,eAAe,GAAG,CAAC,CAAC,WAAW,CAAC,OAAO,qBAAqB,CAAC,CAAC;AAC1E,MAAM,MAAM,4BAA4B,GAAG,CAAC,CAAC,WAAW,CAAC,OAAO,kCAAkC,CAAC,CAAC;AACpG,MAAM,MAAM,qBAAqB,GAAG,CAAC,CAAC,WAAW,CAAC,OAAO,2BAA2B,CAAC,CAAC"}

package/dist/schema/entry-core.js

@@ -17,6 +17,7 @@ export const LEDGER_PHASES = [
 ];
 export const LEDGER_KINDS = [
     'tool-invocation',
+    'stage-write',
     'agent-patch',
     'operator-patch',
     'operator-decision',
@@ -27,6 +28,7 @@ export const LEDGER_KINDS = [
     'strip-decision-reverted',
     'change-log',
 ];
+export const STAGE_WRITE_STAGES = ['intake', 'seed', 'vendor-extract', 'cleanup', 'candidate-promotion'];
 export const OPERATOR_DECISION_ACTIONS = [
     'bypass-doctor',
     'skip-check',
@@ -80,6 +82,7 @@ export const WorkspaceRelativePathSchema = v.pipe(v.string(), v.minLength(1), v.
 const SHA256HexSchema = v.pipe(v.string(), v.regex(SHA256_HEX_PATTERN, 'Expected a lowercase SHA-256 hex digest.'));
 export const LedgerPhaseSchema = v.picklist(LEDGER_PHASES);
 export const LedgerKindSchema = v.picklist(LEDGER_KINDS);
+export const StageWriteStageSchema = v.picklist(STAGE_WRITE_STAGES);
 export const OperatorDecisionActionSchema = v.picklist(OPERATOR_DECISION_ACTIONS);
 const StripDecisionInvalidatedStageSchema = v.picklist(STRIP_DECISION_INVALIDATED_STAGES);
 export const ChangeLogSubkindSchema = v.picklist(CHANGE_LOG_SUBKINDS);

package/dist/schema/entry-read.d.ts

@@ -28,6 +28,35 @@ export declare const ToolInvocationEntrySchema: v.ObjectSchema<{
     readonly summary: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.TrimAction, v.MinLengthAction<string, 1, undefined>]>;
     readonly ts: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.IsoTimestampAction<string, undefined>]>;
 }, undefined>;
+export declare const StageWriteEntrySchema: v.ObjectSchema<{
+    readonly filePath: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.MinLengthAction<string, 1, undefined>, v.CheckAction<string, "Expected a normalized workspace-relative path.">]>;
+    readonly kind: v.LiteralSchema<"stage-write", undefined>;
+    readonly rationale: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.TrimAction, v.MinLengthAction<string, 1, undefined>]>;
+    readonly stage: v.PicklistSchema<readonly ["intake", "seed", "vendor-extract", "cleanup", "candidate-promotion"], undefined>;
+    readonly details: v.OptionalSchema<v.RecordSchema<v.StringSchema<undefined>, v.UnknownSchema, undefined>, undefined>;
+    readonly emitter: v.ObjectSchema<{
+        readonly tool: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.TrimAction, v.MinLengthAction<string, 1, undefined>]>;
+        readonly user: v.OptionalSchema<v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.TrimAction, v.MinLengthAction<string, 1, undefined>]>, undefined>;
+        readonly version: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.TrimAction, v.MinLengthAction<string, 1, undefined>]>;
+    }, undefined>;
+    readonly id: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.TrimAction, v.MinLengthAction<string, 1, undefined>]>;
+    readonly links: v.OptionalSchema<v.ObjectWithRestSchema<{
+        readonly affectedFiles: v.OptionalSchema<v.ArraySchema<v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.MinLengthAction<string, 1, undefined>, v.CheckAction<string, "Expected a normalized workspace-relative path.">]>, undefined>, undefined>;
+        readonly blobs: v.OptionalSchema<v.ArraySchema<v.StringSchema<undefined>, undefined>, undefined>;
+        readonly briefId: v.OptionalSchema<v.StringSchema<undefined>, undefined>;
+        readonly correctsLedgerId: v.OptionalSchema<v.StringSchema<undefined>, undefined>;
+        readonly gitRef: v.OptionalSchema<v.StringSchema<undefined>, undefined>;
+        readonly idempotencyKey: v.OptionalSchema<v.StringSchema<undefined>, undefined>;
+        readonly stripDecisionId: v.OptionalSchema<v.StringSchema<undefined>, undefined>;
+        readonly supersedesLedgerId: v.OptionalSchema<v.StringSchema<undefined>, undefined>;
+        readonly validatorVerdictId: v.OptionalSchema<v.StringSchema<undefined>, undefined>;
+    }, v.UnknownSchema, undefined>, {}>;
+    readonly phase: v.PicklistSchema<readonly ["capture", "intake", "seed", "vendor-extract", "cleanup", "parity", "characterize", "equiv", "analyze", "recover", "ship", "migration"], undefined>;
+    readonly prevEntryId: v.NullableSchema<v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.TrimAction, v.MinLengthAction<string, 1, undefined>]>, undefined>;
+    readonly schemaVersion: v.LiteralSchema<"ushman-ledger-entry/v1", undefined>;
+    readonly summary: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.TrimAction, v.MinLengthAction<string, 1, undefined>]>;
+    readonly ts: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.IsoTimestampAction<string, undefined>]>;
+}, undefined>;
 export declare const AgentPatchEntrySchema: v.ObjectSchema<{
     readonly agent: v.ObjectSchema<{
         readonly name: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.TrimAction, v.MinLengthAction<string, 1, undefined>]>;
@@ -375,6 +404,34 @@ export declare const LedgerEntrySchema: v.VariantSchema<"kind", [v.ObjectSchema<
     readonly schemaVersion: v.LiteralSchema<"ushman-ledger-entry/v1", undefined>;
     readonly summary: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.TrimAction, v.MinLengthAction<string, 1, undefined>]>;
     readonly ts: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.IsoTimestampAction<string, undefined>]>;
+}, undefined>, v.ObjectSchema<{
+    readonly filePath: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.MinLengthAction<string, 1, undefined>, v.CheckAction<string, "Expected a normalized workspace-relative path.">]>;
+    readonly kind: v.LiteralSchema<"stage-write", undefined>;
+    readonly rationale: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.TrimAction, v.MinLengthAction<string, 1, undefined>]>;
+    readonly stage: v.PicklistSchema<readonly ["intake", "seed", "vendor-extract", "cleanup", "candidate-promotion"], undefined>;
+    readonly details: v.OptionalSchema<v.RecordSchema<v.StringSchema<undefined>, v.UnknownSchema, undefined>, undefined>;
+    readonly emitter: v.ObjectSchema<{
+        readonly tool: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.TrimAction, v.MinLengthAction<string, 1, undefined>]>;
+        readonly user: v.OptionalSchema<v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.TrimAction, v.MinLengthAction<string, 1, undefined>]>, undefined>;
+        readonly version: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.TrimAction, v.MinLengthAction<string, 1, undefined>]>;
+    }, undefined>;
+    readonly id: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.TrimAction, v.MinLengthAction<string, 1, undefined>]>;
+    readonly links: v.OptionalSchema<v.ObjectWithRestSchema<{
+        readonly affectedFiles: v.OptionalSchema<v.ArraySchema<v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.MinLengthAction<string, 1, undefined>, v.CheckAction<string, "Expected a normalized workspace-relative path.">]>, undefined>, undefined>;
+        readonly blobs: v.OptionalSchema<v.ArraySchema<v.StringSchema<undefined>, undefined>, undefined>;
+        readonly briefId: v.OptionalSchema<v.StringSchema<undefined>, undefined>;
+        readonly correctsLedgerId: v.OptionalSchema<v.StringSchema<undefined>, undefined>;
+        readonly gitRef: v.OptionalSchema<v.StringSchema<undefined>, undefined>;
+        readonly idempotencyKey: v.OptionalSchema<v.StringSchema<undefined>, undefined>;
+        readonly stripDecisionId: v.OptionalSchema<v.StringSchema<undefined>, undefined>;
+        readonly supersedesLedgerId: v.OptionalSchema<v.StringSchema<undefined>, undefined>;
+        readonly validatorVerdictId: v.OptionalSchema<v.StringSchema<undefined>, undefined>;
+    }, v.UnknownSchema, undefined>, {}>;
+    readonly phase: v.PicklistSchema<readonly ["capture", "intake", "seed", "vendor-extract", "cleanup", "parity", "characterize", "equiv", "analyze", "recover", "ship", "migration"], undefined>;
+    readonly prevEntryId: v.NullableSchema<v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.TrimAction, v.MinLengthAction<string, 1, undefined>]>, undefined>;
+    readonly schemaVersion: v.LiteralSchema<"ushman-ledger-entry/v1", undefined>;
+    readonly summary: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.TrimAction, v.MinLengthAction<string, 1, undefined>]>;
+    readonly ts: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.IsoTimestampAction<string, undefined>]>;
 }, undefined>, v.ObjectSchema<{
     readonly agent: v.ObjectSchema<{
         readonly name: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.TrimAction, v.MinLengthAction<string, 1, undefined>]>;

package/dist/schema/entry-read.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"entry-read.d.ts","sourceRoot":"","sources":["../../src/schema/entry-read.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,CAAC,MAAM,SAAS,CAAC;AAc7B,eAAO,MAAM,yBAAyB;;;;;;;;;;;;;;;;;;;;;;;;;;;;aAMpC,CAAC;AAQH,eAAO,MAAM,qBAAqB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;aAOhC,CAAC;AAEH,eAAO,MAAM,wBAAwB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;aAMnC,CAAC;AAEH,eAAO,MAAM,2BAA2B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;aAItC,CAAC;AAEH,eAAO,MAAM,0BAA0B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;aAOrC,CAAC;AAEH,eAAO,MAAM,uBAAuB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;aAOlC,CAAC;AAEH,eAAO,MAAM,eAAe;;;;;;;;;;;;;;;;;;;;;;;;;;;aAK1B,CAAC;AAEH,eAAO,MAAM,qBAAqB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;yDAOjC,CAAC;AAEF,eAAO,MAAM,gCAAgC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;aAI3C,CAAC;AAEH,eAAO,MAAM,oBAAoB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;aAY/B,CAAC;AAEH,eAAO,MAAM,iBAAiB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;0BAW5B,CAAC;AAEH,MAAM,MAAM,cAAc,GAAG,CAAC,CAAC,WAAW,CAAC,OAAO,oBAAoB,CAAC,CAAC;AACxE,MAAM,MAAM,WAAW,GAAG,CAAC,CAAC,WAAW,CAAC,OAAO,iBAAiB,CAAC,CAAC;AAClE,MAAM,MAAM,SAAS,GAAG,OAAO,CAAC,WAAW,EAAE;IAAE,IAAI,EAAE,MAAM,CAAA;CAAE,CAAC,CAAC"}
+{"version":3,"file":"entry-read.d.ts","sourceRoot":"","sources":["../../src/schema/entry-read.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,CAAC,MAAM,SAAS,CAAC;AAgB7B,eAAO,MAAM,yBAAyB;;;;;;;;;;;;;;;;;;;;;;;;;;;;aAMpC,CAAC;AAEH,eAAO,MAAM,qBAAqB;;;;;;;;;;;;;;;;;;;;;;;;;;;;aAMhC,CAAC;AAQH,eAAO,MAAM,qBAAqB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;aAOhC,CAAC;AAEH,eAAO,MAAM,wBAAwB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;aAMnC,CAAC;AAEH,eAAO,MAAM,2BAA2B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;aAItC,CAAC;AAEH,eAAO,MAAM,0BAA0B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;aAOrC,CAAC;AAEH,eAAO,MAAM,uBAAuB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;aAOlC,CAAC;AAEH,eAAO,MAAM,eAAe;;;;;;;;;;;;;;;;;;;;;;;;;;;aAK1B,CAAC;AAEH,eAAO,MAAM,qBAAqB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;yDAOjC,CAAC;AAEF,eAAO,MAAM,gCAAgC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;aAI3C,CAAC;AAEH,eAAO,MAAM,oBAAoB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;aAY/B,CAAC;AAEH,eAAO,MAAM,iBAAiB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;0BAY5B,CAAC;AAEH,MAAM,MAAM,cAAc,GAAG,CAAC,CAAC,WAAW,CAAC,OAAO,oBAAoB,CAAC,CAAC;AACxE,MAAM,MAAM,WAAW,GAAG,CAAC,CAAC,WAAW,CAAC,OAAO,iBAAiB,CAAC,CAAC;AAClE,MAAM,MAAM,SAAS,GAAG,OAAO,CAAC,WAAW,EAAE;IAAE,IAAI,EAAE,MAAM,CAAA;CAAE,CAAC,CAAC"}

package/dist/schema/entry-read.js

@@ -1,5 +1,5 @@
 import * as v from 'valibot';
-import { AgentPatchDiffSchema, ChangeLogFileChangeSchema, ChangeLogParityStatusSchema, ChangeLogSmokeResultSchema, ChangeLogSubkindSchema, ledgerEntryBaseEntries, NonEmptyTrimmedStringSchema, OperatorDecisionPayloadSchema, StripDecisionRevertedPayloadSchema, } from "./entry-core.js";
+import { AgentPatchDiffSchema, ChangeLogFileChangeSchema, ChangeLogParityStatusSchema, ChangeLogSmokeResultSchema, ChangeLogSubkindSchema, ledgerEntryBaseEntries, NonEmptyTrimmedStringSchema, OperatorDecisionPayloadSchema, StageWriteStageSchema, StripDecisionRevertedPayloadSchema, WorkspaceRelativePathSchema, } from "./entry-core.js";
 import { NoteSubkindSchema } from "./note.js";
 export const ToolInvocationEntrySchema = v.object({
     ...ledgerEntryBaseEntries,
@@ -8,6 +8,13 @@ export const ToolInvocationEntrySchema = v.object({
     exitCode: v.optional(v.pipe(v.number(), v.integer())),
     kind: v.literal('tool-invocation'),
 });
+export const StageWriteEntrySchema = v.object({
+    ...ledgerEntryBaseEntries,
+    filePath: WorkspaceRelativePathSchema,
+    kind: v.literal('stage-write'),
+    rationale: NonEmptyTrimmedStringSchema,
+    stage: StageWriteStageSchema,
+});
 const patchEntryEntries = {
     ...ledgerEntryBaseEntries,
     diff: AgentPatchDiffSchema,
@@ -80,6 +87,7 @@ export const ChangeLogEntrySchema = v.object({
 });
 export const LedgerEntrySchema = v.variant('kind', [
     ToolInvocationEntrySchema,
+    StageWriteEntrySchema,
     AgentPatchEntrySchema,
     OperatorPatchEntrySchema,
     OperatorDecisionEntrySchema,

package/dist/schema/entry-write.d.ts

@@ -25,6 +25,32 @@ export declare const ToolInvocationRecordSchema: v.ObjectSchema<{
     readonly phase: v.PicklistSchema<readonly ["capture", "intake", "seed", "vendor-extract", "cleanup", "parity", "characterize", "equiv", "analyze", "recover", "ship", "migration"], undefined>;
     readonly summary: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.TrimAction, v.MinLengthAction<string, 1, undefined>]>;
 }, undefined>;
+export declare const StageWriteRecordSchema: v.ObjectSchema<{
+    readonly filePath: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.MinLengthAction<string, 1, undefined>, v.CheckAction<string, "Expected a normalized workspace-relative path.">]>;
+    readonly kind: v.LiteralSchema<"stage-write", undefined>;
+    readonly rationale: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.TrimAction, v.MinLengthAction<string, 1, undefined>]>;
+    readonly stage: v.PicklistSchema<readonly ["intake", "seed", "vendor-extract", "cleanup", "candidate-promotion"], undefined>;
+    readonly details: v.OptionalSchema<v.RecordSchema<v.StringSchema<undefined>, v.UnknownSchema, undefined>, undefined>;
+    readonly emitter: v.ObjectSchema<{
+        readonly tool: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.TrimAction, v.MinLengthAction<string, 1, undefined>]>;
+        readonly user: v.OptionalSchema<v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.TrimAction, v.MinLengthAction<string, 1, undefined>]>, undefined>;
+        readonly version: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.TrimAction, v.MinLengthAction<string, 1, undefined>]>;
+    }, undefined>;
+    readonly idempotencyKey: v.OptionalSchema<v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.TrimAction, v.MinLengthAction<string, 1, undefined>]>, undefined>;
+    readonly links: v.OptionalSchema<v.ObjectWithRestSchema<{
+        readonly affectedFiles: v.OptionalSchema<v.ArraySchema<v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.MinLengthAction<string, 1, undefined>, v.CheckAction<string, "Expected a normalized workspace-relative path.">]>, undefined>, undefined>;
+        readonly blobs: v.OptionalSchema<v.ArraySchema<v.StringSchema<undefined>, undefined>, undefined>;
+        readonly briefId: v.OptionalSchema<v.StringSchema<undefined>, undefined>;
+        readonly correctsLedgerId: v.OptionalSchema<v.StringSchema<undefined>, undefined>;
+        readonly gitRef: v.OptionalSchema<v.StringSchema<undefined>, undefined>;
+        readonly idempotencyKey: v.OptionalSchema<v.StringSchema<undefined>, undefined>;
+        readonly stripDecisionId: v.OptionalSchema<v.StringSchema<undefined>, undefined>;
+        readonly supersedesLedgerId: v.OptionalSchema<v.StringSchema<undefined>, undefined>;
+        readonly validatorVerdictId: v.OptionalSchema<v.StringSchema<undefined>, undefined>;
+    }, v.UnknownSchema, undefined>, undefined>;
+    readonly phase: v.PicklistSchema<readonly ["capture", "intake", "seed", "vendor-extract", "cleanup", "parity", "characterize", "equiv", "analyze", "recover", "ship", "migration"], undefined>;
+    readonly summary: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.TrimAction, v.MinLengthAction<string, 1, undefined>]>;
+}, undefined>;
 export declare const AgentPatchRecordSchema: v.SchemaWithPipe<readonly [v.ObjectSchema<{
     readonly agent: v.ObjectSchema<{
         readonly name: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.TrimAction, v.MinLengthAction<string, 1, undefined>]>;
@@ -459,6 +485,31 @@ export declare const LedgerRecordSchema: v.VariantSchema<"kind", [v.ObjectSchema
     }, v.UnknownSchema, undefined>, undefined>;
     readonly phase: v.PicklistSchema<readonly ["capture", "intake", "seed", "vendor-extract", "cleanup", "parity", "characterize", "equiv", "analyze", "recover", "ship", "migration"], undefined>;
     readonly summary: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.TrimAction, v.MinLengthAction<string, 1, undefined>]>;
+}, undefined>, v.ObjectSchema<{
+    readonly filePath: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.MinLengthAction<string, 1, undefined>, v.CheckAction<string, "Expected a normalized workspace-relative path.">]>;
+    readonly kind: v.LiteralSchema<"stage-write", undefined>;
+    readonly rationale: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.TrimAction, v.MinLengthAction<string, 1, undefined>]>;
+    readonly stage: v.PicklistSchema<readonly ["intake", "seed", "vendor-extract", "cleanup", "candidate-promotion"], undefined>;
+    readonly details: v.OptionalSchema<v.RecordSchema<v.StringSchema<undefined>, v.UnknownSchema, undefined>, undefined>;
+    readonly emitter: v.ObjectSchema<{
+        readonly tool: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.TrimAction, v.MinLengthAction<string, 1, undefined>]>;
+        readonly user: v.OptionalSchema<v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.TrimAction, v.MinLengthAction<string, 1, undefined>]>, undefined>;
+        readonly version: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.TrimAction, v.MinLengthAction<string, 1, undefined>]>;
+    }, undefined>;
+    readonly idempotencyKey: v.OptionalSchema<v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.TrimAction, v.MinLengthAction<string, 1, undefined>]>, undefined>;
+    readonly links: v.OptionalSchema<v.ObjectWithRestSchema<{
+        readonly affectedFiles: v.OptionalSchema<v.ArraySchema<v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.MinLengthAction<string, 1, undefined>, v.CheckAction<string, "Expected a normalized workspace-relative path.">]>, undefined>, undefined>;
+        readonly blobs: v.OptionalSchema<v.ArraySchema<v.StringSchema<undefined>, undefined>, undefined>;
+        readonly briefId: v.OptionalSchema<v.StringSchema<undefined>, undefined>;
+        readonly correctsLedgerId: v.OptionalSchema<v.StringSchema<undefined>, undefined>;
+        readonly gitRef: v.OptionalSchema<v.StringSchema<undefined>, undefined>;
+        readonly idempotencyKey: v.OptionalSchema<v.StringSchema<undefined>, undefined>;
+        readonly stripDecisionId: v.OptionalSchema<v.StringSchema<undefined>, undefined>;
+        readonly supersedesLedgerId: v.OptionalSchema<v.StringSchema<undefined>, undefined>;
+        readonly validatorVerdictId: v.OptionalSchema<v.StringSchema<undefined>, undefined>;
+    }, v.UnknownSchema, undefined>, undefined>;
+    readonly phase: v.PicklistSchema<readonly ["capture", "intake", "seed", "vendor-extract", "cleanup", "parity", "characterize", "equiv", "analyze", "recover", "ship", "migration"], undefined>;
+    readonly summary: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.TrimAction, v.MinLengthAction<string, 1, undefined>]>;
 }, undefined>, v.SchemaWithPipe<readonly [v.ObjectSchema<{
     readonly agent: v.ObjectSchema<{
         readonly name: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.TrimAction, v.MinLengthAction<string, 1, undefined>]>;

package/dist/schema/entry-write.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"entry-write.d.ts","sourceRoot":"","sources":["../../src/schema/entry-write.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,CAAC,MAAM,SAAS,CAAC;AAoC7B,eAAO,MAAM,0BAA0B;;;;;;;;;;;;;;;;;;;;;;;;;aAMrC,CAAC;AAUH,eAAO,MAAM,sBAAsB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;8HAUlC,CAAC;AAEF,eAAO,MAAM,yBAAyB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;8HASrC,CAAC;AAEF,eAAO,MAAM,4BAA4B;;;;;;;;;;;;;;;;;;;;;;;;;;;aAIvC,CAAC;AAEH,eAAO,MAAM,2BAA2B;;;;;;;;;;;;;;;;;;;;;;;;;;aAOtC,CAAC;AAEH,eAAO,MAAM,wBAAwB;;;;;;;;;;;;;;;;;;;;;;;;;;aAOnC,CAAC;AAEH,eAAO,MAAM,gBAAgB;;;;;;;;;;;;;;;;;;;;;;;;aAK3B,CAAC;AAEH,eAAO,MAAM,sBAAsB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;yDAOlC,CAAC;AAEF,eAAO,MAAM,iCAAiC;;;;;;;;;;;;;;;;;;;;;;;;;;;aAI5C,CAAC;AAEH,eAAO,MAAM,qBAAqB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;qDAkBjC,CAAC;AAEF,eAAO,MAAM,kBAAkB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;kEAW7B,CAAC;AAEH,MAAM,MAAM,eAAe,GAAG,CAAC,CAAC,WAAW,CAAC,OAAO,qBAAqB,CAAC,CAAC;AAC1E,MAAM,MAAM,YAAY,GAAG,CAAC,CAAC,WAAW,CAAC,OAAO,kBAAkB,CAAC,CAAC"}
+{"version":3,"file":"entry-write.d.ts","sourceRoot":"","sources":["../../src/schema/entry-write.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,CAAC,MAAM,SAAS,CAAC;AAsC7B,eAAO,MAAM,0BAA0B;;;;;;;;;;;;;;;;;;;;;;;;;aAMrC,CAAC;AAEH,eAAO,MAAM,sBAAsB;;;;;;;;;;;;;;;;;;;;;;;;;aAMjC,CAAC;AAUH,eAAO,MAAM,sBAAsB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;8HAUlC,CAAC;AAEF,eAAO,MAAM,yBAAyB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;8HASrC,CAAC;AAEF,eAAO,MAAM,4BAA4B;;;;;;;;;;;;;;;;;;;;;;;;;;;aAIvC,CAAC;AAEH,eAAO,MAAM,2BAA2B;;;;;;;;;;;;;;;;;;;;;;;;;;aAOtC,CAAC;AAEH,eAAO,MAAM,wBAAwB;;;;;;;;;;;;;;;;;;;;;;;;;;aAOnC,CAAC;AAEH,eAAO,MAAM,gBAAgB;;;;;;;;;;;;;;;;;;;;;;;;aAK3B,CAAC;AAEH,eAAO,MAAM,sBAAsB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;yDAOlC,CAAC;AAEF,eAAO,MAAM,iCAAiC;;;;;;;;;;;;;;;;;;;;;;;;;;;aAI5C,CAAC;AAEH,eAAO,MAAM,qBAAqB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;qDAkBjC,CAAC;AAEF,eAAO,MAAM,kBAAkB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;kEAY7B,CAAC;AAEH,MAAM,MAAM,eAAe,GAAG,CAAC,CAAC,WAAW,CAAC,OAAO,qBAAqB,CAAC,CAAC;AAC1E,MAAM,MAAM,YAAY,GAAG,CAAC,CAAC,WAAW,CAAC,OAAO,kBAAkB,CAAC,CAAC"}

package/dist/schema/entry-write.js

@@ -1,5 +1,5 @@
 import * as v from 'valibot';
-import { AgentPatchDiffSchema, ChangeLogFileChangeSchema, ChangeLogParityStatusSchema, ChangeLogSmokeResultSchema, ChangeLogSubkindSchema, NonEmptyTrimmedStringSchema, OperatorDecisionPayloadSchema, recordEntryBaseEntries, StripDecisionRevertedPayloadSchema, } from "./entry-core.js";
+import { AgentPatchDiffSchema, ChangeLogFileChangeSchema, ChangeLogParityStatusSchema, ChangeLogSmokeResultSchema, ChangeLogSubkindSchema, NonEmptyTrimmedStringSchema, OperatorDecisionPayloadSchema, recordEntryBaseEntries, StageWriteStageSchema, StripDecisionRevertedPayloadSchema, WorkspaceRelativePathSchema, } from "./entry-core.js";
 import { NoteSubkindSchema } from "./note.js";
 const validatePatchRecord = (value) => {
     const provided = [value.diff, value.diffPath, value.diffText].filter((entry) => Boolean(entry));
@@ -19,6 +19,13 @@ export const ToolInvocationRecordSchema = v.object({
     exitCode: v.optional(v.pipe(v.number(), v.integer())),
     kind: v.literal('tool-invocation'),
 });
+export const StageWriteRecordSchema = v.object({
+    ...recordEntryBaseEntries,
+    filePath: WorkspaceRelativePathSchema,
+    kind: v.literal('stage-write'),
+    rationale: NonEmptyTrimmedStringSchema,
+    stage: StageWriteStageSchema,
+});
 const patchRecordEntries = {
     ...recordEntryBaseEntries,
     diff: v.optional(AgentPatchDiffSchema),
@@ -93,6 +100,7 @@ export const ChangeLogRecordSchema = v.pipe(v.object({
 }), v.check((value) => value.subkind !== 'rollback' || Boolean(value.rollsBack), 'change-log rollback records require rollsBack'));
 export const LedgerRecordSchema = v.variant('kind', [
     ToolInvocationRecordSchema,
+    StageWriteRecordSchema,
     AgentPatchRecordSchema,
     OperatorPatchRecordSchema,
     OperatorDecisionRecordSchema,

package/dist/storage/filesystem.d.ts

@@ -8,11 +8,22 @@ type AtomicWriteTestHook = {
     readonly beforeWrite?: () => Promise<void>;
     readonly retainOnThrow?: boolean;
 };
+type AtomicTempFileRegistration = {
+    readonly remove: () => Promise<void>;
+};
+type AtomicWriteOptions = {
+    readonly registerTempFile?: (context: {
+        readonly finalPath: string;
+        readonly tempPath: string;
+    }) => Promise<AtomicTempFileRegistration>;
+};
 export type LedgerPaths = {
     readonly blobsDir: string;
+    readonly externalTempFilesDir: string;
     readonly lockFile: (phase: LedgerPhase) => string;
     readonly manifestLockFile: string;
     readonly manifestFile: string;
+    readonly pendingCommitQuarantineDir: string;
     readonly pendingCommitsDir: string;
     readonly pendingArchivesDir: string;
     readonly phaseDir: (phase: LedgerPhase) => string;
@@ -32,9 +43,10 @@ export type AtomicTextFileWriter = {
 export declare const resolveLedgerPaths: (workspaceRoot: string) => LedgerPaths;
 export declare const ensureLedgerDirectories: (workspaceRoot: string) => Promise<LedgerPaths>;
 export declare const setAtomicWriteTestHook: (filePath: string, hook: AtomicWriteTestHook | null) => void;
-export declare const writeAtomicTextFile: (filePath: string, text: string) => Promise<void>;
-export declare const createAtomicTextFileWriter: (filePath: string) => Promise<AtomicTextFileWriter>;
+export declare const writeAtomicTextFile: (filePath: string, text: string, options?: AtomicWriteOptions) => Promise<void>;
+export declare const createAtomicTextFileWriter: (filePath: string, options?: AtomicWriteOptions) => Promise<AtomicTextFileWriter>;
 export declare const writeAtomicJsonFile: (filePath: string, value: unknown) => Promise<void>;
+export declare const createExternalTempFileRegistrar: (workspaceRoot: string) => NonNullable<AtomicWriteOptions["registerTempFile"]>;
 export declare const readManifest: (workspaceRoot: string) => Promise<LedgerManifest>;
 export declare const saveManifest: (workspaceRoot: string, manifest: LedgerManifest) => Promise<void>;
 export declare const cleanupStaleTempFiles: (workspaceRoot: string) => Promise<void>;