@rulvar/executor 1.103.0 → 1.104.0

package/dist/index.d.ts

@@ -244,11 +244,22 @@ declare function containerExecutor(options: ContainerExecutorOptions): ToolExecu
 * `subprocessExecutor({ ledger })` or `containerExecutor({ ledger })`;
 * scan it back with {@link loadEffectLedger}. The first append lazily
 * repairs a torn tail left by a crashed predecessor (RV502).
+*
+* Writer contract (RV606), stated publicly: appends are whole-line
+* O_APPEND writes, and the destructive tail repair is mutually
+* exclusive across processes (a sidecar `<path>.repair-lock` taken with
+* O_EXCL, the file re-read after capture, a stale lock stolen after a
+* ten-second TTL), so several writer processes on one LOCAL path can no
+* longer truncate away each other's confirmed rows while repairing.
+* Still, prefer ONE WRITER PER PATH, a `effects.<worker>.jsonl` file
+* per worker process merged at reconciliation time: per-line append
+* atomicity is a local-filesystem property, and neither O_APPEND nor
+* O_EXCL is dependable on network filesystems.
 */
 declare function jsonlEffectLedger(path: string, options?: {
   now?: () => number;
 }): ToolEffectLedger;
-/** One unparseable interior line of the ledger file, surfaced for triage. */
+/** One malformed line of the ledger file, surfaced for triage. */
 interface CorruptLedgerLine {
   /** 1-based physical line number in the file. */
   line: number;
@@ -256,7 +267,8 @@ interface CorruptLedgerLine {
   offset: number;
   /** sha256 (hex) of the raw line bytes: forensics without re-reading. */
   sha256: string;
-  /** The first 120 characters of the line. */
+  /** The first 120 characters of the line (lossy-decoded when the bytes
+  * are not valid UTF-8; the hash pins the exact bytes). */
   preview: string;
 }
 /** A torn fragment the writer quarantined while repairing a tail (RV502). */
@@ -267,12 +279,15 @@ interface TornLedgerArtifact {
   recoveredAt: number;
 }
 /**
-* The fail-closed refusal of {@link loadEffectLedger} (RV502): the file
-* holds at least one unparseable INTERIOR line, which the writer's tail
-* repair can never produce, so it means external damage or a second
-* writer, never a normal crash artifact. Reconciling from a partial
-* scan would silently drop intents; triage the named lines instead
-* (`tolerateCorrupt: true` surfaces them as data).
+* The fail-closed refusal of {@link loadEffectLedger} (RV502, widened
+* by RV607): the file holds at least one line the scan cannot admit,
+* unparseable bytes on an interior line, invalid UTF-8, a JSON value
+* that is not an object, a missing or mistyped required field, or an
+* unknown phase, none of which the writer's tail repair can produce, so
+* it means external damage or a foreign writer, never a normal crash
+* artifact. Reconciling from a partial scan would silently drop
+* intents; triage the named lines instead (`tolerateCorrupt: true`
+* surfaces them as data).
 */
 declare class LedgerCorruptionError extends Error {
   readonly lines: CorruptLedgerLine[];
@@ -296,9 +311,11 @@ interface EffectLedgerScan {
   */
   orphanedIntents: ToolEffectIntent[];
   /**
-  * Unparseable interior lines, populated only under `tolerateCorrupt`
-  * (the default scan throws {@link LedgerCorruptionError} instead).
-  * Empty on a healthy file.
+  * Lines the scan refused to admit (RV607): unparseable interior
+  * bytes, invalid UTF-8, non-object JSON, a missing or mistyped
+  * required field, or an unknown phase. Populated only under
+  * `tolerateCorrupt` (the default scan throws
+  * {@link LedgerCorruptionError} instead). Empty on a healthy file.
   */
   corrupt: CorruptLedgerLine[];
   /** Fragments the writer quarantined while repairing torn tails (RV502). */
@@ -306,7 +323,10 @@ interface EffectLedgerScan {
   /**
   * A live unterminated, unparseable trailing fragment: the artifact of
   * a crash mid-write no writer has repaired yet. Tolerated and named,
-  * never silent.
+  * never silent. (An unterminated line that PARSES but fails the shape
+  * is corruption instead: a torn prefix of the writer's own flat
+  * record can never parse, so such a line is foreign, not a crash
+  * artifact.)
   */
   tornTail?: {
     preview: string;
@@ -316,9 +336,12 @@ interface EffectLedgerScan {
 * Scans a JSONL ledger file into intents, outcomes, and the orphaned
 * intents a host must reconcile, pairing attempts exactly (RV501). A
 * torn TRAILING fragment (the crash-mid-write artifact) is tolerated
-* and reported; an unparseable INTERIOR line fails the scan closed with
-* a typed {@link LedgerCorruptionError} unless `tolerateCorrupt` asks
-* for the lines as data (RV502).
+* and reported; everything else the scan cannot decode, parse, and
+* validate, invalid UTF-8, non-object JSON, a missing required field,
+* an unknown phase (RV607), fails the scan closed with a typed
+* {@link LedgerCorruptionError} unless `tolerateCorrupt` asks for the
+* lines as data (RV502). Under `tolerateCorrupt` the scan never throws
+* anything rawer than that: a malformed line is data, not an exception.
 */
 declare function loadEffectLedger(path: string, options?: {
   tolerateCorrupt?: boolean;

package/dist/index.js

@@ -1,5 +1,5 @@
 import { createHash, randomUUID } from "node:crypto";
-import { appendFile, mkdtemp, readFile, rm, truncate } from "node:fs/promises";
+import { appendFile, mkdtemp, readFile, rm, stat, truncate, writeFile } from "node:fs/promises";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
 import { tool } from "@rulvar/core";
@@ -580,11 +580,12 @@ function containerExecutor(options) {
 //#region src/ledger.ts
 /**
 * The durable JSONL reference of the two-phase effect ledger (RV404,
-* hardened by RV501/RV502): 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
+* hardened by RV501/RV502, cross-process repair exclusion RV606,
+* fail-closed scan validation RV607): 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.
 *
@@ -595,12 +596,15 @@ function containerExecutor(options) {
 * the logical idempotency key is the host reconciler's job, against
 * the effect provider's receipt.
 *
-* Recovery (RV502): before its first append the writer repairs a torn
-* tail (the artifact of a crash mid-write): a complete record missing
-* only its newline is terminated in place, an unparseable fragment is
-* truncated and quarantined verbatim as a `{"phase":"torn"}` line. A
-* later scan therefore treats an unparseable INTERIOR line as real
-* damage and fails closed instead of skipping it silently.
+* Recovery (RV502, exclusive per RV606): before its first append the
+* writer repairs a torn tail (the artifact of a crash mid-write): a
+* complete record missing only its newline is terminated in place, an
+* unparseable fragment is truncated and quarantined verbatim as a
+* `{"phase":"torn"}` line. The destructive step runs under a sidecar
+* O_EXCL lock and re-reads the file after capture, so two writer
+* processes repairing the same file can no longer erase each other's
+* confirmed rows. A later scan therefore treats an unparseable INTERIOR
+* line as real damage and fails closed instead of skipping it silently.
 *
 * Durability boundary, stated honestly: an awaited append survives a
 * process crash (the write has entered the kernel), not necessarily a
@@ -608,12 +612,96 @@ function containerExecutor(options) {
 * durability wraps the seam over its own fsync or database write.
 */
 const wallClock = Date.now.bind(globalThis);
+/** How stale a repair lock's mtime must be before a writer may presume
+* its holder crashed and steal it. Repairs take milliseconds; ten
+* seconds is a crash verdict, not a performance budget. */
+const REPAIR_LOCK_TTL_MS = 1e4;
+/** How often a writer waiting on another process's repair re-checks. */
+const REPAIR_POLL_MS = 25;
+const delay = (ms) => new Promise((resolve) => {
+	setTimeout(resolve, ms);
+});
+/**
+* The destructive half of the tail repair, mutually exclusive between
+* processes (RV606): a sidecar `<path>.repair-lock` created with O_EXCL
+* serializes repairers, and the ledger file is re-read AFTER the lock
+* is held, so a boundary computed from a read another repairer has
+* since invalidated is never truncated. A writer that loses the race
+* polls; a lock whose mtime is further than the TTL from now (either
+* direction, so a skewed clock cannot pin the file forever) is presumed
+* abandoned by a crashed holder and stolen. The residual window (a
+* holder stalled past the TTL, stolen mid-repair) is shrunk by
+* re-verifying ownership immediately before the truncate; against a
+* millisecond repair and a ten-second TTL it needs a scheduler pause no
+* healthy host exhibits.
+*/
+async function repairUnderLock(path, now) {
+	const lockPath = `${path}.repair-lock`;
+	const token = `${String(process.pid)}-${randomUUID()}`;
+	for (;;) {
+		let acquired = true;
+		try {
+			await writeFile(lockPath, token, { flag: "wx" });
+		} catch (err) {
+			if (err.code !== "EEXIST") throw err;
+			acquired = false;
+		}
+		if (!acquired) {
+			let held;
+			try {
+				held = await stat(lockPath);
+			} catch (err) {
+				if (err.code !== "ENOENT") throw err;
+				continue;
+			}
+			if (Math.abs(wallClock() - held.mtimeMs) > REPAIR_LOCK_TTL_MS) {
+				await rm(lockPath, { force: true });
+				continue;
+			}
+			await delay(REPAIR_POLL_MS);
+			continue;
+		}
+		try {
+			let raw;
+			try {
+				raw = await readFile(path);
+			} catch (err) {
+				if (err.code === "ENOENT") return;
+				throw err;
+			}
+			if (raw.length === 0 || raw[raw.length - 1] === 10) return;
+			const boundary = raw.lastIndexOf(10) + 1;
+			const fragment = raw.subarray(boundary).toString("utf8");
+			let parseable = true;
+			try {
+				JSON.parse(fragment);
+			} catch {
+				parseable = false;
+			}
+			if (parseable) {
+				await appendFile(path, "\n", "utf8");
+				return;
+			}
+			if (await readFile(lockPath, "utf8").catch(() => "") !== token) continue;
+			await truncate(path, boundary);
+			await appendFile(path, `${JSON.stringify({
+				phase: "torn",
+				bytes: fragment,
+				recoveredAt: now()
+			})}\n`, "utf8");
+			return;
+		} finally {
+			if (await readFile(lockPath, "utf8").catch(() => "") === token) await rm(lockPath, { force: true });
+		}
+	}
+}
 /**
 * Repairs the file's tail so an append can never glue onto a torn
 * fragment (RV502): a parseable unterminated record gets its newline, a
 * torn fragment is truncated and preserved verbatim in a quarantine
-* line old readers parse and skip. Runs under the ledger's documented
-* single-writer discipline.
+* line old readers parse and skip. A clean file returns untouched, byte
+* for byte, without the lock ever existing; the repair itself runs
+* under the cross-process exclusion of {@link repairUnderLock} (RV606).
 */
 async function repairTail(path, now) {
 	let raw;
@@ -624,20 +712,7 @@ async function repairTail(path, now) {
 		throw err;
 	}
 	if (raw.length === 0 || raw[raw.length - 1] === 10) return;
-	const boundary = raw.lastIndexOf(10) + 1;
-	const fragment = raw.subarray(boundary).toString("utf8");
-	try {
-		JSON.parse(fragment);
-	} catch {
-		await truncate(path, boundary);
-		await appendFile(path, `${JSON.stringify({
-			phase: "torn",
-			bytes: fragment,
-			recoveredAt: now()
-		})}\n`, "utf8");
-		return;
-	}
-	await appendFile(path, "\n", "utf8");
+	await repairUnderLock(path, now);
 }
 /**
 * A two-phase ToolEffectLedger appending JSON lines to `path`
@@ -645,6 +720,17 @@ async function repairTail(path, now) {
 * `subprocessExecutor({ ledger })` or `containerExecutor({ ledger })`;
 * scan it back with {@link loadEffectLedger}. The first append lazily
 * repairs a torn tail left by a crashed predecessor (RV502).
+*
+* Writer contract (RV606), stated publicly: appends are whole-line
+* O_APPEND writes, and the destructive tail repair is mutually
+* exclusive across processes (a sidecar `<path>.repair-lock` taken with
+* O_EXCL, the file re-read after capture, a stale lock stolen after a
+* ten-second TTL), so several writer processes on one LOCAL path can no
+* longer truncate away each other's confirmed rows while repairing.
+* Still, prefer ONE WRITER PER PATH, a `effects.<worker>.jsonl` file
+* per worker process merged at reconciliation time: per-line append
+* atomicity is a local-filesystem property, and neither O_APPEND nor
+* O_EXCL is dependable on network filesystems.
 */
 function jsonlEffectLedger(path, options) {
 	const now = options?.now ?? wallClock;
@@ -670,29 +756,60 @@ function jsonlEffectLedger(path, options) {
 	};
 }
 /**
-* The fail-closed refusal of {@link loadEffectLedger} (RV502): the file
-* holds at least one unparseable INTERIOR line, which the writer's tail
-* repair can never produce, so it means external damage or a second
-* writer, never a normal crash artifact. Reconciling from a partial
-* scan would silently drop intents; triage the named lines instead
-* (`tolerateCorrupt: true` surfaces them as data).
+* The fail-closed refusal of {@link loadEffectLedger} (RV502, widened
+* by RV607): the file holds at least one line the scan cannot admit,
+* unparseable bytes on an interior line, invalid UTF-8, a JSON value
+* that is not an object, a missing or mistyped required field, or an
+* unknown phase, none of which the writer's tail repair can produce, so
+* it means external damage or a foreign writer, never a normal crash
+* artifact. Reconciling from a partial scan would silently drop
+* intents; triage the named lines instead (`tolerateCorrupt: true`
+* surfaces them as data).
 */
 var LedgerCorruptionError = class extends Error {
 	lines;
 	constructor(path, lines) {
 		const first = lines[0];
-		super(`effect ledger '${path}' has ${String(lines.length)} corrupt interior line(s); first at line ${String(first?.line)}, byte ${String(first?.offset)}, sha256 ${String(first?.sha256)}. An interior line the scan cannot parse means external damage or a second writer; reconciliation must not proceed from a partial scan (loadEffectLedger with { tolerateCorrupt: true } surfaces the lines for triage).`);
+		super(`effect ledger '${path}' has ${String(lines.length)} corrupt line(s); first at line ${String(first?.line)}, byte ${String(first?.offset)}, sha256 ${String(first?.sha256)}. A line the scan cannot decode, parse, and validate means external damage or a foreign writer; reconciliation must not proceed from a partial scan (loadEffectLedger with { tolerateCorrupt: true } surfaces the lines for triage).`);
 		this.name = "LedgerCorruptionError";
 		this.lines = lines;
 	}
 };
+/** Strict per-line decode (RV607): invalid UTF-8 is damage, never a
+* replacement character that forges a key. */
+const decodeStrict = (bytes) => new TextDecoder("utf-8", { fatal: true }).decode(bytes);
+const isRecordObject = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+const hasIntentShape = (value) => typeof value.idempotencyKey === "string" && typeof value.runId === "string" && typeof value.spanId === "string" && typeof value.tool === "string" && typeof value.argsHash === "string" && typeof value.executor === "string" && typeof value.workdir === "string" && typeof value.startedAt === "number" && (value.attemptId === void 0 || typeof value.attemptId === "string");
+const OUTCOME_CLASSES = /* @__PURE__ */ new Set([
+	"ok",
+	"error",
+	"timeout"
+]);
+/**
+* Validates one parsed line's shape BEFORE anything downstream touches
+* it (RV607): the phase must be exactly one of the three the writer
+* emits, and every required field of that phase must carry its type
+* (extra fields pass through untouched). Anything else, a primitive, a
+* null, a missing field, an unknown phase, returns undefined and
+* becomes a {@link CorruptLedgerLine}: forward compatibility with
+* future phases is versioning's job, never silence's.
+*/
+function asLedgerLine(parsed) {
+	if (!isRecordObject(parsed)) return void 0;
+	if (parsed.phase === "intent") return hasIntentShape(parsed) ? parsed : void 0;
+	if (parsed.phase === "outcome") return hasIntentShape(parsed) && typeof parsed.durationMs === "number" && OUTCOME_CLASSES.has(parsed.outcome) && (typeof parsed.exitCode === "number" || parsed.exitCode === null) && (typeof parsed.signal === "string" || parsed.signal === null) ? parsed : void 0;
+	if (parsed.phase === "torn") return typeof parsed.bytes === "string" && typeof parsed.recoveredAt === "number" ? parsed : void 0;
+}
 /**
 * Scans a JSONL ledger file into intents, outcomes, and the orphaned
 * intents a host must reconcile, pairing attempts exactly (RV501). A
 * torn TRAILING fragment (the crash-mid-write artifact) is tolerated
-* and reported; an unparseable INTERIOR line fails the scan closed with
-* a typed {@link LedgerCorruptionError} unless `tolerateCorrupt` asks
-* for the lines as data (RV502).
+* and reported; everything else the scan cannot decode, parse, and
+* validate, invalid UTF-8, non-object JSON, a missing required field,
+* an unknown phase (RV607), fails the scan closed with a typed
+* {@link LedgerCorruptionError} unless `tolerateCorrupt` asks for the
+* lines as data (RV502). Under `tolerateCorrupt` the scan never throws
+* anything rawer than that: a malformed line is data, not an exception.
 */
 async function loadEffectLedger(path, options) {
 	const raw = await readFile(path);
@@ -703,6 +820,14 @@ async function loadEffectLedger(path, options) {
 	let tornTail;
 	let line = 0;
 	let start = 0;
+	const markCorrupt = (lineNo, offset, bytes, preview) => {
+		corrupt.push({
+			line: lineNo,
+			offset,
+			sha256: createHash("sha256").update(bytes).digest("hex"),
+			preview: preview.slice(0, 120)
+		});
+	};
 	for (let i = 0; i <= raw.length; i += 1) {
 		const atEnd = i === raw.length;
 		if (!atEnd && raw[i] !== 10) continue;
@@ -712,30 +837,37 @@ async function loadEffectLedger(path, options) {
 		start = i + 1;
 		if (atEnd && bytes.length === 0) break;
 		line += 1;
-		const text = bytes.toString("utf8");
+		let text;
+		try {
+			text = decodeStrict(bytes);
+		} catch {
+			if (terminated) markCorrupt(line, offset, bytes, bytes.toString("utf8"));
+			else tornTail = { preview: bytes.toString("utf8").slice(0, 120) };
+			continue;
+		}
 		if (text.trim() === "") continue;
 		let parsed;
 		try {
 			parsed = JSON.parse(text);
 		} catch {
-			if (terminated) corrupt.push({
-				line,
-				offset,
-				sha256: createHash("sha256").update(bytes).digest("hex"),
-				preview: text.slice(0, 120)
-			});
+			if (terminated) markCorrupt(line, offset, bytes, text);
 			else tornTail = { preview: text.slice(0, 120) };
 			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);
-		} else if (parsed.phase === "torn") tornArtifacts.push({
-			bytes: parsed.bytes,
-			recoveredAt: parsed.recoveredAt
+		const entry = asLedgerLine(parsed);
+		if (entry === void 0) {
+			markCorrupt(line, offset, bytes, text);
+			continue;
+		}
+		if (entry.phase === "intent") {
+			const { phase: _phase, ...rest } = entry;
+			intents.push(rest);
+		} else if (entry.phase === "outcome") {
+			const { phase: _phase, ...rest } = entry;
+			outcomes.push(rest);
+		} else tornArtifacts.push({
+			bytes: entry.bytes,
+			recoveredAt: entry.recoveredAt
 		});
 	}
 	if (corrupt.length > 0 && options?.tolerateCorrupt !== true) throw new LedgerCorruptionError(path, corrupt);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rulvar/executor",
-  "version": "1.103.0",
+  "version": "1.104.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.103.0"
+    "@rulvar/core": "1.104.0"
   },
   "devDependencies": {
     "@types/node": "^22.20.1",
     "tsdown": "^0.22.14",
     "typescript": "~6.0.3",
-    "@rulvar/testing": "1.103.0"
+    "@rulvar/testing": "1.104.0"
   },
   "repository": {
     "type": "git",