@descryy/runtime-contracts 0.0.0

package/dist/capability.d.ts

@@ -0,0 +1,118 @@
+/**
+ * Capability model.
+ *
+ * Purpose and shape (`{ availability, reason }` per capability, so the AI
+ * planner reads realistic answers like `distributedTrace: unavailable`
+ * instead of a silent gap) come from `documents/descry-runtime-plan.md`
+ * §16 (Runtime capability model). Environment/fidelity concepts are
+ * grounded in the architecture doc's §10.3 (environment tiers: CI-attached
+ * → preview → container → API-only → static-only) and §16.3 (fidelity
+ * levels 1-4: stub, real+disposable DB, real+recordings, real staging).
+ *
+ * The point of this file: `distributedTrace: unavailable` must be a
+ * first-class, structured answer the AI planner can read — never an absent
+ * field, never a thrown error, never a silent gap that reads as "not
+ * checked" only after something downstream fails to find data. Absence is
+ * data, and this contract makes it representable.
+ */
+export declare const ENVIRONMENT_TIERS: readonly ["tier-0-ci-attached", "tier-1-preview", "tier-2-container", "tier-2b-api-only", "tier-3-static-only"];
+export type EnvironmentTier = (typeof ENVIRONMENT_TIERS)[number];
+export declare const FIDELITY_LEVELS: readonly [1, 2, 3, 4];
+/** 1 = rule-aware stub · 2 = real code + disposable DB (preferred default) · 3 = real code + redacted recordings · 4 = real staging. */
+export type FidelityLevel = (typeof FIDELITY_LEVELS)[number];
+export declare const CAPABILITY_AVAILABILITY: readonly ["available", "degraded", "unavailable"];
+export type CapabilityAvailability = (typeof CAPABILITY_AVAILABILITY)[number];
+export interface CapabilityStatus {
+    readonly availability: CapabilityAvailability;
+    /** Why, not just that — required whenever availability is not "available". Null only when availability is "available". */
+    readonly reason: string | null;
+}
+export declare function isCapabilityStatusValid(status: CapabilityStatus): boolean;
+/**
+ * What one collector can and cannot see, computed once at start() and
+ * stable for the collector's lifetime — never re-derived by guessing from
+ * partial results mid-run.
+ */
+export interface CollectorCapabilities {
+    readonly domObservation: CapabilityStatus;
+    readonly consoleObservation: CapabilityStatus;
+    readonly networkObservation: CapabilityStatus;
+    readonly backendLogAccess: CapabilityStatus;
+    /** Whether this collector can participate in trace-id/W3C-trace-context correlation — the top of the six-level order in correlation.ts. */
+    readonly distributedTrace: CapabilityStatus;
+    /** Whether captured source locations can resolve through to authored source — ties to SourceLocationReliability in evidence.ts. */
+    readonly sourceMapping: CapabilityStatus;
+    /** Whether stack capture is possible at all, independent of whether the runtime's concurrency model fragments it — ties to StackFidelity in evidence.ts. */
+    readonly stackCapture: CapabilityStatus;
+    /**
+     * Whether this collector observes **process lifecycle** — spawn, ready,
+     * exit — as `PROCESS_STARTED` / `PROCESS_READY` / `PROCESS_EXITED`.
+     *
+     * **Added because its absence produced an actively wrong report.** The
+     * seven fields above are all DOM, console, network, log, trace, mapping
+     * and stack; none describes watching a process. So `ProcessCollector`
+     * (RT-053) — a collector doing its job correctly — had no honest way to
+     * say what it does, and reported `unavailable` on all seven with real
+     * reasons. Every reason was true and the overall picture was false: a
+     * healthy collector reading as one that can do nothing.
+     *
+     * That is §22's own distinction inverted. The section exists to keep
+     * "unsupported" from being read as "no failure"; a capability model with
+     * no field for a real capability produces the mirror image — **"we
+     * cannot" reported by something that can.** The lane that hit it declined
+     * to invent a field and flagged it instead, which was right; the fix
+     * belongs in the contract, not in a collector working around the
+     * contract.
+     */
+    readonly processLifecycle: CapabilityStatus;
+    /**
+     * Whether this collector observes **database queries** — `DATABASE_QUERY`
+     * evidence, via real driver instrumentation (`node:sqlite` today,
+     * RT-141) — as opposed to inferring them from logs.
+     *
+     * **The same gap `processLifecycle` closed, reopened by §18.** RT-141
+     * built a real `DatabaseQueryCollector` and it had no honest field to
+     * report itself in — every one of the eight fields above is DOM,
+     * console, network, log, trace, mapping, stack or process; none
+     * describes watching a database driver. Deferred at the time (RT-142)
+     * with an explicit trigger — "lanes converge, no collector work in
+     * flight" — because a field with no consumer is exactly the shape that
+     * drifts, and this repo's rule is to land a capability field in the same
+     * change as its first real collector, not ahead of it (§18's own
+     * `TEST_SKIPPED`/`DATABASE_QUERY` precedent, `runtime-event.ts`). Closed
+     * now (RT-146) alongside `externalServiceObservation`, together with
+     * §18's other collector.
+     */
+    readonly databaseObservation: CapabilityStatus;
+    /**
+     * Whether this collector observes **outbound requests to external
+     * services** — `EXTERNAL_REQUEST` evidence, via real client
+     * instrumentation (`fetch`, RT-146) — the process-initiated counterpart
+     * to `databaseObservation` above, added in the same change for the same
+     * reason.
+     *
+     * **Deliberately distinct from `networkObservation`, not a widening of
+     * it.** Every existing claimant of `networkObservation` is
+     * `BrowserNetworkCollector` — browser-page-originated requests captured
+     * through Playwright's own request/response events. A backend process's
+     * own outbound `fetch()` calls are a different mechanism (driver
+     * instrumentation, not a browser event stream) observing a different
+     * thing (server-to-service traffic, not page-to-server traffic) — the
+     * §6/§18 split this file's own checklist already keeps apart. Folding
+     * this into `networkObservation` would make an execution with only an
+     * external-request collector report `networkObservation: available` and
+     * mislead a reader into expecting browser network evidence that was
+     * never captured.
+     */
+    readonly externalServiceObservation: CapabilityStatus;
+}
+/** What an execution as a whole can do, aggregated across its active collectors — the shape the AI planner actually reads. */
+export interface ExecutionCapabilities {
+    readonly environmentTier: EnvironmentTier;
+    readonly fidelityLevel: FidelityLevel;
+    readonly collectors: readonly {
+        readonly collectorId: string;
+        readonly capabilities: CollectorCapabilities;
+    }[];
+}
+//# sourceMappingURL=capability.d.ts.map

package/dist/capability.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"capability.d.ts","sourceRoot":"","sources":["../src/capability.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,eAAO,MAAM,iBAAiB,iHAMpB,CAAC;AACX,MAAM,MAAM,eAAe,GAAG,CAAC,OAAO,iBAAiB,CAAC,CAAC,MAAM,CAAC,CAAC;AAEjE,eAAO,MAAM,eAAe,uBAAwB,CAAC;AACrD,wIAAwI;AACxI,MAAM,MAAM,aAAa,GAAG,CAAC,OAAO,eAAe,CAAC,CAAC,MAAM,CAAC,CAAC;AAE7D,eAAO,MAAM,uBAAuB,mDAAoD,CAAC;AACzF,MAAM,MAAM,sBAAsB,GAAG,CAAC,OAAO,uBAAuB,CAAC,CAAC,MAAM,CAAC,CAAC;AAE9E,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,YAAY,EAAE,sBAAsB,CAAC;IAC9C,0HAA0H;IAC1H,QAAQ,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;CAChC;AAED,wBAAgB,uBAAuB,CAAC,MAAM,EAAE,gBAAgB,GAAG,OAAO,CAEzE;AAED;;;;GAIG;AACH,MAAM,WAAW,qBAAqB;IACpC,QAAQ,CAAC,cAAc,EAAE,gBAAgB,CAAC;IAC1C,QAAQ,CAAC,kBAAkB,EAAE,gBAAgB,CAAC;IAC9C,QAAQ,CAAC,kBAAkB,EAAE,gBAAgB,CAAC;IAC9C,QAAQ,CAAC,gBAAgB,EAAE,gBAAgB,CAAC;IAC5C,2IAA2I;IAC3I,QAAQ,CAAC,gBAAgB,EAAE,gBAAgB,CAAC;IAC5C,mIAAmI;IACnI,QAAQ,CAAC,aAAa,EAAE,gBAAgB,CAAC;IACzC,4JAA4J;IAC5J,QAAQ,CAAC,YAAY,EAAE,gBAAgB,CAAC;IACxC;;;;;;;;;;;;;;;;;;;OAmBG;IACH,QAAQ,CAAC,gBAAgB,EAAE,gBAAgB,CAAC;IAE5C;;;;;;;;;;;;;;;;;OAiBG;IACH,QAAQ,CAAC,mBAAmB,EAAE,gBAAgB,CAAC;IAE/C;;;;;;;;;;;;;;;;;;;OAmBG;IACH,QAAQ,CAAC,0BAA0B,EAAE,gBAAgB,CAAC;CACvD;AAED,8HAA8H;AAC9H,MAAM,WAAW,qBAAqB;IACpC,QAAQ,CAAC,eAAe,EAAE,eAAe,CAAC;IAC1C,QAAQ,CAAC,aAAa,EAAE,aAAa,CAAC;IACtC,QAAQ,CAAC,UAAU,EAAE,SAAS;QAC5B,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;QAC7B,QAAQ,CAAC,YAAY,EAAE,qBAAqB,CAAC;KAC9C,EAAE,CAAC;CACL"}

package/dist/capability.js

@@ -0,0 +1,30 @@
+/**
+ * Capability model.
+ *
+ * Purpose and shape (`{ availability, reason }` per capability, so the AI
+ * planner reads realistic answers like `distributedTrace: unavailable`
+ * instead of a silent gap) come from `documents/descry-runtime-plan.md`
+ * §16 (Runtime capability model). Environment/fidelity concepts are
+ * grounded in the architecture doc's §10.3 (environment tiers: CI-attached
+ * → preview → container → API-only → static-only) and §16.3 (fidelity
+ * levels 1-4: stub, real+disposable DB, real+recordings, real staging).
+ *
+ * The point of this file: `distributedTrace: unavailable` must be a
+ * first-class, structured answer the AI planner can read — never an absent
+ * field, never a thrown error, never a silent gap that reads as "not
+ * checked" only after something downstream fails to find data. Absence is
+ * data, and this contract makes it representable.
+ */
+export const ENVIRONMENT_TIERS = [
+    "tier-0-ci-attached",
+    "tier-1-preview",
+    "tier-2-container",
+    "tier-2b-api-only",
+    "tier-3-static-only",
+];
+export const FIDELITY_LEVELS = [1, 2, 3, 4];
+export const CAPABILITY_AVAILABILITY = ["available", "degraded", "unavailable"];
+export function isCapabilityStatusValid(status) {
+    return status.availability === "available" ? status.reason === null : status.reason !== null;
+}
+//# sourceMappingURL=capability.js.map

package/dist/capability.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"capability.js","sourceRoot":"","sources":["../src/capability.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,MAAM,CAAC,MAAM,iBAAiB,GAAG;IAC/B,oBAAoB;IACpB,gBAAgB;IAChB,kBAAkB;IAClB,kBAAkB;IAClB,oBAAoB;CACZ,CAAC;AAGX,MAAM,CAAC,MAAM,eAAe,GAAG,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,CAAU,CAAC;AAIrD,MAAM,CAAC,MAAM,uBAAuB,GAAG,CAAC,WAAW,EAAE,UAAU,EAAE,aAAa,CAAU,CAAC;AASzF,MAAM,UAAU,uBAAuB,CAAC,MAAwB;IAC9D,OAAO,MAAM,CAAC,YAAY,KAAK,WAAW,CAAC,CAAC,CAAC,MAAM,CAAC,MAAM,KAAK,IAAI,CAAC,CAAC,CAAC,MAAM,CAAC,MAAM,KAAK,IAAI,CAAC;AAC/F,CAAC"}

package/dist/collector.d.ts

@@ -0,0 +1,124 @@
+/**
+ * Collector interface.
+ *
+ * `start()` / `stop()` / `capabilities()` / `emit()` are named directly in
+ * `documents/descry-runtime-plan.md` §15 (Collector architecture), whose
+ * §17 (Runtime failure model) states the rule this file exists to enforce
+ * in types: "A collector failure must not be mistaken for an application
+ * success or absence of failure." Also grounded in the architecture doc's
+ * §17.2 (the observe stream) and §26 (the failure/degradation matrix's
+ * governing rule: "say what could not be checked, never silently do less").
+ *
+ * Design note, since this diverges slightly from a literal reading of
+ * "start / stop / capabilities / emit" as four flat methods: `emit` is
+ * delivered through `CollectorContext` passed into `start()`, not exposed
+ * as a fourth method other code calls *on* the collector. A collector
+ * pushes evidence by calling `context.emit()` as events occur — that is
+ * the only shape consistent with streaming-first (§17.6: partial results
+ * reach the core as they happen, never batched until a run ends). An
+ * `emit()` method callable from outside would mean something else feeds
+ * data *into* the collector, which inverts the actual data flow. Flagging
+ * this as a deliberate interpretation, not a literal one.
+ */
+import type { ExecutionConfiguration } from "./execution.ts";
+import type { Evidence } from "./evidence.ts";
+import type { CollectorCapabilities } from "./capability.ts";
+import type { ServiceRootLookup } from "./source-root.ts";
+export type EmitFn = (evidence: Omit<Evidence, "evidenceId" | "executionId">) => void;
+/** RT-023/RT-029: joins a browser origin to its serving service's declared root. See `resolveServiceRootForOrigin` in `source-root.ts` for the reference implementation this is expected to close over. */
+export type SourceRootResolver = (origin: string) => ServiceRootLookup;
+export interface CollectorContext {
+    readonly executionId: string;
+    readonly configuration: ExecutionConfiguration;
+    readonly emit: EmitFn;
+    /**
+     * Resolves a browser origin to its serving service's declared root, when
+     * the orchestrator assembling this context has enough state to build one
+     * (needs `Execution.processes`, which `CollectorContext` itself does not
+     * carry -- RT-023 decided the join belongs to whoever already holds both
+     * `processes` and `configuration`, never a collector reasoning about
+     * processes on its own; this field is how that decision reaches a
+     * collector without handing it the process list to join itself).
+     *
+     * Absent for a context built without that state — not a function that
+     * always refuses. A collector with no resolver at all degrades to
+     * exactly the same `unavailable` capability report as one whose resolver
+     * returns `found: false`; there is no separate branch for "no resolver
+     * provided" versus "resolver had nothing to say."
+     *
+     * A `found: false` result is not, on its own, a failure worth surfacing
+     * distinctly — most origins a browser collector observes (a CDN, an
+     * extension, `about:blank`) never correspond to a spawned service at
+     * all, and `originNoPort`/`noProcessOnPort` (`ServiceRootRefusal`)
+     * already say so honestly. A collector should treat "not ours" the same
+     * as any other unmapped origin, not as a distinguishable error.
+     */
+    readonly resolveSourceRoot?: SourceRootResolver;
+}
+export type CollectorStartResult = {
+    readonly available: true;
+} | {
+    readonly available: false;
+    readonly reason: string;
+};
+/**
+ * The attach-mode-mitigations lane's forward-looking scope guarantee,
+ * checked against this repo as it stands: no fix-application or
+ * code-execution mechanism (`applyFix`, `fixApplication`, `applyPatch` or
+ * equivalent) exists anywhere in `packages/*\/src` today -- that is
+ * deliberately AI-layer/V2 territory (`descry-core/CLAUDE.md`'s repo
+ * split), not something this repo has and forgot to guard. So this is a
+ * contract for something that does not exist yet, not a removal of
+ * something that does. Its point is to fix the *shape* of `Collector` now,
+ * while it is cheap and there is nothing to migrate, rather than
+ * discovering after a fix-application mechanism is built that the natural
+ * place to wire it in was this interface, which every attach-mode collector
+ * (`attachToRunningProcess`, `attachToRunningNodeProcess`,
+ * `attachToRunningJvmProcess`, in `descry-runtime`'s `packages/orchestrator`)
+ * already implements and would then need retrofitting.
+ */
+export declare const ATTACH_MODE_SCOPE_DISCLOSURE: string;
+/**
+ * **Every `Collector` -- attach-mode collectors in particular -- is
+ * contractually observation-only.** No method on a `Collector`, present
+ * or future, may execute code against the thing it observes or apply a
+ * change to it; `start()`/`stop()`/`capabilities()` govern the
+ * collector's own lifecycle, and `context.emit()` (`CollectorContext`,
+ * above) is a one-way push of evidence outward, never a channel for
+ * commands going the other way in. This matters most for attach-mode: a
+ * process Descry did not spawn was never sandboxed by anything this
+ * runtime controls (see `@descryy/runtime-controller`'s `sandbox.ts` for
+ * why that is structural, not a gap), so an attach-mode collector that
+ * could execute code or apply a fix against its target would be doing so
+ * against a completely unconfined process with no boundary of any kind --
+ * a materially worse shape than the read-only observation this interface
+ * actually permits. See `ATTACH_MODE_SCOPE_DISCLOSURE`, above, for the
+ * in-product statement of this guarantee, and its own comment for why it
+ * is a forward-looking contract rather than a removal of an existing
+ * capability: no fix-application or code-execution mechanism exists
+ * anywhere in this repo yet for this contract to be tested against. Any
+ * future one belongs in a new, separate interface a caller opts into
+ * explicitly -- never added as a new method here.
+ */
+export interface Collector {
+    readonly collectorId: string;
+    /**
+     * Begin collecting for this execution. Must resolve with
+     * `{ available: false, reason }` for a routine unavailability rather
+     * than throwing — absence has to be representable data the caller can
+     * act on, never an exception a caller has to remember to catch and
+     * reinterpret. Reserve rejection for genuine defects in the collector
+     * itself.
+     */
+    start(context: CollectorContext): Promise<CollectorStartResult>;
+    /** Stop collecting and release everything held (processes, sockets, file handles). Idempotent — safe to call on an already-stopped collector. */
+    stop(): Promise<void>;
+    /**
+     * What this collector can and cannot see. Computed once at start() and
+     * stable for the collector's lifetime — an unimplemented capability is
+     * reported as `unavailable` here, never simply omitted from the evidence
+     * stream and left for a reader to notice its absence.
+     */
+    capabilities(): CollectorCapabilities;
+}
+//# sourceMappingURL=collector.d.ts.map

package/dist/collector.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"collector.d.ts","sourceRoot":"","sources":["../src/collector.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAEH,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,gBAAgB,CAAC;AAC7D,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC;AAC9C,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,iBAAiB,CAAC;AAC7D,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,kBAAkB,CAAC;AAE1D,MAAM,MAAM,MAAM,GAAG,CAAC,QAAQ,EAAE,IAAI,CAAC,QAAQ,EAAE,YAAY,GAAG,aAAa,CAAC,KAAK,IAAI,CAAC;AAEtF,2MAA2M;AAC3M,MAAM,MAAM,kBAAkB,GAAG,CAAC,MAAM,EAAE,MAAM,KAAK,iBAAiB,CAAC;AAEvE,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,aAAa,EAAE,sBAAsB,CAAC;IAC/C,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB;;;;;;;;;;;;;;;;;;;;;OAqBG;IACH,QAAQ,CAAC,iBAAiB,CAAC,EAAE,kBAAkB,CAAC;CACjD;AAED,MAAM,MAAM,oBAAoB,GAC5B;IAAE,QAAQ,CAAC,SAAS,EAAE,IAAI,CAAA;CAAE,GAC5B;IAAE,QAAQ,CAAC,SAAS,EAAE,KAAK,CAAC;IAAC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAAC;AAE3D;;;;;;;;;;;;;;;GAeG;AACH,eAAO,MAAM,4BAA4B,QAG6D,CAAC;AAEvG;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,MAAM,WAAW,SAAS;IACxB,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAE7B;;;;;;;OAOG;IACH,KAAK,CAAC,OAAO,EAAE,gBAAgB,GAAG,OAAO,CAAC,oBAAoB,CAAC,CAAC;IAEhE,iJAAiJ;IACjJ,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IAEtB;;;;;OAKG;IACH,YAAY,IAAI,qBAAqB,CAAC;CACvC"}

package/dist/collector.js

@@ -0,0 +1,42 @@
+/**
+ * Collector interface.
+ *
+ * `start()` / `stop()` / `capabilities()` / `emit()` are named directly in
+ * `documents/descry-runtime-plan.md` §15 (Collector architecture), whose
+ * §17 (Runtime failure model) states the rule this file exists to enforce
+ * in types: "A collector failure must not be mistaken for an application
+ * success or absence of failure." Also grounded in the architecture doc's
+ * §17.2 (the observe stream) and §26 (the failure/degradation matrix's
+ * governing rule: "say what could not be checked, never silently do less").
+ *
+ * Design note, since this diverges slightly from a literal reading of
+ * "start / stop / capabilities / emit" as four flat methods: `emit` is
+ * delivered through `CollectorContext` passed into `start()`, not exposed
+ * as a fourth method other code calls *on* the collector. A collector
+ * pushes evidence by calling `context.emit()` as events occur — that is
+ * the only shape consistent with streaming-first (§17.6: partial results
+ * reach the core as they happen, never batched until a run ends). An
+ * `emit()` method callable from outside would mean something else feeds
+ * data *into* the collector, which inverts the actual data flow. Flagging
+ * this as a deliberate interpretation, not a literal one.
+ */
+/**
+ * The attach-mode-mitigations lane's forward-looking scope guarantee,
+ * checked against this repo as it stands: no fix-application or
+ * code-execution mechanism (`applyFix`, `fixApplication`, `applyPatch` or
+ * equivalent) exists anywhere in `packages/*\/src` today -- that is
+ * deliberately AI-layer/V2 territory (`descry-core/CLAUDE.md`'s repo
+ * split), not something this repo has and forgot to guard. So this is a
+ * contract for something that does not exist yet, not a removal of
+ * something that does. Its point is to fix the *shape* of `Collector` now,
+ * while it is cheap and there is nothing to migrate, rather than
+ * discovering after a fix-application mechanism is built that the natural
+ * place to wire it in was this interface, which every attach-mode collector
+ * (`attachToRunningProcess`, `attachToRunningNodeProcess`,
+ * `attachToRunningJvmProcess`, in `descry-runtime`'s `packages/orchestrator`)
+ * already implements and would then need retrofitting.
+ */
+export const ATTACH_MODE_SCOPE_DISCLOSURE = "Attach mode observes an already-running process; it never executes code in it or applies changes to it. " +
+    "This is a permanent, documented architectural limitation, not a temporary gap -- there is no honest way to " +
+    "retroactively sandbox a process that was already running, unconfined, before this tool touched it.";
+//# sourceMappingURL=collector.js.map

package/dist/collector.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"collector.js","sourceRoot":"","sources":["../src/collector.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AA6CH;;;;;;;;;;;;;;;GAeG;AACH,MAAM,CAAC,MAAM,4BAA4B,GACvC,0GAA0G;IAC1G,6GAA6G;IAC7G,oGAAoG,CAAC"}

package/dist/correlation.d.ts

@@ -0,0 +1,61 @@
+/**
+ * Correlation contract.
+ *
+ * The six-level preference order is verbatim from
+ * `documents/descry-runtime-plan.md` §10 (Request and distributed
+ * correlation): trace ID → request ID → W3C trace context →
+ * framework-provided correlation → controlled runtime-generated
+ * correlation → timing/process/context fallback. Also grounded in the
+ * architecture doc's §18.2/§18.3a (evidence bundling and the
+ * RootCauseScore's RuntimeEvidence term both depend on evidence being
+ * linkable across sources).
+ *
+ * The rule that matters most here (this project's version of the
+ * hypothesis boundary, one layer down): never silently convert an inferred
+ * correlation into a confirmed one. The first five methods are all actual
+ * shared identifiers — found in the wild or injected and controlled by the
+ * runtime itself. Only the sixth, timing/context fallback, is a genuine
+ * inference with no identifier behind it. `isConfirmed` is derived
+ * mechanically from `method`, not set by hand, so that boundary can't drift.
+ */
+export declare const CORRELATION_METHODS: readonly ["trace-id", "request-id", "w3c-trace-context", "framework-provided", "runtime-generated", "timing-context-fallback"];
+export type CorrelationMethod = (typeof CORRELATION_METHODS)[number];
+/**
+ * Strongest first. Exported as an explicit ordered array — not inferred
+ * from CORRELATION_METHODS' declaration order — so the ranking is a fact
+ * on its own, not an accident of listing order that a future edit could
+ * silently reorder.
+ */
+export declare const CORRELATION_PREFERENCE_ORDER: readonly CorrelationMethod[];
+export declare function correlationRank(method: CorrelationMethod): number;
+/**
+ * True for every method except timing-context-fallback. This is the
+ * structural distinction Agent 3 asked for: a timing-inferred link must be
+ * distinguishable from a trace-ID match by type, not merely by a lower
+ * confidence number that a careless reader could ignore.
+ */
+export declare function isStructuralCorrelation(method: CorrelationMethod): boolean;
+export interface Correlation {
+    readonly correlationId: string;
+    readonly executionId: string;
+    readonly method: CorrelationMethod;
+    /**
+     * 0-1, independent of rank. Rank says which method produced this
+     * correlation; confidence says how sure this particular instance of that
+     * method's result is. A low-confidence trace-id match and a
+     * high-confidence timing match can coexist — they answer different
+     * questions.
+     */
+    readonly confidence: number;
+    readonly evidenceIds: readonly string[];
+    /**
+     * Derived from `method` via isStructuralCorrelation — never set
+     * independently. A caller cannot construct a Correlation with
+     * method: "timing-context-fallback" and isConfirmed: true; use
+     * `createCorrelation` rather than a bare object literal to keep that
+     * true in practice, not just in a comment.
+     */
+    readonly isConfirmed: boolean;
+}
+export declare function createCorrelation(input: Omit<Correlation, "isConfirmed">): Correlation;
+//# sourceMappingURL=correlation.d.ts.map

package/dist/correlation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"correlation.d.ts","sourceRoot":"","sources":["../src/correlation.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,eAAO,MAAM,mBAAmB,gIAOtB,CAAC;AACX,MAAM,MAAM,iBAAiB,GAAG,CAAC,OAAO,mBAAmB,CAAC,CAAC,MAAM,CAAC,CAAC;AAErE;;;;;GAKG;AACH,eAAO,MAAM,4BAA4B,EAAE,SAAS,iBAAiB,EAOpE,CAAC;AAEF,wBAAgB,eAAe,CAAC,MAAM,EAAE,iBAAiB,GAAG,MAAM,CAMjE;AAED;;;;;GAKG;AACH,wBAAgB,uBAAuB,CAAC,MAAM,EAAE,iBAAiB,GAAG,OAAO,CAE1E;AAED,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAC/B,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,MAAM,EAAE,iBAAiB,CAAC;IACnC;;;;;;OAMG;IACH,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,WAAW,EAAE,SAAS,MAAM,EAAE,CAAC;IACxC;;;;;;OAMG;IACH,QAAQ,CAAC,WAAW,EAAE,OAAO,CAAC;CAC/B;AAED,wBAAgB,iBAAiB,CAC/B,KAAK,EAAE,IAAI,CAAC,WAAW,EAAE,aAAa,CAAC,GACtC,WAAW,CAEb"}

package/dist/correlation.js

@@ -0,0 +1,62 @@
+/**
+ * Correlation contract.
+ *
+ * The six-level preference order is verbatim from
+ * `documents/descry-runtime-plan.md` §10 (Request and distributed
+ * correlation): trace ID → request ID → W3C trace context →
+ * framework-provided correlation → controlled runtime-generated
+ * correlation → timing/process/context fallback. Also grounded in the
+ * architecture doc's §18.2/§18.3a (evidence bundling and the
+ * RootCauseScore's RuntimeEvidence term both depend on evidence being
+ * linkable across sources).
+ *
+ * The rule that matters most here (this project's version of the
+ * hypothesis boundary, one layer down): never silently convert an inferred
+ * correlation into a confirmed one. The first five methods are all actual
+ * shared identifiers — found in the wild or injected and controlled by the
+ * runtime itself. Only the sixth, timing/context fallback, is a genuine
+ * inference with no identifier behind it. `isConfirmed` is derived
+ * mechanically from `method`, not set by hand, so that boundary can't drift.
+ */
+export const CORRELATION_METHODS = [
+    "trace-id",
+    "request-id",
+    "w3c-trace-context",
+    "framework-provided",
+    "runtime-generated",
+    "timing-context-fallback",
+];
+/**
+ * Strongest first. Exported as an explicit ordered array — not inferred
+ * from CORRELATION_METHODS' declaration order — so the ranking is a fact
+ * on its own, not an accident of listing order that a future edit could
+ * silently reorder.
+ */
+export const CORRELATION_PREFERENCE_ORDER = [
+    "trace-id",
+    "request-id",
+    "w3c-trace-context",
+    "framework-provided",
+    "runtime-generated",
+    "timing-context-fallback",
+];
+export function correlationRank(method) {
+    const rank = CORRELATION_PREFERENCE_ORDER.indexOf(method);
+    if (rank === -1) {
+        throw new Error(`unranked correlation method: ${method}`);
+    }
+    return rank;
+}
+/**
+ * True for every method except timing-context-fallback. This is the
+ * structural distinction Agent 3 asked for: a timing-inferred link must be
+ * distinguishable from a trace-ID match by type, not merely by a lower
+ * confidence number that a careless reader could ignore.
+ */
+export function isStructuralCorrelation(method) {
+    return method !== "timing-context-fallback";
+}
+export function createCorrelation(input) {
+    return { ...input, isConfirmed: isStructuralCorrelation(input.method) };
+}
+//# sourceMappingURL=correlation.js.map

package/dist/correlation.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"correlation.js","sourceRoot":"","sources":["../src/correlation.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,MAAM,CAAC,MAAM,mBAAmB,GAAG;IACjC,UAAU;IACV,YAAY;IACZ,mBAAmB;IACnB,oBAAoB;IACpB,mBAAmB;IACnB,yBAAyB;CACjB,CAAC;AAGX;;;;;GAKG;AACH,MAAM,CAAC,MAAM,4BAA4B,GAAiC;IACxE,UAAU;IACV,YAAY;IACZ,mBAAmB;IACnB,oBAAoB;IACpB,mBAAmB;IACnB,yBAAyB;CAC1B,CAAC;AAEF,MAAM,UAAU,eAAe,CAAC,MAAyB;IACvD,MAAM,IAAI,GAAG,4BAA4B,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC;IAC1D,IAAI,IAAI,KAAK,CAAC,CAAC,EAAE,CAAC;QAChB,MAAM,IAAI,KAAK,CAAC,gCAAgC,MAAM,EAAE,CAAC,CAAC;IAC5D,CAAC;IACD,OAAO,IAAI,CAAC;AACd,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,uBAAuB,CAAC,MAAyB;IAC/D,OAAO,MAAM,KAAK,yBAAyB,CAAC;AAC9C,CAAC;AAyBD,MAAM,UAAU,iBAAiB,CAC/B,KAAuC;IAEvC,OAAO,EAAE,GAAG,KAAK,EAAE,WAAW,EAAE,uBAAuB,CAAC,KAAK,CAAC,MAAM,CAAC,EAAE,CAAC;AAC1E,CAAC"}