@descryy/runtime-controller 0.3.8 → 0.4.0

package/dist/readiness.d.ts

@@ -0,0 +1,122 @@
+/**
+ * Readiness (§6): "readiness must not equal 'process exists.'" Mechanisms: HTTP
+ * check, TCP/port check, log pattern, subprocess command, or a caller hook
+ * (consolidates the plan's "framework readiness hook" and "user-defined readiness"
+ * into one predicate shape).
+ *
+ * **`command` is not `custom-hook` (RT-193).** `custom-hook` runs a caller's
+ * in-process predicate; `command` runs a real subprocess and reads its exit code --
+ * built once so a caller with a real CLI health check (`pg_isready`) doesn't have to
+ * shell out from inside a hand-written hook.
+ *
+ * **What `ready: true` does not claim (RT-024).** All mechanisms answer "is
+ * something listening/responding," none confirm it's the process *this* spawn
+ * produced -- a stale listener from an already-dead run satisfies `http`/`tcp-port`
+ * identically. `log-pattern` only carries the stronger this-run guarantee if `read`
+ * is wired to this execution's own `readOutput()` (caller discipline, not enforced
+ * by the type). An ephemeral port closes this gap by construction; a fixed,
+ * guessable port doesn't. Found via a real 30s collector timeout that looked like a
+ * Playwright bug and was actually a wait on an orphaned process from a dead session
+ * (RT-024).
+ *
+ * **A single probe attempt cannot outlive `timeoutMs` (RT-030).** `http`/`tcp-port`
+ * bind I/O to the remaining time until `deadline`, not a fresh per-attempt budget --
+ * measured: an unbound `fetch` here let `awaitReadiness` run 8s+ past a 3s budget.
+ * `command` gets the same treatment via `execFile`'s `timeout`. `custom-hook` is not
+ * wrapped this way -- a caller predicate owns its own timeout, same as every other
+ * `Collector` callback contract here.
+ */
+export declare const READINESS_MECHANISMS: readonly ["http", "tcp-port", "log-pattern", "command", "custom-hook"];
+export type ReadinessMechanism = (typeof READINESS_MECHANISMS)[number];
+/**
+ * How strongly a successful readiness result establishes that the answering
+ * process is THIS run's own -- RT-024. `"verified"`: a real kernel-state
+ * check (`process-identity.ts`) or a mechanism that is this-run-bound by
+ * construction (a directly-executed `command`, or `log-pattern` reading a
+ * branded `ProcessOutputReader`) confirmed it. `"unverified"`: the mechanism
+ * succeeded but nothing confirmed identity -- disclosed, not hidden.
+ * `"not-applicable"`: nothing succeeded, so no identity claim is being made.
+ */
+export declare const READINESS_IDENTITY_LEVELS: readonly ["verified", "unverified", "not-applicable"];
+export type ReadinessIdentity = (typeof READINESS_IDENTITY_LEVELS)[number];
+export interface HttpReadinessCheck {
+    readonly kind: "http";
+    readonly url: string;
+    readonly expectedStatus?: number;
+    /**
+     * The pid this run spawned (or attached to) for this service. When set, a
+     * successful connection is only accepted once `verifyListeningSocketOwner`
+     * confirms this pid actually owns the listening socket -- otherwise the
+     * probe reports not-ready rather than trusting whoever answered. Omitted
+     * means the caller has no pid to bind to (or the mechanism backing this
+     * service, e.g. a container, can't be verified this way) and the result is
+     * disclosed as `identity: "unverified"`, never silently upgraded.
+     */
+    readonly expectedPid?: number;
+}
+export interface TcpPortReadinessCheck {
+    readonly kind: "tcp-port";
+    readonly host: string;
+    readonly port: number;
+    /** See `HttpReadinessCheck.expectedPid` -- same guarantee, same disclosure. */
+    readonly expectedPid?: number;
+}
+declare const PROCESS_OUTPUT_READER_BRAND: unique symbol;
+/**
+ * A `LogPatternReadinessCheck.read` may only be one of these, and the only
+ * way to make one is `createProcessOutputReader`. This is RT-024's own
+ * finding turned into a type: "log-pattern only carries the stronger
+ * this-run guarantee if `read` is wired to this execution's own
+ * `readOutput()` -- caller discipline, not enforced by the type." A plain
+ * `() => string` closure -- however it's actually wired -- no longer
+ * type-checks; a caller must go through the constructor below, which exists
+ * precisely so the only inputs are a real `ManagedProcess.readOutput` (or an
+ * equivalent this execution actually owns).
+ */
+export interface ProcessOutputReader {
+    readonly [PROCESS_OUTPUT_READER_BRAND]: true;
+    read(): string;
+}
+/** The only way to mint a `ProcessOutputReader` -- wrap the real output source this execution owns (`ManagedProcess.readOutput`, or an equivalent). */
+export declare function createProcessOutputReader(readOutput: () => string): ProcessOutputReader;
+export interface LogPatternReadinessCheck {
+    readonly kind: "log-pattern";
+    /**
+     * Tested against `read.read()`'s full return value on every poll. Backed by
+     * `readOutput()`, an unbounded, growing stdout+stderr buffer -- an unbounded
+     * quantifier before an absent-able literal (the ReDoS shape RT-069/RT-070 already
+     * fixed elsewhere) would backtrack catastrophically here on every poll. Disclosed
+     * risk, not fixed: the regex is the caller's to bound, not this module's.
+     */
+    readonly pattern: RegExp;
+    /** A `ProcessOutputReader` — see that type's doc. Only `createProcessOutputReader` can produce one, which is what makes this-execution's-own-output a type guarantee rather than a convention. */
+    readonly read: ProcessOutputReader;
+}
+export interface CommandReadinessCheck {
+    readonly kind: "command";
+    readonly command: string;
+    readonly args?: readonly string[];
+    /** Defaults to this process's own `cwd` (`execFile`'s own default) when omitted. */
+    readonly cwd?: string;
+}
+export interface CustomHookReadinessCheck {
+    readonly kind: "custom-hook";
+    readonly check: () => Promise<boolean>;
+}
+export type ReadinessCheck = HttpReadinessCheck | TcpPortReadinessCheck | LogPatternReadinessCheck | CommandReadinessCheck | CustomHookReadinessCheck;
+export interface ReadinessResult {
+    readonly ready: boolean;
+    /** Which mechanism succeeded — null when none did within the timeout. */
+    readonly mechanism: ReadinessMechanism | null;
+    readonly elapsedMs: number;
+    readonly reason: string | null;
+    /** How strongly `ready: true` establishes this-run's-own-process (RT-024). See `ReadinessIdentity`. `"not-applicable"` whenever `ready` is `false` — nothing succeeded, so no identity claim is made either way. */
+    readonly identity: ReadinessIdentity;
+}
+export interface AwaitReadinessOptions {
+    readonly timeoutMs: number;
+    readonly pollIntervalMs?: number;
+}
+export declare function awaitReadiness(checks: readonly ReadinessCheck[], options: AwaitReadinessOptions): Promise<ReadinessResult>;
+export {};
+//# sourceMappingURL=readiness.d.ts.map

package/dist/readiness.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"readiness.d.ts","sourceRoot":"","sources":["../src/readiness.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AAMH,eAAO,MAAM,oBAAoB,wEAAyE,CAAC;AAC3G,MAAM,MAAM,kBAAkB,GAAG,CAAC,OAAO,oBAAoB,CAAC,CAAC,MAAM,CAAC,CAAC;AAEvE;;;;;;;;GAQG;AACH,eAAO,MAAM,yBAAyB,uDAAwD,CAAC;AAC/F,MAAM,MAAM,iBAAiB,GAAG,CAAC,OAAO,yBAAyB,CAAC,CAAC,MAAM,CAAC,CAAC;AAE3E,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,cAAc,CAAC,EAAE,MAAM,CAAC;IACjC;;;;;;;;OAQG;IACH,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;CAC/B;AAED,MAAM,WAAW,qBAAqB;IACpC,QAAQ,CAAC,IAAI,EAAE,UAAU,CAAC;IAC1B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,+EAA+E;IAC/E,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;CAC/B;AAOD,QAAA,MAAM,2BAA2B,eAAgC,CAAC;AAElE;;;;;;;;;;GAUG;AACH,MAAM,WAAW,mBAAmB;IAClC,QAAQ,CAAC,CAAC,2BAA2B,CAAC,EAAE,IAAI,CAAC;IAC7C,IAAI,IAAI,MAAM,CAAC;CAChB;AAED,uJAAuJ;AACvJ,wBAAgB,yBAAyB,CAAC,UAAU,EAAE,MAAM,MAAM,GAAG,mBAAmB,CAEvF;AAED,MAAM,WAAW,wBAAwB;IACvC,QAAQ,CAAC,IAAI,EAAE,aAAa,CAAC;IAC7B;;;;;;OAMG;IACH,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,kMAAkM;IAClM,QAAQ,CAAC,IAAI,EAAE,mBAAmB,CAAC;CACpC;AAED,MAAM,WAAW,qBAAqB;IACpC,QAAQ,CAAC,IAAI,EAAE,SAAS,CAAC;IACzB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,IAAI,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAClC,oFAAoF;IACpF,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,CAAC;CACvB;AAED,MAAM,WAAW,wBAAwB;IACvC,QAAQ,CAAC,IAAI,EAAE,aAAa,CAAC;IAC7B,QAAQ,CAAC,KAAK,EAAE,MAAM,OAAO,CAAC,OAAO,CAAC,CAAC;CACxC;AAED,MAAM,MAAM,cAAc,GACtB,kBAAkB,GAClB,qBAAqB,GACrB,wBAAwB,GACxB,qBAAqB,GACrB,wBAAwB,CAAC;AAE7B,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAC;IACxB,yEAAyE;IACzE,QAAQ,CAAC,SAAS,EAAE,kBAAkB,GAAG,IAAI,CAAC;IAC9C,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IAC/B,oNAAoN;IACpN,QAAQ,CAAC,QAAQ,EAAE,iBAAiB,CAAC;CACtC;AAED,MAAM,WAAW,qBAAqB;IACpC,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,cAAc,CAAC,EAAE,MAAM,CAAC;CAClC;AAID,wBAAsB,cAAc,CAClC,MAAM,EAAE,SAAS,cAAc,EAAE,EACjC,OAAO,EAAE,qBAAqB,GAC7B,OAAO,CAAC,eAAe,CAAC,CAyC1B"}

package/dist/readiness.js

@@ -0,0 +1,214 @@
+/**
+ * Readiness (§6): "readiness must not equal 'process exists.'" Mechanisms: HTTP
+ * check, TCP/port check, log pattern, subprocess command, or a caller hook
+ * (consolidates the plan's "framework readiness hook" and "user-defined readiness"
+ * into one predicate shape).
+ *
+ * **`command` is not `custom-hook` (RT-193).** `custom-hook` runs a caller's
+ * in-process predicate; `command` runs a real subprocess and reads its exit code --
+ * built once so a caller with a real CLI health check (`pg_isready`) doesn't have to
+ * shell out from inside a hand-written hook.
+ *
+ * **What `ready: true` does not claim (RT-024).** All mechanisms answer "is
+ * something listening/responding," none confirm it's the process *this* spawn
+ * produced -- a stale listener from an already-dead run satisfies `http`/`tcp-port`
+ * identically. `log-pattern` only carries the stronger this-run guarantee if `read`
+ * is wired to this execution's own `readOutput()` (caller discipline, not enforced
+ * by the type). An ephemeral port closes this gap by construction; a fixed,
+ * guessable port doesn't. Found via a real 30s collector timeout that looked like a
+ * Playwright bug and was actually a wait on an orphaned process from a dead session
+ * (RT-024).
+ *
+ * **A single probe attempt cannot outlive `timeoutMs` (RT-030).** `http`/`tcp-port`
+ * bind I/O to the remaining time until `deadline`, not a fresh per-attempt budget --
+ * measured: an unbound `fetch` here let `awaitReadiness` run 8s+ past a 3s budget.
+ * `command` gets the same treatment via `execFile`'s `timeout`. `custom-hook` is not
+ * wrapped this way -- a caller predicate owns its own timeout, same as every other
+ * `Collector` callback contract here.
+ */
+import { createConnection } from "node:net";
+import { execFile } from "node:child_process";
+import { verifyListeningSocketOwner } from "./process-identity.js";
+export const READINESS_MECHANISMS = ["http", "tcp-port", "log-pattern", "command", "custom-hook"];
+/**
+ * How strongly a successful readiness result establishes that the answering
+ * process is THIS run's own -- RT-024. `"verified"`: a real kernel-state
+ * check (`process-identity.ts`) or a mechanism that is this-run-bound by
+ * construction (a directly-executed `command`, or `log-pattern` reading a
+ * branded `ProcessOutputReader`) confirmed it. `"unverified"`: the mechanism
+ * succeeded but nothing confirmed identity -- disclosed, not hidden.
+ * `"not-applicable"`: nothing succeeded, so no identity claim is being made.
+ */
+export const READINESS_IDENTITY_LEVELS = ["verified", "unverified", "not-applicable"];
+// Unexported on purpose: a real, module-private `unique symbol` (TS infers
+// that type for a `const` initialised with `Symbol()`) that only this module
+// can name. Nothing outside `readiness.ts` can construct a
+// structurally-compatible value even though TS is structurally typed
+// elsewhere -- the brand is the enforcement. See `ProcessOutputReader` below.
+const PROCESS_OUTPUT_READER_BRAND = Symbol("ProcessOutputReader");
+/** The only way to mint a `ProcessOutputReader` -- wrap the real output source this execution owns (`ManagedProcess.readOutput`, or an equivalent). */
+export function createProcessOutputReader(readOutput) {
+    return { [PROCESS_OUTPUT_READER_BRAND]: true, read: readOutput };
+}
+const DEFAULT_POLL_INTERVAL_MS = 200;
+export async function awaitReadiness(checks, options) {
+    const startedAt = Date.now();
+    const deadline = startedAt + options.timeoutMs;
+    const pollIntervalMs = options.pollIntervalMs ?? DEFAULT_POLL_INTERVAL_MS;
+    if (checks.length === 0) {
+        return { ready: false, mechanism: null, elapsedMs: 0, reason: "no readiness checks configured", identity: "not-applicable" };
+    }
+    // C-F4: last real diagnostic any probe captured before giving up (chiefly
+    // `command`'s stderr/exit code -- http/tcp-port have nothing richer than
+    // "connection refused"). Kept as "last seen", most likely to explain the timeout.
+    let lastDetail = null;
+    do {
+        for (const check of checks) {
+            const result = await probe(check, deadline);
+            if (result.ok) {
+                return { ready: true, mechanism: check.kind, elapsedMs: Date.now() - startedAt, reason: null, identity: result.identity };
+            }
+            if (result.detail !== null)
+                lastDetail = `${check.kind}: ${result.detail}`;
+        }
+        await sleep(pollIntervalMs);
+    } while (Date.now() < deadline);
+    // Names what was actually probed, not just that nothing answered -- the only
+    // cheap mitigation for the ephemeral-port race in `allocateEphemeralPort`
+    // (bind 0, read, close, spawn): if another process grabs the port first, the
+    // child never comes up and this message is the only symptom. Naming the exact
+    // address probed sends the reader to the port, not the application.
+    return {
+        ready: false,
+        mechanism: null,
+        elapsedMs: Date.now() - startedAt,
+        // "timeout" stays in the wording deliberately -- §41's hung-process test
+        // matches on that word.
+        reason: `no readiness mechanism succeeded within the ${options.timeoutMs}ms timeout — probed ${checks.map(describeCheck).join(", ")}` +
+            (lastDetail !== null ? `; last observed failure — ${lastDetail}` : ""),
+        identity: "not-applicable",
+    };
+}
+function describeCheck(check) {
+    switch (check.kind) {
+        case "http":
+            return check.url;
+        case "tcp-port":
+            return `tcp ${check.host}:${check.port}`;
+        case "log-pattern":
+            return `log pattern ${String(check.pattern)}`;
+        case "command":
+            return `command ${[check.command, ...(check.args ?? [])].join(" ")}`;
+        case "custom-hook":
+            return "custom hook";
+    }
+}
+function ok(identity = "not-applicable") {
+    return { ok: true, detail: null, identity };
+}
+function notReady(detail = null) {
+    return { ok: false, detail, identity: "not-applicable" };
+}
+/**
+ * Applies RT-024's identity check to a successful TCP-level connection
+ * (shared by `http` and `tcp-port`, which are both "something answered on
+ * this host:port"). No `expectedPid` supplied: succeeds, disclosed as
+ * `"unverified"` -- the caller gave this module nothing to check against, so
+ * it makes no claim either way rather than a silent pass reading as a
+ * guarantee. `expectedPid` supplied: only a real, kernel-confirmed
+ * `"verified"` is accepted as ready; `"mismatch"` is refused outright — a
+ * connection accepted by someone else's listener is not this run being
+ * ready; `"unsupported"` (non-Linux, or the pid can't be inspected) degrades
+ * to `"unverified"` rather than blocking a run this module simply cannot
+ * check on this platform.
+ */
+function identityCheckedConnection(port, expectedPid) {
+    if (expectedPid === undefined)
+        return ok("unverified");
+    const verification = verifyListeningSocketOwner(port, expectedPid);
+    if (verification === "verified")
+        return ok("verified");
+    if (verification === "unsupported")
+        return ok("unverified");
+    return notReady(`connected, but the listening socket on port ${String(port)} is not owned by pid ${String(expectedPid)} ` +
+        "(process-identity check via /proc) -- likely a stale listener from a different process, not this run's own");
+}
+async function probe(check, deadline) {
+    switch (check.kind) {
+        case "http":
+            return probeHttp(check, deadline);
+        case "tcp-port":
+            return probeTcpPort(check, deadline);
+        case "log-pattern":
+            // `read` is a branded ProcessOutputReader -- sourced from this
+            // execution's own output by construction, so a match is `"verified"`.
+            return check.pattern.test(check.read.read()) ? ok("verified") : notReady();
+        case "command":
+            return probeCommand(check, deadline);
+        case "custom-hook":
+            // An arbitrary caller predicate -- this module has no way to know
+            // whether it actually checks this run's own process, so it never
+            // claims more than "unverified" for a caller that passes.
+            return (await check.check()) ? ok("unverified") : notReady();
+    }
+}
+async function probeHttp(check, deadline) {
+    try {
+        const response = await fetch(check.url, { signal: AbortSignal.timeout(Math.max(0, deadline - Date.now())) });
+        if (response.status !== (check.expectedStatus ?? 200)) {
+            return notReady(`responded with status ${String(response.status)}, expected ${String(check.expectedStatus ?? 200)}`);
+        }
+        const url = new URL(check.url);
+        const port = url.port !== "" ? Number(url.port) : url.protocol === "https:" ? 443 : 80;
+        return identityCheckedConnection(port, check.expectedPid);
+    }
+    catch (error) {
+        return notReady(error instanceof Error ? error.message : String(error));
+    }
+}
+function probeTcpPort(check, deadline) {
+    return new Promise((resolve) => {
+        const socket = createConnection({ host: check.host, port: check.port });
+        socket.setTimeout(Math.max(0, deadline - Date.now()));
+        const finish = (result) => {
+            socket.destroy();
+            resolve(result);
+        };
+        socket.once("connect", () => finish(identityCheckedConnection(check.port, check.expectedPid)));
+        socket.once("error", (error) => finish(notReady(error.message)));
+        socket.once("timeout", () => finish(notReady("connection attempt timed out")));
+    });
+}
+/**
+ * Ready when `check.command` exits 0 within the remaining time until `deadline`
+ * (RT-030). Non-zero exit, spawn failure, and timeout kill are all "not ready yet" --
+ * same as every other mechanism's `false`.
+ *
+ * C-F4: stdout/stderr are the actual health-check output, the richest diagnostic
+ * available here. Preferring stderr, then stdout, then the bare error message
+ * mirrors `runAttacher`'s ordering in `attach-to-running-jvm-process.ts`.
+ */
+function probeCommand(check, deadline) {
+    return new Promise((resolve) => {
+        const remainingMs = Math.max(0, deadline - Date.now());
+        if (remainingMs === 0) {
+            resolve(notReady("no time remaining before the readiness deadline"));
+            return;
+        }
+        execFile(check.command, check.args ?? [], { cwd: check.cwd, timeout: remainingMs }, (error, stdout, stderr) => {
+            if (error === null) {
+                // A directly `execFile`d subprocess is this-run-bound by
+                // construction -- there is no "which process answered" ambiguity
+                // the way a network probe has.
+                resolve(ok("verified"));
+                return;
+            }
+            const detail = stderr.trim() || stdout.trim() || error.message;
+            resolve(notReady(detail));
+        });
+    });
+}
+function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+//# sourceMappingURL=readiness.js.map

package/dist/readiness.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"readiness.js","sourceRoot":"","sources":["../src/readiness.ts"],"names":[],"mappings":"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"}

package/dist/sandbox.d.ts

@@ -0,0 +1,94 @@
+/**
+ * §21's execution boundary, real isolation half. RT-070/RT-193 gave this runtime a
+ * *named* boundary (trusted-local, resource limits, privilege reporting) but not an
+ * *isolating* one -- nothing stopped a spawned process from reading any file, or
+ * reaching any host, the invoking user could. This module closes that gap for real,
+ * on Linux, for processes this runtime SPAWNS.
+ *
+ * **Architectural constraint this module cannot solve around:** isolation can only
+ * wrap a process Descry itself launches. Attach-mode reaches a process already
+ * running, unconfined, before Descry touched it -- there is no honest way to
+ * retroactively contain it (ptrace-based interception was investigated and rejected
+ * elsewhere as not honestly generalizable). Attach-mode stays permanently and
+ * explicitly unsandboxed -- `SANDBOX_BOUNDARY_DISCLOSURE` in `execution-safety.ts`
+ * discloses this in-product; this module does not and structurally cannot change it.
+ *
+ * **Mechanism: bubblewrap (bwrap), not raw `unshare`/`clone`.** bwrap is the
+ * unprivileged sandboxing helper behind Flatpak -- small, auditable, actively
+ * maintained, not a bespoke native module this repo builds per-platform. Runs
+ * setuid-free on any kernel with unprivileged user namespaces enabled (checked
+ * below, never assumed) and gives one process a new mount namespace (real
+ * filesystem visibility control) and network namespace (real network denial) in one
+ * exec. Composes with `applyResourceLimits`'s `prlimit` wrap and with
+ * `process-manager.ts`'s process-group kill -- verified directly: bwrap does not
+ * create a new process group unless asked, so the existing group-kill reaches it
+ * unchanged. The one dependency this buys: `bwrap` must be on PATH, reported as a
+ * capability exactly like `prlimit` -- refused, never silently unconstrained, when
+ * requested and absent.
+ *
+ * **NOT attempted, deliberately: a native macOS or Windows sandbox.** `sandbox-exec`/
+ * Seatbelt is deprecated with no public API replacement; the Endpoint Security
+ * Framework needs an Apple entitlement this project doesn't have; Windows Job
+ * Objects + AppContainer + WFP would be a second and third bespoke native sandbox.
+ * This is an explicit decision not to build native sandboxes for those platforms at
+ * all -- `../container-sandbox.ts` closes the gap instead, routing macOS/Windows
+ * through a real Docker container that reuses this module's proven Linux mechanism
+ * (see that module's doc for what's real-tested there vs unverified on real
+ * hardware). `filesystemIsolationCapability`/`networkIsolationCapability` below
+ * still report `unavailable` with a reason on non-Linux -- never silently claimed
+ * as covered.
+ */
+import type { CapabilityStatus, FilesystemPolicy, NetworkPolicy } from "@descryy/runtime-contracts";
+/** Real capability check, same shape as `resourceLimitCapability`: PATH existence first, then the Linux-specific precondition existence alone doesn't prove -- unprivileged user namespaces actually usable, not just bwrap installed. */
+export declare function filesystemIsolationCapability(env?: NodeJS.ProcessEnv, platform?: NodeJS.Platform): CapabilityStatus;
+/** Same underlying mechanism as `filesystemIsolationCapability` (one bwrap namespace set covers both) -- delegates rather than duplicating. Kept as its own function because the two policies are declared and reasoned about independently. */
+export declare function networkIsolationCapability(env?: NodeJS.ProcessEnv, platform?: NodeJS.Platform): CapabilityStatus;
+/**
+ * `NetworkPolicy`'s general shape (arbitrary allow/deny host lists) is not what
+ * this mechanism enforces -- only full denial. Returns the reason a policy can't be
+ * applied, or `null` if it's the one shape that can. Checked independently of
+ * `networkIsolationCapability`: "nothing here can enforce any policy" and "this
+ * specific policy asks for something not built yet" are different claims.
+ */
+export declare function unsupportedNetworkPolicyReason(policy: NetworkPolicy): string | null;
+/**
+ * Resolves the real, symlink-followed directory containing the executable
+ * `command` would run as -- the one extra host path a sandboxed process needs
+ * beyond standard OS dirs and whatever the caller declared. Computed generically,
+ * not per-language: an interpreter installed outside `/usr` (nvm, rbenv, pyenv,
+ * sdkman) would otherwise be invisible inside the sandbox regardless of language.
+ * Returns `null` when unresolvable -- the caller proceeds without an extra bind;
+ * the exec fails inside the sandbox the same honest way it would outside one.
+ */
+export declare function resolveExecutableDirectory(command: string, cwd: string, env: NodeJS.ProcessEnv): string | null;
+export interface SandboxOptions {
+    /** Original, un-resource-limit-wrapped command (e.g. "node") -- used only to resolve which extra directory the interpreter needs bound in. */
+    readonly interpreterCommand: string;
+    /** Command to actually exec inside the sandbox -- already passed through `applyResourceLimits`, so may be "prlimit" with the real command in `args`. */
+    readonly command: string;
+    readonly args: readonly string[];
+    readonly cwd: string;
+    readonly filesystemPolicy?: FilesystemPolicy;
+    readonly networkPolicy?: NetworkPolicy;
+    readonly env?: NodeJS.ProcessEnv;
+    readonly platform?: NodeJS.Platform;
+}
+/**
+ * Wraps `command`/`args` with `bwrap` so the OS enforces `filesystemPolicy`/
+ * `networkPolicy`. Neither declared returns them unchanged -- same non-regression
+ * contract as `applyResourceLimits`.
+ *
+ * **Throws rather than silently spawning unconstrained** when a policy is
+ * requested and the real mechanism can't back it -- no mechanism on this platform,
+ * or a declared shape this mechanism doesn't implement.
+ *
+ * Composes with `applyResourceLimits` by wrapping *outside* it (`bwrap … --
+ * prlimit … -- realCommand`) -- the mount namespace must exist before `prlimit` or
+ * the real command run inside it; `prlimit` (in `/usr/bin`) is reachable through
+ * the same base OS binding every sandboxed process gets.
+ */
+export declare function applySandbox(options: SandboxOptions): {
+    readonly command: string;
+    readonly args: readonly string[];
+};
+//# sourceMappingURL=sandbox.d.ts.map

package/dist/sandbox.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sandbox.d.ts","sourceRoot":"","sources":["../src/sandbox.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuCG;AAKH,OAAO,KAAK,EAAE,gBAAgB,EAAE,gBAAgB,EAAE,aAAa,EAAE,MAAM,4BAA4B,CAAC;AAkCpG,0OAA0O;AAC1O,wBAAgB,6BAA6B,CAAC,GAAG,GAAE,MAAM,CAAC,UAAwB,EAAE,QAAQ,GAAE,MAAM,CAAC,QAA2B,GAAG,gBAAgB,CAoBlJ;AAED,gPAAgP;AAChP,wBAAgB,0BAA0B,CAAC,GAAG,GAAE,MAAM,CAAC,UAAwB,EAAE,QAAQ,GAAE,MAAM,CAAC,QAA2B,GAAG,gBAAgB,CAE/I;AAED;;;;;;GAMG;AACH,wBAAgB,8BAA8B,CAAC,MAAM,EAAE,aAAa,GAAG,MAAM,GAAG,IAAI,CAOnF;AAOD;;;;;;;;GAQG;AACH,wBAAgB,0BAA0B,CAAC,OAAO,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,CAAC,UAAU,GAAG,MAAM,GAAG,IAAI,CAwB9G;AAED,MAAM,WAAW,cAAc;IAC7B,8IAA8I;IAC9I,QAAQ,CAAC,kBAAkB,EAAE,MAAM,CAAC;IACpC,wJAAwJ;IACxJ,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,CAAC;IACjC,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,gBAAgB,CAAC,EAAE,gBAAgB,CAAC;IAC7C,QAAQ,CAAC,aAAa,CAAC,EAAE,aAAa,CAAC;IACvC,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,CAAC,UAAU,CAAC;IACjC,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC,QAAQ,CAAC;CACrC;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,YAAY,CAAC,OAAO,EAAE,cAAc,GAAG;IAAE,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,CAAA;CAAE,CAkFpH"}