@llblab/pi-actors 0.41.1 → 0.42.1

package/dist/lib/async-runs.js

@@ -1,10 +1,11 @@
 /**
  * Command-template async run lifecycle facade.
- * Owns launch, state observation, listing, message/control facade methods, and retention while runs-* subdomains own narrower run internals.
+ * Owns: launch, state observation, listing, message/control facade methods, and retention while runs-* subdomains own narrower run internals.
  */
 import { spawn } from "node:child_process";
+import { randomUUID } from "node:crypto";
 import { closeSync, existsSync, mkdirSync, openSync, readdirSync, statSync, writeFileSync, } from "node:fs";
-import { basename, dirname, extname, join, relative, resolve } from "node:path";
+import { basename, dirname, extname, isAbsolute, join, relative, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 import { writeJsonAtomic } from "./file-state.js";
 import { CURRENT_MODEL_VALUE_KEY, CURRENT_THINKING_VALUE_KEY, describeCurrentPolicyProvenance, } from "./model-context.js";
@@ -20,11 +21,33 @@ import { archiveTerminalRun, pruneTerminalRun } from "./runs-retention.js";
 import { captureRunProcessIdentity, verifyRunProcessIdentity, } from "./runs-process.js";
 import * as RunsStart from "./runs-start.js";
 import * as RunsIndex from "./runs-index.js";
+import * as RunsParentTeardown from "./runs-parent-teardown.js";
 import { claimRunInboxMessageInStateDir, parseRunInboxLine, processRunInboxMessagesInStateDir, runInboxFile, updateRunInboxMessageStatusInStateDir, } from "./runs-mailbox.js";
 import { deliverRunMessage, } from "./runs-messages.js";
-import { buildRunStatus, tailFile, tailLines } from "./runs-status.js";
+import { buildRunStatus, tailFile, tailLines, } from "./runs-status.js";
 import { readJsonFileResilient } from "./state-readers.js";
 const RUNNER_IDENTITY_GRACE_MS = 5000;
+export function normalizeRunTransportContext(value) {
+    if (!value || typeof value !== "object" || Array.isArray(value))
+        return undefined;
+    const normalized = {};
+    for (const [key, item] of Object.entries(value).slice(0, 16)) {
+        const safeKey = key.trim().slice(0, 64);
+        if (!safeKey)
+            continue;
+        if (typeof item === "string") {
+            normalized[safeKey] = item.trim().slice(0, 256);
+            continue;
+        }
+        if (typeof item === "number" && Number.isFinite(item)) {
+            normalized[safeKey] = item;
+            continue;
+        }
+        if (typeof item === "boolean")
+            normalized[safeKey] = item;
+    }
+    return Object.keys(normalized).length ? normalized : undefined;
+}
 const DEFAULT_STATE_ROOT = Paths.getRunStateRoot();
 const DEFAULT_RECIPE_ROOT = Paths.getRecipeRoot();
 function packageRoot() {
@@ -89,7 +112,8 @@ function resolveRecipeFile(file) {
 function isMutableUsageRecipeFile(file) {
     const userRoot = resolve(DEFAULT_RECIPE_ROOT);
     const resolved = resolve(file);
-    return resolved.startsWith(`${userRoot}/`);
+    const relation = relative(userRoot, resolved);
+    return relation !== "" && !relation.startsWith("..") && !isAbsolute(relation);
 }
 function readRecipeFile(file) {
     const path = resolveRecipeFile(file);
@@ -201,8 +225,8 @@ function assertCurrentPlaceholderReferencesResolved(template, defaults, values,
         throw Object.assign(new Error(`Template recipe requires the current Pi ${check.label} for inheritance, but no current ${check.label} was available. Pass explicit values or launch from a Pi session with a selected ${check.label}. unresolved=${refs.slice(0, 4).join(",")}`), { model_policy: modelPolicy });
     }
 }
-function acquireStateStartLock(stateDir) {
-    return RunsStart.acquireStateStartLock(stateDir);
+function acquireStateStartLock(stateDir, options = {}) {
+    return RunsStart.acquireStateStartLock(stateDir, options);
 }
 function prepareStateDirForStart(stateDir) {
     RunsStart.prepareStateDirForStart(stateDir, readJson, RUNNER_PATH);
@@ -228,7 +252,9 @@ export function startRun(params, cwd) {
     assertCurrentPlaceholderReferencesResolved(resolved.template, startParams.defaults, values, modelPolicy);
     assertNoActiveRunState(stateDir);
     mkdirSync(stateDir, { recursive: true });
-    const releaseStartLock = acquireStateStartLock(stateDir);
+    const releaseStartLock = acquireStateStartLock(stateDir, {
+        onContention: startParams.lifecycleHooks?.onLockContention,
+    });
     try {
         claimRunStateDirectory(stateDir, run);
         assertNoActiveRunState(stateDir);
@@ -244,8 +270,10 @@ export function startRun(params, cwd) {
         const recipeContextRecords = recipeFile && includeActorRecipeContext
             ? RecipesReferences.buildRecipeContextRecords(recipeFile)
             : undefined;
-        if (recipeFile && isMutableUsageRecipeFile(recipeFile)) {
-            RecipesUsage.recordRecipeLaunch(recipeFile, new Date(), startParams.launch_source === "tool" ? "tool" : "spawn");
+        if (recipeFile &&
+            isMutableUsageRecipeFile(recipeFile) &&
+            !RecipesUsage.recordRecipeLaunch(recipeFile, new Date(), startParams.launch_source === "tool" ? "tool" : "spawn")) {
+            throw new Error(`Recipe launch rejected because its source changed during activation: ${recipeFile}. Reload recipe tools and retry.`);
         }
         const outFd = openSync(stdout, "a");
         const errFd = openSync(stderr, "a");
@@ -254,6 +282,7 @@ export function startRun(params, cwd) {
             ...(startParams.defaults || {}),
             ...values,
         };
+        const transportContext = normalizeRunTransportContext(startParams.transport_context);
         const artifacts = resolveArtifactPaths(startParams.artifacts, outputValues);
         const meta = {
             argv: [process.execPath, ...argv],
@@ -262,11 +291,14 @@ export function startRun(params, cwd) {
             ...(startParams.launch_source
                 ? { launch_source: startParams.launch_source }
                 : {}),
+            ...(startParams.launch_correlation
+                ? { launch_correlation: startParams.launch_correlation } : {}),
             ...(startParams.ownerId ? { ownerId: startParams.ownerId } : {}),
             pid: 0,
             ...(recipe ? { recipe } : {}),
             ...(recipeFile ? { recipe_file: recipeFile } : {}),
             run,
+            run_instance_id: randomUUID(),
             state_dir: stateDir,
             status: "running",
             ...(startParams.tool ? { tool: startParams.tool } : {}),
@@ -276,12 +308,17 @@ export function startRun(params, cwd) {
             ...(artifacts ? { artifacts } : {}),
             ...(startParams.control ? { control: startParams.control } : {}),
             ...(startParams.mailbox ? { mailbox: startParams.mailbox } : {}),
+            ...(startParams.notification_policy === "silent"
+                ? { notification_policy: "silent" }
+                : {}),
             ...(recipeContextRecords && recipeContextRecords.length > 0
                 ? { recipe_context_records: recipeContextRecords }
                 : {}),
             ...(startParams.retire_when === "children_terminal"
                 ? { retire_when: "children_terminal" }
                 : {}),
+            ...(transportContext
+                ? { transport_context: transportContext } : {}),
         };
         writeJsonAtomic(join(stateDir, "run.json"), meta);
         const child = spawn(process.execPath, argv, {
@@ -303,7 +340,7 @@ export function startRun(params, cwd) {
             phase: "starting",
             updatedAt: new Date().toISOString(),
         });
-        writeFileSync(join(stateDir, "events.jsonl"), `${JSON.stringify({ event: "run.start", run, pid: meta.pid, ts: new Date().toISOString() })}\n`, { flag: "a" });
+        writeFileSync(join(stateDir, "events.jsonl"), `${JSON.stringify({ event: "run.start", run, run_instance_id: meta.run_instance_id, pid: meta.pid, ts: new Date().toISOString() })}\n`, { flag: "a" });
         child.unref();
         return meta;
     }
@@ -312,17 +349,20 @@ export function startRun(params, cwd) {
     }
 }
 export { parseRunOutboxEventLine } from "./runs-outbox.js";
-export function getRunStatus(runOrDir) {
-    const stateDir = resolve(runOrDir.includes("/")
+function resolveRunStateDir(runOrDir) {
+    return resolve(/[\\/]/u.test(runOrDir)
         ? runOrDir
         : join(DEFAULT_STATE_ROOT, safeRunId(runOrDir)));
+}
+export function getRunStatus(runOrDir) {
+    const stateDir = resolveRunStateDir(runOrDir);
     const meta = readJson(join(stateDir, "run.json"));
     if (!meta)
         throw new Error(`Run not found: ${runOrDir}`);
     return buildRunStatus(stateDir, runOrDir, meta, readJson, RUNNER_PATH, RUNNER_IDENTITY_GRACE_MS);
 }
-export function listRunStateDirs(stateRoot = DEFAULT_STATE_ROOT, depth = 0, seen = new Set()) {
-    return RunsIndex.listRunStateDirs(stateRoot, depth, seen);
+export function listRunStateDirs(stateRoot = DEFAULT_STATE_ROOT) {
+    return RunsIndex.listRunStateDirs(stateRoot);
 }
 export function rebuildRunStateIndex(stateRoot = DEFAULT_STATE_ROOT) {
     return RunsIndex.rebuildRunStateIndex(stateRoot, getRunStatus);
@@ -333,6 +373,67 @@ export function readRunStateIndex(stateRoot = DEFAULT_STATE_ROOT) {
 export function listRuns(stateRoot = DEFAULT_STATE_ROOT, statusFilter) {
     return RunsIndex.listRuns(stateRoot, getRunStatus, readJson, statusFilter);
 }
+export function teardownRunsOwnedByParent(ownerId, stateRoot = DEFAULT_STATE_ROOT, options = {}) {
+    const result = RunsParentTeardown.teardownParentRuns(ownerId, {
+        getRunStatus,
+        killRun,
+        listRunStatuses: () => {
+            const discovered = RunsIndex.discoverRunStateDirs(stateRoot, Number.POSITIVE_INFINITY);
+            const failures = discovered.issues.map((issue) => ({
+                path: issue.path,
+                reason: issue.reason.replaceAll("_", " "),
+            }));
+            const statuses = discovered.stateDirs.flatMap((stateDir) => {
+                try {
+                    return [getRunStatus(stateDir)];
+                }
+                catch (error) {
+                    failures.push({
+                        path: stateDir,
+                        reason: error instanceof Error ? error.message : String(error),
+                    });
+                    return [];
+                }
+            });
+            return { failures, statuses };
+        },
+        recordAttempt: (attempt) => {
+            const current = getRunStatus(attempt.stateDir);
+            if (!attempt.runInstanceId ||
+                current.run_instance_id !== attempt.runInstanceId) {
+                throw new Error("run generation changed before teardown evidence");
+            }
+            writeFileSync(join(attempt.stateDir, "events.jsonl"), `${JSON.stringify({
+                event: "run.parent_teardown",
+                ownerId: attempt.ownerId,
+                outcome: attempt.outcome,
+                reason: attempt.reason,
+                run: attempt.run,
+                run_instance_id: attempt.runInstanceId,
+                type: "control.kill",
+                trigger: options.trigger ?? "parent_shutdown",
+                ts: new Date().toISOString(),
+            })}\n`, { flag: "a" });
+        },
+    });
+    const summaryPath = join(stateRoot, "teardown", `${Date.now()}-${randomUUID()}.json`);
+    try {
+        writeJsonAtomic(summaryPath, RunsParentTeardown.buildBoundedParentTeardownSummary(result, ownerId ?? "unknown", options.trigger ?? "parent_shutdown", new Date().toISOString()));
+        return { ...result, summaryPath };
+    }
+    catch (error) {
+        const failure = {
+            path: summaryPath,
+            reason: `summary: ${error instanceof Error ? error.message : String(error)}`,
+        };
+        return {
+            ...result,
+            discoveryFailed: result.discoveryFailed + 1,
+            discoveryFailures: [...result.discoveryFailures, failure],
+            failed: result.failed + 1,
+        };
+    }
+}
 export function tailRun(runOrDir, lines = 40) {
     const status = getRunStatus(runOrDir);
     const stateDir = String(status.state_dir);
@@ -441,11 +542,11 @@ function finalizeInterruptedReviewEvidence(stateDir, phase, signal) {
                 return {
                     attempt: index + 1,
                     stdout: {
-                        path: relative(stateDir, stdoutFile),
+                        path: relative(stateDir, stdoutFile).replaceAll("\\", "/"),
                         bytes: existsSync(stdoutFile) ? statSync(stdoutFile).size : 0,
                     },
                     stderr: {
-                        path: relative(stateDir, stderrFile),
+                        path: relative(stateDir, stderrFile).replaceAll("\\", "/"),
                         bytes: existsSync(stderrFile) ? statSync(stderrFile).size : 0,
                     },
                 };
@@ -470,17 +571,38 @@ function finalizeInterruptedReviewEvidence(stateDir, phase, signal) {
         updated_at: completedAt,
     });
 }
-function stopRun(runOrDir, signal, event) {
-    const status = getRunStatus(runOrDir);
-    const pid = Number(status.pid || 0);
-    const stateDir = String(status.state_dir);
-    if (status.status !== "running" && status.status !== "exited") {
-        return { stopped: false, reason: "not running", status };
-    }
-    const identity = verifyRunProcessIdentity(pid, status.process_identity);
-    if (status.status === "exited") {
-        if (identity.status === "owner_mismatch" ||
-            identity.status === "unsupported_proof") {
+function stopRun(runOrDir, signal, event, expected = {}) {
+    const stateDir = resolveRunStateDir(runOrDir);
+    const releaseControlLock = RunsStart.acquireStateStartLock(stateDir);
+    try {
+        expected.onLocked?.();
+        const status = getRunStatus(stateDir);
+        if (expected.ownerId !== undefined &&
+            status.ownerId !== expected.ownerId) {
+            return { stopped: false, reason: "ownership changed", status };
+        }
+        if (expected.runInstanceId !== undefined &&
+            status.run_instance_id !== expected.runInstanceId) {
+            return { stopped: false, reason: "run generation changed", status };
+        }
+        const pid = Number(status.pid || 0);
+        if (status.status !== "running" && status.status !== "exited") {
+            return { stopped: false, reason: "not running", status };
+        }
+        const identity = verifyRunProcessIdentity(pid, status.process_identity);
+        if (status.status === "exited") {
+            if (identity.status === "owner_mismatch" ||
+                identity.status === "unsupported_proof") {
+                return {
+                    stopped: false,
+                    reason: identity.status.replaceAll("_", " "),
+                    process_identity_status: identity.status,
+                    status,
+                };
+            }
+            return { stopped: false, reason: "not running", status };
+        }
+        if (!identity.valid) {
             return {
                 stopped: false,
                 reason: identity.status.replaceAll("_", " "),
@@ -488,28 +610,22 @@ function stopRun(runOrDir, signal, event) {
                 status,
             };
         }
-        return { stopped: false, reason: "not running", status };
-    }
-    if (!identity.valid) {
-        return {
-            stopped: false,
-            reason: identity.status.replaceAll("_", " "),
-            process_identity_status: identity.status,
-            status,
-        };
-    }
-    const signalResult = signalOwnedRunProcess(pid, signal);
-    writeFileSync(join(stateDir, "events.jsonl"), `${JSON.stringify({ event, pid, signal, ...signalResult, ts: new Date().toISOString() })}\n`, { flag: "a" });
-    markTerminalHandled(stateDir, { event, signal });
-    if (event === "run.kill") {
-        finalizeInterruptedReviewEvidence(stateDir, "killed", signal);
-        markTerminalProgress(stateDir, "killed");
+        const signalResult = signalOwnedRunProcess(pid, signal, status.process_identity);
+        writeFileSync(join(stateDir, "events.jsonl"), `${JSON.stringify({ event, pid, signal, ...signalResult, ts: new Date().toISOString() })}\n`, { flag: "a" });
+        markTerminalHandled(stateDir, { event, signal });
+        if (event === "run.kill") {
+            finalizeInterruptedReviewEvidence(stateDir, "killed", signal);
+            markTerminalProgress(stateDir, "killed");
+        }
+        if (event === "run.cancel") {
+            finalizeInterruptedReviewEvidence(stateDir, "cancelled", signal);
+            markTerminalProgress(stateDir, "cancelled");
+        }
+        return { stopped: true, pid, signal, ...signalResult, state_dir: stateDir };
     }
-    if (event === "run.cancel") {
-        finalizeInterruptedReviewEvidence(stateDir, "cancelled", signal);
-        markTerminalProgress(stateDir, "cancelled");
+    finally {
+        releaseControlLock();
     }
-    return { stopped: true, pid, signal, ...signalResult, state_dir: stateDir };
 }
 export function markRunTerminalNotificationHandled(stateDir, status) {
     markTerminalHandled(stateDir, {
@@ -517,8 +633,22 @@ export function markRunTerminalNotificationHandled(stateDir, status) {
         status,
     });
 }
-export function cancelRun(runOrDir) {
-    const result = stopRun(runOrDir, "SIGTERM", "run.cancel");
+export function recordRunTerminalDeliveryFailure(stateDir, status, error) {
+    const path = join(stateDir, "terminal-delivery-failure.json");
+    const previous = readJson(path);
+    const message = (error instanceof Error ? error.message : String(error))
+        .replaceAll(/\s+/g, " ")
+        .trim()
+        .slice(0, 500);
+    writeJsonAtomic(path, {
+        attempts: Math.max(0, Number(previous?.attempts ?? 0)) + 1,
+        error: message || "unknown delivery failure",
+        status,
+        ts: new Date().toISOString(),
+    });
+}
+export function cancelRun(runOrDir, expected = {}) {
+    const result = stopRun(runOrDir, "SIGTERM", "run.cancel", expected);
     return Object.hasOwn(result, "stopped")
         ? { cancelled: result.stopped, ...result }
         : result;
@@ -536,8 +666,8 @@ export function archiveRun(runOrDir) {
 export function pruneRun(runOrDir, options = {}) {
     return pruneTerminalRun(assertTerminalRun(runOrDir), options);
 }
-export function killRun(runOrDir) {
-    const result = stopRun(runOrDir, "SIGKILL", "run.kill");
+export function killRun(runOrDir, expected = {}) {
+    const result = stopRun(runOrDir, "SIGKILL", "run.kill", expected);
     return Object.hasOwn(result, "stopped")
         ? { killed: result.stopped, ...result }
         : result;

package/dist/lib/automatic-review-runtime.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Automatic recipe-review runtime composition.
+ * Zones: session-bound review schedulers, silent reviewer launch adapters, review controls
+ * Owns automatic-review lifecycle wiring without owning review decisions or filesystem transactions.
+ */
+import type * as Pi from "./pi.ts";
+export interface AutomaticReviewRuntime {
+    close(): void;
+    handleMessage(type: string, body: unknown): Record<string, unknown>;
+    schedule(): void;
+    start(ctx: Pi.ExtensionContext): void;
+}
+export interface AutomaticReviewRuntimeDeps {
+    getActiveContext(): Pi.ExtensionContext | undefined;
+    getRunOwnerId(ctx: Pi.ExtensionContext): string;
+    getThinkingLevel(): unknown;
+}
+export declare function createAutomaticReviewRuntime(deps: AutomaticReviewRuntimeDeps): AutomaticReviewRuntime;

package/dist/lib/automatic-review-runtime.js

@@ -0,0 +1,96 @@
+/**
+ * Automatic recipe-review runtime composition.
+ * Zones: session-bound review schedulers, silent reviewer launch adapters, review controls
+ * Owns automatic-review lifecycle wiring without owning review decisions or filesystem transactions.
+ */
+import { join } from "node:path";
+import * as AsyncRuns from "./async-runs.js";
+import * as DraftSleep from "./draft-sleep.js";
+import * as ModelContext from "./model-context.js";
+import * as Paths from "./paths.js";
+import * as ReviewControl from "./review-control.js";
+import * as ToolReviewScheduler from "./tool-review-scheduler.js";
+export function createAutomaticReviewRuntime(deps) {
+    let draftScheduler;
+    let toolScheduler;
+    const close = () => {
+        draftScheduler?.close();
+        draftScheduler = undefined;
+        toolScheduler?.close();
+        toolScheduler = undefined;
+    };
+    const hasActiveActors = () => AsyncRuns.listRuns(Paths.EXTENSION_RUNTIME_PATHS.runStateRoot, "running").length > 0;
+    const policyValues = (ctx) => ModelContext.withCurrentModelValues({}, {
+        ...ctx,
+        getThinkingLevel: deps.getThinkingLevel,
+    });
+    return {
+        close,
+        handleMessage(type, body) {
+            if (type !== "review.retry" && type !== "review.reset") {
+                throw new Error("tool:pi-actors accepts review.retry or review.reset messages.");
+            }
+            if (type === "review.retry" && !Paths.isAutomaticRecipeReviewEnabled()) {
+                throw new Error("Automatic recipe review is disabled by PI_ACTORS_AUTOMATIC_REVIEW.");
+            }
+            return ReviewControl.controlAutomaticReview(type, ReviewControl.parseAutomaticReviewScope(body), {
+                scheduleDraft: () => draftScheduler?.schedule(),
+                scheduleTool: () => toolScheduler?.schedule(),
+            });
+        },
+        schedule() {
+            draftScheduler?.schedule();
+            toolScheduler?.schedule();
+        },
+        start(ctx) {
+            close();
+            if (!Paths.isAutomaticRecipeReviewEnabled())
+                return;
+            ToolReviewScheduler.applyApprovedToolReviewAtSessionBoundary({
+                recipeRoot: Paths.getRecipeRoot(),
+            });
+            draftScheduler = DraftSleep.createDraftSleepScheduler({
+                hasActiveActors,
+                launch: (batch) => {
+                    if (deps.getActiveContext() !== ctx) {
+                        throw new Error("Draft review session changed before launch.");
+                    }
+                    return AsyncRuns.startRun({
+                        file: join(Paths.getPackagedRecipeRoot(), "draft-review.json"),
+                        launch_source: "tool",
+                        notification_policy: "silent",
+                        ownerId: deps.getRunOwnerId(ctx),
+                        policy_values: policyValues(ctx),
+                        run_id: DraftSleep.draftSleepRunId(batch.batchId),
+                        values: { input_path: batch.reviewerInputPath },
+                    }, ctx.cwd);
+                },
+                process: (state) => DraftSleep.processDraftSleepReview(state, {
+                    getRunStatus: AsyncRuns.getRunStatus,
+                    recipeRoot: Paths.getRecipeRoot(),
+                }),
+            });
+            toolScheduler = ToolReviewScheduler.createToolReviewScheduler({
+                hasActiveActors,
+                launch: (batch) => {
+                    if (deps.getActiveContext() !== ctx) {
+                        throw new Error("Tool review session changed before launch.");
+                    }
+                    return AsyncRuns.startRun({
+                        file: join(Paths.getPackagedRecipeRoot(), "tool-review.json"),
+                        launch_source: "tool",
+                        notification_policy: "silent",
+                        ownerId: deps.getRunOwnerId(ctx),
+                        policy_values: policyValues(ctx),
+                        run_id: ToolReviewScheduler.toolReviewRunId(batch.reviewId),
+                        values: { input_path: batch.reviewerInputPath },
+                    }, ctx.cwd);
+                },
+                process: (state) => ToolReviewScheduler.processToolReviewResult(state, {
+                    getRunStatus: AsyncRuns.getRunStatus,
+                    recipeRoot: Paths.getRecipeRoot(),
+                }),
+            });
+        },
+    };
+}

package/dist/lib/command-templates.js

@@ -344,7 +344,7 @@ export function splitCommandTemplate(input) {
     let active = false;
     for (const char of input) {
         if (escaped) {
-            current += char;
+            current += /[\s'"\\]/u.test(char) ? char : `\\${char}`;
             escaped = false;
             active = true;
             continue;

package/dist/lib/draft-consolidation-transaction.d.ts

@@ -0,0 +1,65 @@
+/**
+ * Deterministic draft consolidation transaction and crash recovery.
+ * Owns: cycle claim, source/target compare-and-swap, complete recipe persistence, source quarantine, journal transitions, rollback, and runtime evidence.
+ */
+import type { DraftConsolidationPlan } from "./draft-consolidation.ts";
+import { type DraftConsolidationInventoryItem } from "./draft-consolidation.ts";
+export type DraftConsolidationTransactionPhase = "prepared" | "targets_validated" | "sources_quarantined" | "committed_evidence_pending" | "committed" | "rolled_back" | "rollback_required";
+interface TargetOperation {
+    backupPath?: string;
+    expectedSha256: string | null;
+    intendedSha256: string;
+    path: string;
+    recipe: Record<string, unknown>;
+    target: string;
+}
+interface SourceOperation {
+    path: string;
+    quarantinePath: string;
+    sha256: string;
+}
+interface ConsolidationRootIdentity {
+    dev: string;
+    ino: string;
+    path: string;
+    realpath: string;
+}
+interface ConsolidationRootIdentities {
+    cycleDir: ConsolidationRootIdentity;
+    draftRoot: ConsolidationRootIdentity;
+    recipeRoot: ConsolidationRootIdentity;
+}
+export interface DraftConsolidationJournal {
+    cycleId: string;
+    error?: string;
+    operationsSha256: string;
+    phase: DraftConsolidationTransactionPhase;
+    plan: DraftConsolidationPlan;
+    planSha256: string;
+    roots: ConsolidationRootIdentities;
+    sourceScope: "batch" | "complete";
+    sources: SourceOperation[];
+    targets: TargetOperation[];
+    updatedAt: string;
+}
+export type DraftConsolidationCheckpoint = "prepared" | "target_written" | "targets_validated" | "source_quarantined" | "sources_quarantined" | "committed_evidence_pending" | "evidence_written";
+export interface DraftConsolidationTransactionOptions {
+    checkpoint?(point: DraftConsolidationCheckpoint): void;
+    cycleDir: string;
+    draftRoot: string;
+    inventory: DraftConsolidationInventoryItem[];
+    onLockContention?(): void;
+    sourceScope?: "batch" | "complete";
+    recipeRoot: string;
+}
+export interface DraftConsolidationTransactionResult {
+    cycleId: string;
+    evidencePath: string;
+    phase: "committed" | "rolled_back";
+    plan: DraftConsolidationPlan;
+    sources: number;
+    targets: number;
+}
+export declare function applyDraftConsolidationPlan(plan: DraftConsolidationPlan, options: DraftConsolidationTransactionOptions): DraftConsolidationTransactionResult;
+export declare function recoverDraftConsolidationCycle(options: Pick<DraftConsolidationTransactionOptions, "cycleDir" | "draftRoot" | "recipeRoot">): DraftConsolidationTransactionResult;
+export {};