@descryy/runtime-contracts 0.2.0 → 0.3.1

package/dist/execution.d.ts

@@ -1,19 +1,11 @@
 /**
- * Execution contract.
+ * Execution contract, per §4 (execution model) and §16 (RVE boot sequence
+ * — §16.4's "SETUP FAILURE surfaced immediately, tagged distinctly from a
+ * test failure" is why FAILED_START is a state separate from FAILED).
  *
- * Field list and lifecycle states are verbatim from
- * `documents/descry-runtime-plan.md` §4 (Execution model). Also grounded in
- * the architecture doc's §16 (RVE boot sequence — oracle extraction,
- * environment selection, boot, graph-aware seeding, snapshot, ready; §16.4's
- * "SETUP FAILURE surfaced immediately, tagged distinctly from a test
- * failure" is the direct source of FAILED_START as a state separate from
- * FAILED) and §10.3 (environment tiers, referenced via
- * ExecutionConfiguration.environmentTier from capability.ts).
- *
- * An Execution record holds *references* (event/trace/failure/correlation/
- * finding IDs), never inlines the records themselves — mirrors §18.2's
- * storage rule ("referenced by ID, never inlined") so a long-running
- * execution doesn't grow this record unboundedly.
+ * An Execution record holds references (event/trace/failure/correlation/
+ * finding IDs), never inlines the records themselves (§18.2) — keeps a
+ * long-running execution's record from growing unboundedly.
  */
 import type { EnvironmentTier, FidelityLevel } from "./capability.ts";
 export declare const EXECUTION_STATES: readonly ["CREATED", "STARTING", "READY", "RUNNING", "STOPPING", "COMPLETED", "FAILED_START", "FAILED", "TIMED_OUT", "CANCELLED"];
@@ -21,158 +13,95 @@ export type ExecutionState = (typeof EXECUTION_STATES)[number];
 export declare function isValidExecutionTransition(from: ExecutionState, to: ExecutionState): boolean;
 export declare function isTerminalExecutionState(state: ExecutionState): boolean;
 /**
- * One named service from plan §6's `services` map
- * (`name → {command, cwd, port}`). `port` is an **explicit opt-in** to a
- * fixed port — absent (the default, and the recommended default) means the
- * service is spawned on an OS-assigned ephemeral port, the mitigation
- * RT-024 recommends for the readiness liveness-vs-identity gap: nothing
- * else can already be bound to a port nobody requested, so a stale listener
- * from a dead session can't be mistaken for this run's process by
- * construction, not by convention. A collector recovers `cwd` for a given
- * running process by joining `ProcessHandle.serviceName` back to this map
- * (RT-023's browser script-URL → source mapping).
+ * One named service from §6's `services` map. `port` is explicit opt-in
+ * to a fixed port — absent (recommended default) means an OS-assigned
+ * ephemeral port (RT-024): nothing else can already be bound to a port
+ * nobody requested, so a stale listener from a dead session can't be
+ * mistaken for this run's process. A collector recovers `cwd` by joining
+ * `ProcessHandle.serviceName` back to this map.
  */
 export interface ServiceConfiguration {
-    /**
-     * Required unless `attach` is set — exactly one of `command`/`attach`
-     * must be present (`validateServicesConfiguration` refuses atomically,
-     * before anything spawns, if a service declares neither or both).
-     */
+    /** Required unless `attach` is set — exactly one of `command`/`attach` must be present, refused atomically otherwise. */
     readonly command?: string;
     readonly cwd: string;
-    /** Explicit opt-in only. Omit to get an ephemeral port (RT-024's default). Attach-mode services should set this when the caller already knows what port the already-running target bound — nothing here can allocate one on their behalf, since the target is already listening. */
+    /** Explicit opt-in only. Omit for an ephemeral port (RT-024's default). Attach-mode services should set this when the caller already knows the target's bound port. */
     readonly port?: number;
-    /**
-     * Services (by key into this same `services` map) that must be spawned
-     * and ready before this one starts. **Declared, never inferred** (RT-032)
-     * — an orchestrator refuses rather than guesses at start order from env
-     * references or any other implicit signal.
-     */
+    /** Services (by key into this map) that must be spawned and ready before this one starts. Declared, never inferred (RT-032) — no guessing start order from env references. */
     readonly dependsOn?: readonly string[];
-    /**
-     * Extra environment for this service. A value may contain
-     * `${<name>.port}`, substituted with the actual resolved port of the
-     * named dependency once it has started — `name` must appear in this
-     * service's own `dependsOn`, or an orchestrator refuses rather than spawn
-     * with an unresolved placeholder (RT-032).
-     */
+    /** Extra environment. A value may contain `${<name>.port}`, substituted with the named dependency's resolved port — `name` must be in this service's own `dependsOn`, or the orchestrator refuses (RT-032). */
     readonly env?: Readonly<Record<string, string>>;
     /**
-     * Tokens inserted immediately **after the interpreter** and before the
-     * application's own arguments — `node --import <preload> server.mjs`, not
-     * `node server.mjs --import <preload>`, which would hand them to the
-     * application instead of to the runtime.
-     *
-     * Exists so instrumentation that must be in place *before any application
-     * code runs* can be declared without rewriting `command` as a string and
-     * re-quoting it. Filled by an orchestrator from
-     * `RuntimeAdapter.outboundHttpLaunch()`; nothing here knows which language
-     * asked for it, or what the tokens mean.
+     * Tokens inserted right after the interpreter, before the application's
+     * own args (`node --import <preload> server.mjs`, not the reverse, which
+     * would hand them to the application). Lets pre-application instrumentation
+     * be declared without rewriting `command` as a string. Filled by an
+     * orchestrator from `RuntimeAdapter.outboundHttpLaunch()`.
      */
     readonly interpreterArgs?: readonly string[];
     /**
-     * Alternative to `command`: attach to a process that is already running
-     * instead of spawning a new one. RT-attach-to-running-process-scope.md's
-     * candidate (a) — the target's own pid, and a file its stdout/stderr is
-     * already redirected to (e.g. `npm run dev > server.log 2>&1 &`). Not
-     * generic "attach by base URL" — that remains out of scope, unchanged
-     * (see that same decision file).
+     * Alternative to `command`: attach to an already-running process (pid
+     * plus a redirected stdout/stderr file) instead of spawning one. Not
+     * generic "attach by base URL" (out of scope).
      *
-     * When set, `ExecutionController.run()` calls
-     * `attachManagedProcess`/`isProcessAlive` (`@descryy/runtime-controller`)
-     * instead of `spawnProcess` for this service. `resourceLimits`/
-     * `filesystemPolicy`/`networkPolicy` on `ExecutionConfiguration` are never
-     * applied to an attached service — Descry did not spawn it and, per
-     * `ATTACH_MODE_SCOPE_DISCLOSURE`, never executes code in or applies
-     * changes to a process it merely observes. The resulting `ManagedProcess`'s
-     * `kill()` is correspondingly a no-op: cleanup must not terminate a
-     * process this runtime does not own.
+     * When set, `resourceLimits`/`filesystemPolicy`/`networkPolicy` never
+     * apply — Descry didn't spawn it (`ATTACH_MODE_SCOPE_DISCLOSURE`). The
+     * resulting `ManagedProcess.kill()` is a no-op — cleanup must not
+     * terminate a process this runtime doesn't own.
      */
     readonly attach?: ServiceAttachConfiguration;
 }
 /** See `ServiceConfiguration.attach`. */
 export interface ServiceAttachConfiguration {
-    /** pid of the already-running target. Verified alive before attach is attempted, and re-checked on every poll to detect exit (never signalled by this runtime — see `ServiceConfiguration.attach`'s own comment on `kill()`). */
+    /** pid of the already-running target. Verified alive before attach, re-checked on every poll (never signalled by this runtime). */
     readonly pid: number;
-    /** Path to a file the target is already writing its stdout/stderr to. Read in full on every poll, same growing-buffer contract `ManagedProcess.readOutput()` already has for a spawned process — not a delta. */
+    /** File the target is already writing stdout/stderr to. Read in full on every poll, same growing-buffer contract as `ManagedProcess.readOutput()` — not a delta. */
     readonly logFilePath: string;
 }
 /**
- * §2's "browser options are constructor args, not configuration" gap
- * (RT-068): before this, `launchBrowserSession`'s `BrowserSessionOptions`
- * was a shape only a direct caller could reach, with no path from a
- * declared `ExecutionConfiguration` at all -- every other launch input on
- * this interface (`services`, ports, env, readiness) had that path and this
- * one didn't. Deliberately just `headless` -- the one option that already
- * existed as a constructor arg. Inventing viewport/locale/userAgent fields
- * nothing reads yet would repeat RT-053's lesson about a declared-but-dead
- * type, one layer up.
+ * RT-068: gives `ExecutionConfiguration` a path to browser launch options,
+ * which previously only a direct caller of `launchBrowserSession` could
+ * reach. Deliberately just `headless` — inventing unread viewport/locale/
+ * userAgent fields would repeat RT-053's declared-but-dead-type lesson.
  */
 export interface BrowserConfiguration {
     readonly headless?: boolean;
     /**
-     * Video evidence (competitive research, `documents/decisions-inbox/`
-     * video-evidence proposal): a caller-facing toggle for Playwright's
-     * `recordVideo` context option. Deliberately just a boolean, the same
-     * restraint this interface's own `headless` comment already explains --
-     * `dir` is `browser-session.ts`'s own concern (a session-scoped temp
-     * directory, never caller-supplied) and `size` is not exposed because
-     * nothing reads a caller-supplied value for it yet. Landed together with
-     * its one emitter (`BrowserActionCollector.captureVideo()`), per RT-053's
-     * lesson this file already cites: a declared-but-dead option is the
-     * mistake, not an option existing at all.
+     * Toggle for Playwright's `recordVideo`. Just a boolean, same restraint
+     * as `headless` — `dir` is `browser-session.ts`'s own concern, `size`
+     * isn't exposed because nothing reads it yet. Landed with its one
+     * emitter, `BrowserActionCollector.captureVideo()`.
      */
     readonly recordVideo?: boolean;
 }
 /**
- * §21's execution boundary (RT-070). Applies to every service this
- * execution spawns -- enforced by the OS itself via `prlimit` (util-invoke
- * only, never a shell; RT-036 already refused shell metacharacters in
- * commands and reintroducing `sh -c 'ulimit ...'` to get these would undo
- * that). `prlimit` is util-linux, absent on macOS -- a real **capability**,
- * reported `available`/`unavailable` with a reason
- * (`resourceLimitCapability()`, `@descryy/runtime-controller`), never
- * assumed. Requesting a limit on a platform that cannot enforce it is a
- * refusal, not a silent no-op: the one alternative -- spawn unconstrained
- * and stay quiet about it -- is the exact "sandbox that doesn't sandbox"
- * shape §38 already bans one row up.
+ * §21's execution boundary (RT-070). Enforced by the OS via `prlimit`
+ * (util-invoke only, never a shell — RT-036 already refused shell
+ * metacharacters in commands). `prlimit` is util-linux, absent on macOS —
+ * a real capability, reported `available`/`unavailable` with a reason
+ * (`resourceLimitCapability()`), never assumed. Requesting a limit where
+ * it can't be enforced refuses rather than silently spawning unconstrained.
  *
- * Absent (the default, unchanged from every execution before this) means no
- * limit at all -- this runtime's declared trusted-local boundary (see
- * DECISIONS.md RT-070) does not require one; it is available to a caller
- * that wants a backstop, not imposed on every execution.
+ * Absent (default, unchanged) means no limit — the trusted-local boundary
+ * doesn't require one; it's a backstop a caller opts into, not imposed.
  */
 export interface ResourceLimits {
-    /** Maps to `prlimit --as` (virtual address space) -- the resource the kernel actually enforces for a process that allocates too much; `RLIMIT_RSS` is not enforced on modern Linux. */
+    /** Maps to `prlimit --as` (virtual address space) — what the kernel actually enforces for over-allocation; `RLIMIT_RSS` isn't enforced on modern Linux. */
     readonly maxMemoryBytes?: number;
-    /** Maps to `prlimit --cpu`, in seconds of consumed CPU time. */
+    /** Maps to `prlimit --cpu`, seconds of consumed CPU time. */
     readonly maxCpuSeconds?: number;
-    /** Maps to `prlimit --nproc`. Per-real-uid, not per-process-tree -- a POSIX rlimit property, not a choice made here. A low value on a machine already running many processes under the same user can be exceeded immediately; see `execution-safety.test.ts` for how that risk is tested around rather than through. */
+    /** Maps to `prlimit --nproc`. Per-real-uid, not per-process-tree (a POSIX rlimit property) — a low value can be exceeded immediately on a busy machine; see `execution-safety.test.ts`. */
     readonly maxProcesses?: number;
 }
 /**
- * §21's execution boundary, network half. Sits next to `ResourceLimits` for
- * the same reason and is declared the same way, but the two were not
- * symmetric at RT-193: `prlimit` genuinely enforced CPU/memory/process
- * limits on Linux, while no mechanism anywhere in this runtime restricted
- * which hosts a spawned process could reach.
- *
- * **Real on Linux as of the sandbox-isolation lane**, for one shape only:
- * full denial, `{ mode: "allow", hosts: [] }` (read literally under this
- * interface's own semantics -- only the hosts in `hosts` are reachable, and
- * there are none). Enforced with a network namespace holding nothing but a
- * loopback device, private to the sandboxed process tree -- not even the
- * host's own loopback is reachable from inside it (`networkIsolationCapability()`,
- * `applySandbox()`, `@descryy/runtime-controller`). A non-empty `hosts` list
- * -- selective allow- or deny-listing -- would need DNS interception and IP
- * filtering inside the namespace (a veth pair, NAT, iptables/nftables rules)
- * that this iteration does not build; declaring one still refuses the run,
- * atomically, before anything spawns -- the same "declared, refused rather
- * than silently ignored if unenforceable" precedent `applyResourceLimits`
- * already set one field up. macOS and Windows have no enforcement mechanism
- * wired up at all yet (see the sandbox-isolation lane's own decision note),
- * so every shape refuses there, matching RT-193's original behavior
- * unchanged on those platforms.
+ * §21's execution boundary, network half. Real on Linux for one shape
+ * only: full denial, `{ mode: "allow", hosts: [] }` — enforced via a
+ * network namespace holding nothing but a private loopback device, not
+ * even the host's own loopback reachable from inside
+ * (`networkIsolationCapability()`, `applySandbox()`). A non-empty `hosts`
+ * list would need DNS interception and IP filtering this iteration
+ * doesn't build, so it refuses atomically before anything spawns — same
+ * precedent as `ResourceLimits`. macOS/Windows have no enforcement wired
+ * up, so every shape refuses there.
  */
 export interface NetworkPolicy {
     /** "allow" means only `hosts` are reachable; "deny" means every host in `hosts` is refused, everything else reachable. */
@@ -180,61 +109,44 @@ export interface NetworkPolicy {
     readonly hosts: readonly string[];
 }
 /**
- * §21's execution boundary, filesystem half. Sibling to `NetworkPolicy`:
- * declared the same way, enforced the same way -- real on Linux
- * (`@descryy/runtime-controller`'s `filesystemIsolationCapability`, via a
- * mount namespace built with bubblewrap), refused rather than silently
- * accepted and unenforced everywhere else (macOS, Windows -- no mechanism
- * wired up yet).
+ * §21's execution boundary, filesystem half. Real on Linux (mount
+ * namespace via bubblewrap, `filesystemIsolationCapability`), refused
+ * rather than silently unenforced on macOS/Windows.
  *
- * A path outside `allowedRoots` (plus `cwd`, always included automatically,
- * and the resolved directory of the interpreter binary being spawned -- see
- * `applySandbox`'s own comment) is not merely unreadable inside the
- * sandbox, it is **not present**: `open()` on it fails with `ENOENT`, the
- * same as a path that never existed, because the mount namespace never
- * bound it in. That is a stronger claim than a permission bit, and the one
- * the escape tests in `sandbox.test.ts` exist to prove for real rather than
- * assert from the mechanism's documentation alone.
+ * A path outside `allowedRoots` (plus `cwd` and the interpreter binary's
+ * directory, always included) is not just unreadable — `open()` fails
+ * with `ENOENT`, same as a path that never existed, because the mount
+ * namespace never bound it in. Proved for real by the escape tests in
+ * `sandbox.test.ts`, not just asserted from documentation.
  */
 export interface FilesystemPolicy {
-    /** Absolute paths visible read-write inside the sandbox, in addition to `cwd`. Everything else on the host, including the rest of the user's home directory, is invisible to the spawned process -- not just unwritable, not mounted at all. */
+    /** Absolute paths visible read-write inside the sandbox, in addition to `cwd`. Everything else, including the rest of the user's home directory, is invisible — not mounted at all. */
     readonly allowedRoots: readonly string[];
 }
 /**
- * §2's "commit is recorded; environment metadata is not captured" gap
- * (RT-193): `Execution.commit` alone cannot reproduce a run -- the same
- * commit under a different Node version, OS, or toolchain can behave
- * differently, and nothing recorded which one actually ran. Captured once,
- * at the start of `ExecutionController.run()`, from the real host --
- * declared here as the shape, not computed in the contract layer, matching
- * this file's own "field list lives here, capture logic lives in
- * `packages/controller`" split.
+ * RT-193: `Execution.commit` alone can't reproduce a run — same commit,
+ * different Node/OS/toolchain can behave differently. Captured once at
+ * the start of `ExecutionController.run()`; the shape lives here, capture
+ * logic lives in `packages/controller`.
  */
 export interface EnvironmentMetadata {
-    /** `os.platform()` -- "linux" / "darwin" / "win32" / etc. */
+    /** `os.platform()` — "linux" / "darwin" / "win32" / etc. */
     readonly platform: string;
-    /** `process.version` of the Node process running the controller itself -- always known, never probed. */
+    /** `process.version` of the controller's own Node process — always known, never probed. */
     readonly nodeVersion: string;
     /**
-     * `<command> --version` (or the closest working equivalent), one entry per
-     * distinct executable named by `configuration.services[*].command` --
-     * reuses `scripts/preflight.mjs`'s `interpreters()` probe shape rather
-     * than a second implementation of it. `null` for a command that could not
-     * be probed (absent, or refuses every version flag tried) -- recorded,
-     * not dropped from the map, matching RT-070's "declared, refused rather
-     * than silently ignored" precedent applied to a report instead of an
-     * enforcement gate.
+     * `<command> --version` per distinct executable named in
+     * `configuration.services[*].command` — reuses `scripts/preflight.mjs`'s
+     * `interpreters()` probe. `null` for a command that couldn't be probed,
+     * recorded rather than dropped.
      */
     readonly toolchainVersions: Readonly<Record<string, string | null>>;
 }
 /**
- * §2's "test-runner configuration exists, but not (yet) a field" gap: before
- * this, `createTestRunnerCollector`'s `TestRunnerCollectorOptions.configuration`
- * was declared independently in `@descryy/runtime-test-runner`, with no
- * path from a declared `ExecutionConfiguration` at all -- the same gap
- * `BrowserConfiguration` closed at RT-068, one field over. This is the
- * contracts type; `packages/test-runner` imports and re-exports it rather
- * than keeping a second, driftable copy.
+ * RT-068 gap, one field over: gives `ExecutionConfiguration` a path to
+ * test-runner options that previously only existed independently in
+ * `@descryy/runtime-test-runner`. `packages/test-runner` imports and
+ * re-exports this rather than keeping a driftable second copy.
  */
 export interface TestRunnerConfiguration {
     readonly command: string;
@@ -245,72 +157,50 @@ export interface ExecutionConfiguration {
     readonly fidelityLevel: FidelityLevel;
     readonly timeoutMs: number;
     readonly services: Readonly<Record<string, ServiceConfiguration>>;
-    /** Absent means `launchBrowserSession`'s own default (`headless: true`) -- not a second default defined here that could disagree with it. */
+    /** Absent means `launchBrowserSession`'s own default (`headless: true`) — no second default here to disagree with it. */
     readonly browser?: BrowserConfiguration;
-    /** Absent means no test run declared for this execution -- `createTestRunnerCollector` is a direct caller's own concern, not something `ExecutionController.run()` invokes automatically. See `TestRunnerConfiguration`'s own comment. */
+    /** Absent means no test run declared — `createTestRunnerCollector` is a direct caller's concern, not auto-invoked by `ExecutionController.run()`. */
     readonly testRunner?: TestRunnerConfiguration;
-    /** Absent means unconstrained -- see `ResourceLimits`'s own comment for why that is the correct default, not a gap. */
+    /** Absent means unconstrained — see `ResourceLimits` for why that's the correct default. */
     readonly resourceLimits?: ResourceLimits;
-    /** Absent means no policy declared. See `NetworkPolicy`'s own comment -- full denial is enforced on Linux; every other declared shape, and every shape on macOS/Windows, refuses to start rather than running unconstrained. */
+    /** Absent means no policy declared. See `NetworkPolicy` — full denial enforced on Linux; every other shape, and every shape on macOS/Windows, refuses to start. */
     readonly networkPolicy?: NetworkPolicy;
-    /** Absent means unconstrained -- the default, unchanged. See `FilesystemPolicy`'s own comment -- enforced on Linux, refuses to start elsewhere rather than running unconstrained under a declared policy that cannot be applied. */
+    /** Absent means unconstrained. See `FilesystemPolicy` — enforced on Linux, refuses to start elsewhere rather than running unconstrained under an unenforceable policy. */
     readonly filesystemPolicy?: FilesystemPolicy;
     /**
-     * Which real mechanism enforces `filesystemPolicy`/`networkPolicy` when
-     * either is declared. Absent means `"bwrap"` -- the original Linux
-     * mechanism (`@descryy/runtime-controller`'s `sandbox.ts`), completely
-     * unchanged in behavior by this field's existence. `"container"` routes
-     * the same declared policies through a real Docker container instead
-     * (`container-sandbox.ts`) -- the macOS/Windows path, since neither
-     * platform has a native bwrap equivalent wired up; also usable on Linux.
-     * Declaring `"container"` without a working Docker present refuses to
-     * start, the same "refuse rather than silently run unconstrained"
-     * precedent `filesystemPolicy`/`networkPolicy` already established.
+     * Which mechanism enforces `filesystemPolicy`/`networkPolicy`. Absent
+     * means `"bwrap"` (the original Linux mechanism, unchanged). `"container"`
+     * routes the same policies through Docker instead — the macOS/Windows
+     * path, also usable on Linux. Declaring `"container"` without a working
+     * Docker refuses to start, same precedent as the policies above.
      */
     readonly sandboxBackend?: "bwrap" | "container";
 }
 export interface ProcessHandle {
     readonly processId: string;
     readonly command: string;
-    /** Null once the process has exited and been reaped. */
+    /** Null once exited and reaped. */
     readonly pid: number | null;
     readonly startedAt: string;
     readonly exitedAt: string | null;
     /**
-     * POSIX only sets an exit code on normal `exit()` — null both before the
-     * process has started exiting and after it was killed by a signal, so
-     * `exitCode` alone cannot tell "never ran" apart from "crashed." `signal`
-     * is what actually distinguishes a clean-but-ambiguous exit from a real
-     * crash (RT-032): non-null here means the process was killed by that
-     * signal, whatever `exitCode` says.
+     * POSIX only sets an exit code on normal `exit()` — null both before
+     * exiting and after being killed by a signal, so `exitCode` alone can't
+     * tell "never ran" from "crashed." `signal` distinguishes a clean-but-
+     * ambiguous exit from a real crash (RT-032).
      */
     readonly exitCode: number | null;
     readonly signal: NodeJS.Signals | null;
-    /**
-     * Which key of `ExecutionConfiguration.services` this process is running,
-     * when known — null for a process that doesn't correspond to a named
-     * service (e.g. a one-off test-runner invocation). The join key for
-     * recovering `cwd`/`command` from configuration; see `ServiceConfiguration`.
-     */
+    /** Which key of `ExecutionConfiguration.services` this process runs, when known — null for a process with no named service (e.g. a one-off test-runner invocation). Join key for recovering `cwd`/`command`. */
     readonly serviceName: string | null;
-    /**
-     * The actual port this process is bound to, when it listens on one — the
-     * real OS-assigned port for an ephemeral service, not merely a value that
-     * was requested. Null for a process that isn't a network service, or
-     * before the port is known.
-     */
+    /** The actual OS-assigned port this process is bound to, not merely requested. Null if not a network service, or not yet known. */
     readonly port: number | null;
     /**
      * True only for a service started via `ServiceConfiguration.attach` —
-     * absent (equivalent to `false`) for every process this runtime actually
-     * spawned, unchanged from every `ProcessHandle` before this field existed.
-     * Exists so evidence and lifecycle consumers downstream (`ProcessCollector`,
-     * `runInstrumentedExecution`) can tell "we observed a process we did not
-     * spawn" from "we spawned this ourselves" without inferring it from
-     * `command`'s text — the same "declared, not guessed" discipline this
-     * file already applies everywhere else. See `ATTACH_MODE_SCOPE_DISCLOSURE`
-     * (`@descryy/runtime-contracts`'s `collector.ts`) for what attach mode
-     * does and does not do to the process this describes.
+     * absent for every spawned process. Lets downstream consumers
+     * (`ProcessCollector`, `runInstrumentedExecution`) tell "observed, not
+     * spawned" apart without inferring it from `command`'s text. See
+     * `ATTACH_MODE_SCOPE_DISCLOSURE` in `collector.ts`.
      */
     readonly attached?: boolean;
 }
@@ -325,7 +215,7 @@ export interface Execution {
     readonly application: string;
     readonly repository: string;
     readonly commit: string;
-    /** Null until `run()` captures it (RT-193) -- absent on an `Execution` still in `CREATED`, populated by `STARTING`. See `EnvironmentMetadata`'s own comment for why `commit` alone was not reproducible. */
+    /** Null until `run()` captures it (RT-193) — populated by `STARTING`. See `EnvironmentMetadata` for why `commit` alone isn't reproducible. */
     readonly environmentMetadata: EnvironmentMetadata | null;
     readonly configuration: ExecutionConfiguration;
     readonly state: ExecutionState;

package/dist/execution.d.ts.map

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

package/dist/execution.js

@@ -1,19 +1,11 @@
 /**
- * Execution contract.
+ * Execution contract, per §4 (execution model) and §16 (RVE boot sequence
+ * — §16.4's "SETUP FAILURE surfaced immediately, tagged distinctly from a
+ * test failure" is why FAILED_START is a state separate from FAILED).
  *
- * Field list and lifecycle states are verbatim from
- * `documents/descry-runtime-plan.md` §4 (Execution model). Also grounded in
- * the architecture doc's §16 (RVE boot sequence — oracle extraction,
- * environment selection, boot, graph-aware seeding, snapshot, ready; §16.4's
- * "SETUP FAILURE surfaced immediately, tagged distinctly from a test
- * failure" is the direct source of FAILED_START as a state separate from
- * FAILED) and §10.3 (environment tiers, referenced via
- * ExecutionConfiguration.environmentTier from capability.ts).
- *
- * An Execution record holds *references* (event/trace/failure/correlation/
- * finding IDs), never inlines the records themselves — mirrors §18.2's
- * storage rule ("referenced by ID, never inlined") so a long-running
- * execution doesn't grow this record unboundedly.
+ * An Execution record holds references (event/trace/failure/correlation/
+ * finding IDs), never inlines the records themselves (§18.2) — keeps a
+ * long-running execution's record from growing unboundedly.
  */
 export const EXECUTION_STATES = [
     "CREATED",

package/dist/execution.js.map

@@ -1 +1 @@
-{"version":3,"file":"execution.js","sourceRoot":"","sources":["../src/execution.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAIH,MAAM,CAAC,MAAM,gBAAgB,GAAG;IAC9B,SAAS;IACT,UAAU;IACV,OAAO;IACP,SAAS;IACT,UAAU;IACV,WAAW;IACX,cAAc;IACd,QAAQ;IACR,WAAW;IACX,WAAW;CACH,CAAC;AAGX,MAAM,eAAe,GAAgC,IAAI,GAAG,CAAC;IAC3D,WAAW;IACX,cAAc;IACd,QAAQ;IACR,WAAW;IACX,WAAW;CACZ,CAAC,CAAC;AAEH,MAAM,mBAAmB,GAAgE;IACvF,OAAO,EAAE,CAAC,UAAU,EAAE,WAAW,CAAC;IAClC,QAAQ,EAAE,CAAC,OAAO,EAAE,cAAc,EAAE,WAAW,EAAE,WAAW,CAAC;IAC7D,KAAK,EAAE,CAAC,SAAS,EAAE,UAAU,EAAE,WAAW,CAAC;IAC3C,OAAO,EAAE,CAAC,UAAU,EAAE,QAAQ,EAAE,WAAW,EAAE,WAAW,CAAC;IACzD,QAAQ,EAAE,CAAC,WAAW,EAAE,QAAQ,CAAC;IACjC,SAAS,EAAE,EAAE;IACb,YAAY,EAAE,EAAE;IAChB,MAAM,EAAE,EAAE;IACV,SAAS,EAAE,EAAE;IACb,SAAS,EAAE,EAAE;CACd,CAAC;AAEF,MAAM,UAAU,0BAA0B,CAAC,IAAoB,EAAE,EAAkB;IACjF,OAAO,mBAAmB,CAAC,IAAI,CAAC,CAAC,QAAQ,CAAC,EAAE,CAAC,CAAC;AAChD,CAAC;AAED,MAAM,UAAU,wBAAwB,CAAC,KAAqB;IAC5D,OAAO,eAAe,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC;AACpC,CAAC"}
+{"version":3,"file":"execution.js","sourceRoot":"","sources":["../src/execution.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAIH,MAAM,CAAC,MAAM,gBAAgB,GAAG;IAC9B,SAAS;IACT,UAAU;IACV,OAAO;IACP,SAAS;IACT,UAAU;IACV,WAAW;IACX,cAAc;IACd,QAAQ;IACR,WAAW;IACX,WAAW;CACH,CAAC;AAGX,MAAM,eAAe,GAAgC,IAAI,GAAG,CAAC;IAC3D,WAAW;IACX,cAAc;IACd,QAAQ;IACR,WAAW;IACX,WAAW;CACZ,CAAC,CAAC;AAEH,MAAM,mBAAmB,GAAgE;IACvF,OAAO,EAAE,CAAC,UAAU,EAAE,WAAW,CAAC;IAClC,QAAQ,EAAE,CAAC,OAAO,EAAE,cAAc,EAAE,WAAW,EAAE,WAAW,CAAC;IAC7D,KAAK,EAAE,CAAC,SAAS,EAAE,UAAU,EAAE,WAAW,CAAC;IAC3C,OAAO,EAAE,CAAC,UAAU,EAAE,QAAQ,EAAE,WAAW,EAAE,WAAW,CAAC;IACzD,QAAQ,EAAE,CAAC,WAAW,EAAE,QAAQ,CAAC;IACjC,SAAS,EAAE,EAAE;IACb,YAAY,EAAE,EAAE;IAChB,MAAM,EAAE,EAAE;IACV,SAAS,EAAE,EAAE;IACb,SAAS,EAAE,EAAE;CACd,CAAC;AAEF,MAAM,UAAU,0BAA0B,CAAC,IAAoB,EAAE,EAAkB;IACjF,OAAO,mBAAmB,CAAC,IAAI,CAAC,CAAC,QAAQ,CAAC,EAAE,CAAC,CAAC;AAChD,CAAC;AAED,MAAM,UAAU,wBAAwB,CAAC,KAAqB;IAC5D,OAAO,eAAe,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC;AACpC,CAAC"}

package/dist/runtime-event.d.ts

@@ -1,39 +1,21 @@
 /**
- * Runtime Event vocabulary.
- *
- * The exact 19 values below are the canonical list from
- * `documents/descry-runtime-plan.md` §14 — reproduced verbatim, not
- * reconstructed. An earlier version of this file was written before that
- * document was available in this repo and guessed at a vocabulary that did
- * not match it; this replaces that guess.
- *
- * This vocabulary is DELIBERATELY INDEPENDENT of the Graph Engine's 15 node
- * types / 15 edge types (descry-core CLAUDE.md, DEC-061) — plan §14 states
- * this explicitly. A runtime event is an observation, not a graph fact, and
- * this list may grow or change on its own schedule. If a runtime need ever
- * looks like it wants a new *graph* node or edge type, that is out of scope
- * here — stop and raise it (plan principle 12). The graph vocabulary is
- * frozen; this one is not.
+ * Runtime Event vocabulary, per §14. Deliberately independent of the
+ * Graph Engine's 15 node/15 edge types (DEC-061) — a runtime event is an
+ * observation, not a graph fact, and can grow on its own schedule. A need
+ * that looks like a new graph node/edge type is out of scope here — the
+ * graph vocabulary is frozen, this one is not.
  */
 export declare const RUNTIME_EVENT_TYPES: readonly ["PROCESS_STARTED", "PROCESS_READY", "PROCESS_EXITED", "PAGE_CREATED", "NAVIGATION", "CLICK", "INPUT", "SCREENSHOT", "VIDEO", "CONSOLE_MESSAGE", "NETWORK_REQUEST", "NETWORK_RESPONSE", "HTTP_ERROR", "BACKEND_LOG", "EXCEPTION", "STACK_TRACE", "TEST_STARTED", "TEST_PASSED", "TEST_FAILED", "TEST_SKIPPED", "DATABASE_QUERY", "EXTERNAL_REQUEST", "COLLECTOR_ERROR", "DEPENDENCY_VERSION_MISMATCH", "ENVIRONMENT_VERSION_MISMATCH", "WEBSOCKET_CLOSED"];
 export type RuntimeEventType = (typeof RUNTIME_EVENT_TYPES)[number];
 /**
- * **The prefix Descry reserves on an observed process's stdout.**
- *
- * A preload that instruments a process from the inside reports each
- * observation as one line of structured JSON on that process's own stdout --
- * `DESCRY_DB_QUERY {...}`, `DESCRY_EXTERNAL_REQUEST {...}`. Inside an observed
- * process stdout *is* the evidence channel, so that is right.
- *
- * It also means the backend log collector, reading the same stdout, sees them.
- * Without knowing the prefix it attributed them to the application, and a
- * user's report showed Descry's own instrumentation chatter as lines their
- * service printed. This constant is the one place that says which vocabulary
- * is Descry's, so the collector can leave it alone and every marker module can
- * derive from it instead of spelling the prefix again.
- *
- * Anchored at the start of a line by every consumer: a log line that merely
- * *mentions* a marker is the application's own output.
+ * The prefix Descry reserves on an observed process's stdout. A preload
+ * instrumenting a process from the inside reports each observation as one
+ * line of structured JSON there (`DESCRY_DB_QUERY {...}`, etc). Found the
+ * hard way: without this, the backend log collector reading the same
+ * stdout attributed Descry's own instrumentation chatter to the
+ * application. One place defines the prefix; every marker module derives
+ * from it. Anchored at line start by every consumer — a line that merely
+ * mentions a marker is the application's own output.
  */
 export declare const RESERVED_MARKER_PREFIX = "DESCRY_";
 //# sourceMappingURL=runtime-event.d.ts.map

package/dist/runtime-event.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"runtime-event.d.ts","sourceRoot":"","sources":["../src/runtime-event.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,eAAO,MAAM,mBAAmB,qcAyOtB,CAAC;AAEX,MAAM,MAAM,gBAAgB,GAAG,CAAC,OAAO,mBAAmB,CAAC,CAAC,MAAM,CAAC,CAAC;AAEpE;;;;;;;;;;;;;;;;;GAiBG;AACH,eAAO,MAAM,sBAAsB,YAAY,CAAC"}
+{"version":3,"file":"runtime-event.d.ts","sourceRoot":"","sources":["../src/runtime-event.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,eAAO,MAAM,mBAAmB,qcAkHtB,CAAC;AAEX,MAAM,MAAM,gBAAgB,GAAG,CAAC,OAAO,mBAAmB,CAAC,CAAC,MAAM,CAAC,CAAC;AAEpE;;;;;;;;;GASG;AACH,eAAO,MAAM,sBAAsB,YAAY,CAAC"}