@descryy/runtime-controller 0.2.0 → 0.3.0

package/dist/execution-safety.d.ts

@@ -1,153 +1,95 @@
 /**
- * §21's execution boundary (RT-070): resource limits and privilege
- * reporting for a runtime whose declared mode is trusted-local (see
- * DECISIONS.md RT-070) -- every spawned process runs with the invoking
- * user's own OS privileges, no filesystem or network restriction. That
- * declaration does not make unrestricted execution safe; it names the
- * boundary instead of leaving it absent, which is what §38's "arbitrary
- * application code runs without a defined safety boundary" actually bans.
- * Real isolation (containers/namespaces) is a separate architectural
- * decision this module does not invent (plan §29's own instruction).
+ * §21/RT-070's execution boundary: resource limits and privilege reporting for a
+ * runtime declared trusted-local -- every spawned process runs with the invoking
+ * user's own OS privileges, no filesystem/network restriction. Names the boundary
+ * rather than leaving it absent (§38); real isolation (containers/namespaces) is a
+ * separate decision this module does not invent (§29).
  *
- * What this module DOES enforce, for real, via the OS: CPU time, virtual
- * memory, and process count, through `prlimit` -- an exec wrapper, never a
- * shell. Reintroducing `sh -c 'ulimit ...; exec ...'` to get these would
- * undo RT-036's `tokenizeCommand` refusal of shell metacharacters. `prlimit`
- * is util-linux and absent on macOS, so it is reported as a capability,
- * never assumed.
+ * Enforces for real, via the OS: CPU time, virtual memory, process count, through
+ * `prlimit` -- an exec wrapper, never a shell (a shell would undo RT-036's
+ * `tokenizeCommand` refusal of shell metacharacters). `prlimit` is util-linux, absent
+ * on macOS, so it's reported as a capability, never assumed.
  */
 import type { CapabilityStatus, ResourceLimits } from "@descryy/runtime-contracts";
-/**
- * Whether `prlimit` is reachable on this platform's `PATH`. Takes `env` as
- * a parameter (defaulting to `process.env`) rather than reading it
- * internally so the "unavailable" branch is directly testable without
- * mutating this process's own real environment or depending on running on
- * a platform that genuinely lacks it.
- */
+/** Whether `prlimit` is reachable on PATH. `env` is a parameter (default `process.env`) so the "unavailable" branch is testable without mutating the real environment. */
 export declare function resourceLimitCapability(env?: NodeJS.ProcessEnv): CapabilityStatus;
 /**
- * RT-193 originally made this always `unavailable` -- no platform had any
- * enforcement mechanism wired up. The sandbox-isolation lane changes that
- * on Linux: `networkIsolationCapability()` (`./sandbox.ts`) is real, backed
- * by a bwrap network namespace. This function is kept as the stable name
- * every existing caller (`ExecutionController.run()`, this package's own
- * tests) already imports, delegating rather than duplicating the check --
- * exactly the seam RT-193's own comment anticipated ("if a real mechanism
- * is ever built, this one function changes and every caller keeps working
- * unmodified"). Still unconditionally `unavailable` on macOS/Windows, where
- * nothing enforces it yet.
+ * RT-193 originally made this always `unavailable`. Now delegates to
+ * `networkIsolationCapability()` (`./sandbox.ts`), real on Linux via a bwrap network
+ * namespace -- kept as the stable name every caller already imports (the seam
+ * RT-193 anticipated). Still unconditionally `unavailable` on macOS/Windows.
  */
 export declare function networkPolicyCapability(env?: NodeJS.ProcessEnv): CapabilityStatus;
 /**
- * Wraps `command`/`args` so the OS enforces `limits`, via `prlimit`.
- * `undefined` or an empty `limits` returns `command`/`args` unchanged --
- * every execution before RT-070 keeps behaving exactly as before unless it
- * opts in.
+ * Wraps `command`/`args` so the OS enforces `limits`, via `prlimit`. `undefined` or
+ * empty `limits` returns them unchanged -- opt-in only.
  *
- * **Throws rather than silently spawning unconstrained** when a limit was
- * requested and `prlimit` is unavailable. `tokenizeCommand`'s own precedent
- * (RT-036) is refuse rather than guess; the equivalent failure here would
- * be a caller asking for a memory cap and getting a process that can
- * allocate without bound, silently -- exactly the "sandbox that doesn't
- * sandbox" shape §38 bans, one row up from this one.
+ * **Throws rather than silently spawning unconstrained** when a limit was requested
+ * and `prlimit` is unavailable (refuse-not-guess, per RT-036) -- the alternative is a
+ * caller asking for a memory cap and silently getting an unbounded process, the
+ * "sandbox that doesn't sandbox" shape §38 bans.
  */
 export declare function applyResourceLimits(command: string, args: readonly string[], limits: ResourceLimits | undefined, env?: NodeJS.ProcessEnv): {
     readonly command: string;
     readonly args: readonly string[];
 };
 /**
- * DEC-272's disclosure requirement: the sandbox boundary (RT-070) must be
- * stated to the user directly in-product, not left as a silent gap in a
- * doc. Fixed, not derived from `runningAsRoot` -- the boundary is the same
- * regardless of which privilege level was found; only the observed fact
- * changes.
+ * DEC-272: the sandbox boundary (RT-070) must be stated to the user directly, not
+ * left as a silent doc gap. Fixed, not derived from `runningAsRoot` -- the boundary
+ * is the same regardless of privilege level found.
  *
- * **Scope, corrected by the attach-mode-mitigations lane: this is the
- * unconditional-unisolated text, not a universal one.** Written when
- * RT-193/RT-070 landed, before `sandbox.ts` existed -- at that point it was
- * accurate for every execution, because nothing anywhere in this runtime
- * could isolate anything. That stopped being true the moment the
- * sandbox-isolation lane gave spawn-mode real, bwrap-backed filesystem/
- * network isolation (`applySandbox`, this same package): a spawned process
- * that actually got a `FilesystemPolicy`/`NetworkPolicy` applied to it is
- * genuinely more contained than "the same as if you started it yourself"
- * says. Using this constant unconditionally for that process would be a
- * real disclosure-accuracy bug -- understating a boundary is not the safe
- * direction to be wrong in, it just happens to be a less alarming one.
- * `sandboxBoundaryDisclosureFor()` below is the mode-aware replacement: it
- * returns this exact string when no policy was applied (attach-mode always,
- * and any spawn that declared none -- unchanged from before this lane), and
- * a real, specific description of what is and is not contained when a
- * policy genuinely was. This constant is kept, unchanged, as that function's
- * own no-policy-applied return value and as attach-mode's own disclosure,
- * not deprecated -- attach-mode never has anything more accurate to say.
+ * **Scope: this is the unconditional-unisolated text, not a universal one.** Accurate
+ * for every execution before `sandbox.ts` existed; no longer true once spawn-mode got
+ * real bwrap-backed isolation (`applySandbox`) -- using this unconditionally for an
+ * isolated process would understate its boundary, which is not the safe direction to
+ * be wrong in. `sandboxBoundaryDisclosureFor()` below is the mode-aware replacement;
+ * this constant remains its no-policy-applied return value and attach-mode's own
+ * disclosure (attach-mode never has anything more accurate to say).
  */
 export declare const SANDBOX_BOUNDARY_DISCLOSURE: string;
 /**
- * Whether a real `FilesystemPolicy`/`NetworkPolicy` was actually enforced on
- * the process this disclosure describes -- not merely requested.
- * `applySandbox` already refuses to spawn (throws) rather than proceed
- * unconstrained when a declared policy cannot be enforced (see its own
- * comment), so by the time a caller can observe a successfully spawned
- * process, "declared" and "applied" are the same fact; this type exists so
- * a caller states that fact explicitly rather than this function silently
- * assuming it.
+ * Whether a real policy was actually enforced, not merely requested. `applySandbox`
+ * already throws rather than proceed unconstrained when a declared policy can't be
+ * enforced, so by the time a process is observed running, "declared" and "applied"
+ * are the same fact -- this type makes the caller state it explicitly.
  */
 export interface AppliedIsolationPolicies {
     readonly filesystemPolicyApplied: boolean;
     readonly networkPolicyApplied: boolean;
 }
 /**
- * The mode-aware replacement for reading `SANDBOX_BOUNDARY_DISCLOSURE`
- * unconditionally. Defaults to reporting no policy applied -- so calling
- * this with no argument at all is identical to the pre-existing constant,
- * the same non-regression contract every other opt-in in this file
- * (`applyResourceLimits`, `applySandbox`) already keeps.
+ * Mode-aware replacement for reading `SANDBOX_BOUNDARY_DISCLOSURE` unconditionally.
+ * Defaults to no-policy-applied, so a no-arg call matches the old constant exactly.
  *
- * **Still only ever true for spawn-mode.** Attach-mode has no code path
- * that can produce `filesystemPolicyApplied: true` or
- * `networkPolicyApplied: true` for any process it did not itself spawn --
- * see `sandbox.ts`'s own module doc for why that is structural, not a gap
- * in this function. A caller in attach-mode should simply never pass
- * anything but the default here, and the default's return value is this
- * disclosure's original, unconditional "not isolated" text, unchanged.
+ * **Only ever true for spawn-mode.** Attach-mode has no path to produce
+ * `filesystemPolicyApplied`/`networkPolicyApplied: true` for a process it didn't
+ * spawn (structural, see `sandbox.ts`) -- attach-mode callers should never pass
+ * anything but the default.
  */
 export declare function sandboxBoundaryDisclosureFor(policies?: AppliedIsolationPolicies): string;
 /**
- * Attach mode's own contractual scope guarantee -- distinct from the
- * sandbox-*boundary* disclosure above (what is or isn't contained) because
- * this is a claim about what an attach-mode `Collector` is even permitted
- * to *do*, not about what OS boundary wraps it. See `Collector` in
- * `@descryy/runtime-contracts` for the interface-level statement this
- * mirrors, and `sandbox.ts`'s own module doc for why attach-mode can never
- * acquire the isolation `sandboxBoundaryDisclosureFor` describes for
- * spawn-mode. Stated once, here, so every attach-mode caller surfaces the
- * identical sentence rather than each writing its own paraphrase.
+ * Attach mode's contractual scope guarantee -- distinct from the sandbox-boundary
+ * disclosure above: this is what an attach-mode `Collector` is permitted to *do*, not
+ * what OS boundary wraps it. Mirrors `Collector` in `@descryy/runtime-contracts`.
+ * Stated once so every attach-mode caller surfaces the identical sentence.
  */
 export declare const ATTACH_MODE_SCOPE_DISCLOSURE: string;
 export interface PrivilegeReport {
-    /** Null when this platform has no uid concept at all (`process.getuid` is undefined on Windows) -- distinct from `false`, which is a real answer, not an absent one. */
+    /** Null when the platform has no uid concept (`process.getuid` undefined on Windows) -- distinct from `false`, a real answer. */
     readonly runningAsRoot: boolean | null;
-    /** DEC-272: plain-language statement of the sandbox boundary, carried on the same result the privilege level already travels on rather than a new return path. Always populated -- the disclosure is unconditional, not dependent on `runningAsRoot`. */
+    /** DEC-272: plain-language sandbox boundary statement, carried on this result rather than a new return path. Always populated, independent of `runningAsRoot`. */
     readonly disclosure: string;
 }
 /**
- * Reports, never enforces. §21's privilege policy for a runtime declared
- * trusted-local (RT-070) is not "refuse to run as root" -- CI containers
- * commonly run as root by default, and a hard refusal there would turn a
- * documented boundary into an undocumented outage. The policy is: the real
- * privilege level becomes an observable fact instead of an invisible one,
- * which is what nothing before RT-070 made it.
+ * Reports, never enforces. §21's policy for trusted-local (RT-070) is not "refuse to
+ * run as root" -- CI containers commonly do, and a hard refusal would turn a
+ * documented boundary into an undocumented outage. The privilege level just becomes
+ * observable instead of invisible.
  *
- * A required parameter, not a defaulted one: `undefined` is the real,
- * meaningful value a platform with no uid concept produces
- * (`process.getuid` is itself `undefined` on Windows), and a *default*
- * parameter cannot tell "caller explicitly passed undefined" apart from
- * "caller omitted the argument" -- both look identical to the function.
- * `currentPrivilegeReport()` below is the zero-argument convenience wrapper
- * real callers use; this is what makes both branches -- root, and no uid
- * concept at all -- directly testable without this process actually
- * needing to run as root or on Windows.
+ * A required parameter, not defaulted: `undefined` is the real value a no-uid-concept
+ * platform produces, and a default can't distinguish "explicitly undefined" from
+ * "omitted." `currentPrivilegeReport()` below is the convenience wrapper; this makes
+ * both branches testable without actually running as root or on Windows.
  */
 export declare function privilegeReportFor(getuid: (() => number) | undefined): PrivilegeReport;
 export declare function currentPrivilegeReport(): PrivilegeReport;

package/dist/execution-safety.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"execution-safety.d.ts","sourceRoot":"","sources":["../src/execution-safety.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAGH,OAAO,KAAK,EAAE,gBAAgB,EAAE,cAAc,EAAE,MAAM,4BAA4B,CAAC;AAGnF;;;;;;GAMG;AACH,wBAAgB,uBAAuB,CAAC,GAAG,GAAE,MAAM,CAAC,UAAwB,GAAG,gBAAgB,CAU9F;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,uBAAuB,CAAC,GAAG,GAAE,MAAM,CAAC,UAAwB,GAAG,gBAAgB,CAE9F;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,mBAAmB,CACjC,OAAO,EAAE,MAAM,EACf,IAAI,EAAE,SAAS,MAAM,EAAE,EACvB,MAAM,EAAE,cAAc,GAAG,SAAS,EAClC,GAAG,GAAE,MAAM,CAAC,UAAwB,GACnC;IAAE,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,CAAA;CAAE,CAchE;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,eAAO,MAAM,2BAA2B,QAGT,CAAC;AAEhC;;;;;;;;;GASG;AACH,MAAM,WAAW,wBAAwB;IACvC,QAAQ,CAAC,uBAAuB,EAAE,OAAO,CAAC;IAC1C,QAAQ,CAAC,oBAAoB,EAAE,OAAO,CAAC;CACxC;AAID;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,4BAA4B,CAAC,QAAQ,GAAE,wBAA8C,GAAG,MAAM,CAwB7G;AAED;;;;;;;;;;GAUG;AACH,eAAO,MAAM,4BAA4B,QAKoC,CAAC;AAE9E,MAAM,WAAW,eAAe;IAC9B,wKAAwK;IACxK,QAAQ,CAAC,aAAa,EAAE,OAAO,GAAG,IAAI,CAAC;IACvC,yPAAyP;IACzP,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;CAC7B;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,CAAC,MAAM,MAAM,CAAC,GAAG,SAAS,GAAG,eAAe,CAGtF;AAED,wBAAgB,sBAAsB,IAAI,eAAe,CAExD"}
+{"version":3,"file":"execution-safety.d.ts","sourceRoot":"","sources":["../src/execution-safety.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAGH,OAAO,KAAK,EAAE,gBAAgB,EAAE,cAAc,EAAE,MAAM,4BAA4B,CAAC;AAGnF,0KAA0K;AAC1K,wBAAgB,uBAAuB,CAAC,GAAG,GAAE,MAAM,CAAC,UAAwB,GAAG,gBAAgB,CAU9F;AAED;;;;;GAKG;AACH,wBAAgB,uBAAuB,CAAC,GAAG,GAAE,MAAM,CAAC,UAAwB,GAAG,gBAAgB,CAE9F;AAED;;;;;;;;GAQG;AACH,wBAAgB,mBAAmB,CACjC,OAAO,EAAE,MAAM,EACf,IAAI,EAAE,SAAS,MAAM,EAAE,EACvB,MAAM,EAAE,cAAc,GAAG,SAAS,EAClC,GAAG,GAAE,MAAM,CAAC,UAAwB,GACnC;IAAE,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,CAAA;CAAE,CAchE;AAED;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,2BAA2B,QAGT,CAAC;AAEhC;;;;;GAKG;AACH,MAAM,WAAW,wBAAwB;IACvC,QAAQ,CAAC,uBAAuB,EAAE,OAAO,CAAC;IAC1C,QAAQ,CAAC,oBAAoB,EAAE,OAAO,CAAC;CACxC;AAID;;;;;;;;GAQG;AACH,wBAAgB,4BAA4B,CAAC,QAAQ,GAAE,wBAA8C,GAAG,MAAM,CAwB7G;AAED;;;;;GAKG;AACH,eAAO,MAAM,4BAA4B,QAKoC,CAAC;AAE9E,MAAM,WAAW,eAAe;IAC9B,iIAAiI;IACjI,QAAQ,CAAC,aAAa,EAAE,OAAO,GAAG,IAAI,CAAC;IACvC,kKAAkK;IAClK,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;CAC7B;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,CAAC,MAAM,MAAM,CAAC,GAAG,SAAS,GAAG,eAAe,CAGtF;AAED,wBAAgB,sBAAsB,IAAI,eAAe,CAExD"}

package/dist/execution-safety.js

@@ -1,30 +1,18 @@
 /**
- * §21's execution boundary (RT-070): resource limits and privilege
- * reporting for a runtime whose declared mode is trusted-local (see
- * DECISIONS.md RT-070) -- every spawned process runs with the invoking
- * user's own OS privileges, no filesystem or network restriction. That
- * declaration does not make unrestricted execution safe; it names the
- * boundary instead of leaving it absent, which is what §38's "arbitrary
- * application code runs without a defined safety boundary" actually bans.
- * Real isolation (containers/namespaces) is a separate architectural
- * decision this module does not invent (plan §29's own instruction).
+ * §21/RT-070's execution boundary: resource limits and privilege reporting for a
+ * runtime declared trusted-local -- every spawned process runs with the invoking
+ * user's own OS privileges, no filesystem/network restriction. Names the boundary
+ * rather than leaving it absent (§38); real isolation (containers/namespaces) is a
+ * separate decision this module does not invent (§29).
  *
- * What this module DOES enforce, for real, via the OS: CPU time, virtual
- * memory, and process count, through `prlimit` -- an exec wrapper, never a
- * shell. Reintroducing `sh -c 'ulimit ...; exec ...'` to get these would
- * undo RT-036's `tokenizeCommand` refusal of shell metacharacters. `prlimit`
- * is util-linux and absent on macOS, so it is reported as a capability,
- * never assumed.
+ * Enforces for real, via the OS: CPU time, virtual memory, process count, through
+ * `prlimit` -- an exec wrapper, never a shell (a shell would undo RT-036's
+ * `tokenizeCommand` refusal of shell metacharacters). `prlimit` is util-linux, absent
+ * on macOS, so it's reported as a capability, never assumed.
  */
 import { execFileSync } from "node:child_process";
 import { networkIsolationCapability } from "./sandbox.js";
-/**
- * Whether `prlimit` is reachable on this platform's `PATH`. Takes `env` as
- * a parameter (defaulting to `process.env`) rather than reading it
- * internally so the "unavailable" branch is directly testable without
- * mutating this process's own real environment or depending on running on
- * a platform that genuinely lacks it.
- */
+/** Whether `prlimit` is reachable on PATH. `env` is a parameter (default `process.env`) so the "unavailable" branch is testable without mutating the real environment. */
 export function resourceLimitCapability(env = process.env) {
     try {
         execFileSync("prlimit", ["--version"], { env, stdio: "ignore" });
@@ -38,32 +26,22 @@ export function resourceLimitCapability(env = process.env) {
     }
 }
 /**
- * RT-193 originally made this always `unavailable` -- no platform had any
- * enforcement mechanism wired up. The sandbox-isolation lane changes that
- * on Linux: `networkIsolationCapability()` (`./sandbox.ts`) is real, backed
- * by a bwrap network namespace. This function is kept as the stable name
- * every existing caller (`ExecutionController.run()`, this package's own
- * tests) already imports, delegating rather than duplicating the check --
- * exactly the seam RT-193's own comment anticipated ("if a real mechanism
- * is ever built, this one function changes and every caller keeps working
- * unmodified"). Still unconditionally `unavailable` on macOS/Windows, where
- * nothing enforces it yet.
+ * RT-193 originally made this always `unavailable`. Now delegates to
+ * `networkIsolationCapability()` (`./sandbox.ts`), real on Linux via a bwrap network
+ * namespace -- kept as the stable name every caller already imports (the seam
+ * RT-193 anticipated). Still unconditionally `unavailable` on macOS/Windows.
  */
 export function networkPolicyCapability(env = process.env) {
     return networkIsolationCapability(env);
 }
 /**
- * Wraps `command`/`args` so the OS enforces `limits`, via `prlimit`.
- * `undefined` or an empty `limits` returns `command`/`args` unchanged --
- * every execution before RT-070 keeps behaving exactly as before unless it
- * opts in.
+ * Wraps `command`/`args` so the OS enforces `limits`, via `prlimit`. `undefined` or
+ * empty `limits` returns them unchanged -- opt-in only.
  *
- * **Throws rather than silently spawning unconstrained** when a limit was
- * requested and `prlimit` is unavailable. `tokenizeCommand`'s own precedent
- * (RT-036) is refuse rather than guess; the equivalent failure here would
- * be a caller asking for a memory cap and getting a process that can
- * allocate without bound, silently -- exactly the "sandbox that doesn't
- * sandbox" shape §38 bans, one row up from this one.
+ * **Throws rather than silently spawning unconstrained** when a limit was requested
+ * and `prlimit` is unavailable (refuse-not-guess, per RT-036) -- the alternative is a
+ * caller asking for a memory cap and silently getting an unbounded process, the
+ * "sandbox that doesn't sandbox" shape §38 bans.
  */
 export function applyResourceLimits(command, args, limits, env = process.env) {
     if (limits === undefined)
@@ -84,50 +62,30 @@ export function applyResourceLimits(command, args, limits, env = process.env) {
     return { command: "prlimit", args: [...flags, "--", command, ...args] };
 }
 /**
- * DEC-272's disclosure requirement: the sandbox boundary (RT-070) must be
- * stated to the user directly in-product, not left as a silent gap in a
- * doc. Fixed, not derived from `runningAsRoot` -- the boundary is the same
- * regardless of which privilege level was found; only the observed fact
- * changes.
+ * DEC-272: the sandbox boundary (RT-070) must be stated to the user directly, not
+ * left as a silent doc gap. Fixed, not derived from `runningAsRoot` -- the boundary
+ * is the same regardless of privilege level found.
  *
- * **Scope, corrected by the attach-mode-mitigations lane: this is the
- * unconditional-unisolated text, not a universal one.** Written when
- * RT-193/RT-070 landed, before `sandbox.ts` existed -- at that point it was
- * accurate for every execution, because nothing anywhere in this runtime
- * could isolate anything. That stopped being true the moment the
- * sandbox-isolation lane gave spawn-mode real, bwrap-backed filesystem/
- * network isolation (`applySandbox`, this same package): a spawned process
- * that actually got a `FilesystemPolicy`/`NetworkPolicy` applied to it is
- * genuinely more contained than "the same as if you started it yourself"
- * says. Using this constant unconditionally for that process would be a
- * real disclosure-accuracy bug -- understating a boundary is not the safe
- * direction to be wrong in, it just happens to be a less alarming one.
- * `sandboxBoundaryDisclosureFor()` below is the mode-aware replacement: it
- * returns this exact string when no policy was applied (attach-mode always,
- * and any spawn that declared none -- unchanged from before this lane), and
- * a real, specific description of what is and is not contained when a
- * policy genuinely was. This constant is kept, unchanged, as that function's
- * own no-policy-applied return value and as attach-mode's own disclosure,
- * not deprecated -- attach-mode never has anything more accurate to say.
+ * **Scope: this is the unconditional-unisolated text, not a universal one.** Accurate
+ * for every execution before `sandbox.ts` existed; no longer true once spawn-mode got
+ * real bwrap-backed isolation (`applySandbox`) -- using this unconditionally for an
+ * isolated process would understate its boundary, which is not the safe direction to
+ * be wrong in. `sandboxBoundaryDisclosureFor()` below is the mode-aware replacement;
+ * this constant remains its no-policy-applied return value and attach-mode's own
+ * disclosure (attach-mode never has anything more accurate to say).
  */
 export const SANDBOX_BOUNDARY_DISCLOSURE = "This app runs with your own user permissions, the same as if you started it yourself. " +
     "The filesystem and network are not isolated -- anything your own account could read, write, " +
     "or reach, this run can too.";
 const NO_POLICIES_APPLIED = { filesystemPolicyApplied: false, networkPolicyApplied: false };
 /**
- * The mode-aware replacement for reading `SANDBOX_BOUNDARY_DISCLOSURE`
- * unconditionally. Defaults to reporting no policy applied -- so calling
- * this with no argument at all is identical to the pre-existing constant,
- * the same non-regression contract every other opt-in in this file
- * (`applyResourceLimits`, `applySandbox`) already keeps.
+ * Mode-aware replacement for reading `SANDBOX_BOUNDARY_DISCLOSURE` unconditionally.
+ * Defaults to no-policy-applied, so a no-arg call matches the old constant exactly.
  *
- * **Still only ever true for spawn-mode.** Attach-mode has no code path
- * that can produce `filesystemPolicyApplied: true` or
- * `networkPolicyApplied: true` for any process it did not itself spawn --
- * see `sandbox.ts`'s own module doc for why that is structural, not a gap
- * in this function. A caller in attach-mode should simply never pass
- * anything but the default here, and the default's return value is this
- * disclosure's original, unconditional "not isolated" text, unchanged.
+ * **Only ever true for spawn-mode.** Attach-mode has no path to produce
+ * `filesystemPolicyApplied`/`networkPolicyApplied: true` for a process it didn't
+ * spawn (structural, see `sandbox.ts`) -- attach-mode callers should never pass
+ * anything but the default.
  */
 export function sandboxBoundaryDisclosureFor(policies = NO_POLICIES_APPLIED) {
     const { filesystemPolicyApplied, networkPolicyApplied } = policies;
@@ -150,15 +108,10 @@ export function sandboxBoundaryDisclosureFor(policies = NO_POLICIES_APPLIED) {
         "it can read, write, or reach anything your own account's filesystem could.");
 }
 /**
- * Attach mode's own contractual scope guarantee -- distinct from the
- * sandbox-*boundary* disclosure above (what is or isn't contained) because
- * this is a claim about what an attach-mode `Collector` is even permitted
- * to *do*, not about what OS boundary wraps it. See `Collector` in
- * `@descryy/runtime-contracts` for the interface-level statement this
- * mirrors, and `sandbox.ts`'s own module doc for why attach-mode can never
- * acquire the isolation `sandboxBoundaryDisclosureFor` describes for
- * spawn-mode. Stated once, here, so every attach-mode caller surfaces the
- * identical sentence rather than each writing its own paraphrase.
+ * Attach mode's contractual scope guarantee -- distinct from the sandbox-boundary
+ * disclosure above: this is what an attach-mode `Collector` is permitted to *do*, not
+ * what OS boundary wraps it. Mirrors `Collector` in `@descryy/runtime-contracts`.
+ * Stated once so every attach-mode caller surfaces the identical sentence.
  */
 export const ATTACH_MODE_SCOPE_DISCLOSURE = "Attach mode observes an already-running process; it never executes code in it or applies changes to it. " +
     "This is a permanent, documented architectural limitation, not a temporary gap -- there is no honest way to " +
@@ -166,22 +119,15 @@ export const ATTACH_MODE_SCOPE_DISCLOSURE = "Attach mode observes an already-run
     "Respawn-and-supervise and the cgroup resource-limit move are real alternatives next to attach mode, not " +
     "fixes to it; see their own documentation for what each actually gets you.";
 /**
- * Reports, never enforces. §21's privilege policy for a runtime declared
- * trusted-local (RT-070) is not "refuse to run as root" -- CI containers
- * commonly run as root by default, and a hard refusal there would turn a
- * documented boundary into an undocumented outage. The policy is: the real
- * privilege level becomes an observable fact instead of an invisible one,
- * which is what nothing before RT-070 made it.
+ * Reports, never enforces. §21's policy for trusted-local (RT-070) is not "refuse to
+ * run as root" -- CI containers commonly do, and a hard refusal would turn a
+ * documented boundary into an undocumented outage. The privilege level just becomes
+ * observable instead of invisible.
  *
- * A required parameter, not a defaulted one: `undefined` is the real,
- * meaningful value a platform with no uid concept produces
- * (`process.getuid` is itself `undefined` on Windows), and a *default*
- * parameter cannot tell "caller explicitly passed undefined" apart from
- * "caller omitted the argument" -- both look identical to the function.
- * `currentPrivilegeReport()` below is the zero-argument convenience wrapper
- * real callers use; this is what makes both branches -- root, and no uid
- * concept at all -- directly testable without this process actually
- * needing to run as root or on Windows.
+ * A required parameter, not defaulted: `undefined` is the real value a no-uid-concept
+ * platform produces, and a default can't distinguish "explicitly undefined" from
+ * "omitted." `currentPrivilegeReport()` below is the convenience wrapper; this makes
+ * both branches testable without actually running as root or on Windows.
  */
 export function privilegeReportFor(getuid) {
     if (getuid === undefined)

package/dist/execution-safety.js.map

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

package/dist/index.d.ts

@@ -20,16 +20,6 @@ export type { DependencyVersionMismatch, DependencyVersionCheckResult } from "./
 export { checkDependencyVersions } from "./dependency-version-check.ts";
 export type { DeclaredVersionSource, EnvironmentVersionCheckResult } from "./environment-version-check.ts";
 export { DECLARED_VERSION_SOURCES, checkEnvironmentVersion, satisfiesDeclaredNodeVersion } from "./environment-version-check.ts";
-/**
- * RT-073: promoted from internal-only. `tokenizeCommand`'s POSIX-style
- * "refuse rather than guess" tokenizer is exactly what `packages/test-runner`
- * needs to validate a declared runner command before spawning it -- the
- * same job it already does for `ServiceConfiguration.command` here.
- * Re-implementing a second copy for one more caller would be the "two
- * shapes that could drift" mistake this codebase has already named and
- * avoided elsewhere (RT-068's `BrowserConfiguration`, RT-070's
- * `ResourceLimits`).
- */
 export type { CommandTokenization, ServicesValidation } from "./orchestration.ts";
 export { tokenizeCommand, validateServicesConfiguration, substitutePortPlaceholders } from "./orchestration.ts";
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,qBAAqB,EAAE,MAAM,UAAU,CAAC;AAEjD,YAAY,EAAE,mBAAmB,EAAE,eAAe,EAAE,cAAc,EAAE,oBAAoB,EAAE,MAAM,sBAAsB,CAAC;AACvH,OAAO,EAAE,YAAY,EAAE,oBAAoB,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AAE1F,YAAY,EACV,kBAAkB,EAClB,kBAAkB,EAClB,qBAAqB,EACrB,wBAAwB,EACxB,qBAAqB,EACrB,wBAAwB,EACxB,cAAc,EACd,eAAe,EACf,qBAAqB,GACtB,MAAM,gBAAgB,CAAC;AACxB,OAAO,EAAE,oBAAoB,EAAE,cAAc,EAAE,MAAM,gBAAgB,CAAC;AAEtE,YAAY,EAAE,oBAAoB,EAAE,UAAU,EAAE,qBAAqB,EAAE,MAAM,iBAAiB,CAAC;AAC/F,OAAO,EAAE,mBAAmB,EAAE,MAAM,iBAAiB,CAAC;AAEtD,YAAY,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAC;AAC/D,OAAO,EAAE,sBAAsB,EAAE,MAAM,wBAAwB,CAAC;AAEhE,YAAY,EAAE,+BAA+B,EAAE,sBAAsB,EAAE,MAAM,0BAA0B,CAAC;AACxG,OAAO,EAAE,0BAA0B,EAAE,oBAAoB,EAAE,MAAM,0BAA0B,CAAC;AAE5F,YAAY,EAAE,eAAe,EAAE,wBAAwB,EAAE,MAAM,uBAAuB,CAAC;AACvF,OAAO,EACL,uBAAuB,EACvB,mBAAmB,EACnB,uBAAuB,EACvB,kBAAkB,EAClB,sBAAsB,EACtB,2BAA2B,EAC3B,4BAA4B,EAC5B,4BAA4B,GAC7B,MAAM,uBAAuB,CAAC;AAE/B,YAAY,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AACnD,OAAO,EACL,6BAA6B,EAC7B,0BAA0B,EAC1B,8BAA8B,EAC9B,0BAA0B,EAC1B,YAAY,GACb,MAAM,cAAc,CAAC;AAEtB,YAAY,EAAE,uBAAuB,EAAE,MAAM,wBAAwB,CAAC;AACtE,OAAO,EACL,0BAA0B,EAC1B,sCAAsC,EACtC,mCAAmC,EACnC,uCAAuC,EACvC,qBAAqB,EACrB,qBAAqB,GACtB,MAAM,wBAAwB,CAAC;AAEhC,OAAO,EAAE,0BAA0B,EAAE,MAAM,2BAA2B,CAAC;AAEvE,YAAY,EAAE,yBAAyB,EAAE,4BAA4B,EAAE,MAAM,+BAA+B,CAAC;AAC7G,OAAO,EAAE,uBAAuB,EAAE,MAAM,+BAA+B,CAAC;AAExE,YAAY,EAAE,qBAAqB,EAAE,6BAA6B,EAAE,MAAM,gCAAgC,CAAC;AAC3G,OAAO,EAAE,wBAAwB,EAAE,uBAAuB,EAAE,4BAA4B,EAAE,MAAM,gCAAgC,CAAC;AAEjI;;;;;;;;;GASG;AACH,YAAY,EAAE,mBAAmB,EAAE,kBAAkB,EAAE,MAAM,oBAAoB,CAAC;AAClF,OAAO,EAAE,eAAe,EAAE,6BAA6B,EAAE,0BAA0B,EAAE,MAAM,oBAAoB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,qBAAqB,EAAE,MAAM,UAAU,CAAC;AAEjD,YAAY,EAAE,mBAAmB,EAAE,eAAe,EAAE,cAAc,EAAE,oBAAoB,EAAE,MAAM,sBAAsB,CAAC;AACvH,OAAO,EAAE,YAAY,EAAE,oBAAoB,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AAE1F,YAAY,EACV,kBAAkB,EAClB,kBAAkB,EAClB,qBAAqB,EACrB,wBAAwB,EACxB,qBAAqB,EACrB,wBAAwB,EACxB,cAAc,EACd,eAAe,EACf,qBAAqB,GACtB,MAAM,gBAAgB,CAAC;AACxB,OAAO,EAAE,oBAAoB,EAAE,cAAc,EAAE,MAAM,gBAAgB,CAAC;AAEtE,YAAY,EAAE,oBAAoB,EAAE,UAAU,EAAE,qBAAqB,EAAE,MAAM,iBAAiB,CAAC;AAC/F,OAAO,EAAE,mBAAmB,EAAE,MAAM,iBAAiB,CAAC;AAEtD,YAAY,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAC;AAC/D,OAAO,EAAE,sBAAsB,EAAE,MAAM,wBAAwB,CAAC;AAEhE,YAAY,EAAE,+BAA+B,EAAE,sBAAsB,EAAE,MAAM,0BAA0B,CAAC;AACxG,OAAO,EAAE,0BAA0B,EAAE,oBAAoB,EAAE,MAAM,0BAA0B,CAAC;AAE5F,YAAY,EAAE,eAAe,EAAE,wBAAwB,EAAE,MAAM,uBAAuB,CAAC;AACvF,OAAO,EACL,uBAAuB,EACvB,mBAAmB,EACnB,uBAAuB,EACvB,kBAAkB,EAClB,sBAAsB,EACtB,2BAA2B,EAC3B,4BAA4B,EAC5B,4BAA4B,GAC7B,MAAM,uBAAuB,CAAC;AAE/B,YAAY,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AACnD,OAAO,EACL,6BAA6B,EAC7B,0BAA0B,EAC1B,8BAA8B,EAC9B,0BAA0B,EAC1B,YAAY,GACb,MAAM,cAAc,CAAC;AAEtB,YAAY,EAAE,uBAAuB,EAAE,MAAM,wBAAwB,CAAC;AACtE,OAAO,EACL,0BAA0B,EAC1B,sCAAsC,EACtC,mCAAmC,EACnC,uCAAuC,EACvC,qBAAqB,EACrB,qBAAqB,GACtB,MAAM,wBAAwB,CAAC;AAEhC,OAAO,EAAE,0BAA0B,EAAE,MAAM,2BAA2B,CAAC;AAEvE,YAAY,EAAE,yBAAyB,EAAE,4BAA4B,EAAE,MAAM,+BAA+B,CAAC;AAC7G,OAAO,EAAE,uBAAuB,EAAE,MAAM,+BAA+B,CAAC;AAExE,YAAY,EAAE,qBAAqB,EAAE,6BAA6B,EAAE,MAAM,gCAAgC,CAAC;AAC3G,OAAO,EAAE,wBAAwB,EAAE,uBAAuB,EAAE,4BAA4B,EAAE,MAAM,gCAAgC,CAAC;AAKjI,YAAY,EAAE,mBAAmB,EAAE,kBAAkB,EAAE,MAAM,oBAAoB,CAAC;AAClF,OAAO,EAAE,eAAe,EAAE,6BAA6B,EAAE,0BAA0B,EAAE,MAAM,oBAAoB,CAAC"}

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,qBAAqB,EAAE,MAAM,UAAU,CAAC;AAGjD,OAAO,EAAE,YAAY,EAAE,oBAAoB,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AAa1F,OAAO,EAAE,oBAAoB,EAAE,cAAc,EAAE,MAAM,gBAAgB,CAAC;AAGtE,OAAO,EAAE,mBAAmB,EAAE,MAAM,iBAAiB,CAAC;AAGtD,OAAO,EAAE,sBAAsB,EAAE,MAAM,wBAAwB,CAAC;AAGhE,OAAO,EAAE,0BAA0B,EAAE,oBAAoB,EAAE,MAAM,0BAA0B,CAAC;AAG5F,OAAO,EACL,uBAAuB,EACvB,mBAAmB,EACnB,uBAAuB,EACvB,kBAAkB,EAClB,sBAAsB,EACtB,2BAA2B,EAC3B,4BAA4B,EAC5B,4BAA4B,GAC7B,MAAM,uBAAuB,CAAC;AAG/B,OAAO,EACL,6BAA6B,EAC7B,0BAA0B,EAC1B,8BAA8B,EAC9B,0BAA0B,EAC1B,YAAY,GACb,MAAM,cAAc,CAAC;AAGtB,OAAO,EACL,0BAA0B,EAC1B,sCAAsC,EACtC,mCAAmC,EACnC,uCAAuC,EACvC,qBAAqB,EACrB,qBAAqB,GACtB,MAAM,wBAAwB,CAAC;AAEhC,OAAO,EAAE,0BAA0B,EAAE,MAAM,2BAA2B,CAAC;AAGvE,OAAO,EAAE,uBAAuB,EAAE,MAAM,+BAA+B,CAAC;AAGxE,OAAO,EAAE,wBAAwB,EAAE,uBAAuB,EAAE,4BAA4B,EAAE,MAAM,gCAAgC,CAAC;AAajI,OAAO,EAAE,eAAe,EAAE,6BAA6B,EAAE,0BAA0B,EAAE,MAAM,oBAAoB,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,qBAAqB,EAAE,MAAM,UAAU,CAAC;AAGjD,OAAO,EAAE,YAAY,EAAE,oBAAoB,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AAa1F,OAAO,EAAE,oBAAoB,EAAE,cAAc,EAAE,MAAM,gBAAgB,CAAC;AAGtE,OAAO,EAAE,mBAAmB,EAAE,MAAM,iBAAiB,CAAC;AAGtD,OAAO,EAAE,sBAAsB,EAAE,MAAM,wBAAwB,CAAC;AAGhE,OAAO,EAAE,0BAA0B,EAAE,oBAAoB,EAAE,MAAM,0BAA0B,CAAC;AAG5F,OAAO,EACL,uBAAuB,EACvB,mBAAmB,EACnB,uBAAuB,EACvB,kBAAkB,EAClB,sBAAsB,EACtB,2BAA2B,EAC3B,4BAA4B,EAC5B,4BAA4B,GAC7B,MAAM,uBAAuB,CAAC;AAG/B,OAAO,EACL,6BAA6B,EAC7B,0BAA0B,EAC1B,8BAA8B,EAC9B,0BAA0B,EAC1B,YAAY,GACb,MAAM,cAAc,CAAC;AAGtB,OAAO,EACL,0BAA0B,EAC1B,sCAAsC,EACtC,mCAAmC,EACnC,uCAAuC,EACvC,qBAAqB,EACrB,qBAAqB,GACtB,MAAM,wBAAwB,CAAC;AAEhC,OAAO,EAAE,0BAA0B,EAAE,MAAM,2BAA2B,CAAC;AAGvE,OAAO,EAAE,uBAAuB,EAAE,MAAM,+BAA+B,CAAC;AAGxE,OAAO,EAAE,wBAAwB,EAAE,uBAAuB,EAAE,4BAA4B,EAAE,MAAM,gCAAgC,CAAC;AAMjI,OAAO,EAAE,eAAe,EAAE,6BAA6B,EAAE,0BAA0B,EAAE,MAAM,oBAAoB,CAAC"}

package/dist/orchestration.d.ts

@@ -1,15 +1,12 @@
 /**
- * Turns a declarative `services` map (plan §6, RT-028) into a concrete
- * spawn order for `ExecutionController.run()` (RT-032). Everything here is
- * pure and side-effect-free — validated and ordered before anything is
- * spawned, so a bad reference is refused atomically rather than discovered
- * mid-sequence with some services already running.
+ * Turns a declarative `services` map (§6, RT-028) into a concrete spawn order for
+ * `ExecutionController.run()` (RT-032). Pure and side-effect-free -- validated and
+ * ordered before anything is spawned, so a bad reference is refused atomically
+ * rather than discovered mid-sequence.
  *
- * Start order and port injection are **declared in configuration, never
- * inferred** — the same "ask, don't guess" discipline RT-023 already
- * applied to browser script-URL roots. A `${name.port}` reference alone
- * does not create an ordering guarantee; `name` must also appear in the
- * referencing service's own `dependsOn`, or validation refuses.
+ * Start order and port injection are declared, never inferred (RT-023's "ask, don't
+ * guess"): a `${name.port}` reference alone doesn't create an ordering guarantee --
+ * `name` must also appear in the referencing service's `dependsOn`, or validation refuses.
  */
 import type { ServiceConfiguration } from "@descryy/runtime-contracts";
 export type ServicesValidation = {
@@ -20,23 +17,17 @@ export type ServicesValidation = {
     readonly reason: string;
 };
 /**
- * Validates a `services` map and returns a valid topological spawn order.
- * Three checks, all before anything is spawned:
- * 1. every `dependsOn` entry names a real key in `services`;
- * 2. the `dependsOn` graph has no cycle (a start order must exist);
- * 3. every `${name}.port` placeholder referenced in a service's own `env`
- *    has `name` in that same service's `dependsOn` — the placeholder does
- *    not itself create the ordering guarantee it depends on.
+ * Validates a `services` map and returns a topological spawn order. Checks, all
+ * before anything is spawned: every `dependsOn` names a real key; the `dependsOn`
+ * graph has no cycle; every `${name}.port` placeholder in a service's `env` has
+ * `name` in that service's own `dependsOn`.
  */
 export declare function validateServicesConfiguration(services: Readonly<Record<string, ServiceConfiguration>>): ServicesValidation;
 /**
- * Replaces every `${name}.port` in `env`'s values with the resolved port
- * for `name`. Assumes `validateServicesConfiguration` already confirmed
- * every referenced name is a declared dependency that the caller resolves
- * earlier in the same spawn order — a reference this function can't
- * resolve is left untouched rather than silently dropped, so a caller that
- * skipped validation sees an obviously-wrong literal `${...}` instead of a
- * silently empty substitution.
+ * Replaces every `${name}.port` in `env`'s values with the resolved port for `name`.
+ * Assumes `validateServicesConfiguration` already confirmed the reference. An
+ * unresolvable reference is left untouched, not dropped -- a caller that skipped
+ * validation sees an obviously-wrong literal instead of a silent empty substitution.
  */
 export declare function substitutePortPlaceholders(env: Readonly<Record<string, string>> | undefined, resolvedPorts: ReadonlyMap<string, number>): Record<string, string>;
 export type CommandTokenization = {
@@ -48,23 +39,17 @@ export type CommandTokenization = {
     readonly reason: string;
 };
 /**
- * POSIX-style tokenizer for `ServiceConfiguration.command`: single quotes
- * (literal throughout), double quotes (with `\` escaping `"` and `\`), and
- * backslash escapes outside quotes. `spawnProcess` takes `command`/`args`
- * separately while configuration carries one string (plan §6's YAML shape),
- * so something has to split it, and doing that by whitespace alone breaks
- * every path with a space in it — `"C:\Program Files\node.exe"` and
- * `python3 -c "import app; app.main()"` both tokenized wrong before.
+ * POSIX-style tokenizer for `ServiceConfiguration.command`: single quotes (literal),
+ * double quotes (`\` escapes `"` and `\`), backslash escapes outside quotes. Needed
+ * because config carries one string (§6) but `spawnProcess` wants `command`/`args`
+ * separately, and plain whitespace-split breaks paths with spaces.
  *
- * **Refuses rather than guesses** on an unterminated quote, a trailing
- * backslash, or an unquoted shell operator. Each of those has no correct
- * interpretation without a shell, and returning a plausible tokenization
- * for input that cannot mean what it says is how a configuration error
- * arrives disguised as an application failure.
+ * Refuses rather than guesses on an unterminated quote, trailing backslash, or
+ * unquoted shell operator -- a plausible-but-wrong tokenization would disguise a
+ * config error as an application failure.
  *
- * Globs and `~` are *not* refused: they pass through literally, which is
- * exactly what happens with no shell, and unlike the operators above they
- * are frequently intended literally.
+ * Globs and `~` pass through literally, unrefused -- exactly what happens with no
+ * shell, and frequently intended literally.
  */
 export declare function tokenizeCommand(raw: string): CommandTokenization;
 //# sourceMappingURL=orchestration.d.ts.map

package/dist/orchestration.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"orchestration.d.ts","sourceRoot":"","sources":["../src/orchestration.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,4BAA4B,CAAC;AAiBvE,MAAM,MAAM,kBAAkB,GAC1B;IAAE,QAAQ,CAAC,KAAK,EAAE,IAAI,CAAC;IAAC,QAAQ,CAAC,KAAK,EAAE,SAAS,MAAM,EAAE,CAAA;CAAE,GAC3D;IAAE,QAAQ,CAAC,KAAK,EAAE,KAAK,CAAC;IAAC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAAC;AAEvD;;;;;;;;GAQG;AACH,wBAAgB,6BAA6B,CAC3C,QAAQ,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,oBAAoB,CAAC,CAAC,GACvD,kBAAkB,CA+DpB;AAkCD;;;;;;;;GAQG;AACH,wBAAgB,0BAA0B,CACxC,GAAG,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,GAAG,SAAS,EACjD,aAAa,EAAE,WAAW,CAAC,MAAM,EAAE,MAAM,CAAC,GACzC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CASxB;AAED,MAAM,MAAM,mBAAmB,GAC3B;IAAE,QAAQ,CAAC,EAAE,EAAE,IAAI,CAAC;IAAC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,CAAA;CAAE,GACjF;IAAE,QAAQ,CAAC,EAAE,EAAE,KAAK,CAAC;IAAC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAAC;AAkBpD;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,eAAe,CAAC,GAAG,EAAE,MAAM,GAAG,mBAAmB,CA8EhE"}
+{"version":3,"file":"orchestration.d.ts","sourceRoot":"","sources":["../src/orchestration.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,4BAA4B,CAAC;AAUvE,MAAM,MAAM,kBAAkB,GAC1B;IAAE,QAAQ,CAAC,KAAK,EAAE,IAAI,CAAC;IAAC,QAAQ,CAAC,KAAK,EAAE,SAAS,MAAM,EAAE,CAAA;CAAE,GAC3D;IAAE,QAAQ,CAAC,KAAK,EAAE,KAAK,CAAC;IAAC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAAC;AAEvD;;;;;GAKG;AACH,wBAAgB,6BAA6B,CAC3C,QAAQ,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,oBAAoB,CAAC,CAAC,GACvD,kBAAkB,CAyDpB;AAkCD;;;;;GAKG;AACH,wBAAgB,0BAA0B,CACxC,GAAG,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,GAAG,SAAS,EACjD,aAAa,EAAE,WAAW,CAAC,MAAM,EAAE,MAAM,CAAC,GACzC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CASxB;AAED,MAAM,MAAM,mBAAmB,GAC3B;IAAE,QAAQ,CAAC,EAAE,EAAE,IAAI,CAAC;IAAC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,CAAA;CAAE,GACjF;IAAE,QAAQ,CAAC,EAAE,EAAE,KAAK,CAAC;IAAC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAAC;AAWpD;;;;;;;;;;;;GAYG;AACH,wBAAgB,eAAe,CAAC,GAAG,EAAE,MAAM,GAAG,mBAAmB,CA6EhE"}