@descryy/runtime-graph-correlator 0.0.0

package/dist/confirm-observed-caller.d.ts

@@ -0,0 +1,92 @@
+/**
+ * The first production caller of `applyRuntimeObservations()` — architecture
+ * §11B.3's R4 runtime confirmation, wired to a real observation source.
+ *
+ * §11B.3 calls runtime confirmation *"the core technical moat rather than the
+ * graph itself"*, and states the consequence plainly: *"a purely static
+ * code-graph tool is capped at R3 permanently."* The mechanism has existed in
+ * `@descryy/core` since it was built, and the two EARNED tables it writes
+ * (`observed_edges`, `edge_corrections`) have been in the store's schema since
+ * the store was first written — each with a comment explaining why they cannot
+ * be regenerated from source at any price. **Nothing read or wrote either one.**
+ * This is what makes the moat run.
+ *
+ * ## Why this producer
+ *
+ * `resolveObservedFrontendCaller` already does the hard half. It takes a real
+ * captured `fetch()` call-site stack, resolves its site of interest to a
+ * `FUNCTION` node, and checks that node against the structural candidate set the
+ * graph holds for the endpoint. Its two observed outcomes *are* two of §11B.3's
+ * three arrows, and needed only to be spoken in the vocabulary
+ * `applyRuntimeObservations` reads:
+ *
+ * | resolution outcome | arrow |
+ * | --- | --- |
+ * | `observed` | the graph already holds this `USES_API` edge below R4 — **promote it** |
+ * | `structural-observed-conflict` | a real node the structural side never named — **mint the edge at R4** (§11B.3's *"recall gap closed"*) |
+ *
+ * Everything else — no stack, an unresolvable frame, an ambiguous or missing
+ * symbol — produces **no observation at all**. Not an empty confirmation that
+ * looks like one; none.
+ *
+ * ## Why there is no denial arrow here, and why that is a decision
+ *
+ * `applyRuntimeObservations` accepts `held: false` — runtime saw that an edge
+ * did not hold — and records a correction that demotes the edge's confidence.
+ * **This producer never emits one, and must not.**
+ *
+ * A frontend caller resolution can establish that a call *happened*. It cannot
+ * establish that one did not: a page visit exercises one code path, and the
+ * absence of a captured stack for some other function is absence of evidence,
+ * not evidence of absence. Minting a denial from that would demote a correct
+ * edge on the strength of a route the run happened not to take — precisely the
+ * wrong-direction failure rule 2 exists to prevent, arriving through the one
+ * mechanism designed to make the graph *more* trustworthy.
+ *
+ * The denial arrow is real and stays available; it belongs to a producer that
+ * can actually establish non-occurrence (an exhaustive call-graph trace over a
+ * fully exercised path), not to this one.
+ *
+ * ## What this does not do
+ *
+ * - **It does not judge a finding.** Resolution has no opinion on confidence
+ *   (RT-027). Nothing here reads or writes a finding, hypothesis or category.
+ * - **It does not decide staleness.** An R4-vs-R4 disagreement is reported by
+ *   the core function as `staleR4` and passed through untouched.
+ * - **It does not invent a node.** That refusal is core's, and its `refused`
+ *   list is passed through rather than swallowed.
+ */
+import type { RuntimeEdgeObservation } from "@descryy/ir";
+import { type RuntimeConfirmationResult, type SqlDriver } from "@descryy/core";
+import type { StackTrace } from "@descryy/runtime-contracts";
+import { type ObservedFrontendCallerResolution } from "./observed-frontend-caller.ts";
+export interface ConfirmObservedCallerInput {
+    /** The endpoint whose callers this observation is about. */
+    readonly endpointNodeId: string;
+    /** The captured call-site stack, or `null` when the collector captured none. */
+    readonly stackTrace: StackTrace | null;
+    readonly repo: string;
+    /** The run that witnessed this. Becomes `edges.observed_by_run` and `observed_edges.run_id`. */
+    readonly runId: string;
+    /** The commit the observed application was built from, so a later reader can tell whether the code moved under the observation. */
+    readonly commitSha: string;
+    readonly repoRoot?: string;
+}
+export interface ConfirmObservedCallerOutcome {
+    /**
+     * The underlying resolution, unchanged and always present — including when it
+     * produced no observation. A caller that wants the structural answer still
+     * gets exactly what `resolveObservedFrontendCaller` would have returned.
+     */
+    readonly resolution: ObservedFrontendCallerResolution;
+    /** What was sent to the graph. Empty when the resolution observed nothing. */
+    readonly observations: readonly RuntimeEdgeObservation[];
+    /** Core's own result, passed through whole — refusals and `staleR4` included. */
+    readonly confirmation: RuntimeConfirmationResult;
+}
+/**
+ * Resolve one observed frontend call and, when it genuinely observed something,
+ * record it as R4 evidence against the graph.
+ */
+export declare function confirmObservedFrontendCaller(driver: SqlDriver, input: ConfirmObservedCallerInput): ConfirmObservedCallerOutcome;
+//# sourceMappingURL=confirm-observed-caller.d.ts.map

package/dist/confirm-observed-caller.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"confirm-observed-caller.d.ts","sourceRoot":"","sources":["../src/confirm-observed-caller.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAyDG;AAEH,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,aAAa,CAAC;AAC1D,OAAO,EAEL,KAAK,yBAAyB,EAC9B,KAAK,SAAS,EACf,MAAM,eAAe,CAAC;AACvB,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,4BAA4B,CAAC;AAE7D,OAAO,EAEL,KAAK,gCAAgC,EACtC,MAAM,+BAA+B,CAAC;AAEvC,MAAM,WAAW,0BAA0B;IACzC,4DAA4D;IAC5D,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;IAChC,gFAAgF;IAChF,QAAQ,CAAC,UAAU,EAAE,UAAU,GAAG,IAAI,CAAC;IACvC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,gGAAgG;IAChG,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,mIAAmI;IACnI,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;CAC5B;AAED,MAAM,WAAW,4BAA4B;IAC3C;;;;OAIG;IACH,QAAQ,CAAC,UAAU,EAAE,gCAAgC,CAAC;IACtD,8EAA8E;IAC9E,QAAQ,CAAC,YAAY,EAAE,SAAS,sBAAsB,EAAE,CAAC;IACzD,iFAAiF;IACjF,QAAQ,CAAC,YAAY,EAAE,yBAAyB,CAAC;CAClD;AAMD;;;GAGG;AACH,wBAAgB,6BAA6B,CAC3C,MAAM,EAAE,SAAS,EACjB,KAAK,EAAE,0BAA0B,GAChC,4BAA4B,CAyB9B"}

package/dist/confirm-observed-caller.js

@@ -0,0 +1,117 @@
+/**
+ * The first production caller of `applyRuntimeObservations()` — architecture
+ * §11B.3's R4 runtime confirmation, wired to a real observation source.
+ *
+ * §11B.3 calls runtime confirmation *"the core technical moat rather than the
+ * graph itself"*, and states the consequence plainly: *"a purely static
+ * code-graph tool is capped at R3 permanently."* The mechanism has existed in
+ * `@descryy/core` since it was built, and the two EARNED tables it writes
+ * (`observed_edges`, `edge_corrections`) have been in the store's schema since
+ * the store was first written — each with a comment explaining why they cannot
+ * be regenerated from source at any price. **Nothing read or wrote either one.**
+ * This is what makes the moat run.
+ *
+ * ## Why this producer
+ *
+ * `resolveObservedFrontendCaller` already does the hard half. It takes a real
+ * captured `fetch()` call-site stack, resolves its site of interest to a
+ * `FUNCTION` node, and checks that node against the structural candidate set the
+ * graph holds for the endpoint. Its two observed outcomes *are* two of §11B.3's
+ * three arrows, and needed only to be spoken in the vocabulary
+ * `applyRuntimeObservations` reads:
+ *
+ * | resolution outcome | arrow |
+ * | --- | --- |
+ * | `observed` | the graph already holds this `USES_API` edge below R4 — **promote it** |
+ * | `structural-observed-conflict` | a real node the structural side never named — **mint the edge at R4** (§11B.3's *"recall gap closed"*) |
+ *
+ * Everything else — no stack, an unresolvable frame, an ambiguous or missing
+ * symbol — produces **no observation at all**. Not an empty confirmation that
+ * looks like one; none.
+ *
+ * ## Why there is no denial arrow here, and why that is a decision
+ *
+ * `applyRuntimeObservations` accepts `held: false` — runtime saw that an edge
+ * did not hold — and records a correction that demotes the edge's confidence.
+ * **This producer never emits one, and must not.**
+ *
+ * A frontend caller resolution can establish that a call *happened*. It cannot
+ * establish that one did not: a page visit exercises one code path, and the
+ * absence of a captured stack for some other function is absence of evidence,
+ * not evidence of absence. Minting a denial from that would demote a correct
+ * edge on the strength of a route the run happened not to take — precisely the
+ * wrong-direction failure rule 2 exists to prevent, arriving through the one
+ * mechanism designed to make the graph *more* trustworthy.
+ *
+ * The denial arrow is real and stays available; it belongs to a producer that
+ * can actually establish non-occurrence (an exhaustive call-graph trace over a
+ * fully exercised path), not to this one.
+ *
+ * ## What this does not do
+ *
+ * - **It does not judge a finding.** Resolution has no opinion on confidence
+ *   (RT-027). Nothing here reads or writes a finding, hypothesis or category.
+ * - **It does not decide staleness.** An R4-vs-R4 disagreement is reported by
+ *   the core function as `staleR4` and passed through untouched.
+ * - **It does not invent a node.** That refusal is core's, and its `refused`
+ *   list is passed through rather than swallowed.
+ */
+import { applyRuntimeObservations, } from "@descryy/core";
+import { resolveObservedFrontendCaller, } from "./observed-frontend-caller.js";
+const EMPTY = {
+    promoted: [], created: [], confirmed: [], contradictions: [], staleR4: [], refused: [],
+};
+/**
+ * Resolve one observed frontend call and, when it genuinely observed something,
+ * record it as R4 evidence against the graph.
+ */
+export function confirmObservedFrontendCaller(driver, input) {
+    const resolution = resolveObservedFrontendCaller(driver, input.endpointNodeId, input.stackTrace, input.repo, input.repoRoot === undefined ? {} : { repoRoot: input.repoRoot });
+    const observations = observationsFor(resolution, input.endpointNodeId);
+    if (observations.length === 0) {
+        // Nothing observed. Deliberately not a call with an empty list: an
+        // `adapter_runs` row would be minted for a run that witnessed nothing,
+        // which reads in the ledger exactly like a run that observed and found
+        // nothing to say. Those are different statements.
+        return { resolution, observations, confirmation: EMPTY };
+    }
+    const confirmation = applyRuntimeObservations(driver, {
+        runId: input.runId,
+        commitSha: input.commitSha,
+        observations,
+    });
+    return { resolution, observations, confirmation };
+}
+function observationsFor(resolution, endpointNodeId) {
+    if (resolution.outcome === "observed") {
+        return [
+            {
+                from: resolution.node.id,
+                to: endpointNodeId,
+                edgeType: "USES_API",
+                held: true,
+                detail: `A captured fetch() call-site stack resolved to ${resolution.node.name} ` +
+                    `(${resolution.node.file ?? "unknown file"}), which the graph already names as a ` +
+                    "structural caller of this endpoint.",
+            },
+        ];
+    }
+    if (resolution.outcome === "structural-observed-conflict") {
+        return [
+            {
+                from: resolution.observedNode.id,
+                to: endpointNodeId,
+                edgeType: "USES_API",
+                held: true,
+                detail: `A captured fetch() call-site stack resolved to ${resolution.observedNode.name} ` +
+                    `(${resolution.observedNode.file ?? "unknown file"}), which static analysis did not name ` +
+                    `as a caller of this endpoint (${resolution.structuralCandidates.length} structural ` +
+                    "candidate(s) found, none of them this one). Recorded as observed rather than adjudicated.",
+            },
+        ];
+    }
+    // Every other outcome is a refusal or a purely structural answer. Neither is
+    // an observation, and neither becomes one by being written down.
+    return [];
+}
+//# sourceMappingURL=confirm-observed-caller.js.map

package/dist/confirm-observed-caller.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"confirm-observed-caller.js","sourceRoot":"","sources":["../src/confirm-observed-caller.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAyDG;AAGH,OAAO,EACL,wBAAwB,GAGzB,MAAM,eAAe,CAAC;AAGvB,OAAO,EACL,6BAA6B,GAE9B,MAAM,+BAA+B,CAAC;AA4BvC,MAAM,KAAK,GAA8B;IACvC,QAAQ,EAAE,EAAE,EAAE,OAAO,EAAE,EAAE,EAAE,SAAS,EAAE,EAAE,EAAE,cAAc,EAAE,EAAE,EAAE,OAAO,EAAE,EAAE,EAAE,OAAO,EAAE,EAAE;CACvF,CAAC;AAEF;;;GAGG;AACH,MAAM,UAAU,6BAA6B,CAC3C,MAAiB,EACjB,KAAiC;IAEjC,MAAM,UAAU,GAAG,6BAA6B,CAC9C,MAAM,EACN,KAAK,CAAC,cAAc,EACpB,KAAK,CAAC,UAAU,EAChB,KAAK,CAAC,IAAI,EACV,KAAK,CAAC,QAAQ,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,QAAQ,EAAE,KAAK,CAAC,QAAQ,EAAE,CACjE,CAAC;IAEF,MAAM,YAAY,GAAG,eAAe,CAAC,UAAU,EAAE,KAAK,CAAC,cAAc,CAAC,CAAC;IACvE,IAAI,YAAY,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QAC9B,mEAAmE;QACnE,uEAAuE;QACvE,uEAAuE;QACvE,kDAAkD;QAClD,OAAO,EAAE,UAAU,EAAE,YAAY,EAAE,YAAY,EAAE,KAAK,EAAE,CAAC;IAC3D,CAAC;IAED,MAAM,YAAY,GAAG,wBAAwB,CAAC,MAAM,EAAE;QACpD,KAAK,EAAE,KAAK,CAAC,KAAK;QAClB,SAAS,EAAE,KAAK,CAAC,SAAS;QAC1B,YAAY;KACb,CAAC,CAAC;IAEH,OAAO,EAAE,UAAU,EAAE,YAAY,EAAE,YAAY,EAAE,CAAC;AACpD,CAAC;AAED,SAAS,eAAe,CACtB,UAA4C,EAC5C,cAAsB;IAEtB,IAAI,UAAU,CAAC,OAAO,KAAK,UAAU,EAAE,CAAC;QACtC,OAAO;YACL;gBACE,IAAI,EAAE,UAAU,CAAC,IAAI,CAAC,EAAE;gBACxB,EAAE,EAAE,cAAc;gBAClB,QAAQ,EAAE,UAAU;gBACpB,IAAI,EAAE,IAAI;gBACV,MAAM,EACJ,kDAAkD,UAAU,CAAC,IAAI,CAAC,IAAI,GAAG;oBACzE,IAAI,UAAU,CAAC,IAAI,CAAC,IAAI,IAAI,cAAc,wCAAwC;oBAClF,qCAAqC;aACxC;SACF,CAAC;IACJ,CAAC;IAED,IAAI,UAAU,CAAC,OAAO,KAAK,8BAA8B,EAAE,CAAC;QAC1D,OAAO;YACL;gBACE,IAAI,EAAE,UAAU,CAAC,YAAY,CAAC,EAAE;gBAChC,EAAE,EAAE,cAAc;gBAClB,QAAQ,EAAE,UAAU;gBACpB,IAAI,EAAE,IAAI;gBACV,MAAM,EACJ,kDAAkD,UAAU,CAAC,YAAY,CAAC,IAAI,GAAG;oBACjF,IAAI,UAAU,CAAC,YAAY,CAAC,IAAI,IAAI,cAAc,wCAAwC;oBAC1F,iCAAiC,UAAU,CAAC,oBAAoB,CAAC,MAAM,cAAc;oBACrF,2FAA2F;aAC9F;SACF,CAAC;IACJ,CAAC;IAED,6EAA6E;IAC7E,iEAAiE;IACjE,OAAO,EAAE,CAAC;AACZ,CAAC"}

package/dist/database-table.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Resolving a captured query's target table name (a real, observed string —
+ * `extractTargetTable`, `@descryhq-wq/runtime-database-observation`) to the
+ * `DATABASE_TABLE` node it names — the §10/§18 join `DatabaseQueryCollector`
+ * disclosed as missing since RT-141: real query capture, `graphNodeId`
+ * always null.
+ *
+ * **`DATABASE_TABLE` is workspace-scoped, not repo-scoped** (`adapter-sql`'s
+ * own `extract`/`adapter.ts`, DEC-054) — the same reason `resolveEndpointNode`
+ * (`endpoint.ts`, this package) takes no `repo` parameter: a migration can
+ * live in one repository and the service reading the table in another, and
+ * DEC-054 exists specifically so they still join. A runtime observation
+ * carries no repository at all for a bare table name — the observed
+ * process's own source may not even be one of the repos this graph indexed
+ * — so taking a `repo` filter here would be inventing a constraint the
+ * caller has no way to satisfy.
+ *
+ * **Unlike an endpoint, a table name is not a template.** No segment
+ * matching, no `{param}` — `DATABASE_TABLE.name` is the bare table name
+ * (`adapter-sql`'s `extract.ts`: `name: table.table`), so this is a plain
+ * equality match against every candidate, the simpler half of
+ * `resolveEndpointNode`'s own two-part job.
+ */
+import type { IRNode } from "@descryy/ir";
+import { type SqlDriver } from "@descryy/core";
+export type DatabaseTableResolution = {
+    readonly outcome: "resolved";
+    readonly node: IRNode;
+} | {
+    readonly outcome: "not-found";
+    readonly reason: string;
+} | {
+    readonly outcome: "ambiguous";
+    readonly candidates: readonly IRNode[];
+    readonly reason: string;
+};
+export declare function resolveDatabaseTableNode(driver: SqlDriver, tableName: string, options?: {
+    readonly limit?: number;
+}): DatabaseTableResolution;
+//# sourceMappingURL=database-table.d.ts.map

package/dist/database-table.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"database-table.d.ts","sourceRoot":"","sources":["../src/database-table.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AAC1C,OAAO,EAAe,KAAK,SAAS,EAAE,MAAM,eAAe,CAAC;AAE5D,MAAM,MAAM,uBAAuB,GAC/B;IAAE,QAAQ,CAAC,OAAO,EAAE,UAAU,CAAC;IAAC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;CAAE,GACvD;IAAE,QAAQ,CAAC,OAAO,EAAE,WAAW,CAAC;IAAC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;CAAE,GAC1D;IAAE,QAAQ,CAAC,OAAO,EAAE,WAAW,CAAC;IAAC,QAAQ,CAAC,UAAU,EAAE,SAAS,MAAM,EAAE,CAAC;IAAC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAAC;AAEvG,wBAAgB,wBAAwB,CACtC,MAAM,EAAE,SAAS,EACjB,SAAS,EAAE,MAAM,EACjB,OAAO,GAAE;IAAE,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAA;CAAO,GACxC,uBAAuB,CA+BzB"}

package/dist/database-table.js

@@ -0,0 +1,52 @@
+/**
+ * Resolving a captured query's target table name (a real, observed string —
+ * `extractTargetTable`, `@descryhq-wq/runtime-database-observation`) to the
+ * `DATABASE_TABLE` node it names — the §10/§18 join `DatabaseQueryCollector`
+ * disclosed as missing since RT-141: real query capture, `graphNodeId`
+ * always null.
+ *
+ * **`DATABASE_TABLE` is workspace-scoped, not repo-scoped** (`adapter-sql`'s
+ * own `extract`/`adapter.ts`, DEC-054) — the same reason `resolveEndpointNode`
+ * (`endpoint.ts`, this package) takes no `repo` parameter: a migration can
+ * live in one repository and the service reading the table in another, and
+ * DEC-054 exists specifically so they still join. A runtime observation
+ * carries no repository at all for a bare table name — the observed
+ * process's own source may not even be one of the repos this graph indexed
+ * — so taking a `repo` filter here would be inventing a constraint the
+ * caller has no way to satisfy.
+ *
+ * **Unlike an endpoint, a table name is not a template.** No segment
+ * matching, no `{param}` — `DATABASE_TABLE.name` is the bare table name
+ * (`adapter-sql`'s `extract.ts`: `name: table.table`), so this is a plain
+ * equality match against every candidate, the simpler half of
+ * `resolveEndpointNode`'s own two-part job.
+ */
+import { nodesOfType } from "@descryy/core";
+export function resolveDatabaseTableNode(driver, tableName, options = {}) {
+    const { nodes, truncated } = nodesOfType(driver, "DATABASE_TABLE", options.limit ?? 5000);
+    const matches = nodes.filter((node) => node.name === tableName);
+    if (matches.length === 0) {
+        return {
+            outcome: "not-found",
+            reason: `No DATABASE_TABLE node named "${tableName}".` +
+                (truncated
+                    ? " The DATABASE_TABLE scan was truncated by the node budget, so this may be a coverage " +
+                        "gap rather than a genuine absence."
+                    : " Either no schema declares this table, or no SQL adapter has read the migration that " +
+                        "creates it — a real gap to report rather than assume clean."),
+        };
+    }
+    if (matches.length > 1) {
+        return {
+            outcome: "ambiguous",
+            candidates: matches,
+            reason: `${matches.length} DATABASE_TABLE nodes are named "${tableName}" — ` +
+                `${matches.map((n) => `${n.attrs.schema ?? "?"}.${n.name}`).join(", ")}. ` +
+                "Two schemas naming the same table is real and not rare (a per-tenant schema pattern, " +
+                "or two workspaces this graph both indexed); picking one would be a guess this resolver " +
+                "has no basis for.",
+        };
+    }
+    return { outcome: "resolved", node: matches[0] };
+}
+//# sourceMappingURL=database-table.js.map

package/dist/database-table.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"database-table.js","sourceRoot":"","sources":["../src/database-table.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAGH,OAAO,EAAE,WAAW,EAAkB,MAAM,eAAe,CAAC;AAO5D,MAAM,UAAU,wBAAwB,CACtC,MAAiB,EACjB,SAAiB,EACjB,UAAuC,EAAE;IAEzC,MAAM,EAAE,KAAK,EAAE,SAAS,EAAE,GAAG,WAAW,CAAC,MAAM,EAAE,gBAAgB,EAAE,OAAO,CAAC,KAAK,IAAI,IAAI,CAAC,CAAC;IAC1F,MAAM,OAAO,GAAG,KAAK,CAAC,MAAM,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,IAAI,KAAK,SAAS,CAAC,CAAC;IAEhE,IAAI,OAAO,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACzB,OAAO;YACL,OAAO,EAAE,WAAW;YACpB,MAAM,EACJ,iCAAiC,SAAS,IAAI;gBAC9C,CAAC,SAAS;oBACR,CAAC,CAAC,uFAAuF;wBACvF,oCAAoC;oBACtC,CAAC,CAAC,uFAAuF;wBACvF,6DAA6D,CAAC;SACrE,CAAC;IACJ,CAAC;IAED,IAAI,OAAO,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QACvB,OAAO;YACL,OAAO,EAAE,WAAW;YACpB,UAAU,EAAE,OAAO;YACnB,MAAM,EACJ,GAAG,OAAO,CAAC,MAAM,oCAAoC,SAAS,MAAM;gBACpE,GAAG,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,GAAI,CAAC,CAAC,KAAK,CAAC,MAA6B,IAAI,GAAG,IAAI,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI;gBAClG,uFAAuF;gBACvF,yFAAyF;gBACzF,mBAAmB;SACtB,CAAC;IACJ,CAAC;IAED,OAAO,EAAE,OAAO,EAAE,UAAU,EAAE,IAAI,EAAE,OAAO,CAAC,CAAC,CAAE,EAAE,CAAC;AACpD,CAAC"}

package/dist/endpoint.d.ts

@@ -0,0 +1,73 @@
+/**
+ * Resolving observed HTTP evidence (a real request's method + literal path)
+ * to the `API_ENDPOINT` node it was served by — plan §12/§25 ("Runtime
+ * should be able to build an observed path such as FUNCTION → API_ROUTE →
+ * API_ENDPOINT → FUNCTION → DATABASE_TABLE, where the static graph and
+ * runtime evidence actually support those links").
+ *
+ * `API_ENDPOINT` is workspace-scoped, not repo-scoped (DEC-054) — it is
+ * deliberately the one join node two repositories mint identically with no
+ * shared code (DEC-115). That means, unlike a `FUNCTION` lookup, there is no
+ * "wrong repository" version of this node to accidentally pick: any
+ * `API_ENDPOINT` in the store is the one shared join point by construction,
+ * so this file takes no `repo`/`scope` parameter — adding one would be
+ * inventing a filter with nothing behind it to filter on.
+ *
+ * What this file *does* have to solve, that a bare identity hash cannot: a
+ * real request's URL is a literal (`/orders/5`), while the route that served
+ * it may have been minted from a parameterised template
+ * (`/orders/{param}`, per `normaliseEndpointPath`). Those hash to different
+ * ids, so resolution here is a segment-wise match against every candidate's
+ * *name*, not a single `getNode` by a computed id. That is also what makes
+ * "similar endpoint" (plan §38's own negative-control name) a real,
+ * representable outcome here rather than a hypothetical: a literal route
+ * (`GET /orders/active`) and a parameterised one (`GET /orders/{param}`) can
+ * both legitimately match one observed request, and this resolver reports
+ * that as `ambiguous` rather than guessing which one actually served it —
+ * the same discipline `resolveOneNode` (descry-core's MCP lookup) applies to
+ * a name search, one layer down at the network-evidence layer instead.
+ */
+import { type IRNode } from "@descryy/ir";
+import { type SqlDriver } from "@descryy/core";
+export type EndpointResolution = {
+    readonly outcome: "resolved";
+    readonly node: IRNode;
+} | {
+    readonly outcome: "not-found";
+    readonly reason: string;
+} | {
+    readonly outcome: "ambiguous";
+    readonly candidates: readonly IRNode[];
+    readonly reason: string;
+};
+export declare function resolveEndpointNode(driver: SqlDriver, method: string, observedPath: string, options?: {
+    readonly limit?: number;
+}): EndpointResolution;
+/**
+ * Every `API_ENDPOINT` whose path shape matches `observedPath`, **regardless
+ * of method** — the query `resolveEndpointNode` deliberately does not answer
+ * on its own, since it filters by method first and a caller asking "does
+ * this path exist under a different method" needs the method filter removed
+ * entirely, not relaxed.
+ *
+ * Built for one caller (`@descryhq-wq/runtime-openapi-observation`'s "wrong
+ * method" vs "undocumented" distinction, checklist §15): a request whose
+ * exact method+path resolves to nothing is a different fact from one whose
+ * path resolves under some *other* method — the first says the operation
+ * was never declared, the second says it was declared and the request used
+ * the wrong verb. Conflating them would report "undocumented" for a request
+ * a contract-reading person would call a client bug, not a documentation
+ * gap.
+ *
+ * Ambiguity is not resolved here either — every shape-matching node is
+ * returned, and the caller decides what "more than one, across methods"
+ * means for its own question, the same "refuse rather than rank" split
+ * `resolveEndpointNode` already uses for its own single-method case.
+ */
+export declare function resolveEndpointNodesByPath(driver: SqlDriver, observedPath: string, options?: {
+    readonly limit?: number;
+}): {
+    readonly nodes: readonly IRNode[];
+    readonly truncated: boolean;
+};
+//# sourceMappingURL=endpoint.d.ts.map

package/dist/endpoint.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"endpoint.d.ts","sourceRoot":"","sources":["../src/endpoint.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AAEH,OAAO,EAAsC,KAAK,MAAM,EAAE,MAAM,aAAa,CAAC;AAC9E,OAAO,EAAe,KAAK,SAAS,EAAE,MAAM,eAAe,CAAC;AAE5D,MAAM,MAAM,kBAAkB,GAC1B;IAAE,QAAQ,CAAC,OAAO,EAAE,UAAU,CAAC;IAAC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;CAAE,GACvD;IAAE,QAAQ,CAAC,OAAO,EAAE,WAAW,CAAC;IAAC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;CAAE,GAC1D;IAAE,QAAQ,CAAC,OAAO,EAAE,WAAW,CAAC;IAAC,QAAQ,CAAC,UAAU,EAAE,SAAS,MAAM,EAAE,CAAC;IAAC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAAC;AAavG,wBAAgB,mBAAmB,CACjC,MAAM,EAAE,SAAS,EACjB,MAAM,EAAE,MAAM,EACd,YAAY,EAAE,MAAM,EACpB,OAAO,GAAE;IAAE,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAA;CAAO,GACxC,kBAAkB,CA2CpB;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,0BAA0B,CACxC,MAAM,EAAE,SAAS,EACjB,YAAY,EAAE,MAAM,EACpB,OAAO,GAAE;IAAE,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAA;CAAO,GACxC;IAAE,QAAQ,CAAC,KAAK,EAAE,SAAS,MAAM,EAAE,CAAC;IAAC,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAA;CAAE,CAapE"}

package/dist/endpoint.js

@@ -0,0 +1,115 @@
+/**
+ * Resolving observed HTTP evidence (a real request's method + literal path)
+ * to the `API_ENDPOINT` node it was served by — plan §12/§25 ("Runtime
+ * should be able to build an observed path such as FUNCTION → API_ROUTE →
+ * API_ENDPOINT → FUNCTION → DATABASE_TABLE, where the static graph and
+ * runtime evidence actually support those links").
+ *
+ * `API_ENDPOINT` is workspace-scoped, not repo-scoped (DEC-054) — it is
+ * deliberately the one join node two repositories mint identically with no
+ * shared code (DEC-115). That means, unlike a `FUNCTION` lookup, there is no
+ * "wrong repository" version of this node to accidentally pick: any
+ * `API_ENDPOINT` in the store is the one shared join point by construction,
+ * so this file takes no `repo`/`scope` parameter — adding one would be
+ * inventing a filter with nothing behind it to filter on.
+ *
+ * What this file *does* have to solve, that a bare identity hash cannot: a
+ * real request's URL is a literal (`/orders/5`), while the route that served
+ * it may have been minted from a parameterised template
+ * (`/orders/{param}`, per `normaliseEndpointPath`). Those hash to different
+ * ids, so resolution here is a segment-wise match against every candidate's
+ * *name*, not a single `getNode` by a computed id. That is also what makes
+ * "similar endpoint" (plan §38's own negative-control name) a real,
+ * representable outcome here rather than a hypothetical: a literal route
+ * (`GET /orders/active`) and a parameterised one (`GET /orders/{param}`) can
+ * both legitimately match one observed request, and this resolver reports
+ * that as `ambiguous` rather than guessing which one actually served it —
+ * the same discipline `resolveOneNode` (descry-core's MCP lookup) applies to
+ * a name search, one layer down at the network-evidence layer instead.
+ */
+import { endpointQsp, normaliseEndpointPath } from "@descryy/ir";
+import { nodesOfType } from "@descryy/core";
+function pathSegments(path) {
+    // `endpointQsp`'s own qualified path is "METHOD /normalised/path" — split
+    // on "/" after the method prefix is stripped, same shape either side.
+    return normaliseEndpointPath(path).split("/");
+}
+function segmentsMatch(templateSegments, observedSegments) {
+    if (templateSegments.length !== observedSegments.length)
+        return false;
+    return templateSegments.every((segment, i) => segment === "{param}" || segment === observedSegments[i]);
+}
+export function resolveEndpointNode(driver, method, observedPath, options = {}) {
+    const methodUpper = method.toUpperCase();
+    const observedSegments = pathSegments(observedPath);
+    const prefix = `${methodUpper} `;
+    const { nodes, truncated } = nodesOfType(driver, "API_ENDPOINT", options.limit ?? 5000);
+    const matches = [];
+    for (const node of nodes) {
+        if (!node.name.startsWith(prefix))
+            continue;
+        const templateSegments = node.name.slice(prefix.length).split("/");
+        if (segmentsMatch(templateSegments, observedSegments))
+            matches.push(node);
+    }
+    const observed = endpointQsp(methodUpper, observedPath);
+    if (matches.length === 0) {
+        return {
+            outcome: "not-found",
+            reason: `No API_ENDPOINT node's shape matches ${observed}.` +
+                (truncated
+                    ? " The API_ENDPOINT scan was truncated by the node budget, so this may be a coverage " +
+                        "gap rather than a genuine absence."
+                    : " Either no route was minted for this request, or it was, and this is a real gap to " +
+                        "report rather than assume clean."),
+        };
+    }
+    if (matches.length > 1) {
+        return {
+            outcome: "ambiguous",
+            candidates: matches,
+            reason: `${matches.length} API_ENDPOINT nodes' shapes all match ${observed} — ` +
+                `${matches.map((n) => n.name).join(", ")}. This is the "similar endpoint" case (a literal ` +
+                "route and a parameterised one can both textually match one real request): this resolver " +
+                "has no router-precedence information to break the tie, so it refuses rather than guessing " +
+                "which one actually served the request.",
+        };
+    }
+    return { outcome: "resolved", node: matches[0] };
+}
+/**
+ * Every `API_ENDPOINT` whose path shape matches `observedPath`, **regardless
+ * of method** — the query `resolveEndpointNode` deliberately does not answer
+ * on its own, since it filters by method first and a caller asking "does
+ * this path exist under a different method" needs the method filter removed
+ * entirely, not relaxed.
+ *
+ * Built for one caller (`@descryhq-wq/runtime-openapi-observation`'s "wrong
+ * method" vs "undocumented" distinction, checklist §15): a request whose
+ * exact method+path resolves to nothing is a different fact from one whose
+ * path resolves under some *other* method — the first says the operation
+ * was never declared, the second says it was declared and the request used
+ * the wrong verb. Conflating them would report "undocumented" for a request
+ * a contract-reading person would call a client bug, not a documentation
+ * gap.
+ *
+ * Ambiguity is not resolved here either — every shape-matching node is
+ * returned, and the caller decides what "more than one, across methods"
+ * means for its own question, the same "refuse rather than rank" split
+ * `resolveEndpointNode` already uses for its own single-method case.
+ */
+export function resolveEndpointNodesByPath(driver, observedPath, options = {}) {
+    const observedSegments = pathSegments(observedPath);
+    const { nodes, truncated } = nodesOfType(driver, "API_ENDPOINT", options.limit ?? 5000);
+    const matches = [];
+    for (const node of nodes) {
+        const spaceIndex = node.name.indexOf(" ");
+        if (spaceIndex === -1)
+            continue; // not this adapter's "METHOD /path" naming -- refuse rather than guess at a split
+        const templateSegments = node.name.slice(spaceIndex + 1).split("/");
+        if (segmentsMatch(templateSegments, observedSegments))
+            matches.push(node);
+    }
+    return { nodes: matches, truncated };
+}
+//# sourceMappingURL=endpoint.js.map

package/dist/endpoint.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"endpoint.js","sourceRoot":"","sources":["../src/endpoint.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AAEH,OAAO,EAAE,WAAW,EAAE,qBAAqB,EAAe,MAAM,aAAa,CAAC;AAC9E,OAAO,EAAE,WAAW,EAAkB,MAAM,eAAe,CAAC;AAO5D,SAAS,YAAY,CAAC,IAAY;IAChC,0EAA0E;IAC1E,sEAAsE;IACtE,OAAO,qBAAqB,CAAC,IAAI,CAAC,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;AAChD,CAAC;AAED,SAAS,aAAa,CAAC,gBAAmC,EAAE,gBAAmC;IAC7F,IAAI,gBAAgB,CAAC,MAAM,KAAK,gBAAgB,CAAC,MAAM;QAAE,OAAO,KAAK,CAAC;IACtE,OAAO,gBAAgB,CAAC,KAAK,CAAC,CAAC,OAAO,EAAE,CAAC,EAAE,EAAE,CAAC,OAAO,KAAK,SAAS,IAAI,OAAO,KAAK,gBAAgB,CAAC,CAAC,CAAC,CAAC,CAAC;AAC1G,CAAC;AAED,MAAM,UAAU,mBAAmB,CACjC,MAAiB,EACjB,MAAc,EACd,YAAoB,EACpB,UAAuC,EAAE;IAEzC,MAAM,WAAW,GAAG,MAAM,CAAC,WAAW,EAAE,CAAC;IACzC,MAAM,gBAAgB,GAAG,YAAY,CAAC,YAAY,CAAC,CAAC;IACpD,MAAM,MAAM,GAAG,GAAG,WAAW,GAAG,CAAC;IAEjC,MAAM,EAAE,KAAK,EAAE,SAAS,EAAE,GAAG,WAAW,CAAC,MAAM,EAAE,cAAc,EAAE,OAAO,CAAC,KAAK,IAAI,IAAI,CAAC,CAAC;IAExF,MAAM,OAAO,GAAa,EAAE,CAAC;IAC7B,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;QACzB,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,UAAU,CAAC,MAAM,CAAC;YAAE,SAAS;QAC5C,MAAM,gBAAgB,GAAG,IAAI,CAAC,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;QACnE,IAAI,aAAa,CAAC,gBAAgB,EAAE,gBAAgB,CAAC;YAAE,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IAC5E,CAAC;IAED,MAAM,QAAQ,GAAG,WAAW,CAAC,WAAW,EAAE,YAAY,CAAC,CAAC;IAExD,IAAI,OAAO,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACzB,OAAO;YACL,OAAO,EAAE,WAAW;YACpB,MAAM,EACJ,wCAAwC,QAAQ,GAAG;gBACnD,CAAC,SAAS;oBACR,CAAC,CAAC,qFAAqF;wBACrF,oCAAoC;oBACtC,CAAC,CAAC,qFAAqF;wBACrF,kCAAkC,CAAC;SAC1C,CAAC;IACJ,CAAC;IAED,IAAI,OAAO,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QACvB,OAAO;YACL,OAAO,EAAE,WAAW;YACpB,UAAU,EAAE,OAAO;YACnB,MAAM,EACJ,GAAG,OAAO,CAAC,MAAM,yCAAyC,QAAQ,KAAK;gBACvE,GAAG,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,mDAAmD;gBAC3F,0FAA0F;gBAC1F,4FAA4F;gBAC5F,wCAAwC;SAC3C,CAAC;IACJ,CAAC;IAED,OAAO,EAAE,OAAO,EAAE,UAAU,EAAE,IAAI,EAAE,OAAO,CAAC,CAAC,CAAE,EAAE,CAAC;AACpD,CAAC;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,MAAM,UAAU,0BAA0B,CACxC,MAAiB,EACjB,YAAoB,EACpB,UAAuC,EAAE;IAEzC,MAAM,gBAAgB,GAAG,YAAY,CAAC,YAAY,CAAC,CAAC;IACpD,MAAM,EAAE,KAAK,EAAE,SAAS,EAAE,GAAG,WAAW,CAAC,MAAM,EAAE,cAAc,EAAE,OAAO,CAAC,KAAK,IAAI,IAAI,CAAC,CAAC;IAExF,MAAM,OAAO,GAAa,EAAE,CAAC;IAC7B,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;QACzB,MAAM,UAAU,GAAG,IAAI,CAAC,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC;QAC1C,IAAI,UAAU,KAAK,CAAC,CAAC;YAAE,SAAS,CAAC,kFAAkF;QACnH,MAAM,gBAAgB,GAAG,IAAI,CAAC,IAAI,CAAC,KAAK,CAAC,UAAU,GAAG,CAAC,CAAC,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;QACpE,IAAI,aAAa,CAAC,gBAAgB,EAAE,gBAAgB,CAAC;YAAE,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IAC5E,CAAC;IAED,OAAO,EAAE,KAAK,EAAE,OAAO,EAAE,SAAS,EAAE,CAAC;AACvC,CAAC"}

package/dist/frontend-caller.d.ts

@@ -0,0 +1,67 @@
+/**
+ * The **first leg** of the path the product requires:
+ * `Frontend FUNCTION → API_ENDPOINT → API_ROUTE → Backend FUNCTION`.
+ *
+ * `RUNTIME-CHECKLIST.md` §11 states that path and its own boxes covered
+ * only the last three legs — the audit added a box for the first and marked
+ * it absent. The graph has had the edge all along: `adapter-typescript`
+ * emits `USES_API` from a frontend function to the endpoint it calls, read
+ * from source. Nothing correlated it.
+ *
+ * ---
+ *
+ * **This is a structural claim, and calling it anything else would be the
+ * central lie this project exists not to tell.**
+ *
+ * `USES_API` says *this function contains a call to that endpoint*. It does
+ * **not** say this function issued the request that was just observed. When
+ * three components call one endpoint, the graph names all three and the
+ * browser saw one — and nothing in a `NETWORK_REQUEST` says which. Playwright
+ * exposes an initiator chain that could narrow it; the network collector
+ * does not capture it today (§6 records that as a gap), and until it does,
+ * *which* caller ran is not something this repo knows.
+ *
+ * So the outcome vocabulary says so at the type level: a single caller is
+ * `sole-structural-caller`, never `resolved`. A reader who sees `resolved`
+ * elsewhere in this package is looking at an observation; here they are
+ * looking at the only candidate the code admits, which is a different and
+ * weaker fact even when it happens to be right.
+ *
+ * **Consequence for reliability, per the architecture's resolution cap:** a
+ * finding whose path rests on this leg is capped by the `USES_API` edge's
+ * own resolution, exactly as any other structural hop is. Extending the
+ * path does not upgrade the evidence.
+ */
+import { type SqlDriver } from "@descryy/core";
+import type { IRNode } from "@descryy/ir";
+export type FrontendCallerResolution = 
+/** Exactly one frontend function declares a call to this endpoint. The only candidate — **not** proof that it is the one that ran. */
+{
+    readonly outcome: "sole-structural-caller";
+    readonly node: IRNode;
+    readonly reason: string;
+}
+/** Several functions call this endpoint. The graph cannot say which one issued the observed request, and neither can this. */
+ | {
+    readonly outcome: "ambiguous";
+    readonly candidates: readonly IRNode[];
+    readonly reason: string;
+}
+/** No `USES_API` edge points at this endpoint — the caller is in code this adapter did not read, or is not a direct call at all. */
+ | {
+    readonly outcome: "not-found";
+    readonly reason: string;
+};
+/**
+ * Every frontend function the graph says calls this endpoint.
+ *
+ * Ambiguity is returned to the caller rather than ranked, the same way
+ * `resolveSymbolNode` and `resolveEndpointNode` refuse it. There is a
+ * tempting heuristic here — prefer the caller in the file the browser most
+ * recently loaded, or the one whose line number is nearest the event — and
+ * both are timing and locality standing in for causality, which §27's own
+ * rule forbids in one sentence: *similarity must never be treated as
+ * causality*.
+ */
+export declare function resolveFrontendCallers(driver: SqlDriver, endpointNodeId: string): FrontendCallerResolution;
+//# sourceMappingURL=frontend-caller.d.ts.map

package/dist/frontend-caller.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"frontend-caller.d.ts","sourceRoot":"","sources":["../src/frontend-caller.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AAEH,OAAO,EAAY,KAAK,SAAS,EAAE,MAAM,eAAe,CAAC;AACzD,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AAG1C,MAAM,MAAM,wBAAwB;AAClC,sIAAsI;AACpI;IAAE,QAAQ,CAAC,OAAO,EAAE,wBAAwB,CAAC;IAAC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;CAAE;AAChG,8HAA8H;GAC5H;IAAE,QAAQ,CAAC,OAAO,EAAE,WAAW,CAAC;IAAC,QAAQ,CAAC,UAAU,EAAE,SAAS,MAAM,EAAE,CAAC;IAAC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;CAAE;AACpG,oIAAoI;GAClI;IAAE,QAAQ,CAAC,OAAO,EAAE,WAAW,CAAC;IAAC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAAC;AAE/D;;;;;;;;;;GAUG;AACH,wBAAgB,sBAAsB,CAAC,MAAM,EAAE,SAAS,EAAE,cAAc,EAAE,MAAM,GAAG,wBAAwB,CA2C1G"}