@descryy/runtime-controller 0.2.1 → 0.3.0

package/LICENSE

@@ -0,0 +1,6 @@
+Copyright (c) Descry
+
+All rights reserved. This software is proprietary and confidential.
+No license, express or implied, to reproduce, distribute, modify, or
+create derivative works is granted except as explicitly agreed in
+writing.

package/dist/capability-registry.d.ts

@@ -1,11 +1,3 @@
-/**
- * Capability registry (plan §16): assembles per-execution capabilities
- * from the collectors actually present, so `distributedTrace: unavailable`
- * is a first-class answer the AI planner can read rather than a silent
- * gap. Does not know how to *produce* a `CollectorCapabilities` value —
- * that's each collector's own `capabilities()` (Agents 2-4's concern) —
- * only how to assemble and query what's been registered.
- */
 import type { CapabilityStatus, CollectorCapabilities, EnvironmentTier, ExecutionCapabilities, FidelityLevel } from "@descryy/runtime-contracts";
 export interface RegisteredCollectorCapabilities {
     readonly collectorId: string;
@@ -13,12 +5,5 @@ export interface RegisteredCollectorCapabilities {
 }
 export declare function buildExecutionCapabilities(environmentTier: EnvironmentTier, fidelityLevel: FidelityLevel, collectors: readonly RegisteredCollectorCapabilities[]): ExecutionCapabilities;
 export type CollectorCapabilityKey = keyof CollectorCapabilities;
-/**
- * The best (most available) status for one capability across every
- * registered collector — "is this observable *anywhere* in this
- * execution," not per-collector. An execution with two network collectors
- * where one degraded and one is fully available should read as available,
- * not degraded.
- */
 export declare function bestCapabilityStatus(capabilities: ExecutionCapabilities, key: CollectorCapabilityKey): CapabilityStatus;
 //# sourceMappingURL=capability-registry.d.ts.map

package/dist/capability-registry.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"capability-registry.d.ts","sourceRoot":"","sources":["../src/capability-registry.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAEV,gBAAgB,EAChB,qBAAqB,EACrB,eAAe,EACf,qBAAqB,EACrB,aAAa,EACd,MAAM,4BAA4B,CAAC;AAEpC,MAAM,WAAW,+BAA+B;IAC9C,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,YAAY,EAAE,qBAAqB,CAAC;CAC9C;AAED,wBAAgB,0BAA0B,CACxC,eAAe,EAAE,eAAe,EAChC,aAAa,EAAE,aAAa,EAC5B,UAAU,EAAE,SAAS,+BAA+B,EAAE,GACrD,qBAAqB,CAEvB;AAED,MAAM,MAAM,sBAAsB,GAAG,MAAM,qBAAqB,CAAC;AAajE;;;;;;GAMG;AACH,wBAAgB,oBAAoB,CAClC,YAAY,EAAE,qBAAqB,EACnC,GAAG,EAAE,sBAAsB,GAC1B,gBAAgB,CAalB"}
+{"version":3,"file":"capability-registry.d.ts","sourceRoot":"","sources":["../src/capability-registry.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAEV,gBAAgB,EAChB,qBAAqB,EACrB,eAAe,EACf,qBAAqB,EACrB,aAAa,EACd,MAAM,4BAA4B,CAAC;AAEpC,MAAM,WAAW,+BAA+B;IAC9C,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,YAAY,EAAE,qBAAqB,CAAC;CAC9C;AAED,wBAAgB,0BAA0B,CACxC,eAAe,EAAE,eAAe,EAChC,aAAa,EAAE,aAAa,EAC5B,UAAU,EAAE,SAAS,+BAA+B,EAAE,GACrD,qBAAqB,CAEvB;AAED,MAAM,MAAM,sBAAsB,GAAG,MAAM,qBAAqB,CAAC;AAgBjE,wBAAgB,oBAAoB,CAClC,YAAY,EAAE,qBAAqB,EACnC,GAAG,EAAE,sBAAsB,GAC1B,gBAAgB,CAWlB"}

package/dist/capability-registry.js

@@ -1,11 +1,7 @@
-/**
- * Capability registry (plan §16): assembles per-execution capabilities
- * from the collectors actually present, so `distributedTrace: unavailable`
- * is a first-class answer the AI planner can read rather than a silent
- * gap. Does not know how to *produce* a `CollectorCapabilities` value —
- * that's each collector's own `capabilities()` (Agents 2-4's concern) —
- * only how to assemble and query what's been registered.
- */
+// Capability registry (§16): assembles per-execution capabilities from the collectors
+// actually present, so e.g. `distributedTrace: unavailable` is a first-class answer
+// rather than a silent gap. Assembles and queries only — producing a
+// `CollectorCapabilities` value is each collector's own `capabilities()`.
 export function buildExecutionCapabilities(environmentTier, fidelityLevel, collectors) {
     return { environmentTier, fidelityLevel, collectors };
 }
@@ -18,18 +14,12 @@ const NO_COLLECTOR_STATUS = {
     availability: "unavailable",
     reason: "no collector registered for this execution",
 };
-/**
- * The best (most available) status for one capability across every
- * registered collector — "is this observable *anywhere* in this
- * execution," not per-collector. An execution with two network collectors
- * where one degraded and one is fully available should read as available,
- * not degraded.
- */
+// Best (most available) status for one capability across all registered collectors —
+// "observable anywhere in this execution," not per-collector: two network collectors,
+// one degraded one available, should read as available.
 export function bestCapabilityStatus(capabilities, key) {
-    // Seeded from the first collector actually seen, not from
-    // NO_COLLECTOR_STATUS -- seeding from the placeholder would make a
-    // single collector's genuine "unavailable" tie the placeholder's rank
-    // and lose its specific reason to the generic one.
+    // Seeded from the first collector seen, not NO_COLLECTOR_STATUS — seeding from the
+    // placeholder would let a real "unavailable" tie the placeholder and lose its reason.
     let best = null;
     for (const collector of capabilities.collectors) {
         const status = collector.capabilities[key];

package/dist/capability-registry.js.map

@@ -1 +1 @@
-{"version":3,"file":"capability-registry.js","sourceRoot":"","sources":["../src/capability-registry.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAgBH,MAAM,UAAU,0BAA0B,CACxC,eAAgC,EAChC,aAA4B,EAC5B,UAAsD;IAEtD,OAAO,EAAE,eAAe,EAAE,aAAa,EAAE,UAAU,EAAE,CAAC;AACxD,CAAC;AAID,MAAM,iBAAiB,GAAqD;IAC1E,WAAW,EAAE,CAAC;IACd,QAAQ,EAAE,CAAC;IACX,SAAS,EAAE,CAAC;CACb,CAAC;AAEF,MAAM,mBAAmB,GAAqB;IAC5C,YAAY,EAAE,aAAa;IAC3B,MAAM,EAAE,4CAA4C;CACrD,CAAC;AAEF;;;;;;GAMG;AACH,MAAM,UAAU,oBAAoB,CAClC,YAAmC,EACnC,GAA2B;IAE3B,0DAA0D;IAC1D,mEAAmE;IACnE,sEAAsE;IACtE,mDAAmD;IACnD,IAAI,IAAI,GAA4B,IAAI,CAAC;IACzC,KAAK,MAAM,SAAS,IAAI,YAAY,CAAC,UAAU,EAAE,CAAC;QAChD,MAAM,MAAM,GAAG,SAAS,CAAC,YAAY,CAAC,GAAG,CAAC,CAAC;QAC3C,IAAI,IAAI,KAAK,IAAI,IAAI,iBAAiB,CAAC,MAAM,CAAC,YAAY,CAAC,GAAG,iBAAiB,CAAC,IAAI,CAAC,YAAY,CAAC,EAAE,CAAC;YACnG,IAAI,GAAG,MAAM,CAAC;QAChB,CAAC;IACH,CAAC;IACD,OAAO,IAAI,IAAI,mBAAmB,CAAC;AACrC,CAAC"}
+{"version":3,"file":"capability-registry.js","sourceRoot":"","sources":["../src/capability-registry.ts"],"names":[],"mappings":"AAAA,sFAAsF;AACtF,oFAAoF;AACpF,qEAAqE;AACrE,0EAA0E;AAgB1E,MAAM,UAAU,0BAA0B,CACxC,eAAgC,EAChC,aAA4B,EAC5B,UAAsD;IAEtD,OAAO,EAAE,eAAe,EAAE,aAAa,EAAE,UAAU,EAAE,CAAC;AACxD,CAAC;AAID,MAAM,iBAAiB,GAAqD;IAC1E,WAAW,EAAE,CAAC;IACd,QAAQ,EAAE,CAAC;IACX,SAAS,EAAE,CAAC;CACb,CAAC;AAEF,MAAM,mBAAmB,GAAqB;IAC5C,YAAY,EAAE,aAAa;IAC3B,MAAM,EAAE,4CAA4C;CACrD,CAAC;AAEF,qFAAqF;AACrF,sFAAsF;AACtF,wDAAwD;AACxD,MAAM,UAAU,oBAAoB,CAClC,YAAmC,EACnC,GAA2B;IAE3B,mFAAmF;IACnF,sFAAsF;IACtF,IAAI,IAAI,GAA4B,IAAI,CAAC;IACzC,KAAK,MAAM,SAAS,IAAI,YAAY,CAAC,UAAU,EAAE,CAAC;QAChD,MAAM,MAAM,GAAG,SAAS,CAAC,YAAY,CAAC,GAAG,CAAC,CAAC;QAC3C,IAAI,IAAI,KAAK,IAAI,IAAI,iBAAiB,CAAC,MAAM,CAAC,YAAY,CAAC,GAAG,iBAAiB,CAAC,IAAI,CAAC,YAAY,CAAC,EAAE,CAAC;YACnG,IAAI,GAAG,MAAM,CAAC;QAChB,CAAC;IACH,CAAC;IACD,OAAO,IAAI,IAAI,mBAAmB,CAAC;AACrC,CAAC"}

package/dist/collector-version.d.ts

@@ -1,10 +1,3 @@
-/**
- * `Evidence.collectorVersion`'s source for `ProcessCollector`: this
- * package's own `package.json` "version", read from the artifact itself
- * rather than hand-duplicated into a second string that can drift from
- * what actually shipped. Same idea as `nodeVersion` elsewhere in this repo
- * (`process.version`, always known, never probed) applied to a package
- * instead of the Node runtime.
- */
+/** `Evidence.collectorVersion` for `ProcessCollector`: read from package.json itself so it can't drift from what shipped. Same pattern as `nodeVersion` (`process.version`), applied to a package instead of the runtime. */
 export declare const COLLECTOR_VERSION: string;
 //# sourceMappingURL=collector-version.d.ts.map

package/dist/collector-version.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"collector-version.d.ts","sourceRoot":"","sources":["../src/collector-version.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAMH,eAAO,MAAM,iBAAiB,EAAE,MAA6E,CAAC"}
+{"version":3,"file":"collector-version.d.ts","sourceRoot":"","sources":["../src/collector-version.ts"],"names":[],"mappings":"AAAA,6NAA6N;AAM7N,eAAO,MAAM,iBAAiB,EAAE,MAA6E,CAAC"}

package/dist/collector-version.js

@@ -1,11 +1,4 @@
-/**
- * `Evidence.collectorVersion`'s source for `ProcessCollector`: this
- * package's own `package.json` "version", read from the artifact itself
- * rather than hand-duplicated into a second string that can drift from
- * what actually shipped. Same idea as `nodeVersion` elsewhere in this repo
- * (`process.version`, always known, never probed) applied to a package
- * instead of the Node runtime.
- */
+/** `Evidence.collectorVersion` for `ProcessCollector`: read from package.json itself so it can't drift from what shipped. Same pattern as `nodeVersion` (`process.version`), applied to a package instead of the runtime. */
 import { createRequire } from "node:module";
 const require = createRequire(import.meta.url);
 export const COLLECTOR_VERSION = require("../package.json").version;

package/dist/collector-version.js.map

@@ -1 +1 @@
-{"version":3,"file":"collector-version.js","sourceRoot":"","sources":["../src/collector-version.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAE5C,MAAM,OAAO,GAAG,aAAa,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;AAE/C,MAAM,CAAC,MAAM,iBAAiB,GAAY,OAAO,CAAC,iBAAiB,CAAkC,CAAC,OAAO,CAAC"}
+{"version":3,"file":"collector-version.js","sourceRoot":"","sources":["../src/collector-version.ts"],"names":[],"mappings":"AAAA,6NAA6N;AAE7N,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAE5C,MAAM,OAAO,GAAG,aAAa,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;AAE/C,MAAM,CAAC,MAAM,iBAAiB,GAAY,OAAO,CAAC,iBAAiB,CAAkC,CAAC,OAAO,CAAC"}

package/dist/container-sandbox.d.ts

@@ -1,184 +1,100 @@
 /**
- * §21's execution boundary, container backend -- the macOS/Windows half of
- * the sandbox-isolation lane. `sandbox.ts` closed this gap for Linux via
- * bubblewrap; this module closes it for macOS and Windows, but NOT by
- * building a second and third native OS sandbox. That path was researched
- * (`sandbox.ts`'s own original module doc named `sandbox-exec`/Seatbelt on
- * macOS and Job Objects/AppContainer on Windows as candidates) and
- * explicitly rejected as an architecture decision: `sandbox-exec` is
- * deprecated (no public API replacement), the Endpoint Security Framework
- * needs a special Apple entitlement this project does not have, and
- * hand-building Job Objects + AppContainer + WFP network enforcement on
- * Windows is a second and third bespoke native sandbox to build and
- * maintain for the same problem already solved once.
+ * §21's execution boundary, container backend -- the macOS/Windows half of the
+ * sandbox-isolation lane (`sandbox.ts` covers Linux via bubblewrap).
  *
- * **Mechanism: route the spawned process through a real container instead.**
- * This runtime's actual targets -- JVM/Spring, Node, Python backends -- are
- * already containerizable, so this reuses the *Linux* sandbox mechanism
- * bwrap already proved, by running the target process inside a `docker run`
- * invocation. The container's own rootfs IS the "outside allowedRoots is
- * unreachable" boundary; nothing inside the container needs bwrap. On
- * macOS, `docker run` targets Docker Desktop's Linux VM; on Windows, WSL2 /
- * Docker Desktop's Windows backend. Both ultimately run the same Linux
- * container runtime this module already drives directly.
+ * **Not a second native sandbox.** `sandbox-exec`/Seatbelt (macOS) and Job
+ * Objects/AppContainer/WFP (Windows) were researched and rejected: `sandbox-exec` is
+ * deprecated with no public API replacement, Endpoint Security needs an Apple
+ * entitlement this project doesn't have, and hand-building Windows equivalents is a
+ * second and third bespoke sandbox for a problem already solved once.
  *
- * **What was actually verified, and what was not -- stated precisely,
- * matching `sandbox.ts`'s own "researched and disclosed rather than
- * guessed" discipline:**
+ * **Mechanism: route the spawned process through a real container instead**, via
+ * `docker run` (Docker Desktop's Linux VM on macOS, WSL2/Docker Desktop on Windows).
+ * The container's own rootfs is the isolation boundary; no bwrap needed inside it.
  *
- * REAL-TESTED, on this Linux development machine, via a real installed
- * Docker daemon (server 29.6.1) and real `docker run` invocations -- not
- * mocked, not asserted from documentation: a file outside a container's
- * bind-mounts is genuinely unreachable (`ENOENT` from inside the running
- * container); a network call under `--network none` is genuinely refused
- * against a real host listener; both together on one spawn; the same
- * boundary through the full `ExecutionController.run()` path, not just this
- * module's own function called directly. See `container-sandbox.test.ts`
- * and `controller.test.ts`'s container-backend end-to-end test.
+ * **Verified for real** (Linux dev machine, real Docker daemon 29.6.1, not mocked):
+ * a file outside bind-mounts is unreachable (`ENOENT`); a network call under
+ * `--network none` is refused against a real listener; both together, through the
+ * full `ExecutionController.run()` path. See `container-sandbox.test.ts`,
+ * `controller.test.ts`'s container-backend e2e test.
  *
- * **IMPLEMENTATION-NOT-DONE, not a "gap" and not a coverage caveat: the
- * macOS-Docker-Desktop-VM-specific and Windows-WSL2-specific integration
- * paths are UNVERIFIED on real macOS/Windows hardware.** No such hardware
- * is available in this environment. Concretely unverified: detecting
- * whether Docker Desktop is actually running before attempting a spawn;
- * path translation across the Docker Desktop VM boundary on macOS; WSL2
- * path translation on Windows (a Windows host path and the path Linux
- * containers see are not the same string). This module's bind-mount
- * strategy assumes the host path and the in-container path are identical
- * (`-v hostPath:hostPath`, mirroring `sandbox.ts`'s own `--bind root root`
- * convention) -- true on Linux, true for Docker Desktop's Linux VM when the
- * path is already inside the VM's shared-drive mapping, but the exact
- * translation rules for an arbitrary Windows path are not exercised here at
- * all. This is "the container mechanism exists and is tested where it can
- * be, but full cross-platform verification needs hardware nobody here has"
- * -- a distinct category from a real bug or an intentionally out-of-scope
- * capability, and this module does not claim otherwise.
+ * **UNVERIFIED on real macOS/Windows hardware** (none available here): Docker
+ * Desktop running-detection before spawn, path translation across the Docker
+ * Desktop VM boundary (macOS) and WSL2 (Windows) -- this module's bind-mount assumes
+ * host path == in-container path (`-v hostPath:hostPath`), true on Linux and for
+ * Docker Desktop's Linux VM when already inside its shared-drive mapping, untested
+ * for an arbitrary Windows path. Mechanism exists and is tested where it can be;
+ * cross-platform verification needs hardware nobody here has -- not a bug, not
+ * claimed otherwise.
  *
- * **Explicit scope boundary, same treatment attach-mode already gets in
- * this codebase:** a target that cannot run containerized at all --deep
- * native OS integration, GUI-dependent processes, OS-specific native
- * dependencies that don't exist inside a Linux container image-- is out of
- * scope for this approach, on any platform. There is no fallback to a
- * native sandbox for such a target; it is simply not isolatable by this
- * mechanism, and that is disclosed rather than silently unsupported.
+ * **Scope boundary** (same treatment as attach-mode elsewhere): a target that can't
+ * run containerized at all (deep native OS integration, GUI, native deps absent
+ * from a Linux image) is out of scope on any platform, with no native-sandbox
+ * fallback -- disclosed, not silently unsupported.
  *
- * **Real escape testing on the container boundary is still required and
- * was done** -- "the container starts successfully" is not treated as
- * sufficient evidence here, the same bar `sandbox.ts`'s bwrap path was held
- * to. A mutation check on the first version of that testing (temporarily
- * removing `--network none`, rerunning) surfaced a genuine behavioral
- * difference from bwrap worth stating precisely rather than glossing over:
- * **Docker gives every container its own network namespace by default,
- * with or without `--network none`** -- unlike bwrap, which shares the
- * host's network unless `networkPolicy` is declared. A containerized
- * process can therefore never reach the HOST's own loopback either way
- * (that alone is not evidence `--network none` specifically did anything),
- * but it CAN still reach the public internet via Docker's default bridge
- * NAT when no `networkPolicy` is declared -- only `--network none`
- * additionally blocks that. `container-sandbox.test.ts`'s dedicated
- * mutation-sensitive test isolates exactly this variable (an external
- * host, not the host's own loopback) to prove the flag itself is what is
- * being tested, not mere containerization.
+ * **Measured Docker/bwrap difference** (found via a mutation check removing
+ * `--network none` and rerunning): Docker gives every container its own network
+ * namespace regardless of `--network none` -- unlike bwrap, which shares the host's
+ * network unless `networkPolicy` is declared. So a container can never reach the
+ * HOST's loopback either way, but it CAN still reach the public internet via
+ * Docker's default bridge NAT unless `--network none` is set. The dedicated
+ * mutation-sensitive test in `container-sandbox.test.ts` checks reachability to an
+ * external host (not loopback) to isolate exactly this.
  *
- * **What this module does NOT attempt to solve, disclosed rather than
- * silently dropped:** composition with `ResourceLimits` (`prlimit`) --
- * `sandbox.ts` composes bwrap with `applyResourceLimits` by wrapping
- * outside it; this module does not attempt the equivalent composition with
- * Docker's own `--memory`/`--cpus`/`--pids-limit` flags in this pass. A
- * `resourceLimits`-declared execution routed through the container backend
- * runs without OS-enforced resource limits inside the container. Selective
- * network allow-/deny-listing (`NetworkPolicy` shapes other than full
- * denial) is unimplemented here for the same reason `sandbox.ts` doesn't
- * implement it: it needs DNS interception and IP filtering this iteration
- * does not build -- `unsupportedContainerNetworkPolicyReason` reports this
- * the same way `sandbox.ts`'s own `unsupportedNetworkPolicyReason` does,
- * deliberately matching posture rather than silently claiming broader
- * support than the underlying mechanism has.
+ * **Not solved here, disclosed:** `ResourceLimits` composition -- `sandbox.ts` wraps
+ * bwrap with `applyResourceLimits`; this module does not wrap Docker's
+ * `--memory`/`--cpus`/`--pids-limit` equivalents, so a `resourceLimits`-declared
+ * execution on this backend runs unlimited inside the container. Selective network
+ * allow/deny-listing is unimplemented for the same reason as `sandbox.ts` (needs DNS
+ * interception + IP filtering) -- `unsupportedContainerNetworkPolicyReason` reports
+ * it the same way, matching posture rather than overclaiming.
  */
 import type { CapabilityStatus, FilesystemPolicy, NetworkPolicy } from "@descryy/runtime-contracts";
-/**
- * Real capability check: is a working Docker CLI + reachable daemon
- * actually present, not merely "does a `docker` binary exist on PATH."
- * `docker version` talks to the daemon; a CLI with no running daemon behind
- * it (Docker Desktop not started, dockerd not running) fails this the same
- * way a missing binary does -- both are "cannot enforce," and the caller
- * does not need to tell them apart to make the right decision (refuse).
- */
+/** Real check: working Docker CLI + reachable daemon, not just a `docker` binary on PATH. `docker version` talks to the daemon, so a CLI with no daemon running fails the same way a missing binary does -- both mean "cannot enforce." */
 export declare function containerRuntimeCapability(env?: NodeJS.ProcessEnv): CapabilityStatus;
-/**
- * Mirrors `sandbox.ts`'s `filesystemIsolationCapability`/
- * `networkIsolationCapability` split: one real mechanism underneath
- * (a container boundary), two named capabilities because the two policies
- * are declared, refused, and reasoned about independently at the call
- * site.
- */
 export declare function containerFilesystemIsolationCapability(env?: NodeJS.ProcessEnv): CapabilityStatus;
 export declare function containerNetworkIsolationCapability(env?: NodeJS.ProcessEnv): CapabilityStatus;
-/**
- * Same posture as `sandbox.ts`'s `unsupportedNetworkPolicyReason`, matched
- * deliberately rather than reinvented: only full denial
- * (`{ mode: "allow", hosts: [] }`, `docker run --network none`) is
- * enforced. A shape bwrap already discloses as unsupported is not silently
- * claimed as supported here just because the underlying mechanism changed.
- */
+/** Same posture as `sandbox.ts`'s `unsupportedNetworkPolicyReason`: only full denial (`--network none`) is enforced. A shape bwrap discloses as unsupported isn't silently claimed here just because the mechanism changed. */
 export declare function unsupportedContainerNetworkPolicyReason(policy: NetworkPolicy): string | null;
 export declare function resolveContainerImage(interpreterCommand: string): string | null;
 export interface ContainerSandboxOptions {
-    /** Used only to resolve a default base image via `resolveContainerImage` when `containerImage` is not given. */
+    /** Resolves a default base image via `resolveContainerImage` when `containerImage` is not given. */
     readonly interpreterCommand: string;
-    /** The command to exec *inside* the container -- resolved against the image's own PATH, not the host's (see `processEnv`'s own comment for why `PATH` is never forwarded). */
+    /** Command to exec inside the container -- resolved against the image's own PATH, not the host's. */
     readonly command: string;
     readonly args: readonly string[];
-    /** Bind-mounted into the container at the identical path (`-v cwd:cwd`), always -- mirrors `sandbox.ts`'s "cwd always bound" default, and is the one directory the target process is guaranteed to need. */
+    /** Always bind-mounted at the identical path (`-v cwd:cwd`) -- mirrors sandbox.ts's "cwd always bound" default. */
     readonly cwd: string;
     readonly filesystemPolicy?: FilesystemPolicy;
     readonly networkPolicy?: NetworkPolicy;
     /**
-     * Env vars the CONTAINERIZED PROCESS itself needs (e.g. `PORT`, a
-     * service's declared `env`) -- forwarded into the container via `-e
-     * KEY=VALUE`. **`PATH` is deliberately never forwarded**: the container
-     * must resolve `command` against its own image's filesystem layout
-     * (`/usr/local/bin/node` in `node:22-slim`, not wherever the host's
-     * interpreter happens to live), and forwarding the host's `PATH` would
-     * silently break that resolution or -- if it named a path that happens to
-     * exist for a different binary inside the image -- run the wrong thing.
-     * Every other variable is forwarded unfiltered, matching the same
-     * unfiltered-inheritance precedent `process-manager.ts` already
-     * established for the bwrap path (bwrap does not `--clearenv` either).
+     * Env vars the containerized process needs, forwarded via `-e KEY=VALUE`. `PATH` is
+     * never forwarded: the container must resolve `command` against its own image
+     * layout (`/usr/local/bin/node`, not the host's), and the host's PATH would break
+     * that or run the wrong binary. Everything else forwards unfiltered, matching
+     * bwrap's own unfiltered-inheritance precedent (no `--clearenv`).
      */
     readonly processEnv?: Readonly<Record<string, string | undefined>>;
-    /** Env used only to run the `docker` CLI itself (PATH lookup for `docker`, `DOCKER_HOST`, etc.) -- plays the same role `SandboxOptions.env` plays for bwrap's own capability check. Defaults to `process.env`. */
+    /** Env for running the `docker` CLI itself (PATH, `DOCKER_HOST`). Defaults to `process.env`. */
     readonly env?: NodeJS.ProcessEnv;
-    /** Explicit override -- bypasses `resolveContainerImage`'s name-based guess entirely. */
+    /** Explicit override, bypasses `resolveContainerImage`'s name-based guess. */
     readonly containerImage?: string;
 }
 /**
- * Wraps `command`/`args` with `docker run` so a real container boundary
- * enforces `filesystemPolicy`/`networkPolicy`. Neither declared returns
- * `command`/`args` unchanged and never invokes docker at all -- the same
- * non-regression contract `sandbox.ts`'s `applySandbox` established for
- * bwrap, applied here too: a caller who never opts into a policy is
- * completely unaffected by this module's existence.
+ * Wraps `command`/`args` with `docker run` so a container boundary enforces
+ * `filesystemPolicy`/`networkPolicy`. Neither declared returns them unchanged and
+ * never invokes docker -- same non-regression contract as `sandbox.ts`'s
+ * `applySandbox`.
  *
- * **Throws rather than silently spawning unconstrained** when a policy is
- * requested and cannot actually be backed -- no working Docker, or a
- * `networkPolicy` shape this mechanism doesn't implement -- matching
- * `applySandbox`'s own refuse-rather-than-guess precedent exactly.
+ * **Throws rather than silently spawning unconstrained** when a policy can't
+ * actually be backed (no working Docker, unimplemented `networkPolicy` shape).
  *
- * **Returns a real, unique `containerName` whenever it wraps.** This was
- * added after a genuine finding from this module's own real escape tests,
- * not assumed up front: `process-manager.ts`'s existing group-kill
- * (`process.kill(-pid, signal)`) targets the *local* `docker` CLI process's
- * group -- exactly right for bwrap, which execs the sandboxed process
- * directly and never creates a second process group. Docker is different:
- * the container runs under `dockerd`, not as a child of the local `docker`
- * CLI, so killing the CLI's process group does not reliably stop the
- * container -- observed directly (a `kill()` call left a real orphaned
- * `node:22-slim` container running after both the CLI process and its
- * grace period were gone). `containerName` lets the caller
- * (`process-manager.ts`) issue a real, explicit `docker stop <name>`
- * against the container itself as the actual mechanism, not the CLI
- * process, for the container backend.
+ * **Returns a real, unique `containerName` whenever it wraps.** Found via real
+ * escape testing: `process-manager.ts`'s group-kill targets the local `docker` CLI
+ * process's group, which is right for bwrap but not Docker -- the container runs
+ * under `dockerd`, not as the CLI's child, so killing the CLI's group left an
+ * orphaned `node:22-slim` container running in testing. `containerName` lets the
+ * caller issue an explicit `docker stop <name>` against the container itself.
  */
 export declare function applyContainerSandbox(options: ContainerSandboxOptions): {
     readonly command: string;

package/dist/container-sandbox.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"container-sandbox.d.ts","sourceRoot":"","sources":["../src/container-sandbox.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgGG;AAKH,OAAO,KAAK,EAAE,gBAAgB,EAAE,gBAAgB,EAAE,aAAa,EAAE,MAAM,4BAA4B,CAAC;AAEpG;;;;;;;GAOG;AACH,wBAAgB,0BAA0B,CAAC,GAAG,GAAE,MAAM,CAAC,UAAwB,GAAG,gBAAgB,CAUjG;AAED;;;;;;GAMG;AACH,wBAAgB,sCAAsC,CAAC,GAAG,GAAE,MAAM,CAAC,UAAwB,GAAG,gBAAgB,CAE7G;AAED,wBAAgB,mCAAmC,CAAC,GAAG,GAAE,MAAM,CAAC,UAAwB,GAAG,gBAAgB,CAE1G;AAED;;;;;;GAMG;AACH,wBAAgB,uCAAuC,CAAC,MAAM,EAAE,aAAa,GAAG,MAAM,GAAG,IAAI,CAO5F;AAkBD,wBAAgB,qBAAqB,CAAC,kBAAkB,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAE/E;AAED,MAAM,WAAW,uBAAuB;IACtC,gHAAgH;IAChH,QAAQ,CAAC,kBAAkB,EAAE,MAAM,CAAC;IACpC,8KAA8K;IAC9K,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,CAAC;IACjC,4MAA4M;IAC5M,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,gBAAgB,CAAC,EAAE,gBAAgB,CAAC;IAC7C,QAAQ,CAAC,aAAa,CAAC,EAAE,aAAa,CAAC;IACvC;;;;;;;;;;;;OAYG;IACH,QAAQ,CAAC,UAAU,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,CAAC,CAAC;IACnE,kNAAkN;IAClN,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,CAAC,UAAU,CAAC;IACjC,yFAAyF;IACzF,QAAQ,CAAC,cAAc,CAAC,EAAE,MAAM,CAAC;CAClC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,wBAAgB,qBAAqB,CACnC,OAAO,EAAE,uBAAuB,GAC/B;IAAE,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,CAAC;IAAC,QAAQ,CAAC,aAAa,CAAC,EAAE,MAAM,CAAA;CAAE,CAkDjG"}
+{"version":3,"file":"container-sandbox.d.ts","sourceRoot":"","sources":["../src/container-sandbox.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkDG;AAKH,OAAO,KAAK,EAAE,gBAAgB,EAAE,gBAAgB,EAAE,aAAa,EAAE,MAAM,4BAA4B,CAAC;AAEpG,2OAA2O;AAC3O,wBAAgB,0BAA0B,CAAC,GAAG,GAAE,MAAM,CAAC,UAAwB,GAAG,gBAAgB,CAUjG;AAKD,wBAAgB,sCAAsC,CAAC,GAAG,GAAE,MAAM,CAAC,UAAwB,GAAG,gBAAgB,CAE7G;AAED,wBAAgB,mCAAmC,CAAC,GAAG,GAAE,MAAM,CAAC,UAAwB,GAAG,gBAAgB,CAE1G;AAED,+NAA+N;AAC/N,wBAAgB,uCAAuC,CAAC,MAAM,EAAE,aAAa,GAAG,MAAM,GAAG,IAAI,CAO5F;AAYD,wBAAgB,qBAAqB,CAAC,kBAAkB,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAE/E;AAED,MAAM,WAAW,uBAAuB;IACtC,oGAAoG;IACpG,QAAQ,CAAC,kBAAkB,EAAE,MAAM,CAAC;IACpC,qGAAqG;IACrG,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,CAAC;IACjC,mHAAmH;IACnH,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,gBAAgB,CAAC,EAAE,gBAAgB,CAAC;IAC7C,QAAQ,CAAC,aAAa,CAAC,EAAE,aAAa,CAAC;IACvC;;;;;;OAMG;IACH,QAAQ,CAAC,UAAU,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,CAAC,CAAC;IACnE,gGAAgG;IAChG,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,CAAC,UAAU,CAAC;IACjC,8EAA8E;IAC9E,QAAQ,CAAC,cAAc,CAAC,EAAE,MAAM,CAAC;CAClC;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,qBAAqB,CACnC,OAAO,EAAE,uBAAuB,GAC/B;IAAE,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,CAAC;IAAC,QAAQ,CAAC,aAAa,CAAC,EAAE,MAAM,CAAA;CAAE,CAkDjG"}