@rulvar/executor 1.90.0 → 1.92.0

package/dist/index.d.ts

@@ -2,7 +2,7 @@ import { IsolatedExecRequest, IsolatedExecutorTag, SchemaSpec, ToolDef, ToolExec
 
 //#region src/spi.d.ts
 /** Why an isolated dispatch failed. */
-type ExecutorErrorCode = "config" | "timeout" | "aborted" | "output-cap" | "exit" | "protocol" | "spawn";
+type ExecutorErrorCode = "config" | "timeout" | "aborted" | "output-cap" | "exit" | "protocol" | "spawn" | "ledger";
 /**
 * A failed isolated dispatch. The engine catches whatever a
 * ToolExecutorProvider throws and turns it into the call's error tool
@@ -13,8 +13,15 @@ declare class ExecutorError extends Error {
   readonly code: ExecutorErrorCode;
   constructor(code: ExecutorErrorCode, message: string);
 }
-/** One dispatch's side-effect facts, for the ledger. */
-interface ToolEffectRecord {
+/**
+* The pre-dispatch half of a two-phase ledger entry (RV404): everything
+* the executor knows BEFORE the external effect is dispatched, which is
+* exactly the set a host needs to reconcile an orphaned effect with the
+* effect's provider (look the idempotency key up, correlate by tool and
+* argsHash). `startedAt` is the attempt join key: the outcome record of
+* the same attempt carries the identical value.
+*/
+interface ToolEffectIntent {
   /** The stable per-call idempotency key (createEngine derives it). */
   idempotencyKey: string;
   runId: string;
@@ -23,9 +30,12 @@ interface ToolEffectRecord {
   /** sha256 of the canonical arguments: correlates without storing them. */
   argsHash: string;
   executor: IsolatedExecutorTag;
-  /** The ephemeral working directory the dispatch ran in. */
+  /** The ephemeral working directory the dispatch runs in. */
   workdir: string;
   startedAt: number;
+}
+/** One dispatch's side-effect facts, for the ledger. */
+interface ToolEffectRecord extends ToolEffectIntent {
   durationMs: number;
   outcome: "ok" | "error" | "timeout";
   /** Child exit code, or null when terminated by a signal. */
@@ -42,10 +52,28 @@ interface ToolEffectRecord {
 */
 interface ToolEffectLedger {
   record(entry: ToolEffectRecord): void | Promise<void>;
+  /**
+  * The two-phase capability (RV404): when the method is present, the
+  * reference executors durably record the intent BEFORE the external
+  * effect is dispatched (awaited; a failed write refuses the dispatch
+  * with the typed `ledger` code) and the outcome `record` after it. A
+  * host crash between the effect and the outcome row then leaves an
+  * orphan intent, the reconciliation signal, instead of an untracked
+  * effect: an intent whose idempotency key has no outcome row means
+  * "look this key up with the effect's provider before retrying or
+  * compensating". Absent, the ledger keeps the historical
+  * single-record contract and executor behavior is byte-identical.
+  */
+  intent?(entry: ToolEffectIntent): void | Promise<void>;
 }
-/** An in-memory ledger for tests and single-process hosts. */
+/**
+* An in-memory ledger for tests and single-process hosts. It implements
+* the two-phase capability: `intents()` exposes the pre-dispatch rows,
+* `entries()` the outcomes, exactly as before.
+*/
 declare function memoryEffectLedger(): ToolEffectLedger & {
   entries(): readonly ToolEffectRecord[];
+  intents(): readonly ToolEffectIntent[];
 };
 /**
 * A stable content hash of the arguments for the ledger's `argsHash`. It
@@ -197,6 +225,35 @@ interface ContainerExecutorOptions {
 */
 declare function containerExecutor(options: ContainerExecutorOptions): ToolExecutorProvider;
 //#endregion
+//#region src/ledger.d.ts
+/**
+* A two-phase ToolEffectLedger appending JSON lines to `path`
+* (`{ phase: 'intent' | 'outcome', ... }`). Pass it to
+* `subprocessExecutor({ ledger })` or `containerExecutor({ ledger })`;
+* scan it back with {@link loadEffectLedger}.
+*/
+declare function jsonlEffectLedger(path: string): ToolEffectLedger;
+/** What {@link loadEffectLedger} reads back from a JSONL ledger file. */
+interface EffectLedgerScan {
+  intents: ToolEffectIntent[];
+  outcomes: ToolEffectRecord[];
+  /**
+  * The reconciliation signal (RV404): every intent whose idempotency
+  * key has NO outcome row at all. A key with a later outcome (an
+  * at-least-once retry of the same logical call that completed) is not
+  * orphaned: the retry resolved it. For each orphan, look the key up
+  * with the effect's provider before retrying or compensating.
+  */
+  orphanedIntents: ToolEffectIntent[];
+}
+/**
+* Scans a JSONL ledger file into intents, outcomes, and the orphaned
+* intents a host must reconcile. A torn trailing line (the artifact of
+* a crash mid-write) is skipped, never a scan failure: the durable rows
+* before it are exactly what reconciliation needs.
+*/
+declare function loadEffectLedger(path: string): Promise<EffectLedgerScan>;
+//#endregion
 //#region src/conformance.d.ts
 /** The executor options the shared contract exercises. */
 interface ConformanceExecutorConfig {
@@ -206,7 +263,7 @@ interface ConformanceExecutorConfig {
   credentials?: (request: IsolatedExecRequest) => Record<string, string>;
   timeoutMs?: number;
   maxOutputBytes?: number;
-  ledger?: ReturnType<typeof memoryEffectLedger>;
+  ledger?: ToolEffectLedger;
 }
 /** Builds the provider under test from a shared-contract config. */
 type ConformanceExecutorFactory = (config: ConformanceExecutorConfig) => ToolExecutorProvider;
@@ -280,4 +337,4 @@ interface ChildResult {
 */
 declare function runChildProcess(spec: ChildSpec): Promise<ChildResult>;
 //#endregion
-export { type ChildResult, type ChildSpec, type ChildStopReason, type ConformanceExecutorConfig, type ConformanceExecutorFactory, type ContainerExecutorOptions, type ExecutorConformanceCheck, type ExecutorConformanceSuite, ExecutorError, type ExecutorErrorCode, type ExecutorTestRegistrar, type SubprocessCommandSpec, type SubprocessExecutorOptions, type SubprocessToolInit, type ToolEffectLedger, type ToolEffectRecord, containerExecutor, executorConformance, hashArgs, memoryEffectLedger, parseToolResult, registerExecutorConformance, runChildProcess, subprocessExecutor, subprocessTool };
+export { type ChildResult, type ChildSpec, type ChildStopReason, type ConformanceExecutorConfig, type ConformanceExecutorFactory, type ContainerExecutorOptions, type EffectLedgerScan, type ExecutorConformanceCheck, type ExecutorConformanceSuite, ExecutorError, type ExecutorErrorCode, type ExecutorTestRegistrar, type SubprocessCommandSpec, type SubprocessExecutorOptions, type SubprocessToolInit, type ToolEffectIntent, type ToolEffectLedger, type ToolEffectRecord, containerExecutor, executorConformance, hashArgs, jsonlEffectLedger, loadEffectLedger, memoryEffectLedger, parseToolResult, registerExecutorConformance, runChildProcess, subprocessExecutor, subprocessTool };

package/dist/index.js

@@ -1,10 +1,10 @@
-import { mkdtemp, rm } from "node:fs/promises";
+import { appendFile, mkdtemp, readFile, rm } from "node:fs/promises";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
 import { tool } from "@rulvar/core";
 import { spawn } from "node:child_process";
 import { createHash } from "node:crypto";
-import { existsSync, mkdtempSync, writeFileSync } from "node:fs";
+import { existsSync, mkdtempSync, readdirSync, writeFileSync } from "node:fs";
 //#region src/child.ts
 /**
 * The shared child-process runner both reference executors build on. It
@@ -132,15 +132,26 @@ var ExecutorError = class extends Error {
 		this.code = code;
 	}
 };
-/** An in-memory ledger for tests and single-process hosts. */
+/**
+* An in-memory ledger for tests and single-process hosts. It implements
+* the two-phase capability: `intents()` exposes the pre-dispatch rows,
+* `entries()` the outcomes, exactly as before.
+*/
 function memoryEffectLedger() {
 	const rows = [];
+	const intentRows = [];
 	return {
 		record(entry) {
 			rows.push(entry);
 		},
+		intent(entry) {
+			intentRows.push(entry);
+		},
 		entries() {
 			return rows;
+		},
+		intents() {
+			return intentRows;
 		}
 	};
 }
@@ -224,7 +235,26 @@ function subprocessExecutor(options = {}) {
 		const { command, args } = resolveCommand(request, options);
 		const workdir = await mkdtemp(join(workdirBase, `rulvar-exec-${request.tool}-`));
 		const startedAt = now();
-		let outcome = "ok";
+		const argsHash = hashArgs(request.args);
+		if (options.ledger?.intent !== void 0) try {
+			await options.ledger.intent({
+				idempotencyKey: request.ctx.idempotencyKey,
+				runId: request.ctx.runId,
+				spanId: request.ctx.spanId,
+				tool: request.tool,
+				argsHash,
+				executor: request.executor,
+				workdir,
+				startedAt
+			});
+		} catch (err) {
+			await rm(workdir, {
+				recursive: true,
+				force: true
+			});
+			throw new ExecutorError("ledger", `tool '${request.tool}' was not dispatched: the two-phase ledger intent write failed (${err instanceof Error ? err.message : String(err)})`);
+		}
+		let outcome = "error";
 		let exitCode = null;
 		let signal = null;
 		try {
@@ -266,7 +296,6 @@ function subprocessExecutor(options = {}) {
 					signal: request.ctx.signal
 				});
 			} catch (err) {
-				outcome = "error";
 				throw new ExecutorError("spawn", `tool '${request.tool}' could not be spawned: ${err instanceof Error ? err.message : String(err)}`);
 			}
 			exitCode = child.code;
@@ -275,25 +304,15 @@ function subprocessExecutor(options = {}) {
 				outcome = "timeout";
 				throw new ExecutorError("timeout", `tool '${request.tool}' exceeded ${timeoutMs}ms and was killed`);
 			}
-			if (child.stopped && child.reason === "aborted") {
-				outcome = "error";
-				throw new ExecutorError("aborted", `tool '${request.tool}' was cancelled`);
-			}
-			if (child.stopped && child.reason === "output-cap") {
-				outcome = "error";
-				throw new ExecutorError("output-cap", `tool '${request.tool}' wrote more than ${maxOutputBytes} bytes and was killed`);
-			}
+			if (child.stopped && child.reason === "aborted") throw new ExecutorError("aborted", `tool '${request.tool}' was cancelled`);
+			if (child.stopped && child.reason === "output-cap") throw new ExecutorError("output-cap", `tool '${request.tool}' wrote more than ${maxOutputBytes} bytes and was killed`);
 			if (child.code !== 0) {
-				outcome = "error";
 				const tail = child.stderr.trim().slice(-500);
 				throw new ExecutorError("exit", `tool '${request.tool}' exited ${child.code ?? "null"}${child.signal === null ? "" : ` (signal ${child.signal})`}${tail === "" ? "" : `: ${tail}`}`);
 			}
-			try {
-				return parseToolResult(child.stdout, request.tool);
-			} catch (err) {
-				outcome = "error";
-				throw err;
-			}
+			const result = parseToolResult(child.stdout, request.tool);
+			outcome = "ok";
+			return result;
 		} finally {
 			const durationMs = now() - startedAt;
 			if (options.ledger !== void 0) await options.ledger.record({
@@ -301,7 +320,7 @@ function subprocessExecutor(options = {}) {
 				runId: request.ctx.runId,
 				spanId: request.ctx.spanId,
 				tool: request.tool,
-				argsHash: hashArgs(request.args),
+				argsHash,
 				executor: request.executor,
 				workdir,
 				startedAt,
@@ -404,7 +423,26 @@ function containerExecutor(options) {
 		const toolArgs = [...options.args ?? [], ...specArgs];
 		const workdir = await mkdtemp(join(workdirBase, `rulvar-cexec-${request.tool}-`));
 		const startedAt = now();
-		let outcome = "ok";
+		const argsHash = hashArgs(request.args);
+		if (options.ledger?.intent !== void 0) try {
+			await options.ledger.intent({
+				idempotencyKey: request.ctx.idempotencyKey,
+				runId: request.ctx.runId,
+				spanId: request.ctx.spanId,
+				tool: request.tool,
+				argsHash,
+				executor: request.executor,
+				workdir,
+				startedAt
+			});
+		} catch (err) {
+			await rm(workdir, {
+				recursive: true,
+				force: true
+			});
+			throw new ExecutorError("ledger", `container tool '${request.tool}' was not dispatched: the two-phase ledger intent write failed (${err instanceof Error ? err.message : String(err)})`);
+		}
+		let outcome = "error";
 		let exitCode = null;
 		let signal = null;
 		try {
@@ -466,7 +504,6 @@ function containerExecutor(options) {
 					signal: request.ctx.signal
 				});
 			} catch (err) {
-				outcome = "error";
 				throw new ExecutorError("spawn", `container tool '${request.tool}' could not launch '${docker}': ${err instanceof Error ? err.message : String(err)}`);
 			}
 			exitCode = child.code;
@@ -475,25 +512,15 @@ function containerExecutor(options) {
 				outcome = "timeout";
 				throw new ExecutorError("timeout", `container tool '${request.tool}' exceeded ${timeoutMs}ms and was killed`);
 			}
-			if (child.stopped && child.reason === "aborted") {
-				outcome = "error";
-				throw new ExecutorError("aborted", `container tool '${request.tool}' was cancelled`);
-			}
-			if (child.stopped && child.reason === "output-cap") {
-				outcome = "error";
-				throw new ExecutorError("output-cap", `container tool '${request.tool}' wrote more than ${maxOutputBytes} bytes and was killed`);
-			}
+			if (child.stopped && child.reason === "aborted") throw new ExecutorError("aborted", `container tool '${request.tool}' was cancelled`);
+			if (child.stopped && child.reason === "output-cap") throw new ExecutorError("output-cap", `container tool '${request.tool}' wrote more than ${maxOutputBytes} bytes and was killed`);
 			if (child.code !== 0) {
-				outcome = "error";
 				const tail = child.stderr.trim().slice(-500);
 				throw new ExecutorError("exit", `container tool '${request.tool}' exited ${child.code ?? "null"}${tail === "" ? "" : `: ${tail}`}`);
 			}
-			try {
-				return parseToolResult(child.stdout, request.tool);
-			} catch (err) {
-				outcome = "error";
-				throw err;
-			}
+			const result = parseToolResult(child.stdout, request.tool);
+			outcome = "ok";
+			return result;
 		} finally {
 			const durationMs = now() - startedAt;
 			if (options.ledger !== void 0) await options.ledger.record({
@@ -501,7 +528,7 @@ function containerExecutor(options) {
 				runId: request.ctx.runId,
 				spanId: request.ctx.spanId,
 				tool: request.tool,
-				argsHash: hashArgs(request.args),
+				argsHash,
 				executor: request.executor,
 				workdir,
 				startedAt,
@@ -518,6 +545,78 @@ function containerExecutor(options) {
 	} };
 }
 //#endregion
+//#region src/ledger.ts
+/**
+* The durable JSONL reference of the two-phase effect ledger (RV404):
+* one JSON line per phase, appended and awaited, so the intent row is
+* on disk before the external effect is dispatched and survives a host
+* process crash between the effect and the outcome write. What it is
+* NOT: a transactional outbox, business authorization, or monetary
+* reconciliation; those stay host obligations, this file is the strict
+* interface the host reconciles FROM.
+*
+* Durability boundary, stated honestly: an awaited append survives a
+* process crash (the write has entered the kernel), not necessarily a
+* power loss before the OS flushes; a host that needs power-loss
+* durability wraps the seam over its own fsync or database write.
+*/
+/**
+* A two-phase ToolEffectLedger appending JSON lines to `path`
+* (`{ phase: 'intent' | 'outcome', ... }`). Pass it to
+* `subprocessExecutor({ ledger })` or `containerExecutor({ ledger })`;
+* scan it back with {@link loadEffectLedger}.
+*/
+function jsonlEffectLedger(path) {
+	const append = (line) => appendFile(path, `${JSON.stringify(line)}\n`, "utf8");
+	return {
+		intent(entry) {
+			return append({
+				phase: "intent",
+				...entry
+			});
+		},
+		record(entry) {
+			return append({
+				phase: "outcome",
+				...entry
+			});
+		}
+	};
+}
+/**
+* Scans a JSONL ledger file into intents, outcomes, and the orphaned
+* intents a host must reconcile. A torn trailing line (the artifact of
+* a crash mid-write) is skipped, never a scan failure: the durable rows
+* before it are exactly what reconciliation needs.
+*/
+async function loadEffectLedger(path) {
+	const raw = await readFile(path, "utf8");
+	const intents = [];
+	const outcomes = [];
+	for (const line of raw.split("\n")) {
+		if (line.trim() === "") continue;
+		let parsed;
+		try {
+			parsed = JSON.parse(line);
+		} catch {
+			continue;
+		}
+		if (parsed.phase === "intent") {
+			const { phase: _phase, ...entry } = parsed;
+			intents.push(entry);
+		} else if (parsed.phase === "outcome") {
+			const { phase: _phase, ...entry } = parsed;
+			outcomes.push(entry);
+		}
+	}
+	const resolvedKeys = new Set(outcomes.map((entry) => entry.idempotencyKey));
+	return {
+		intents,
+		outcomes,
+		orphanedIntents: intents.filter((entry) => !resolvedKeys.has(entry.idempotencyKey))
+	};
+}
+//#endregion
 //#region src/conformance.ts
 /**
 * The executable executor conformance kit (RV-216): the shared-contract
@@ -824,6 +923,33 @@ function executorConformance(factory, options = {}) {
 				ensure(rows[0]?.outcome === "error", "e12", `a protocol failure must ledger outcome 'error', got '${String(rows[0]?.outcome)}'`);
 				ensure(rows[0]?.exitCode === 0, "e12", "the clean exit code must still be recorded");
 			}
+		},
+		{
+			id: "e13",
+			title: "a kill between the effect and the outcome write leaves the orphan intent (RV404)",
+			async run() {
+				const intents = [];
+				const emptyAtIntent = [];
+				let outcomeWrites = 0;
+				ensure((await factory({
+					command: runtime,
+					args: baseArgs,
+					ledger: {
+						intent(entry) {
+							emptyAtIntent.push(readdirSync(entry.workdir).length === 0);
+							intents.push(entry);
+						},
+						record() {
+							outcomeWrites += 1;
+						}
+					}
+				}).run(request("effector", { behavior: "workdir" }, { idempotencyKey: "k-orphan" }))).before === 0, "e13", "the effect did not run");
+				ensure(intents.length === 1, "e13", `expected 1 intent, got ${intents.length}`);
+				ensure(emptyAtIntent[0] === true, "e13", "the intent must be recorded BEFORE the effect (the workdir already had content)");
+				const orphan = intents[0];
+				ensure(orphan?.idempotencyKey === "k-orphan" && orphan.tool === "effector" && typeof orphan.argsHash === "string" && orphan.argsHash.length === 64 && orphan.runId === "conf-run" && orphan.spanId === "conf-span", "e13", "the orphan intent must carry the full reconciliation lookup set");
+				ensure(outcomeWrites === 1, "e13", "the executor must still attempt the outcome write exactly once");
+			}
 		}
 	];
 	return {
@@ -835,4 +961,4 @@ function executorConformance(factory, options = {}) {
 	};
 }
 //#endregion
-export { ExecutorError, containerExecutor, executorConformance, hashArgs, memoryEffectLedger, parseToolResult, registerExecutorConformance, runChildProcess, subprocessExecutor, subprocessTool };
+export { ExecutorError, containerExecutor, executorConformance, hashArgs, jsonlEffectLedger, loadEffectLedger, memoryEffectLedger, parseToolResult, registerExecutorConformance, runChildProcess, subprocessExecutor, subprocessTool };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rulvar/executor",
-  "version": "1.90.0",
+  "version": "1.92.0",
   "description": "Rulvar isolated tool executors: reference ToolExecutorProvider adapters that run tool work out of process (subprocess and container) so hostile or model-generated scripts cannot reach host capabilities.",
   "type": "module",
   "license": "Apache-2.0",
@@ -22,13 +22,13 @@
     "access": "public"
   },
   "dependencies": {
-    "@rulvar/core": "1.90.0"
+    "@rulvar/core": "1.92.0"
   },
   "devDependencies": {
     "@types/node": "^22.20.1",
     "tsdown": "^0.22.14",
     "typescript": "~6.0.3",
-    "@rulvar/testing": "1.90.0"
+    "@rulvar/testing": "1.92.0"
   },
   "repository": {
     "type": "git",