@descryy/runtime-contracts 0.0.0

package/dist/runtime-event.js

@@ -0,0 +1,252 @@
+/**
+ * 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 const RUNTIME_EVENT_TYPES = [
+    "PROCESS_STARTED",
+    "PROCESS_READY",
+    "PROCESS_EXITED",
+    "PAGE_CREATED",
+    "NAVIGATION",
+    "CLICK",
+    "INPUT",
+    /**
+     * Beyond plan §14's printed 19 — same standing as `COLLECTOR_ERROR` below,
+     * which that list also predates. §5 had no honest type for "an image was
+     * captured": not `INPUT`, not `CLICK`, not nothing. Landed together with
+     * its one emitter (`BrowserActionCollector.screenshot()`, RT-061) in the
+     * same change, per RT-053's own lesson — a declared-but-dead type with no
+     * annotation is the mistake, not a type existing at all, but the safest
+     * way not to repeat it is to not create one ahead of its wiring.
+     */
+    "SCREENSHOT",
+    /**
+     * Video evidence (competitive research, `documents/decisions-inbox/`:
+     * `PROPOSAL-video-evidence-capture.md`, this repo, and
+     * `descry-desktop`'s companion `DEC-D-NEXT-video-evidence-kind.md` --
+     * Greptile's TREX: a captured video of a UI change playing out, attached
+     * to a finding alongside screenshots/logs). Same standing as `SCREENSHOT`
+     * immediately above and the same discipline: landed together with its one
+     * emitter (`BrowserActionCollector.captureVideo()`, `browser-session.ts`'s
+     * new `recordVideo` option), not ahead of it.
+     *
+     * `source: "browser-dom"`, the same source `SCREENSHOT` already uses --
+     * see `evidence.ts`'s `EVIDENCE_SOURCES` list for why this did NOT get a
+     * new source of its own. Every entry in that list names a domain being
+     * *watched*; a kind of captured artifact (an image, a video) is not a
+     * domain, which is exactly `SCREENSHOT`'s own precedent applied here
+     * rather than re-litigated.
+     */
+    "VIDEO",
+    "CONSOLE_MESSAGE",
+    "NETWORK_REQUEST",
+    "NETWORK_RESPONSE",
+    "HTTP_ERROR",
+    "BACKEND_LOG",
+    "EXCEPTION",
+    "STACK_TRACE",
+    /**
+     * §17 (Test Runner Support). **All four are emitted**, by
+     * `packages/test-runner`, for `node:test` (RT-073), Jest and Vitest
+     * (RT-123) — each read from that runner's own structured reporter API,
+     * never from printed prose.
+     *
+     * The annotation this comment replaces said *"Nothing emits these three,
+     * on purpose, not yet"* and asked to be removed "when §17 lands and one
+     * of these three actually gets emitted somewhere." §17 landed in RT-073
+     * and the comment outlived it by four entries — noted because the
+     * mechanism this file exists to guard against is a claim that stops
+     * being true and nothing forcing it to be re-read.
+     *
+     * ## `TEST_SKIPPED` is the fourth, and it exists because the other three
+     * made a skipped test unsayable
+     *
+     * Measured across three runners (RT-124):
+     *
+     * | runner | `test.skip` | `test.todo` |
+     * | --- | --- | --- |
+     * | node:test | `test:pass` carrying `skip: true` | `test:pass` carrying `todo: true` |
+     * | Vitest 4 | `state: "skipped"` | `state: "skipped"` |
+     * | Jest 30 | omitted from `onTestCaseResult` entirely | `status: "todo"` |
+     *
+     * node:test's is why this is a contract change rather than a bug fix:
+     * **a skipped test arrives as a pass event**, and with no fourth member
+     * the translator mapped it to `TEST_PASSED`. A skipped test is not a
+     * pass (nothing was asserted), not a failure (nothing failed), and not
+     * absent (the developer wrote it and the runner knows about it).
+     *
+     * Counting them was tried first and is what shipped in RT-123. It is
+     * honest and insufficient: a counter carries no `sourceLocation`, no
+     * `qualifiedName` and no graph node, so **"the function you changed has
+     * a test and it is disabled" cannot be expressed at all** — a real
+     * finding, needing something resolvable to a `TEST_CASE` node to exist.
+     * Expressible-at-all, not accuracy, is what decided this.
+     *
+     * **Landed with its producers in the same change**, deliberately. §3's
+     * warning is about `DATABASE_QUERY`/`EXTERNAL_REQUEST` sitting declared
+     * and dead below; a type merged "ready for the producers next week" is
+     * that same shape regardless of intent.
+     *
+     * Consumers were checked before this was added rather than after: the
+     * only `eventType` branching outside `test-runner` is
+     * `evidence-package`'s two **allowlists** (`NETWORK_EVENTS`,
+     * `BACKEND_LOG_EVENTS`), and `composeFinding` does not read `eventType`
+     * at all. So nothing treats "not passed" as evidence of a problem, and a
+     * disabled test cannot be read as a failing one. A future
+     * `!== "TEST_PASSED"` would reintroduce exactly that.
+     *
+     * ## Why there is no `TEST_ABORTED` (RT-129)
+     *
+     * JUnit reports **four** outcomes, not three: `aborted` (a failed
+     * assumption — ran real code, bailed on a precondition) is distinct from
+     * `skipped` (`@Disabled` — never ran). Measured by Lane A (RT-088),
+     * along with the fact that JUnit's own XML collapses them into one bare
+     * `<skipped>` element while its `TestExecutionListener` keeps them apart.
+     *
+     * The distinction is real and did **not** get a type. The test applied:
+     * **does collapsing it change the answer to "was this code covered?"**
+     * Skipped-vs-passed does, oppositely, which is why the fourth member
+     * above exists. Skipped-vs-aborted does not — every one of them answers
+     * `notRun`, carries a location and a qualified name, and is not a
+     * failure, so no consumer routes differently. What differs is the
+     * *explanation*, and an explanation belongs in the payload.
+     *
+     * So `TEST_SKIPPED`'s payload carries `skipReason`
+     * (`test-runner`'s `SkipReason`): a closed, runner-agnostic vocabulary
+     * of `disabled` / `not-implemented` / `precondition-unmet` /
+     * `unspecified`. `unspecified` is a real answer, not a fallback — Vitest
+     * cannot tell `.skip` from `.todo`, and saying so beats guessing.
+     *
+     * This also repaired RT-124's own silent collapse: node:test **does**
+     * distinguish `skip` from `todo`, and the first version of this type
+     * threw that away.
+     */
+    "TEST_STARTED",
+    "TEST_PASSED",
+    "TEST_FAILED",
+    "TEST_SKIPPED",
+    /**
+     * `DATABASE_QUERY` / `EXTERNAL_REQUEST`: §18 (Database / External Service
+     * Observation). Both are now real. `DATABASE_QUERY` is emitted by
+     * `@descryhq-wq/runtime-database-observation`'s `DatabaseQueryCollector`, via
+     * real `node:sqlite` driver instrumentation (RT-141). `EXTERNAL_REQUEST`
+     * is emitted by `@descryhq-wq/runtime-external-service-observation`'s
+     * `ExternalRequestCollector`, via real global-`fetch` instrumentation
+     * (RT-146) — same `--import`-preload mechanism, a different global.
+     * Neither is derived from logs. What §18 still does not have: a
+     * transaction-boundary concept for queries, graph correlation for either
+     * (no resolver from a table name or a hostname to a graph node exists),
+     * and provider classification for external requests (a captured
+     * hostname, never a guessed provider name) — real, disclosed gaps, not
+     * silent ones.
+     */
+    "DATABASE_QUERY",
+    "EXTERNAL_REQUEST",
+    /**
+     * The observer failed, not the observed system. Added beyond plan §14's
+     * printed list, which §14 explicitly permits ("the exact event vocabulary
+     * can evolve") and which §17 in fact requires: `collector failure` is one
+     * of the failures the runtime model must represent, under the rule **"a
+     * collector failure must not be mistaken for an application success or
+     * absence of failure."**
+     *
+     * Without this type there was no way to state that at all. A collector
+     * whose consumption loop threw mid-stream logged to the console and
+     * resolved `stop()` cleanly, so a run that lost half its backend output
+     * was indistinguishable from a run where the backend printed half as
+     * much. That is precisely the confusion between *found nothing* and
+     * *stopped looking* that the five report categories exist to prevent.
+     */
+    "COLLECTOR_ERROR",
+    /**
+     * `DEC-NEXT-fault-layer-empirical-confirmation.md`'s `dependency`
+     * mechanism, landed together with its one emitter
+     * (`packages/orchestrator/src/instrumented-execution.ts`, via
+     * `@descryy/runtime-controller`'s `checkDependencyVersions`) in the same
+     * change -- same "not declared ahead of its wiring" discipline
+     * `SCREENSHOT`'s own comment states above. Not `COLLECTOR_ERROR`: this is
+     * not the observer failing, it is a real structural fact the runtime
+     * established about the project it is executing (the lockfile-declared
+     * version of a dependency does not match what is actually installed),
+     * the same "a genuinely new kind of fact gets its own type" precedent
+     * `DATABASE_QUERY`/`EXTERNAL_REQUEST` already set for §18 above. Payload
+     * carries `name`/`declaredVersion`/`resolvedVersion`, mirroring
+     * `DependencyVersionMismatch`'s own shape.
+     */
+    "DEPENDENCY_VERSION_MISMATCH",
+    /**
+     * The same ruling's `environment` mechanism, same emitter, same standing
+     * as `DEPENDENCY_VERSION_MISMATCH` above -- landed together with its one
+     * emitter, not a `COLLECTOR_ERROR` because nothing failed to observe.
+     * Payload carries `declaredVersion`/`declaredSource`/`observedVersion`,
+     * mirroring `EnvironmentVersionCheckResult`'s own shape.
+     */
+    "ENVIRONMENT_VERSION_MISMATCH",
+    /**
+     * RT-225: `BrowserNetworkCollector`'s WebSocket lifecycle listener
+     * (`page.on("websocket")`, plus the per-socket `close`/`socketerror`
+     * events Playwright's `WebSocket` object exposes). Closes
+     * `documents/decisions-inbox/RT-PENDING-websocket-network-observation-gap.md` --
+     * a WebSocket connection, successful or refused, fired none of
+     * `NETWORK_REQUEST`/`NETWORK_RESPONSE`/`HTTP_ERROR` before this, because
+     * those three are wired to `request`/`requestfinished`/`requestfailed`
+     * only, and Playwright surfaces WebSocket traffic through a wholly
+     * separate event stream.
+     *
+     * A connection **attempt** reuses `NETWORK_REQUEST` (a real outbound call
+     * was made, to a URL -- the same fact that type already exists to
+     * record) and a connection **failure** (`socketerror`) reuses
+     * `HTTP_ERROR` with `status: null` -- the exact "no usable response ever
+     * came back" convention this vocabulary already applies to a refused
+     * `fetch()` (`requestfailed`) and to this collector's own timeout. Both
+     * reuses are deliberate: forcing WS's *fields* into the HTTP shape would
+     * fabricate a `method`/`status` nothing observed, but the *event*
+     * (request went out / no usable response arrived) is the identical fact
+     * under a different wire protocol, and reusing the type keeps this
+     * evidence inside the existing `network` signal channel
+     * (`packages/finding/src/signal-channel.ts`) and the existing
+     * `NETWORK_EVENTS` package view with no governance-table change.
+     *
+     * `WEBSOCKET_CLOSED` is the one genuinely new fact, because a **close**
+     * has no honest HTTP-shaped answer: `NETWORK_RESPONSE` means "a response
+     * with a status arrived," which forcing a close into it would fabricate.
+     * Measured, not assumed (`websocket-intercept-gap.test.ts`): Playwright's
+     * public `WebSocket.on("close")` carries no code or reason at all --
+     * identical for a clean server-initiated 1000 close and a raw abrupt TCP
+     * termination. So this type does not claim "normal" vs "abnormal"
+     * either; it states only that the socket closed, and says so in its own
+     * payload rather than guessing. Emitted only when no `socketerror` was
+     * already reported for the same socket, so a failed connection is never
+     * double-reported once as `HTTP_ERROR` and again as `WEBSOCKET_CLOSED`.
+     *
+     * Deliberately outside `signal-channel.ts`'s `CHANNEL_BY_EVENT_TYPE`
+     * table (§5.2 of the ratified `ai-governance-spec.md`, a separate,
+     * already-settled ruling this change does not reopen) -- falls through to
+     * `null`/no-signal there, which is that table's own documented "fail
+     * closed" default for a type it has not ruled on, and is the honest
+     * answer for a fact this thin: "the socket closed" carries far less on
+     * its own than a real request/response/error triple does.
+     *
+     * Per-message frame traffic (`framesent`/`framereceived`) is not
+     * captured as evidence at all -- out of scope here, disclosed rather than
+     * silently dropped, in `browser-network-collector.ts`'s own module
+     * comment. Neither is `EventSource`/SSE, which shares the same
+     * uncovered shape (the RT-PENDING note above flagged it as unmeasured;
+     * still unmeasured after this change).
+     */
+    "WEBSOCKET_CLOSED",
+];
+//# sourceMappingURL=runtime-event.js.map

package/dist/runtime-event.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"runtime-event.js","sourceRoot":"","sources":["../src/runtime-event.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,MAAM,CAAC,MAAM,mBAAmB,GAAG;IACjC,iBAAiB;IACjB,eAAe;IACf,gBAAgB;IAChB,cAAc;IACd,YAAY;IACZ,OAAO;IACP,OAAO;IACP;;;;;;;;OAQG;IACH,YAAY;IACZ;;;;;;;;;;;;;;;;OAgBG;IACH,OAAO;IACP,iBAAiB;IACjB,iBAAiB;IACjB,kBAAkB;IAClB,YAAY;IACZ,aAAa;IACb,WAAW;IACX,aAAa;IACb;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA2EG;IACH,cAAc;IACd,aAAa;IACb,aAAa;IACb,cAAc;IACd;;;;;;;;;;;;;;OAcG;IACH,gBAAgB;IAChB,kBAAkB;IAClB;;;;;;;;;;;;;;OAcG;IACH,iBAAiB;IACjB;;;;;;;;;;;;;;OAcG;IACH,6BAA6B;IAC7B;;;;;;OAMG;IACH,8BAA8B;IAC9B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAmDG;IACH,kBAAkB;CACV,CAAC"}

package/dist/source-root.d.ts

@@ -0,0 +1,97 @@
+/**
+ * Origin -> service root (RT-023, built on RT-028's `ProcessHandle.serviceName`/
+ * `.port` and `ExecutionConfiguration.services`). Answers "which service's
+ * declared `cwd` served this browser origin," the missing link
+ * `BrowserConsoleCollector` needs to turn `http://localhost:4000/app.js`
+ * into a candidate on-disk root before the existing `file://`-based source
+ * resolution logic can run.
+ *
+ * Deliberately stops here, at a configuration-layer fact, not a collector.
+ * `packages/browser`'s runtime code depends on `@descryy/runtime-contracts`
+ * only (RT-021's precedent) -- this lives in contracts so that boundary
+ * holds for this resolver too.
+ *
+ * Two distinct, RT-024-shaped honesty gaps live here, not one:
+ *
+ * 1. **The port join proves an address, not a correspondent.** Matching
+ *    `origin.port` to the `ProcessHandle` we recorded on that port proves
+ *    the browser's origin matches a port this execution assigned -- not
+ *    that the browser actually talked to that specific process. Under
+ *    ephemeral allocation (RT-024's own default) this is true almost all
+ *    of the time, which is exactly the phrase RT-024 says not to write
+ *    down as identity. Nothing here re-verifies the process is still the
+ *    one that was live when the browser made the request.
+ * 2. **A resolved root is configured, not verified** -- see
+ *    `ConfiguredServiceRoot`.
+ *
+ * Same class of gap, two layers: a port match confirms an address: a
+ * `cwd` confirms a declared root. Neither confirms who was actually there.
+ */
+import type { Execution } from "./execution.ts";
+/**
+ * A service's declared working directory, recovered by joining a running
+ * process's assigned port back to `ExecutionConfiguration.services`.
+ *
+ * **Configured, not verified.** This proves the origin maps to a directory
+ * the orchestrator was told to run the service from -- it does not prove
+ * any specific file a browser frame names actually lives under it. A
+ * static file server rooted at a subdirectory (`public/`, `dist/`), a
+ * symlink, a proxy, or a `cwd` that changed after spawn would all break
+ * the stronger claim without breaking this weaker one. Same shape as
+ * RT-024's "readiness proves liveness, not identity": this proves *a*
+ * root, not that a given file came from the checkout in it.
+ *
+ * Not a refusal, because the weaker claim is still real and useful, and
+ * because this project already has a pattern for exactly this gap: the
+ * caller joins the frame's path onto `declaredCwd` and confirms the file
+ * exists there before trusting a source location built from it -- the same
+ * `existsSync` discipline `createNodeSourceLocationResolver` already
+ * applies to `file://` paths rather than trusting "the path looks right."
+ * A failed existence check downstream is the honest refusal; this function
+ * returning a root is not, by itself, a claim that the check will pass.
+ */
+export interface ConfiguredServiceRoot {
+    readonly serviceName: string;
+    readonly declaredCwd: string;
+}
+/**
+ * Closed, so a caller can branch on *why* rather than pattern-match prose --
+ * same reasoning as `descry-core`'s `attrs.refusalClass`: free-text refusal
+ * reasons can't be counted by a census or acted on differently by a caller.
+ * The four cases split into three different kinds of problem a caller
+ * would want to tell apart: `originNoPort`/`originUnparseable` mean the
+ * input itself wasn't a resolvable origin; `noProcessOnPort` means nothing
+ * in this execution claims that port at all; `processUnnamed` is a wiring
+ * gap (a real process, spawned without a `serviceName`) that's closable by
+ * whoever spawned it; `serviceNotConfigured` is a configuration error (a
+ * `serviceName` with no matching `services` entry) -- different from a
+ * wiring gap because the name exists but the config doesn't back it.
+ */
+export declare const SERVICE_ROOT_REFUSALS: readonly ["originNoPort", "originUnparseable", "noProcessOnPort", "processUnnamed", "serviceNotConfigured"];
+export type ServiceRootRefusal = (typeof SERVICE_ROOT_REFUSALS)[number];
+export type ServiceRootLookup = {
+    readonly found: true;
+    readonly root: ConfiguredServiceRoot;
+} | {
+    readonly found: false;
+    readonly refusal: ServiceRootRefusal;
+    readonly message: string;
+};
+/**
+ * Resolves a browser origin (e.g. `"http://localhost:4000"`) to the
+ * service that served it, by port: `execution.processes[].port` (the real,
+ * OS-assigned port -- RT-028) to `.serviceName`, then `.serviceName` to
+ * `execution.configuration.services[name].cwd`.
+ *
+ * `origin` is a clean origin, not a full frame location -- stripping a
+ * `file:37:12`-shaped V8 frame down to its origin is the caller's job
+ * (mirrors `createNodeSourceLocationResolver`'s own division of labor:
+ * frame parsing is a separate concern from root resolution).
+ *
+ * Two services sharing the same `declaredCwd` in configuration is not
+ * ambiguous here: resolution runs process -> serviceName -> a direct keyed
+ * lookup in `services`, never a reverse search by directory, so a
+ * coincidentally-shared path on the output side has nothing to disambiguate.
+ */
+export declare function resolveServiceRootForOrigin(origin: string, execution: Pick<Execution, "processes" | "configuration">): ServiceRootLookup;
+//# sourceMappingURL=source-root.d.ts.map

package/dist/source-root.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"source-root.d.ts","sourceRoot":"","sources":["../src/source-root.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAEhD;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,MAAM,WAAW,qBAAqB;IACpC,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;CAC9B;AAED;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,qBAAqB,6GAMxB,CAAC;AACX,MAAM,MAAM,kBAAkB,GAAG,CAAC,OAAO,qBAAqB,CAAC,CAAC,MAAM,CAAC,CAAC;AAExE,MAAM,MAAM,iBAAiB,GACzB;IAAE,QAAQ,CAAC,KAAK,EAAE,IAAI,CAAC;IAAC,QAAQ,CAAC,IAAI,EAAE,qBAAqB,CAAA;CAAE,GAC9D;IAAE,QAAQ,CAAC,KAAK,EAAE,KAAK,CAAC;IAAC,QAAQ,CAAC,OAAO,EAAE,kBAAkB,CAAC;IAAC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;CAAE,CAAC;AAE9F;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,2BAA2B,CACzC,MAAM,EAAE,MAAM,EACd,SAAS,EAAE,IAAI,CAAC,SAAS,EAAE,WAAW,GAAG,eAAe,CAAC,GACxD,iBAAiB,CA2CnB"}

package/dist/source-root.js

@@ -0,0 +1,107 @@
+/**
+ * Origin -> service root (RT-023, built on RT-028's `ProcessHandle.serviceName`/
+ * `.port` and `ExecutionConfiguration.services`). Answers "which service's
+ * declared `cwd` served this browser origin," the missing link
+ * `BrowserConsoleCollector` needs to turn `http://localhost:4000/app.js`
+ * into a candidate on-disk root before the existing `file://`-based source
+ * resolution logic can run.
+ *
+ * Deliberately stops here, at a configuration-layer fact, not a collector.
+ * `packages/browser`'s runtime code depends on `@descryy/runtime-contracts`
+ * only (RT-021's precedent) -- this lives in contracts so that boundary
+ * holds for this resolver too.
+ *
+ * Two distinct, RT-024-shaped honesty gaps live here, not one:
+ *
+ * 1. **The port join proves an address, not a correspondent.** Matching
+ *    `origin.port` to the `ProcessHandle` we recorded on that port proves
+ *    the browser's origin matches a port this execution assigned -- not
+ *    that the browser actually talked to that specific process. Under
+ *    ephemeral allocation (RT-024's own default) this is true almost all
+ *    of the time, which is exactly the phrase RT-024 says not to write
+ *    down as identity. Nothing here re-verifies the process is still the
+ *    one that was live when the browser made the request.
+ * 2. **A resolved root is configured, not verified** -- see
+ *    `ConfiguredServiceRoot`.
+ *
+ * Same class of gap, two layers: a port match confirms an address: a
+ * `cwd` confirms a declared root. Neither confirms who was actually there.
+ */
+/**
+ * Closed, so a caller can branch on *why* rather than pattern-match prose --
+ * same reasoning as `descry-core`'s `attrs.refusalClass`: free-text refusal
+ * reasons can't be counted by a census or acted on differently by a caller.
+ * The four cases split into three different kinds of problem a caller
+ * would want to tell apart: `originNoPort`/`originUnparseable` mean the
+ * input itself wasn't a resolvable origin; `noProcessOnPort` means nothing
+ * in this execution claims that port at all; `processUnnamed` is a wiring
+ * gap (a real process, spawned without a `serviceName`) that's closable by
+ * whoever spawned it; `serviceNotConfigured` is a configuration error (a
+ * `serviceName` with no matching `services` entry) -- different from a
+ * wiring gap because the name exists but the config doesn't back it.
+ */
+export const SERVICE_ROOT_REFUSALS = [
+    "originNoPort",
+    "originUnparseable",
+    "noProcessOnPort",
+    "processUnnamed",
+    "serviceNotConfigured",
+];
+/**
+ * Resolves a browser origin (e.g. `"http://localhost:4000"`) to the
+ * service that served it, by port: `execution.processes[].port` (the real,
+ * OS-assigned port -- RT-028) to `.serviceName`, then `.serviceName` to
+ * `execution.configuration.services[name].cwd`.
+ *
+ * `origin` is a clean origin, not a full frame location -- stripping a
+ * `file:37:12`-shaped V8 frame down to its origin is the caller's job
+ * (mirrors `createNodeSourceLocationResolver`'s own division of labor:
+ * frame parsing is a separate concern from root resolution).
+ *
+ * Two services sharing the same `declaredCwd` in configuration is not
+ * ambiguous here: resolution runs process -> serviceName -> a direct keyed
+ * lookup in `services`, never a reverse search by directory, so a
+ * coincidentally-shared path on the output side has nothing to disambiguate.
+ */
+export function resolveServiceRootForOrigin(origin, execution) {
+    let port;
+    try {
+        const url = new URL(origin);
+        if (url.port === "") {
+            return {
+                found: false,
+                refusal: "originNoPort",
+                message: `origin "${origin}" has no explicit port; cannot match against a process's assigned port`,
+            };
+        }
+        port = Number(url.port);
+    }
+    catch {
+        return { found: false, refusal: "originUnparseable", message: `"${origin}" is not a parseable origin` };
+    }
+    const process = execution.processes.find((candidate) => candidate.port === port);
+    if (process === undefined) {
+        return {
+            found: false,
+            refusal: "noProcessOnPort",
+            message: `no process in this execution is bound to port ${port}`,
+        };
+    }
+    if (process.serviceName === null) {
+        return {
+            found: false,
+            refusal: "processUnnamed",
+            message: `the process bound to port ${port} has no serviceName -- it was not spawned as a named service, so its declared root cannot be recovered from configuration.services`,
+        };
+    }
+    const service = execution.configuration.services[process.serviceName];
+    if (service === undefined) {
+        return {
+            found: false,
+            refusal: "serviceNotConfigured",
+            message: `serviceName "${process.serviceName}" (from the process bound to port ${port}) has no matching entry in configuration.services`,
+        };
+    }
+    return { found: true, root: { serviceName: process.serviceName, declaredCwd: service.cwd } };
+}
+//# sourceMappingURL=source-root.js.map

package/dist/source-root.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"source-root.js","sourceRoot":"","sources":["../src/source-root.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AA+BH;;;;;;;;;;;;GAYG;AACH,MAAM,CAAC,MAAM,qBAAqB,GAAG;IACnC,cAAc;IACd,mBAAmB;IACnB,iBAAiB;IACjB,gBAAgB;IAChB,sBAAsB;CACd,CAAC;AAOX;;;;;;;;;;;;;;;GAeG;AACH,MAAM,UAAU,2BAA2B,CACzC,MAAc,EACd,SAAyD;IAEzD,IAAI,IAAY,CAAC;IACjB,IAAI,CAAC;QACH,MAAM,GAAG,GAAG,IAAI,GAAG,CAAC,MAAM,CAAC,CAAC;QAC5B,IAAI,GAAG,CAAC,IAAI,KAAK,EAAE,EAAE,CAAC;YACpB,OAAO;gBACL,KAAK,EAAE,KAAK;gBACZ,OAAO,EAAE,cAAc;gBACvB,OAAO,EAAE,WAAW,MAAM,wEAAwE;aACnG,CAAC;QACJ,CAAC;QACD,IAAI,GAAG,MAAM,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;IAC1B,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,EAAE,KAAK,EAAE,KAAK,EAAE,OAAO,EAAE,mBAAmB,EAAE,OAAO,EAAE,IAAI,MAAM,6BAA6B,EAAE,CAAC;IAC1G,CAAC;IAED,MAAM,OAAO,GAAG,SAAS,CAAC,SAAS,CAAC,IAAI,CAAC,CAAC,SAAS,EAAE,EAAE,CAAC,SAAS,CAAC,IAAI,KAAK,IAAI,CAAC,CAAC;IACjF,IAAI,OAAO,KAAK,SAAS,EAAE,CAAC;QAC1B,OAAO;YACL,KAAK,EAAE,KAAK;YACZ,OAAO,EAAE,iBAAiB;YAC1B,OAAO,EAAE,iDAAiD,IAAI,EAAE;SACjE,CAAC;IACJ,CAAC;IAED,IAAI,OAAO,CAAC,WAAW,KAAK,IAAI,EAAE,CAAC;QACjC,OAAO;YACL,KAAK,EAAE,KAAK;YACZ,OAAO,EAAE,gBAAgB;YACzB,OAAO,EAAE,6BAA6B,IAAI,oIAAoI;SAC/K,CAAC;IACJ,CAAC;IAED,MAAM,OAAO,GAAG,SAAS,CAAC,aAAa,CAAC,QAAQ,CAAC,OAAO,CAAC,WAAW,CAAC,CAAC;IACtE,IAAI,OAAO,KAAK,SAAS,EAAE,CAAC;QAC1B,OAAO;YACL,KAAK,EAAE,KAAK;YACZ,OAAO,EAAE,sBAAsB;YAC/B,OAAO,EAAE,gBAAgB,OAAO,CAAC,WAAW,qCAAqC,IAAI,mDAAmD;SACzI,CAAC;IACJ,CAAC;IAED,OAAO,EAAE,KAAK,EAAE,IAAI,EAAE,IAAI,EAAE,EAAE,WAAW,EAAE,OAAO,CAAC,WAAW,EAAE,WAAW,EAAE,OAAO,CAAC,GAAG,EAAE,EAAE,CAAC;AAC/F,CAAC"}

package/package.json

@@ -0,0 +1,26 @@
+{
+  "name": "@descryy/runtime-contracts",
+  "version": "0.0.0",
+  "type": "module",
+  "description": "The six runtime contracts: Execution, Evidence, Runtime Event, Collector, Capability, Correlation. Agents 2-4 build against this; it does not depend on them.",
+  "license": "UNLICENSED",
+  "engines": {
+    "node": ">=22.5"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "publishConfig": {
+    "registry": "https://npm.pkg.github.com"
+  },
+  "scripts": {
+    "build": "tsc -b"
+  },
+  "dependencies": {}
+}