@descryy/runtime-contracts 0.0.0

package/dist/execution.d.ts

@@ -0,0 +1,329 @@
+/**
+ * Execution contract.
+ *
+ * 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.
+ */
+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"];
+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).
+ */
+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).
+     */
+    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. */
+    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.
+     */
+    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).
+     */
+    readonly env?: Readonly<Record<string, 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).
+     *
+     * 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.
+     */
+    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()`). */
+    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. */
+    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.
+ */
+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.
+     */
+    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.
+ *
+ * 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.
+ */
+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. */
+    readonly maxMemoryBytes?: number;
+    /** Maps to `prlimit --cpu`, in 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. */
+    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.
+ */
+export interface NetworkPolicy {
+    /** "allow" means only `hosts` are reachable; "deny" means every host in `hosts` is refused, everything else reachable. */
+    readonly mode: "allow" | "deny";
+    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).
+ *
+ * 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.
+ */
+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. */
+    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.
+ */
+export interface EnvironmentMetadata {
+    /** `os.platform()` -- "linux" / "darwin" / "win32" / etc. */
+    readonly platform: string;
+    /** `process.version` of the Node process running the controller itself -- 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.
+     */
+    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 `@descryhq-wq/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.
+ */
+export interface TestRunnerConfiguration {
+    readonly command: string;
+    readonly cwd: string;
+}
+export interface ExecutionConfiguration {
+    readonly environmentTier: EnvironmentTier;
+    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. */
+    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. */
+    readonly testRunner?: TestRunnerConfiguration;
+    /** Absent means unconstrained -- see `ResourceLimits`'s own comment for why that is the correct default, not a gap. */
+    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. */
+    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. */
+    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.
+     */
+    readonly sandboxBackend?: "bwrap" | "container";
+}
+export interface ProcessHandle {
+    readonly processId: string;
+    readonly command: string;
+    /** Null once the process has exited and been 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.
+     */
+    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`.
+     */
+    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.
+     */
+    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.
+     */
+    readonly attached?: boolean;
+}
+export interface BrowserSessionHandle {
+    readonly sessionId: string;
+    readonly targetUrl: string;
+    readonly startedAt: string;
+    readonly endedAt: string | null;
+}
+export interface Execution {
+    readonly executionId: string;
+    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. */
+    readonly environmentMetadata: EnvironmentMetadata | null;
+    readonly configuration: ExecutionConfiguration;
+    readonly state: ExecutionState;
+    readonly startedAt: string | null;
+    readonly endedAt: string | null;
+    readonly processes: readonly ProcessHandle[];
+    readonly browserSessions: readonly BrowserSessionHandle[];
+    readonly eventIds: readonly string[];
+    readonly traceIds: readonly string[];
+    readonly failureIds: readonly string[];
+    readonly correlationIds: readonly string[];
+    readonly findingIds: readonly string[];
+}
+//# sourceMappingURL=execution.d.ts.map

package/dist/execution.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"execution.d.ts","sourceRoot":"","sources":["../src/execution.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,OAAO,KAAK,EAAE,eAAe,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAC;AAEtE,eAAO,MAAM,gBAAgB,mIAWnB,CAAC;AACX,MAAM,MAAM,cAAc,GAAG,CAAC,OAAO,gBAAgB,CAAC,CAAC,MAAM,CAAC,CAAC;AAuB/D,wBAAgB,0BAA0B,CAAC,IAAI,EAAE,cAAc,EAAE,EAAE,EAAE,cAAc,GAAG,OAAO,CAE5F;AAED,wBAAgB,wBAAwB,CAAC,KAAK,EAAE,cAAc,GAAG,OAAO,CAEvE;AAED;;;;;;;;;;;GAWG;AACH,MAAM,WAAW,oBAAoB;IACnC;;;;OAIG;IACH,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,oRAAoR;IACpR,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IACvB;;;;;OAKG;IACH,QAAQ,CAAC,SAAS,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IACvC;;;;;;OAMG;IACH,QAAQ,CAAC,GAAG,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;IAChD;;;;;;;;;;;;;;;;;OAiBG;IACH,QAAQ,CAAC,MAAM,CAAC,EAAE,0BAA0B,CAAC;CAC9C;AAED,yCAAyC;AACzC,MAAM,WAAW,0BAA0B;IACzC,iOAAiO;IACjO,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,iNAAiN;IACjN,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;CAC9B;AAED;;;;;;;;;;GAUG;AACH,MAAM,WAAW,oBAAoB;IACnC,QAAQ,CAAC,QAAQ,CAAC,EAAE,OAAO,CAAC;IAC5B;;;;;;;;;;;OAWG;IACH,QAAQ,CAAC,WAAW,CAAC,EAAE,OAAO,CAAC;CAChC;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,WAAW,cAAc;IAC7B,uLAAuL;IACvL,QAAQ,CAAC,cAAc,CAAC,EAAE,MAAM,CAAC;IACjC,gEAAgE;IAChE,QAAQ,CAAC,aAAa,CAAC,EAAE,MAAM,CAAC;IAChC,wTAAwT;IACxT,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,CAAC;CAChC;AAED;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,MAAM,WAAW,aAAa;IAC5B,0HAA0H;IAC1H,QAAQ,CAAC,IAAI,EAAE,OAAO,GAAG,MAAM,CAAC;IAChC,QAAQ,CAAC,KAAK,EAAE,SAAS,MAAM,EAAE,CAAC;CACnC;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,WAAW,gBAAgB;IAC/B,gPAAgP;IAChP,QAAQ,CAAC,YAAY,EAAE,SAAS,MAAM,EAAE,CAAC;CAC1C;AAED;;;;;;;;;GASG;AACH,MAAM,WAAW,mBAAmB;IAClC,6DAA6D;IAC7D,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,yGAAyG;IACzG,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B;;;;;;;;;OASG;IACH,QAAQ,CAAC,iBAAiB,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC,CAAC,CAAC;CACrE;AAED;;;;;;;;GAQG;AACH,MAAM,WAAW,uBAAuB;IACtC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;CACtB;AAED,MAAM,WAAW,sBAAsB;IACrC,QAAQ,CAAC,eAAe,EAAE,eAAe,CAAC;IAC1C,QAAQ,CAAC,aAAa,EAAE,aAAa,CAAC;IACtC,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,QAAQ,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,oBAAoB,CAAC,CAAC,CAAC;IAClE,6IAA6I;IAC7I,QAAQ,CAAC,OAAO,CAAC,EAAE,oBAAoB,CAAC;IACxC,0OAA0O;IAC1O,QAAQ,CAAC,UAAU,CAAC,EAAE,uBAAuB,CAAC;IAC9C,uHAAuH;IACvH,QAAQ,CAAC,cAAc,CAAC,EAAE,cAAc,CAAC;IACzC,gOAAgO;IAChO,QAAQ,CAAC,aAAa,CAAC,EAAE,aAAa,CAAC;IACvC,oOAAoO;IACpO,QAAQ,CAAC,gBAAgB,CAAC,EAAE,gBAAgB,CAAC;IAC7C;;;;;;;;;;;OAWG;IACH,QAAQ,CAAC,cAAc,CAAC,EAAE,OAAO,GAAG,WAAW,CAAC;CACjD;AAED,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,wDAAwD;IACxD,QAAQ,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IACjC;;;;;;;OAOG;IACH,QAAQ,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IACjC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC,OAAO,GAAG,IAAI,CAAC;IACvC;;;;;OAKG;IACH,QAAQ,CAAC,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;IACpC;;;;;OAKG;IACH,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IAC7B;;;;;;;;;;;OAWG;IACH,QAAQ,CAAC,QAAQ,CAAC,EAAE,OAAO,CAAC;CAC7B;AAED,MAAM,WAAW,oBAAoB;IACnC,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;CACjC;AAED,MAAM,WAAW,SAAS;IACxB,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,4MAA4M;IAC5M,QAAQ,CAAC,mBAAmB,EAAE,mBAAmB,GAAG,IAAI,CAAC;IACzD,QAAQ,CAAC,aAAa,EAAE,sBAAsB,CAAC;IAC/C,QAAQ,CAAC,KAAK,EAAE,cAAc,CAAC;IAC/B,QAAQ,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IAClC,QAAQ,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IAChC,QAAQ,CAAC,SAAS,EAAE,SAAS,aAAa,EAAE,CAAC;IAC7C,QAAQ,CAAC,eAAe,EAAE,SAAS,oBAAoB,EAAE,CAAC;IAC1D,QAAQ,CAAC,QAAQ,EAAE,SAAS,MAAM,EAAE,CAAC;IACrC,QAAQ,CAAC,QAAQ,EAAE,SAAS,MAAM,EAAE,CAAC;IACrC,QAAQ,CAAC,UAAU,EAAE,SAAS,MAAM,EAAE,CAAC;IACvC,QAAQ,CAAC,cAAc,EAAE,SAAS,MAAM,EAAE,CAAC;IAC3C,QAAQ,CAAC,UAAU,EAAE,SAAS,MAAM,EAAE,CAAC;CACxC"}

package/dist/execution.js

@@ -0,0 +1,55 @@
+/**
+ * Execution contract.
+ *
+ * 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.
+ */
+export const EXECUTION_STATES = [
+    "CREATED",
+    "STARTING",
+    "READY",
+    "RUNNING",
+    "STOPPING",
+    "COMPLETED",
+    "FAILED_START",
+    "FAILED",
+    "TIMED_OUT",
+    "CANCELLED",
+];
+const TERMINAL_STATES = new Set([
+    "COMPLETED",
+    "FAILED_START",
+    "FAILED",
+    "TIMED_OUT",
+    "CANCELLED",
+]);
+const ALLOWED_TRANSITIONS = {
+    CREATED: ["STARTING", "CANCELLED"],
+    STARTING: ["READY", "FAILED_START", "TIMED_OUT", "CANCELLED"],
+    READY: ["RUNNING", "STOPPING", "CANCELLED"],
+    RUNNING: ["STOPPING", "FAILED", "TIMED_OUT", "CANCELLED"],
+    STOPPING: ["COMPLETED", "FAILED"],
+    COMPLETED: [],
+    FAILED_START: [],
+    FAILED: [],
+    TIMED_OUT: [],
+    CANCELLED: [],
+};
+export function isValidExecutionTransition(from, to) {
+    return ALLOWED_TRANSITIONS[from].includes(to);
+}
+export function isTerminalExecutionState(state) {
+    return TERMINAL_STATES.has(state);
+}
+//# sourceMappingURL=execution.js.map

package/dist/execution.js.map

@@ -0,0 +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"}

package/dist/index.d.ts

@@ -0,0 +1,14 @@
+export type { EnvironmentTier, FidelityLevel, CapabilityAvailability, CapabilityStatus, CollectorCapabilities, ExecutionCapabilities, } from "./capability.ts";
+export { ENVIRONMENT_TIERS, FIDELITY_LEVELS, CAPABILITY_AVAILABILITY, isCapabilityStatusValid } from "./capability.ts";
+export type { ExecutionState, ServiceConfiguration, ServiceAttachConfiguration, BrowserConfiguration, ResourceLimits, NetworkPolicy, FilesystemPolicy, EnvironmentMetadata, TestRunnerConfiguration, ExecutionConfiguration, ProcessHandle, BrowserSessionHandle, Execution, } from "./execution.ts";
+export { EXECUTION_STATES, isValidExecutionTransition, isTerminalExecutionState, } from "./execution.ts";
+export type { ConfiguredServiceRoot, ServiceRootRefusal, ServiceRootLookup } from "./source-root.ts";
+export { SERVICE_ROOT_REFUSALS, resolveServiceRootForOrigin } from "./source-root.ts";
+export type { RuntimeEventType } from "./runtime-event.ts";
+export { RUNTIME_EVENT_TYPES } from "./runtime-event.ts";
+export type { EvidenceSource, RedactionStatus, SourceLocationReliability, SourceLocation, StackFidelity, StackFrame, StackTrace, Evidence, } from "./evidence.ts";
+export { EVIDENCE_SOURCES, REDACTION_STATUSES, SOURCE_LOCATION_RELIABILITIES, STACK_FIDELITIES, primaryFrameLocation, locationNamesNothing, } from "./evidence.ts";
+export type { CorrelationMethod, Correlation } from "./correlation.ts";
+export { CORRELATION_METHODS, CORRELATION_PREFERENCE_ORDER, correlationRank, isStructuralCorrelation, createCorrelation, } from "./correlation.ts";
+export type { EmitFn, SourceRootResolver, CollectorContext, CollectorStartResult, Collector, } from "./collector.ts";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,YAAY,EACV,eAAe,EACf,aAAa,EACb,sBAAsB,EACtB,gBAAgB,EAChB,qBAAqB,EACrB,qBAAqB,GACtB,MAAM,iBAAiB,CAAC;AACzB,OAAO,EAAE,iBAAiB,EAAE,eAAe,EAAE,uBAAuB,EAAE,uBAAuB,EAAE,MAAM,iBAAiB,CAAC;AAEvH,YAAY,EACV,cAAc,EACd,oBAAoB,EACpB,0BAA0B,EAC1B,oBAAoB,EACpB,cAAc,EACd,aAAa,EACb,gBAAgB,EAChB,mBAAmB,EACnB,uBAAuB,EACvB,sBAAsB,EACtB,aAAa,EACb,oBAAoB,EACpB,SAAS,GACV,MAAM,gBAAgB,CAAC;AACxB,OAAO,EACL,gBAAgB,EAChB,0BAA0B,EAC1B,wBAAwB,GACzB,MAAM,gBAAgB,CAAC;AAExB,YAAY,EAAE,qBAAqB,EAAE,kBAAkB,EAAE,iBAAiB,EAAE,MAAM,kBAAkB,CAAC;AACrG,OAAO,EAAE,qBAAqB,EAAE,2BAA2B,EAAE,MAAM,kBAAkB,CAAC;AAEtF,YAAY,EAAE,gBAAgB,EAAE,MAAM,oBAAoB,CAAC;AAC3D,OAAO,EAAE,mBAAmB,EAAE,MAAM,oBAAoB,CAAC;AAEzD,YAAY,EACV,cAAc,EACd,eAAe,EACf,yBAAyB,EACzB,cAAc,EACd,aAAa,EACb,UAAU,EACV,UAAU,EACV,QAAQ,GACT,MAAM,eAAe,CAAC;AACvB,OAAO,EACL,gBAAgB,EAChB,kBAAkB,EAClB,6BAA6B,EAC7B,gBAAgB,EAChB,oBAAoB,EACpB,oBAAoB,GACrB,MAAM,eAAe,CAAC;AAEvB,YAAY,EAAE,iBAAiB,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AACvE,OAAO,EACL,mBAAmB,EACnB,4BAA4B,EAC5B,eAAe,EACf,uBAAuB,EACvB,iBAAiB,GAClB,MAAM,kBAAkB,CAAC;AAE1B,YAAY,EACV,MAAM,EACN,kBAAkB,EAClB,gBAAgB,EAChB,oBAAoB,EACpB,SAAS,GACV,MAAM,gBAAgB,CAAC"}

package/dist/index.js

@@ -0,0 +1,7 @@
+export { ENVIRONMENT_TIERS, FIDELITY_LEVELS, CAPABILITY_AVAILABILITY, isCapabilityStatusValid } from "./capability.js";
+export { EXECUTION_STATES, isValidExecutionTransition, isTerminalExecutionState, } from "./execution.js";
+export { SERVICE_ROOT_REFUSALS, resolveServiceRootForOrigin } from "./source-root.js";
+export { RUNTIME_EVENT_TYPES } from "./runtime-event.js";
+export { EVIDENCE_SOURCES, REDACTION_STATUSES, SOURCE_LOCATION_RELIABILITIES, STACK_FIDELITIES, primaryFrameLocation, locationNamesNothing, } from "./evidence.js";
+export { CORRELATION_METHODS, CORRELATION_PREFERENCE_ORDER, correlationRank, isStructuralCorrelation, createCorrelation, } from "./correlation.js";
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAQA,OAAO,EAAE,iBAAiB,EAAE,eAAe,EAAE,uBAAuB,EAAE,uBAAuB,EAAE,MAAM,iBAAiB,CAAC;AAiBvH,OAAO,EACL,gBAAgB,EAChB,0BAA0B,EAC1B,wBAAwB,GACzB,MAAM,gBAAgB,CAAC;AAGxB,OAAO,EAAE,qBAAqB,EAAE,2BAA2B,EAAE,MAAM,kBAAkB,CAAC;AAGtF,OAAO,EAAE,mBAAmB,EAAE,MAAM,oBAAoB,CAAC;AAYzD,OAAO,EACL,gBAAgB,EAChB,kBAAkB,EAClB,6BAA6B,EAC7B,gBAAgB,EAChB,oBAAoB,EACpB,oBAAoB,GACrB,MAAM,eAAe,CAAC;AAGvB,OAAO,EACL,mBAAmB,EACnB,4BAA4B,EAC5B,eAAe,EACf,uBAAuB,EACvB,iBAAiB,GAClB,MAAM,kBAAkB,CAAC"}

package/dist/runtime-event.d.ts

@@ -0,0 +1,20 @@
+/**
+ * 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.
+ */
+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];
+//# sourceMappingURL=runtime-event.d.ts.map

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

@@ -0,0 +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"}