@rulvar/executor 1.59.0

package/LICENSE

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/dist/index.d.ts

@@ -0,0 +1,283 @@
+import { IsolatedExecRequest, IsolatedExecutorTag, SchemaSpec, ToolDef, ToolExecutorProvider, ToolRisk } from "@rulvar/core";
+
+//#region src/spi.d.ts
+/** Why an isolated dispatch failed. */
+type ExecutorErrorCode = "config" | "timeout" | "aborted" | "output-cap" | "exit" | "protocol" | "spawn";
+/**
+* A failed isolated dispatch. The engine catches whatever a
+* ToolExecutorProvider throws and turns it into the call's error tool
+* result, so `message` is what the model sees: it is kept concise and
+* carries a stderr tail on `exit`.
+*/
+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 stable per-call idempotency key (createEngine derives it). */
+  idempotencyKey: string;
+  runId: string;
+  spanId: string;
+  tool: string;
+  /** sha256 of the canonical arguments: correlates without storing them. */
+  argsHash: string;
+  executor: IsolatedExecutorTag;
+  /** The ephemeral working directory the dispatch ran in. */
+  workdir: string;
+  startedAt: number;
+  durationMs: number;
+  outcome: "ok" | "error" | "timeout";
+  /** Child exit code, or null when terminated by a signal. */
+  exitCode: number | null;
+  /** The terminating signal, when any. */
+  signal: string | null;
+}
+/**
+* The side-effect ledger seam. An executor calls `record` once per
+* dispatch (success or failure). Binding an approval to its effect is
+* then a lookup: the approval entry and the effect share
+* (runId, tool, argsHash), and the idempotency key is stable across a
+* rerun of the same call.
+*/
+interface ToolEffectLedger {
+  record(entry: ToolEffectRecord): void | Promise<void>;
+}
+/** An in-memory ledger for tests and single-process hosts. */
+declare function memoryEffectLedger(): ToolEffectLedger & {
+  entries(): readonly ToolEffectRecord[];
+};
+/**
+* A stable content hash of the arguments for the ledger's `argsHash`. It
+* canonicalizes object key order so equal arguments hash equally
+* regardless of property order.
+*/
+declare function hashArgs(args: unknown): string;
+/**
+* The tool-program result protocol: the child's stdout, trimmed, is the
+* JSON result. Empty stdout is the null result; anything else must parse
+* as JSON or the dispatch fails typed `protocol`. Diagnostics belong on
+* stderr, which never enters the result.
+*/
+declare function parseToolResult(stdout: string, tool: string): unknown;
+//#endregion
+//#region src/subprocess.d.ts
+/** The command a subprocess tool runs, carried on its `executorSpec`. */
+interface SubprocessCommandSpec {
+  command: string;
+  args?: readonly string[];
+}
+interface SubprocessExecutorOptions {
+  /**
+  * Host environment variable names copied into the child. DEFAULT: none.
+  * The child's environment is otherwise empty except the per-call vars
+  * the executor injects, so host credentials in process.env never reach
+  * the tool. A bare command name needs 'PATH' here to be resolvable;
+  * prefer an absolute command path instead.
+  */
+  allowEnv?: readonly string[];
+  /**
+  * Mints short-lived credentials for one dispatch, injected as child
+  * environment variables. Called fresh per call, so a rotating or
+  * request-scoped token is minted at use and never lives in the host
+  * environment. Return an empty object to inject none.
+  */
+  credentials?: (request: IsolatedExecRequest) => Record<string, string> | Promise<Record<string, string>>;
+  /** Hard wall-clock ceiling per call; the child is killed on expiry. Default 30_000. */
+  timeoutMs?: number;
+  /** Grace between SIGTERM and SIGKILL. Default 2_000. */
+  killGraceMs?: number;
+  /** Max stdout/stderr bytes captured; exceeding it kills the child. Default 1 MiB. */
+  maxOutputBytes?: number;
+  /** Base directory for the per-call ephemeral workdir. Default os.tmpdir(). */
+  workdirBase?: string;
+  /**
+  * A sandbox launcher whose argv is prepended to the command: the real
+  * filesystem and network isolation plug in here. It receives the
+  * resolved workdir and the request and returns the wrapper argv (for
+  * example `['bwrap', '--unshare-net', '--bind', workdir, workdir, ...]`).
+  * Default: none.
+  */
+  sandbox?: (context: {
+    workdir: string;
+    request: IsolatedExecRequest;
+  }) => readonly string[];
+  /** Records every dispatch; the host owns retention and approval binding. */
+  ledger?: ToolEffectLedger;
+  /** Fallback command when a tool's executorSpec omits one. */
+  command?: string;
+  /** Argv prepended before the tool's own args (e.g. a fixed runner script). */
+  args?: readonly string[];
+  /** Injectable clock for the ledger's timing fields (tests). */
+  now?: () => number;
+}
+/**
+* Builds a subprocess ToolExecutorProvider. Register it on the engine as
+* `createEngine({ executors: { subprocess: subprocessExecutor(...) } })`;
+* tools declaring `executor: 'subprocess'` (see {@link subprocessTool})
+* then dispatch through it.
+*/
+declare function subprocessExecutor(options?: SubprocessExecutorOptions): ToolExecutorProvider;
+interface SubprocessToolInit<S extends SchemaSpec> {
+  name: string;
+  description: string;
+  parameters: S;
+  /** Contract version, part of toolsetHash. */
+  version?: string;
+  /** The program to run, and its fixed argv. */
+  command: string;
+  args?: readonly string[];
+  /** The terminal permission default asks when true. */
+  needsApproval?: boolean;
+  /** Policy metadata; never identity. */
+  risk?: ToolRisk;
+}
+/**
+* Defines a tool that runs under a subprocess (or container) executor.
+* The returned ToolDef declares `executor: 'subprocess'` and carries the
+* command on `executorSpec`; its `execute` closure exists only as a
+* guard, and throws if ever called in process, because dispatch routes to
+* the registered executor instead. Register that executor on the engine
+* for the tool to run.
+*/
+declare function subprocessTool<S extends SchemaSpec>(init: SubprocessToolInit<S>): ToolDef<S>;
+//#endregion
+//#region src/container.d.ts
+interface ContainerExecutorOptions {
+  /** The image the tool runs in (required). */
+  image: string;
+  /** The docker-compatible CLI. Default 'docker'. */
+  docker?: string;
+  /** `--network`. Default 'none' (no network at all). */
+  network?: string;
+  /** `--memory`. Default '256m'. */
+  memory?: string;
+  /** `--cpus`. Default '1.0'. */
+  cpus?: string;
+  /** `--pids-limit`. Default 128. */
+  pidsLimit?: number;
+  /** `--read-only` root filesystem. Default true. */
+  readOnly?: boolean;
+  /** Capabilities to drop. Default ['ALL']. */
+  capDrop?: readonly string[];
+  /** Where the ephemeral workdir is mounted inside the container. Default '/work'. */
+  workMount?: string;
+  /** Extra raw `docker run` flags, appended before the image. */
+  extraDockerArgs?: readonly string[];
+  /** Host env names forwarded INTO the container (not the daemon env). Default none. */
+  forwardEnv?: readonly string[];
+  /** Host env names the docker CLI itself may read. Default the daemon set. */
+  daemonEnv?: readonly string[];
+  /** Mints per-call short-lived credentials, forwarded into the container. */
+  credentials?: (request: IsolatedExecRequest) => Record<string, string> | Promise<Record<string, string>>;
+  /** Hard wall-clock ceiling per call. Default 30_000. */
+  timeoutMs?: number;
+  /** Grace between SIGTERM and SIGKILL of the docker CLI. Default 5_000. */
+  killGraceMs?: number;
+  /** Max stdout/stderr bytes captured. Default 1 MiB. */
+  maxOutputBytes?: number;
+  /** Base directory for the per-call ephemeral workdir. Default os.tmpdir(). */
+  workdirBase?: string;
+  /** Records every dispatch. */
+  ledger?: ToolEffectLedger;
+  /** Fallback command (inside the container) when executorSpec omits one. */
+  command?: string;
+  /** Argv prepended before the tool's own args. */
+  args?: readonly string[];
+  /** Injectable clock for the ledger's timing fields (tests). */
+  now?: () => number;
+}
+/**
+* Builds a container ToolExecutorProvider over a docker-compatible CLI.
+* Register it as
+* `createEngine({ executors: { container: containerExecutor({ image }) } })`;
+* tools declaring `executor: 'container'` dispatch through it. Define such
+* tools with {@link subprocessTool} and set `executor` to 'container', or
+* hand-build a ToolDef.
+*/
+declare function containerExecutor(options: ContainerExecutorOptions): ToolExecutorProvider;
+//#endregion
+//#region src/conformance.d.ts
+/** The executor options the shared contract exercises. */
+interface ConformanceExecutorConfig {
+  command: string;
+  args: string[];
+  allowEnv?: string[];
+  credentials?: (request: IsolatedExecRequest) => Record<string, string>;
+  timeoutMs?: number;
+  maxOutputBytes?: number;
+  ledger?: ReturnType<typeof memoryEffectLedger>;
+}
+/** Builds the provider under test from a shared-contract config. */
+type ConformanceExecutorFactory = (config: ConformanceExecutorConfig) => ToolExecutorProvider;
+interface ExecutorConformanceCheck {
+  id: string;
+  title: string;
+  run(): Promise<void>;
+}
+interface ExecutorConformanceSuite {
+  name: string;
+  checks: readonly ExecutorConformanceCheck[];
+  run(): Promise<void>;
+}
+/** Structural subset of the Vitest/Jest registration API. */
+interface ExecutorTestRegistrar {
+  describe(name: string, factory: () => void): void;
+  it(name: string, fn: () => Promise<void>): void;
+}
+declare function registerExecutorConformance(suite: ExecutorConformanceSuite, api: ExecutorTestRegistrar): void;
+/**
+* Builds the conformance suite. `factory` produces the provider under
+* test from a shared config; the kit supplies the command (its own
+* runner, run by `runtime`, default the current Node) and the per-check
+* options.
+*/
+declare function executorConformance(factory: ConformanceExecutorFactory, options?: {
+  runtime?: string;
+}): ExecutorConformanceSuite;
+//#endregion
+//#region src/child.d.ts
+interface ChildSpec {
+  command: string;
+  args: readonly string[];
+  /**
+  * The child's COMPLETE environment. It replaces the host environment
+  * rather than extending it: whatever is not listed here is absent from
+  * the child, which is how host credentials in process.env are kept out
+  * of the tool.
+  */
+  env: Record<string, string>;
+  cwd: string;
+  /** Written to the child's stdin, which is then closed. */
+  stdinData: string;
+  /** Hard wall-clock ceiling; on expiry the child is SIGTERM'd then SIGKILL'd. */
+  timeoutMs: number;
+  /** Grace between SIGTERM and the SIGKILL that follows if it ignores it. */
+  killGraceMs: number;
+  /** Captured stdout/stderr are each bounded to this many bytes. */
+  maxOutputBytes: number;
+  /** Cancels the child immediately when it fires (run abort, budget, limits). */
+  signal?: AbortSignal;
+}
+type ChildStopReason = "timeout" | "aborted" | "output-cap";
+interface ChildResult {
+  stdout: string;
+  stderr: string;
+  /** Process exit code; null when the child was terminated by a signal. */
+  code: number | null;
+  /** The terminating signal, when any. */
+  signal: NodeJS.Signals | null;
+  /** True when the runner (not the child) ended it, with the reason why. */
+  stopped: boolean;
+  reason?: ChildStopReason;
+}
+/**
+* Spawns one child and resolves with its captured output and exit status,
+* or rejects if the process could not be spawned at all (e.g. the command
+* is a bare name and PATH is not in `env`, so it cannot be resolved). A
+* child that exits non-zero or is killed resolves normally; interpreting
+* that is the caller's job.
+*/
+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 };

package/dist/index.js

@@ -0,0 +1,810 @@
+import { mkdtemp, 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";
+//#region src/child.ts
+/**
+* The shared child-process runner both reference executors build on. It
+* owns the parts that must be exactly right for isolation to hold: a
+* replaced (not inherited) environment, a hard wall-clock timeout that
+* escalates SIGTERM to SIGKILL, cancellation via the run's AbortSignal,
+* and a hard cap on captured output so a runaway child cannot exhaust
+* host memory. Nothing here decides policy; subprocess.ts and
+* container.ts assemble the command and environment and interpret the
+* result.
+*/
+/**
+* Spawns one child and resolves with its captured output and exit status,
+* or rejects if the process could not be spawned at all (e.g. the command
+* is a bare name and PATH is not in `env`, so it cannot be resolved). A
+* child that exits non-zero or is killed resolves normally; interpreting
+* that is the caller's job.
+*/
+function runChildProcess(spec) {
+	return new Promise((resolve, reject) => {
+		let child;
+		try {
+			child = spawn(spec.command, [...spec.args], {
+				cwd: spec.cwd,
+				env: spec.env,
+				stdio: [
+					"pipe",
+					"pipe",
+					"pipe"
+				]
+			});
+		} catch (err) {
+			reject(err instanceof Error ? err : new Error(String(err)));
+			return;
+		}
+		const stdoutChunks = [];
+		const stderrChunks = [];
+		let stdoutBytes = 0;
+		let stderrBytes = 0;
+		let stopped = false;
+		let reason;
+		let settled = false;
+		const timers = {};
+		const clearTimers = () => {
+			if (timers.kill !== void 0) clearTimeout(timers.kill);
+			if (timers.grace !== void 0) clearTimeout(timers.grace);
+			if (spec.signal !== void 0) spec.signal.removeEventListener("abort", onAbort);
+		};
+		const escalateKill = () => {
+			timers.grace = setTimeout(() => {
+				child.kill("SIGKILL");
+			}, spec.killGraceMs);
+			child.kill("SIGTERM");
+		};
+		const stop = (why) => {
+			if (stopped) return;
+			stopped = true;
+			reason = why;
+			escalateKill();
+		};
+		function onAbort() {
+			stop("aborted");
+		}
+		timers.kill = setTimeout(() => stop("timeout"), spec.timeoutMs);
+		if (spec.signal !== void 0) if (spec.signal.aborted) stop("aborted");
+		else spec.signal.addEventListener("abort", onAbort);
+		child.stdout.on("data", (chunk) => {
+			if (stdoutBytes >= spec.maxOutputBytes) return;
+			const room = spec.maxOutputBytes - stdoutBytes;
+			stdoutChunks.push(chunk.length > room ? chunk.subarray(0, room) : chunk);
+			stdoutBytes += Math.min(chunk.length, room);
+			if (stdoutBytes >= spec.maxOutputBytes) stop("output-cap");
+		});
+		child.stderr.on("data", (chunk) => {
+			if (stderrBytes >= spec.maxOutputBytes) return;
+			const room = spec.maxOutputBytes - stderrBytes;
+			stderrChunks.push(chunk.length > room ? chunk.subarray(0, room) : chunk);
+			stderrBytes += Math.min(chunk.length, room);
+		});
+		child.on("error", (err) => {
+			if (settled) return;
+			settled = true;
+			clearTimers();
+			reject(err);
+		});
+		child.on("close", (code, signal) => {
+			if (settled) return;
+			settled = true;
+			clearTimers();
+			resolve({
+				stdout: Buffer.concat(stdoutChunks).toString("utf8"),
+				stderr: Buffer.concat(stderrChunks).toString("utf8"),
+				code,
+				signal,
+				stopped,
+				...reason === void 0 ? {} : { reason }
+			});
+		});
+		child.stdin.on("error", () => void 0);
+		child.stdin.end(spec.stdinData);
+	});
+}
+//#endregion
+//#region src/spi.ts
+/**
+* The types shared by the reference executors: the typed failure a
+* provider throws (which the engine surfaces to the model as the call's
+* error tool result), and the side-effect ledger that records every
+* dispatch so a host can bind an approval to the effect it authorized.
+*
+* The provider seam itself (ToolExecutorProvider, IsolatedExecRequest,
+* IsolatedExecContext) is defined in and re-exported from `@rulvar/core`.
+*/
+/**
+* A failed isolated dispatch. The engine catches whatever a
+* ToolExecutorProvider throws and turns it into the call's error tool
+* result, so `message` is what the model sees: it is kept concise and
+* carries a stderr tail on `exit`.
+*/
+var ExecutorError = class extends Error {
+	code;
+	constructor(code, message) {
+		super(message);
+		this.name = "ExecutorError";
+		this.code = code;
+	}
+};
+/** An in-memory ledger for tests and single-process hosts. */
+function memoryEffectLedger() {
+	const rows = [];
+	return {
+		record(entry) {
+			rows.push(entry);
+		},
+		entries() {
+			return rows;
+		}
+	};
+}
+/**
+* A stable content hash of the arguments for the ledger's `argsHash`. It
+* canonicalizes object key order so equal arguments hash equally
+* regardless of property order.
+*/
+function hashArgs(args) {
+	return createHash("sha256").update(stableStringify(args), "utf8").digest("hex");
+}
+function stableStringify(value) {
+	if (value === null || typeof value !== "object") return JSON.stringify(value) ?? "null";
+	if (Array.isArray(value)) return `[${value.map(stableStringify).join(",")}]`;
+	const record = value;
+	return `{${Object.keys(record).sort().map((k) => `${JSON.stringify(k)}:${stableStringify(record[k])}`).join(",")}}`;
+}
+/**
+* The tool-program result protocol: the child's stdout, trimmed, is the
+* JSON result. Empty stdout is the null result; anything else must parse
+* as JSON or the dispatch fails typed `protocol`. Diagnostics belong on
+* stderr, which never enters the result.
+*/
+function parseToolResult(stdout, tool) {
+	const trimmed = stdout.trim();
+	if (trimmed === "") return null;
+	try {
+		return JSON.parse(trimmed);
+	} catch {
+		throw new ExecutorError("protocol", `tool '${tool}' did not write a JSON result to stdout (write diagnostics to stderr)`);
+	}
+}
+//#endregion
+//#region src/subprocess.ts
+/**
+* The subprocess reference executor (RV-216): runs a tool's work in a
+* child process with a REPLACED environment (host credentials scrubbed),
+* a fresh ephemeral working directory per call, a hard timeout that kills
+* the child, a bounded output capture, and per-call short-lived
+* credentials. It records every dispatch to the side-effect ledger.
+*
+* What it does and does not isolate is stated plainly in the guide:
+* scrubbing the environment removes the host's ambient credentials (the
+* usual exfiltration path), and the timeout and output cap bound a
+* runaway child. It does NOT by itself block a child from reading
+* world-readable host files or opening sockets: for that, either pass a
+* `sandbox` launcher (bwrap, firejail, sandbox-exec, nsjail) or use the
+* container executor, which drops the network and mounts the filesystem
+* read-only.
+*
+* The tool-program protocol: the child reads one JSON line on stdin,
+* `{ tool, args, idempotencyKey }`, does its work, and writes its JSON
+* result to stdout. Diagnostics go to stderr.
+*
+* Docs: https://docs.rulvar.com/guide/isolated-executor.
+*/
+const wallClock$1 = Date.now.bind(globalThis);
+function resolveCommand(request, options) {
+	const spec = request.spec ?? {};
+	const command = typeof spec.command === "string" ? spec.command : options.command;
+	if (command === void 0 || command === "") throw new ExecutorError("config", `tool '${request.tool}' has no command: set executorSpec.command on the tool or command on the executor`);
+	const specArgs = Array.isArray(spec.args) ? spec.args.filter((a) => typeof a === "string") : [];
+	return {
+		command,
+		args: [...options.args ?? [], ...specArgs]
+	};
+}
+/**
+* Builds a subprocess ToolExecutorProvider. Register it on the engine as
+* `createEngine({ executors: { subprocess: subprocessExecutor(...) } })`;
+* tools declaring `executor: 'subprocess'` (see {@link subprocessTool})
+* then dispatch through it.
+*/
+function subprocessExecutor(options = {}) {
+	const timeoutMs = options.timeoutMs ?? 3e4;
+	const killGraceMs = options.killGraceMs ?? 2e3;
+	const maxOutputBytes = options.maxOutputBytes ?? 1024 * 1024;
+	const workdirBase = options.workdirBase ?? tmpdir();
+	const now = options.now ?? wallClock$1;
+	return { async run(request) {
+		const { command, args } = resolveCommand(request, options);
+		const workdir = await mkdtemp(join(workdirBase, `rulvar-exec-${request.tool}-`));
+		const startedAt = now();
+		let outcome = "ok";
+		let exitCode = null;
+		let signal = null;
+		try {
+			const env = {};
+			for (const name of options.allowEnv ?? []) {
+				const value = process.env[name];
+				if (value !== void 0) env[name] = value;
+			}
+			const creds = options.credentials === void 0 ? {} : await options.credentials(request);
+			Object.assign(env, creds);
+			env.RULVAR_TOOL = request.tool;
+			env.RULVAR_RUN_ID = request.ctx.runId;
+			env.RULVAR_IDEMPOTENCY_KEY = request.ctx.idempotencyKey;
+			const wrapper = options.sandbox === void 0 ? [] : [...options.sandbox({
+				workdir,
+				request
+			})];
+			const [spawnCommand, ...spawnPrefix] = wrapper.length > 0 ? wrapper : [command];
+			const spawnArgs = wrapper.length > 0 ? [
+				...spawnPrefix,
+				command,
+				...args
+			] : args;
+			let child;
+			try {
+				child = await runChildProcess({
+					command: spawnCommand,
+					args: spawnArgs,
+					env,
+					cwd: workdir,
+					stdinData: JSON.stringify({
+						tool: request.tool,
+						args: request.args,
+						idempotencyKey: request.ctx.idempotencyKey
+					}),
+					timeoutMs,
+					killGraceMs,
+					maxOutputBytes,
+					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;
+			signal = child.signal;
+			if (child.stopped && child.reason === "timeout") {
+				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.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}`}`);
+			}
+			return parseToolResult(child.stdout, request.tool);
+		} finally {
+			const durationMs = now() - startedAt;
+			if (options.ledger !== void 0) await options.ledger.record({
+				idempotencyKey: request.ctx.idempotencyKey,
+				runId: request.ctx.runId,
+				spanId: request.ctx.spanId,
+				tool: request.tool,
+				argsHash: hashArgs(request.args),
+				executor: request.executor,
+				workdir,
+				startedAt,
+				durationMs,
+				outcome,
+				exitCode,
+				signal
+			});
+			await rm(workdir, {
+				recursive: true,
+				force: true
+			});
+		}
+	} };
+}
+/**
+* Defines a tool that runs under a subprocess (or container) executor.
+* The returned ToolDef declares `executor: 'subprocess'` and carries the
+* command on `executorSpec`; its `execute` closure exists only as a
+* guard, and throws if ever called in process, because dispatch routes to
+* the registered executor instead. Register that executor on the engine
+* for the tool to run.
+*/
+function subprocessTool(init) {
+	return tool({
+		name: init.name,
+		description: init.description,
+		parameters: init.parameters,
+		...init.version === void 0 ? {} : { version: init.version },
+		executor: "subprocess",
+		executorSpec: {
+			command: init.command,
+			...init.args === void 0 ? {} : { args: [...init.args] }
+		},
+		...init.needsApproval === void 0 ? {} : { needsApproval: init.needsApproval },
+		...init.risk === void 0 ? {} : { risk: init.risk },
+		execute: () => Promise.reject(new ExecutorError("config", `tool '${init.name}' runs under an out-of-process executor; register it via createEngine({ executors: { subprocess: subprocessExecutor(...) } })`))
+	});
+}
+//#endregion
+//#region src/container.ts
+/**
+* The container reference executor (RV-216): runs a tool's work inside a
+* one-shot container, which is where the isolation the subprocess
+* executor cannot promise actually holds. By default it drops the network
+* entirely (`--network none`), mounts the root filesystem read-only
+* (`--read-only`), caps memory, CPU, and process count, and drops all
+* Linux capabilities (`--cap-drop ALL`). The only writable path is the
+* per-call ephemeral workdir, bind-mounted at `/work`.
+*
+* Host credentials never enter the container: the container starts from
+* the image's environment plus exactly the variables the executor
+* forwards by name, and those values live in the docker CLI process's
+* environment, not in the argv. Short-lived credentials are minted per
+* call and forwarded the same way.
+*
+* The tool-program protocol is identical to the subprocess executor: one
+* JSON line on stdin, the JSON result on stdout, diagnostics on stderr.
+*
+* A microVM adapter (Firecracker, gVisor, Kata) implements the same
+* ToolExecutorProvider seam; this docker adapter is the batteries-included
+* reference. Docs: https://docs.rulvar.com/guide/isolated-executor.
+*/
+const wallClock = Date.now.bind(globalThis);
+/** The default host variables the docker CLI needs to reach its daemon. */
+const DEFAULT_DAEMON_ENV = [
+	"PATH",
+	"HOME",
+	"DOCKER_HOST",
+	"DOCKER_TLS_VERIFY",
+	"DOCKER_CERT_PATH"
+];
+/**
+* Builds a container ToolExecutorProvider over a docker-compatible CLI.
+* Register it as
+* `createEngine({ executors: { container: containerExecutor({ image }) } })`;
+* tools declaring `executor: 'container'` dispatch through it. Define such
+* tools with {@link subprocessTool} and set `executor` to 'container', or
+* hand-build a ToolDef.
+*/
+function containerExecutor(options) {
+	const docker = options.docker ?? "docker";
+	const network = options.network ?? "none";
+	const memory = options.memory ?? "256m";
+	const cpus = options.cpus ?? "1.0";
+	const pidsLimit = options.pidsLimit ?? 128;
+	const readOnly = options.readOnly ?? true;
+	const capDrop = options.capDrop ?? ["ALL"];
+	const workMount = options.workMount ?? "/work";
+	const timeoutMs = options.timeoutMs ?? 3e4;
+	const killGraceMs = options.killGraceMs ?? 5e3;
+	const maxOutputBytes = options.maxOutputBytes ?? 1024 * 1024;
+	const workdirBase = options.workdirBase ?? tmpdir();
+	const now = options.now ?? wallClock;
+	return { async run(request) {
+		const spec = request.spec ?? {};
+		const command = typeof spec.command === "string" ? spec.command : options.command;
+		if (command === void 0 || command === "") throw new ExecutorError("config", `tool '${request.tool}' has no command: set executorSpec.command or the executor command`);
+		const specArgs = Array.isArray(spec.args) ? spec.args.filter((a) => typeof a === "string") : [];
+		const toolArgs = [...options.args ?? [], ...specArgs];
+		const workdir = await mkdtemp(join(workdirBase, `rulvar-cexec-${request.tool}-`));
+		const startedAt = now();
+		let outcome = "ok";
+		let exitCode = null;
+		let signal = null;
+		try {
+			const daemonEnv = options.daemonEnv ?? DEFAULT_DAEMON_ENV;
+			const env = {};
+			for (const name of daemonEnv) {
+				const value = process.env[name];
+				if (value !== void 0) env[name] = value;
+			}
+			const forwardNames = /* @__PURE__ */ new Set([
+				"RULVAR_TOOL",
+				"RULVAR_RUN_ID",
+				"RULVAR_IDEMPOTENCY_KEY"
+			]);
+			for (const name of options.forwardEnv ?? []) {
+				const value = process.env[name];
+				if (value !== void 0) {
+					env[name] = value;
+					forwardNames.add(name);
+				}
+			}
+			const creds = options.credentials === void 0 ? {} : await options.credentials(request);
+			for (const [name, value] of Object.entries(creds)) {
+				env[name] = value;
+				forwardNames.add(name);
+			}
+			env.RULVAR_TOOL = request.tool;
+			env.RULVAR_RUN_ID = request.ctx.runId;
+			env.RULVAR_IDEMPOTENCY_KEY = request.ctx.idempotencyKey;
+			const dockerArgs = [
+				"run",
+				"--rm",
+				"-i",
+				"--network",
+				network
+			];
+			dockerArgs.push("--memory", memory, "--cpus", cpus, "--pids-limit", String(pidsLimit));
+			if (readOnly) dockerArgs.push("--read-only");
+			for (const cap of capDrop) dockerArgs.push("--cap-drop", cap);
+			for (const name of forwardNames) dockerArgs.push("-e", name);
+			dockerArgs.push("-v", `${workdir}:${workMount}`, "-w", workMount);
+			dockerArgs.push(...options.extraDockerArgs ?? []);
+			dockerArgs.push(options.image, command, ...toolArgs);
+			let child;
+			try {
+				child = await runChildProcess({
+					command: docker,
+					args: dockerArgs,
+					env,
+					cwd: workdir,
+					stdinData: JSON.stringify({
+						tool: request.tool,
+						args: request.args,
+						idempotencyKey: request.ctx.idempotencyKey
+					}),
+					timeoutMs,
+					killGraceMs,
+					maxOutputBytes,
+					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;
+			signal = child.signal;
+			if (child.stopped && child.reason === "timeout") {
+				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.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}`}`);
+			}
+			return parseToolResult(child.stdout, request.tool);
+		} finally {
+			const durationMs = now() - startedAt;
+			if (options.ledger !== void 0) await options.ledger.record({
+				idempotencyKey: request.ctx.idempotencyKey,
+				runId: request.ctx.runId,
+				spanId: request.ctx.spanId,
+				tool: request.tool,
+				argsHash: hashArgs(request.args),
+				executor: request.executor,
+				workdir,
+				startedAt,
+				durationMs,
+				outcome,
+				exitCode,
+				signal
+			});
+			await rm(workdir, {
+				recursive: true,
+				force: true
+			});
+		}
+	} };
+}
+//#endregion
+//#region src/conformance.ts
+/**
+* The executable executor conformance kit (RV-216): the shared-contract
+* battery every command-based ToolExecutorProvider must pass, mirroring
+* @rulvar/store-conformance. It drives a provider through the tool-program
+* protocol and asserts the isolation and durability properties the seam
+* promises, foremost the gate the epic exists for: a hostile tool cannot
+* read the host's ambient credentials.
+*
+* The subprocess reference executor passes it directly. A container or
+* microVM adapter passes it too when its runtime can run the kit's runner
+* (see the docker-gated container test), and additionally proves the
+* network and filesystem isolation only a container can enforce.
+*
+* Usage under Vitest:
+*
+*   const suite = executorConformance((cfg) => subprocessExecutor(cfg));
+*   registerExecutorConformance(suite, { describe, it });
+*
+* Docs: https://docs.rulvar.com/guide/isolated-executor.
+*/
+function registerExecutorConformance(suite, api) {
+	api.describe(suite.name, () => {
+		for (const check of suite.checks) api.it(`${check.id}: ${check.title}`, () => check.run());
+	});
+}
+function ensure(condition, id, message) {
+	if (!condition) throw new Error(`executor-conformance ${id}: ${message}`);
+}
+const RUNNER_SOURCE = `
+let input = '';
+process.stdin.on('data', (c) => { input += c; });
+process.stdin.on('end', () => {
+  let msg;
+  try { msg = JSON.parse(input || '{}'); } catch { process.stderr.write('bad protocol input'); process.exit(2); }
+  const args = (msg && msg.args) || {};
+  const done = (v) => { process.stdout.write(JSON.stringify(v)); process.exit(0); };
+  switch (args.behavior) {
+    case 'echo': return done({ tool: msg.tool, payload: args.payload ?? null, idempotencyKey: msg.idempotencyKey });
+    case 'read-env': return done({ value: process.env[args.name] ?? null });
+    case 'sleep': return setTimeout(() => done({ slept: true }), args.ms ?? 100000);
+    case 'huge': {
+      const chunk = 'x'.repeat(64 * 1024);
+      for (let i = 0; i < (args.chunks ?? 128); i++) process.stdout.write(chunk);
+      return;
+    }
+    case 'exit': { if (args.stderr) process.stderr.write(String(args.stderr)); return process.exit(args.code ?? 1); }
+    case 'garbage': { process.stdout.write('this is not json'); return process.exit(0); }
+    case 'workdir': {
+      const fs = require('node:fs');
+      const before = fs.readdirSync(process.cwd()).length;
+      fs.writeFileSync('marker.txt', 'x');
+      return done({ before });
+    }
+    default: return done({ unknown: args.behavior ?? null });
+  }
+});
+`;
+/**
+* Builds the conformance suite. `factory` produces the provider under
+* test from a shared config; the kit supplies the command (its own
+* runner, run by `runtime`, default the current Node) and the per-check
+* options.
+*/
+function executorConformance(factory, options = {}) {
+	const runtime = options.runtime ?? process.execPath;
+	const runner = join(mkdtempSync(join(tmpdir(), "rulvar-exec-conf-")), "runner.cjs");
+	writeFileSync(runner, RUNNER_SOURCE, "utf8");
+	const baseArgs = [runner];
+	const request = (tool, args, over = {}) => ({
+		executor: "subprocess",
+		tool,
+		args,
+		spec: {},
+		ctx: {
+			runId: "conf-run",
+			spanId: "conf-span",
+			agentType: "conf",
+			idempotencyKey: "conf-key",
+			signal: new AbortController().signal,
+			log: () => void 0,
+			...over
+		}
+	});
+	const asExecutorError = async (id, promise) => {
+		try {
+			await promise;
+		} catch (err) {
+			ensure(err instanceof ExecutorError, id, `expected ExecutorError, got ${String(err)}`);
+			return err;
+		}
+		throw new Error(`executor-conformance ${id}: expected the dispatch to reject`);
+	};
+	const checks = [
+		{
+			id: "e1",
+			title: "round-trips the tool-program protocol (stdin args to stdout JSON result)",
+			async run() {
+				const result = await factory({
+					command: runtime,
+					args: baseArgs
+				}).run(request("echo_tool", {
+					behavior: "echo",
+					payload: {
+						hello: "world",
+						n: 7
+					}
+				}));
+				ensure(result.tool === "echo_tool", "e1", "the tool name did not reach the program");
+				ensure(JSON.stringify(result.payload) === JSON.stringify({
+					hello: "world",
+					n: 7
+				}), "e1", "the arguments did not round-trip");
+			}
+		},
+		{
+			id: "e2",
+			title: "scrubs the host environment: a hostile tool cannot read a host secret",
+			async run() {
+				const secretName = "RV_CONFORMANCE_SECRET";
+				process.env[secretName] = "sk-live-should-never-reach-a-tool";
+				try {
+					const result = await factory({
+						command: runtime,
+						args: baseArgs
+					}).run(request("reader", {
+						behavior: "read-env",
+						name: secretName
+					}));
+					ensure(result.value === null, "e2", `the host secret reached the tool (${String(result.value)}); the environment was not scrubbed`);
+				} finally {
+					delete process.env[secretName];
+				}
+			}
+		},
+		{
+			id: "e3",
+			title: "honors the environment allowlist (a named var passes through)",
+			async run() {
+				const name = "RV_CONFORMANCE_ALLOWED";
+				process.env[name] = "passed-through";
+				try {
+					ensure((await factory({
+						command: runtime,
+						args: baseArgs,
+						allowEnv: [name]
+					}).run(request("reader", {
+						behavior: "read-env",
+						name
+					}))).value === "passed-through", "e3", "an allowlisted var did not pass through");
+				} finally {
+					delete process.env[name];
+				}
+			}
+		},
+		{
+			id: "e4",
+			title: "injects per-call short-lived credentials",
+			async run() {
+				ensure((await factory({
+					command: runtime,
+					args: baseArgs,
+					credentials: () => ({ RV_CRED: "minted-token" })
+				}).run(request("reader", {
+					behavior: "read-env",
+					name: "RV_CRED"
+				}))).value === "minted-token", "e4", "the minted credential did not reach the tool");
+			}
+		},
+		{
+			id: "e5",
+			title: "forwards the idempotency key to the tool",
+			async run() {
+				ensure((await factory({
+					command: runtime,
+					args: baseArgs
+				}).run(request("reader", {
+					behavior: "read-env",
+					name: "RULVAR_IDEMPOTENCY_KEY"
+				}, { idempotencyKey: "key-abc" }))).value === "key-abc", "e5", "the idempotency key did not reach the tool");
+			}
+		},
+		{
+			id: "e6",
+			title: "kills a tool that exceeds its wall-clock timeout",
+			async run() {
+				const provider = factory({
+					command: runtime,
+					args: baseArgs,
+					timeoutMs: 300
+				});
+				const startedAt = Date.now();
+				const err = await asExecutorError("e6", provider.run(request("slow", {
+					behavior: "sleep",
+					ms: 1e5
+				})));
+				ensure(err.code === "timeout", "e6", `expected code 'timeout', got '${err.code}'`);
+				ensure(Date.now() - startedAt < 5e3, "e6", "the timeout did not fire promptly");
+			}
+		},
+		{
+			id: "e7",
+			title: "bounds captured output and kills a runaway writer",
+			async run() {
+				const provider = factory({
+					command: runtime,
+					args: baseArgs,
+					maxOutputBytes: 32 * 1024
+				});
+				const err = await asExecutorError("e7", provider.run(request("flood", {
+					behavior: "huge",
+					chunks: 256
+				})));
+				ensure(err.code === "output-cap", "e7", `expected code 'output-cap', got '${err.code}'`);
+			}
+		},
+		{
+			id: "e8",
+			title: "surfaces a non-zero exit as a typed error carrying the stderr tail",
+			async run() {
+				const provider = factory({
+					command: runtime,
+					args: baseArgs
+				});
+				const err = await asExecutorError("e8", provider.run(request("crasher", {
+					behavior: "exit",
+					code: 3,
+					stderr: "boom-diagnostic"
+				})));
+				ensure(err.code === "exit", "e8", `expected code 'exit', got '${err.code}'`);
+				ensure(err.message.includes("boom-diagnostic"), "e8", "the stderr tail was not surfaced");
+			}
+		},
+		{
+			id: "e9",
+			title: "rejects a tool that does not write a JSON result",
+			async run() {
+				const provider = factory({
+					command: runtime,
+					args: baseArgs
+				});
+				const err = await asExecutorError("e9", provider.run(request("sloppy", { behavior: "garbage" })));
+				ensure(err.code === "protocol", "e9", `expected code 'protocol', got '${err.code}'`);
+			}
+		},
+		{
+			id: "e10",
+			title: "gives each call a fresh, empty, ephemeral working directory",
+			async run() {
+				const ledger = memoryEffectLedger();
+				const provider = factory({
+					command: runtime,
+					args: baseArgs,
+					ledger
+				});
+				const first = await provider.run(request("w", { behavior: "workdir" }));
+				const second = await provider.run(request("w", { behavior: "workdir" }));
+				ensure(first.before === 0, "e10", "the first workdir was not empty");
+				ensure(second.before === 0, "e10", "the second call saw leftovers from the first");
+				for (const record of ledger.entries()) ensure(!existsSync(record.workdir), "e10", "the ephemeral workdir was not removed after the call");
+			}
+		},
+		{
+			id: "e11",
+			title: "records every dispatch to the side-effect ledger",
+			async run() {
+				const ledger = memoryEffectLedger();
+				const provider = factory({
+					command: runtime,
+					args: baseArgs,
+					ledger
+				});
+				await provider.run(request("ok_tool", {
+					behavior: "echo",
+					payload: 1
+				}, { idempotencyKey: "k-ok" }));
+				await asExecutorError("e11", provider.run(request("bad_tool", {
+					behavior: "exit",
+					code: 1
+				}, { idempotencyKey: "k-bad" })));
+				const rows = ledger.entries();
+				ensure(rows.length === 2, "e11", `expected 2 ledger records, got ${rows.length}`);
+				const ok = rows.find((r) => r.tool === "ok_tool");
+				const bad = rows.find((r) => r.tool === "bad_tool");
+				ensure(ok?.outcome === "ok" && ok.idempotencyKey === "k-ok", "e11", "the ok record is wrong");
+				ensure(bad?.outcome === "error" && bad.exitCode === 1, "e11", "the error record is wrong");
+				ensure(rows.every((r) => typeof r.argsHash === "string" && r.argsHash.length === 64), "e11", "every record must carry a content argsHash");
+			}
+		}
+	];
+	return {
+		name: "executor conformance (RV-216 shared contract)",
+		checks,
+		async run() {
+			for (const check of checks) await check.run();
+		}
+	};
+}
+//#endregion
+export { ExecutorError, containerExecutor, executorConformance, hashArgs, memoryEffectLedger, parseToolResult, registerExecutorConformance, runChildProcess, subprocessExecutor, subprocessTool };

package/package.json

@@ -0,0 +1,48 @@
+{
+  "name": "@rulvar/executor",
+  "version": "1.59.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",
+  "engines": {
+    "node": ">=22.12.0"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist"
+  ],
+  "sideEffects": false,
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@rulvar/core": "1.59.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.20.0",
+    "tsdown": "^0.22.3",
+    "typescript": "~6.0.3",
+    "@rulvar/testing": "1.59.0"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/o-stepper/rulvar.git",
+    "directory": "packages/executor"
+  },
+  "homepage": "https://rulvar.com",
+  "bugs": {
+    "url": "https://github.com/o-stepper/rulvar/issues"
+  },
+  "scripts": {
+    "build": "tsdown",
+    "typecheck": "tsc --noEmit",
+    "lint": "eslint .",
+    "pack-check": "publint --pack pnpm && attw --pack . --profile esm-only"
+  }
+}