@descryy/runtime-contracts 0.2.0 → 0.3.0

package/dist/runtime-event.js

@@ -1,19 +1,9 @@
 /**
- * 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 const RUNTIME_EVENT_TYPES = [
     "PROCESS_STARTED",
@@ -23,32 +13,13 @@ export const RUNTIME_EVENT_TYPES = [
     "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.
-     */
+    /** Beyond plan §14's printed 19: no honest type existed for "an image was captured." Landed with its one emitter (`BrowserActionCollector.screenshot()`, RT-061), not ahead of it. */
     "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 evidence, landed with its one emitter
+     * (`BrowserActionCollector.captureVideo()`), same discipline as
+     * `SCREENSHOT`. Uses `source: "browser-dom"`, not a new source — a
+     * captured-artifact kind isn't a watched domain (see `EVIDENCE_SOURCES`).
      */
     "VIDEO",
     "CONSOLE_MESSAGE",
@@ -59,213 +30,105 @@ export const RUNTIME_EVENT_TYPES = [
     "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
+     * §17. All four emitted by `packages/test-runner` for node:test,
+     * Jest and Vitest, each read from the runner's own structured reporter
+     * API, never printed prose.
      *
-     * Measured across three runners (RT-124):
+     * `TEST_SKIPPED` exists because the other three make a skipped test
+     * unsayable. Measured across runners (RT-124):
      *
      * | runner | `test.skip` | `test.todo` |
      * | --- | --- | --- |
-     * | node:test | `test:pass` carrying `skip: true` | `test:pass` carrying `todo: true` |
+     * | node:test | `test:pass` w/ `skip: true` | `test:pass` w/ `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.
+     * | Jest 30 | omitted from `onTestCaseResult` | `status: "todo"` |
+     *
+     * node:test reports a skip as a pass event — without a fourth member
+     * the translator mapped it to `TEST_PASSED`. A counter was tried first
+     * (RT-123) but can't carry `sourceLocation`/`qualifiedName`, so "this
+     * function's test is disabled" isn't expressible as a finding.
+     *
+     * No `TEST_ABORTED`: JUnit's `aborted` (failed assumption) is distinct
+     * from `skipped` (`@Disabled`, RT-088/RT-129), but both answer `notRun`
+     * and neither is a failure, so no consumer routes differently — the
+     * difference is explanation, not type. `TEST_SKIPPED`'s payload carries
+     * `skipReason` (`disabled`/`not-implemented`/`precondition-unmet`/
+     * `unspecified`) instead; `unspecified` is a real answer since Vitest
+     * can't tell `.skip` from `.todo`.
      */
     "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
-     * `@descryy/runtime-database-observation`'s `DatabaseQueryCollector`, via
-     * real `node:sqlite` driver instrumentation (RT-141). `EXTERNAL_REQUEST`
-     * is emitted by `@descryy/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.
+     * §18. `DATABASE_QUERY` via `DatabaseQueryCollector`'s real `node:sqlite`
+     * instrumentation (RT-141); `EXTERNAL_REQUEST` via `ExternalRequestCollector`'s
+     * real global-`fetch` instrumentation (RT-146). Neither derived from logs.
+     * Disclosed gaps: no transaction-boundary concept, no graph correlation
+     * (table name / hostname to graph node), no provider classification for
+     * external requests (hostname captured, never a guessed provider).
      */
     "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.
+     * The observer failed, not the observed system (§17: "a collector
+     * failure must not be mistaken for an application success or absence of
+     * failure"). Without it, a collector whose consumption loop threw
+     * mid-stream logged to console and resolved `stop()` cleanly — a run
+     * that lost half its backend output was indistinguishable from one
+     * where the backend just printed less.
      */
     "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.
+     * `checkDependencyVersions`: lockfile-declared dependency version vs.
+     * what's actually installed. Not `COLLECTOR_ERROR` — nothing failed to
+     * observe, this is a structural fact about the project. Payload carries
+     * `name`/`declaredVersion`/`resolvedVersion`.
      */
     "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.
+     * `checkEnvironmentVersion`, same standing as `DEPENDENCY_VERSION_MISMATCH`.
+     * Payload carries `declaredVersion`/`declaredSource`/`observedVersion`.
      */
     "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).
+     * RT-225: `BrowserNetworkCollector`'s WebSocket lifecycle listener.
+     * Before this, a WS connection fired none of
+     * `NETWORK_REQUEST`/`NETWORK_RESPONSE`/`HTTP_ERROR` — those are wired to
+     * `request`/`requestfinished`/`requestfailed` only, and Playwright
+     * surfaces WebSocket traffic through a separate event stream.
+     *
+     * A connection attempt reuses `NETWORK_REQUEST`; a connection failure
+     * (`socketerror`) reuses `HTTP_ERROR` with `status: null` — same "no
+     * usable response" convention as a refused `fetch()`. Forcing WS fields
+     * into the HTTP shape would fabricate a method/status, but the event
+     * itself is the same fact under a different protocol, so reuse keeps
+     * this in the existing network signal channel.
+     *
+     * `WEBSOCKET_CLOSED` is the one new fact: a close has no honest
+     * HTTP-shaped answer. Measured (`websocket-intercept-gap.test.ts`):
+     * Playwright's `WebSocket.on("close")` carries no code or reason —
+     * identical for a clean 1000 close and an abrupt TCP termination — so
+     * this type doesn't claim normal vs. abnormal either. Emitted only when
+     * no `socketerror` was already reported for the same socket, so a
+     * failed connection isn't double-reported.
+     *
+     * Deliberately outside `signal-channel.ts`'s `CHANNEL_BY_EVENT_TYPE` —
+     * falls through to no-signal, the documented fail-closed default.
+     * Per-message frame traffic and EventSource/SSE are not captured
+     * (disclosed gap, `browser-network-collector.ts`).
      */
     "WEBSOCKET_CLOSED",
 ];
 /**
- * **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 const RESERVED_MARKER_PREFIX = "DESCRY_";
 //# sourceMappingURL=runtime-event.js.map

package/dist/runtime-event.js.map

@@ -1 +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;AAIX;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,CAAC,MAAM,sBAAsB,GAAG,SAAS,CAAC"}
+{"version":3,"file":"runtime-event.js","sourceRoot":"","sources":["../src/runtime-event.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,MAAM,CAAC,MAAM,mBAAmB,GAAG;IACjC,iBAAiB;IACjB,eAAe;IACf,gBAAgB;IAChB,cAAc;IACd,YAAY;IACZ,OAAO;IACP,OAAO;IACP,sLAAsL;IACtL,YAAY;IACZ;;;;;OAKG;IACH,OAAO;IACP,iBAAiB;IACjB,iBAAiB;IACjB,kBAAkB;IAClB,YAAY;IACZ,aAAa;IACb,WAAW;IACX,aAAa;IACb;;;;;;;;;;;;;;;;;;;;;;;;;;OA0BG;IACH,cAAc;IACd,aAAa;IACb,aAAa;IACb,cAAc;IACd;;;;;;;OAOG;IACH,gBAAgB;IAChB,kBAAkB;IAClB;;;;;;;OAOG;IACH,iBAAiB;IACjB;;;;;OAKG;IACH,6BAA6B;IAC7B;;;OAGG;IACH,8BAA8B;IAC9B;;;;;;;;;;;;;;;;;;;;;;;;;;OA0BG;IACH,kBAAkB;CACV,CAAC;AAIX;;;;;;;;;GASG;AACH,MAAM,CAAC,MAAM,sBAAsB,GAAG,SAAS,CAAC"}

package/dist/source-root.d.ts

@@ -1,71 +1,47 @@
 /**
  * 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.
+ * declared `cwd` served this browser origin" — the link `BrowserConsoleCollector`
+ * needs to turn `http://localhost:4000/app.js` into a candidate on-disk root
+ * before `file://`-based source resolution 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.
+ * Stops at a configuration-layer fact, not a collector — `packages/browser`
+ * depends on `@descryy/runtime-contracts` only (RT-021), so this lives here.
  *
- * 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.
+ * Two disclosed honesty gaps (RT-024-shaped):
+ * 1. The port join proves an address, not a correspondent — matching
+ *    `origin.port` to a recorded `ProcessHandle` proves the origin matches
+ *    a port this execution assigned, not that the browser talked to that
+ *    specific process. Nothing re-verifies the process was still live.
+ * 2. A resolved root is configured, not verified — see `ConfiguredServiceRoot`.
  */
 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.
+ * Configured, not verified: proves the origin maps to a directory the
+ * orchestrator was told to run the service from, not that any specific
+ * file actually lives under it (a subdirectory-rooted static server,
+ * symlink, proxy, or post-spawn `cwd` change would all break the stronger
+ * claim without breaking this one).
  *
- * 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.
+ * Not a refusal — the weaker claim is still useful. The caller should
+ * join the frame's path onto `declaredCwd` and confirm the file exists
+ * (same `existsSync` discipline `createNodeSourceLocationResolver` uses
+ * for `file://` paths) — that check, not this function, is where a
+ * failure should surface.
  */
 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.
+ * Closed, so a caller can branch on *why* rather than pattern-match prose.
+ * `originNoPort`/`originUnparseable`: input wasn't a resolvable origin.
+ * `noProcessOnPort`: nothing in this execution claims that port.
+ * `processUnnamed`: a real process spawned without a `serviceName` (wiring gap).
+ * `serviceNotConfigured`: a `serviceName` with no matching `services` entry.
  */
 export declare const SERVICE_ROOT_REFUSALS: readonly ["originNoPort", "originUnparseable", "noProcessOnPort", "processUnnamed", "serviceNotConfigured"];
 export type ServiceRootRefusal = (typeof SERVICE_ROOT_REFUSALS)[number];
@@ -79,19 +55,16 @@ export type ServiceRootLookup = {
 };
 /**
  * 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
+ * service that served it: `execution.processes[].port` (real OS-assigned
+ * port, RT-028) to `.serviceName`, then 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).
+ * `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.
  *
- * 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.
+ * Two services sharing the same `declaredCwd` isn't ambiguous here:
+ * resolution is process -> serviceName -> keyed lookup, never a reverse
+ * search by directory.
  */
 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

@@ -1 +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"}
+{"version":3,"file":"source-root.d.ts","sourceRoot":"","sources":["../src/source-root.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAEhD;;;;;;;;;;;;;;;GAeG;AACH,MAAM,WAAW,qBAAqB;IACpC,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;CAC9B;AAED;;;;;;GAMG;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;;;;;;;;;;;;GAYG;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

@@ -1,44 +1,26 @@
 /**
  * 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.
+ * declared `cwd` served this browser origin" — the link `BrowserConsoleCollector`
+ * needs to turn `http://localhost:4000/app.js` into a candidate on-disk root
+ * before `file://`-based source resolution 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.
+ * Stops at a configuration-layer fact, not a collector — `packages/browser`
+ * depends on `@descryy/runtime-contracts` only (RT-021), so this lives here.
  *
- * 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.
+ * Two disclosed honesty gaps (RT-024-shaped):
+ * 1. The port join proves an address, not a correspondent — matching
+ *    `origin.port` to a recorded `ProcessHandle` proves the origin matches
+ *    a port this execution assigned, not that the browser talked to that
+ *    specific process. Nothing re-verifies the process was still live.
+ * 2. A resolved root is configured, not verified — see `ConfiguredServiceRoot`.
  */
 /**
- * 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.
+ * Closed, so a caller can branch on *why* rather than pattern-match prose.
+ * `originNoPort`/`originUnparseable`: input wasn't a resolvable origin.
+ * `noProcessOnPort`: nothing in this execution claims that port.
+ * `processUnnamed`: a real process spawned without a `serviceName` (wiring gap).
+ * `serviceNotConfigured`: a `serviceName` with no matching `services` entry.
  */
 export const SERVICE_ROOT_REFUSALS = [
     "originNoPort",
@@ -49,19 +31,16 @@ export const SERVICE_ROOT_REFUSALS = [
 ];
 /**
  * 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
+ * service that served it: `execution.processes[].port` (real OS-assigned
+ * port, RT-028) to `.serviceName`, then 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).
+ * `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.
  *
- * 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.
+ * Two services sharing the same `declaredCwd` isn't ambiguous here:
+ * resolution is process -> serviceName -> keyed lookup, never a reverse
+ * search by directory.
  */
 export function resolveServiceRootForOrigin(origin, execution) {
     let port;

package/dist/source-root.js.map

@@ -1 +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"}
+{"version":3,"file":"source-root.js","sourceRoot":"","sources":["../src/source-root.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAyBH;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,qBAAqB,GAAG;IACnC,cAAc;IACd,mBAAmB;IACnB,iBAAiB;IACjB,gBAAgB;IAChB,sBAAsB;CACd,CAAC;AAOX;;;;;;;;;;;;GAYG;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

@@ -1,9 +1,14 @@
 {
   "name": "@descryy/runtime-contracts",
-  "version": "0.2.0",
+  "version": "0.3.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",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/descryhq-wq/descry-runtime.git",
+    "directory": "packages/contracts"
+  },
   "engines": {
     "node": ">=22.5"
   },