@descryy/runtime-graph-correlator 0.0.0

package/dist/frontend-caller.js

@@ -0,0 +1,87 @@
+/**
+ * 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 { incoming } from "@descryy/core";
+import { getNode } from "@descryy/core";
+/**
+ * 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 function resolveFrontendCallers(driver, endpointNodeId) {
+    const edges = incoming(driver, endpointNodeId, { types: ["USES_API"] });
+    const callers = [];
+    const seen = new Set();
+    for (const edge of edges) {
+        if (seen.has(edge.from))
+            continue;
+        seen.add(edge.from);
+        const node = getNode(driver, edge.from);
+        if (node === null || node === undefined)
+            continue; // an edge whose source is not in this store: a disclosed gap, not a caller to invent
+        callers.push(node);
+    }
+    if (callers.length === 0) {
+        return {
+            outcome: "not-found",
+            reason: `No USES_API edge points at endpoint "${endpointNodeId}". The calling code was not read by an adapter, ` +
+                "or the call is not a direct one this extractor recognises. Reported as a gap in the graph rather than " +
+                "as an absence of callers.",
+        };
+    }
+    if (callers.length > 1) {
+        return {
+            outcome: "ambiguous",
+            candidates: callers,
+            reason: `${callers.length} frontend functions call this endpoint: ${callers.map((c) => c.name).join(", ")}. ` +
+                "The graph names all of them and the browser observed one request; nothing in that request says which " +
+                "caller issued it. Refused rather than ranked — preferring the nearest line or the most recently loaded " +
+                "file would be locality standing in for causality.",
+        };
+    }
+    return {
+        outcome: "sole-structural-caller",
+        node: callers[0],
+        reason: `"${callers[0].name}" is the only function the graph says calls this endpoint. That makes it the sole ` +
+            "candidate, not a confirmed caller: USES_API is read from source and states that a call exists, not that " +
+            "this call is the one that ran.",
+    };
+}
+//# sourceMappingURL=frontend-caller.js.map

package/dist/frontend-caller.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"frontend-caller.js","sourceRoot":"","sources":["../src/frontend-caller.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AAEH,OAAO,EAAE,QAAQ,EAAkB,MAAM,eAAe,CAAC;AAEzD,OAAO,EAAE,OAAO,EAAE,MAAM,eAAe,CAAC;AAUxC;;;;;;;;;;GAUG;AACH,MAAM,UAAU,sBAAsB,CAAC,MAAiB,EAAE,cAAsB;IAC9E,MAAM,KAAK,GAAG,QAAQ,CAAC,MAAM,EAAE,cAAc,EAAE,EAAE,KAAK,EAAE,CAAC,UAAU,CAAC,EAAE,CAAC,CAAC;IAExE,MAAM,OAAO,GAAa,EAAE,CAAC;IAC7B,MAAM,IAAI,GAAG,IAAI,GAAG,EAAU,CAAC;IAC/B,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;QACzB,IAAI,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,IAAI,CAAC;YAAE,SAAS;QAClC,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QACpB,MAAM,IAAI,GAAG,OAAO,CAAC,MAAM,EAAE,IAAI,CAAC,IAAI,CAAC,CAAC;QACxC,IAAI,IAAI,KAAK,IAAI,IAAI,IAAI,KAAK,SAAS;YAAE,SAAS,CAAC,qFAAqF;QACxI,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IACrB,CAAC;IAED,IAAI,OAAO,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACzB,OAAO;YACL,OAAO,EAAE,WAAW;YACpB,MAAM,EACJ,wCAAwC,cAAc,kDAAkD;gBACxG,wGAAwG;gBACxG,2BAA2B;SAC9B,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,2CAA2C,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI;gBACrG,uGAAuG;gBACvG,yGAAyG;gBACzG,mDAAmD;SACtD,CAAC;IACJ,CAAC;IAED,OAAO;QACL,OAAO,EAAE,wBAAwB;QACjC,IAAI,EAAE,OAAO,CAAC,CAAC,CAAE;QACjB,MAAM,EACJ,IAAI,OAAO,CAAC,CAAC,CAAE,CAAC,IAAI,oFAAoF;YACxG,0GAA0G;YAC1G,gCAAgC;KACnC,CAAC;AACJ,CAAC"}

package/dist/index.d.ts

@@ -0,0 +1,19 @@
+/**
+ * The graph correlator: resolves runtime evidence to descry-core graph
+ * nodes. Deliberately does not re-wrap graph-path building — `traceApi`
+ * (`@descryy/core`) already answers "how does this reach that" end to end,
+ * `direction: "both"` already crosses the `API_ENDPOINT` join with no extra
+ * option needed (DEC-228 traced this directly; `crossApiEndpoint` is only
+ * for `impactOf`'s single-direction walk). A caller resolves both ends here,
+ * then calls `traceApi` from `@descryy/core` directly — adding a wrapper
+ * around a function that already does the whole job would be an
+ * abstraction with nothing behind it.
+ */
+export { resolveEndpointNode, resolveEndpointNodesByPath, type EndpointResolution } from "./endpoint.ts";
+export { resolveSymbolNode, resolveSymbolAcrossRepos, resolveContainingModule, resolveTestCaseNode, type SymbolResolution, type CrossRepoSymbolResolution, type ModuleResolution, type TestCaseResolution, } from "./symbol.ts";
+export { resolveEndpointFromLogText, findEndpointMentions, type LogEndpointResolution, type LogEndpointMention, } from "./log-endpoint.ts";
+export { resolveFrontendCallers, type FrontendCallerResolution } from "./frontend-caller.ts";
+export { resolveObservedFrontendCaller, type ObservedFrontendCallerResolution } from "./observed-frontend-caller.ts";
+export { resolveDatabaseTableNode, type DatabaseTableResolution } from "./database-table.ts";
+export { confirmObservedFrontendCaller, type ConfirmObservedCallerInput, type ConfirmObservedCallerOutcome, } from "./confirm-observed-caller.ts";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,EAAE,mBAAmB,EAAE,0BAA0B,EAAE,KAAK,kBAAkB,EAAE,MAAM,eAAe,CAAC;AACzG,OAAO,EACL,iBAAiB,EACjB,wBAAwB,EACxB,uBAAuB,EACvB,mBAAmB,EACnB,KAAK,gBAAgB,EACrB,KAAK,yBAAyB,EAC9B,KAAK,gBAAgB,EACrB,KAAK,kBAAkB,GACxB,MAAM,aAAa,CAAC;AACrB,OAAO,EACL,0BAA0B,EAC1B,oBAAoB,EACpB,KAAK,qBAAqB,EAC1B,KAAK,kBAAkB,GACxB,MAAM,mBAAmB,CAAC;AAC3B,OAAO,EAAE,sBAAsB,EAAE,KAAK,wBAAwB,EAAE,MAAM,sBAAsB,CAAC;AAC7F,OAAO,EAAE,6BAA6B,EAAE,KAAK,gCAAgC,EAAE,MAAM,+BAA+B,CAAC;AACrH,OAAO,EAAE,wBAAwB,EAAE,KAAK,uBAAuB,EAAE,MAAM,qBAAqB,CAAC;AAC7F,OAAO,EACL,6BAA6B,EAC7B,KAAK,0BAA0B,EAC/B,KAAK,4BAA4B,GAClC,MAAM,8BAA8B,CAAC"}

package/dist/index.js

@@ -0,0 +1,19 @@
+/**
+ * The graph correlator: resolves runtime evidence to descry-core graph
+ * nodes. Deliberately does not re-wrap graph-path building — `traceApi`
+ * (`@descryy/core`) already answers "how does this reach that" end to end,
+ * `direction: "both"` already crosses the `API_ENDPOINT` join with no extra
+ * option needed (DEC-228 traced this directly; `crossApiEndpoint` is only
+ * for `impactOf`'s single-direction walk). A caller resolves both ends here,
+ * then calls `traceApi` from `@descryy/core` directly — adding a wrapper
+ * around a function that already does the whole job would be an
+ * abstraction with nothing behind it.
+ */
+export { resolveEndpointNode, resolveEndpointNodesByPath } from "./endpoint.js";
+export { resolveSymbolNode, resolveSymbolAcrossRepos, resolveContainingModule, resolveTestCaseNode, } from "./symbol.js";
+export { resolveEndpointFromLogText, findEndpointMentions, } from "./log-endpoint.js";
+export { resolveFrontendCallers } from "./frontend-caller.js";
+export { resolveObservedFrontendCaller } from "./observed-frontend-caller.js";
+export { resolveDatabaseTableNode } from "./database-table.js";
+export { confirmObservedFrontendCaller, } from "./confirm-observed-caller.js";
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,EAAE,mBAAmB,EAAE,0BAA0B,EAA2B,MAAM,eAAe,CAAC;AACzG,OAAO,EACL,iBAAiB,EACjB,wBAAwB,EACxB,uBAAuB,EACvB,mBAAmB,GAKpB,MAAM,aAAa,CAAC;AACrB,OAAO,EACL,0BAA0B,EAC1B,oBAAoB,GAGrB,MAAM,mBAAmB,CAAC;AAC3B,OAAO,EAAE,sBAAsB,EAAiC,MAAM,sBAAsB,CAAC;AAC7F,OAAO,EAAE,6BAA6B,EAAyC,MAAM,+BAA+B,CAAC;AACrH,OAAO,EAAE,wBAAwB,EAAgC,MAAM,qBAAqB,CAAC;AAC7F,OAAO,EACL,6BAA6B,GAG9B,MAAM,8BAA8B,CAAC"}

package/dist/log-endpoint.d.ts

@@ -0,0 +1,67 @@
+/**
+ * Resolving the API endpoint a **backend log line names in its own text** to
+ * an `API_ENDPOINT` node.
+ *
+ * **Why this exists.** RT-044's measurement, re-run after RT-045, left
+ * `confirmed` blocked by one precisely-named thing: four evidence items
+ * share the real request id, but three of them are the same source
+ * (`browser-network`) and the fourth — the backend exception — resolves to
+ * the *function* that threw, via its stack. So no node has two independent
+ * sources in one request, and the top report category is unreachable in
+ * principle rather than merely unmet.
+ *
+ * The backend's own header line, measured from the real fixture, is:
+ *
+ * ```
+ * [broken-invoices] DELETE /api/invoices/3 failed [request-id=...]: TypeError: ...
+ * ```
+ *
+ * It names the endpoint. A browser saying "I sent DELETE /api/invoices/3"
+ * and a backend saying "I failed DELETE /api/invoices/3" are **two
+ * independent observations of one request from opposite sides of the wire**,
+ * joined by an id the backend itself echoed. That is corroboration in the
+ * exact sense the gate means, and missing it was a gap in resolution, not a
+ * property of the evidence.
+ *
+ * **What this deliberately does not do.** It does not scan for a bare path.
+ * A log line mentioning `/api/invoices/3` with no method is not a statement
+ * that *this* endpoint was exercised — `GET` and `DELETE` on one path are
+ * different endpoints, and `endpoint.ts` already refuses a method mismatch
+ * for exactly that reason. Requiring an explicit HTTP method in the text is
+ * what keeps this from becoming a substring search that resolves whatever
+ * happens to look familiar (RT-031's identity-proxy class, applied to prose).
+ */
+import type { SqlDriver } from "@descryy/core";
+export interface LogEndpointMention {
+    readonly method: string;
+    readonly path: string;
+}
+/** Every `METHOD /path` pair the text states, in order, deduplicated. Empty when the text names none — the common and correct case for an ordinary log line. */
+export declare function findEndpointMentions(text: string): readonly LogEndpointMention[];
+export type LogEndpointResolution = {
+    readonly outcome: "resolved";
+    readonly nodeId: string;
+    readonly mention: LogEndpointMention;
+} | {
+    readonly outcome: "no-mention";
+    readonly reason: string;
+} | {
+    readonly outcome: "ambiguous";
+    readonly reason: string;
+    readonly mentions: readonly LogEndpointMention[];
+} | {
+    readonly outcome: "not-found";
+    readonly reason: string;
+    readonly mentions: readonly LogEndpointMention[];
+};
+/**
+ * The endpoint a log line names, when it names exactly one that resolves.
+ *
+ * **Two mentions resolving to two different endpoints is refused, not
+ * ranked.** A line naming several routes (a proxy summary, a batch report)
+ * genuinely does not identify one, and picking the first would be a
+ * heuristic standing in for evidence. `endpoint.ts` refuses ambiguity to the
+ * caller and this inherits that rather than deciding differently.
+ */
+export declare function resolveEndpointFromLogText(driver: SqlDriver, text: string): LogEndpointResolution;
+//# sourceMappingURL=log-endpoint.d.ts.map

package/dist/log-endpoint.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"log-endpoint.d.ts","sourceRoot":"","sources":["../src/log-endpoint.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,eAAe,CAAC;AAY/C,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;CACvB;AAED,gKAAgK;AAChK,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,MAAM,GAAG,SAAS,kBAAkB,EAAE,CAchF;AAED,MAAM,MAAM,qBAAqB,GAC7B;IAAE,QAAQ,CAAC,OAAO,EAAE,UAAU,CAAC;IAAC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,OAAO,EAAE,kBAAkB,CAAA;CAAE,GAC/F;IAAE,QAAQ,CAAC,OAAO,EAAE,YAAY,CAAC;IAAC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;CAAE,GAC3D;IAAE,QAAQ,CAAC,OAAO,EAAE,WAAW,CAAC;IAAC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,QAAQ,EAAE,SAAS,kBAAkB,EAAE,CAAA;CAAE,GAC5G;IAAE,QAAQ,CAAC,OAAO,EAAE,WAAW,CAAC;IAAC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,QAAQ,EAAE,SAAS,kBAAkB,EAAE,CAAA;CAAE,CAAC;AAEjH;;;;;;;;GAQG;AACH,wBAAgB,0BAA0B,CAAC,MAAM,EAAE,SAAS,EAAE,IAAI,EAAE,MAAM,GAAG,qBAAqB,CA8BjG"}

package/dist/log-endpoint.js

@@ -0,0 +1,97 @@
+/**
+ * Resolving the API endpoint a **backend log line names in its own text** to
+ * an `API_ENDPOINT` node.
+ *
+ * **Why this exists.** RT-044's measurement, re-run after RT-045, left
+ * `confirmed` blocked by one precisely-named thing: four evidence items
+ * share the real request id, but three of them are the same source
+ * (`browser-network`) and the fourth — the backend exception — resolves to
+ * the *function* that threw, via its stack. So no node has two independent
+ * sources in one request, and the top report category is unreachable in
+ * principle rather than merely unmet.
+ *
+ * The backend's own header line, measured from the real fixture, is:
+ *
+ * ```
+ * [broken-invoices] DELETE /api/invoices/3 failed [request-id=...]: TypeError: ...
+ * ```
+ *
+ * It names the endpoint. A browser saying "I sent DELETE /api/invoices/3"
+ * and a backend saying "I failed DELETE /api/invoices/3" are **two
+ * independent observations of one request from opposite sides of the wire**,
+ * joined by an id the backend itself echoed. That is corroboration in the
+ * exact sense the gate means, and missing it was a gap in resolution, not a
+ * property of the evidence.
+ *
+ * **What this deliberately does not do.** It does not scan for a bare path.
+ * A log line mentioning `/api/invoices/3` with no method is not a statement
+ * that *this* endpoint was exercised — `GET` and `DELETE` on one path are
+ * different endpoints, and `endpoint.ts` already refuses a method mismatch
+ * for exactly that reason. Requiring an explicit HTTP method in the text is
+ * what keeps this from becoming a substring search that resolves whatever
+ * happens to look familiar (RT-031's identity-proxy class, applied to prose).
+ */
+import { resolveEndpointNode } from "./endpoint.js";
+/**
+ * `DELETE /api/invoices/3` anywhere in a line, method uppercase and
+ * standalone. The trailing character class stops at whitespace and at the
+ * punctuation that ordinarily follows a path in prose (`failed:`, `(404)`,
+ * `"..."`), so a real path is captured without swallowing the sentence.
+ */
+const METHOD_AND_PATH = /\b(GET|POST|PUT|PATCH|DELETE|HEAD|OPTIONS)\s+(\/[^\s"'(),;]*)/g;
+/** Every `METHOD /path` pair the text states, in order, deduplicated. Empty when the text names none — the common and correct case for an ordinary log line. */
+export function findEndpointMentions(text) {
+    const seen = new Set();
+    const mentions = [];
+    for (const match of text.matchAll(METHOD_AND_PATH)) {
+        const method = match[1] ?? "";
+        // A trailing '.' or ':' is sentence punctuation, not part of the path.
+        const path = (match[2] ?? "").replace(/[.:,;]+$/, "");
+        if (path === "")
+            continue;
+        const key = `${method} ${path}`;
+        if (seen.has(key))
+            continue;
+        seen.add(key);
+        mentions.push({ method, path });
+    }
+    return mentions;
+}
+/**
+ * The endpoint a log line names, when it names exactly one that resolves.
+ *
+ * **Two mentions resolving to two different endpoints is refused, not
+ * ranked.** A line naming several routes (a proxy summary, a batch report)
+ * genuinely does not identify one, and picking the first would be a
+ * heuristic standing in for evidence. `endpoint.ts` refuses ambiguity to the
+ * caller and this inherits that rather than deciding differently.
+ */
+export function resolveEndpointFromLogText(driver, text) {
+    const mentions = findEndpointMentions(text);
+    if (mentions.length === 0) {
+        return { outcome: "no-mention", reason: "The text states no `METHOD /path` pair. A bare path is not a statement that a particular endpoint was exercised." };
+    }
+    const resolved = [];
+    for (const mention of mentions) {
+        const resolution = resolveEndpointNode(driver, mention.method, mention.path);
+        if (resolution.outcome === "resolved")
+            resolved.push({ nodeId: resolution.node.id, mention });
+    }
+    if (resolved.length === 0) {
+        return {
+            outcome: "not-found",
+            reason: `The text names ${mentions.map((m) => `${m.method} ${m.path}`).join(", ")}, none of which resolves to an API_ENDPOINT in this graph.`,
+            mentions,
+        };
+    }
+    const distinctNodes = new Set(resolved.map((r) => r.nodeId));
+    if (distinctNodes.size > 1) {
+        return {
+            outcome: "ambiguous",
+            reason: `The text names ${distinctNodes.size} different endpoints that all resolve; a line naming several routes does not identify one, and picking the first would be a heuristic standing in for evidence.`,
+            mentions,
+        };
+    }
+    return { outcome: "resolved", nodeId: resolved[0].nodeId, mention: resolved[0].mention };
+}
+//# sourceMappingURL=log-endpoint.js.map

package/dist/log-endpoint.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"log-endpoint.js","sourceRoot":"","sources":["../src/log-endpoint.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AAIH,OAAO,EAAE,mBAAmB,EAA2B,MAAM,eAAe,CAAC;AAE7E;;;;;GAKG;AACH,MAAM,eAAe,GAAG,gEAAgE,CAAC;AAOzF,gKAAgK;AAChK,MAAM,UAAU,oBAAoB,CAAC,IAAY;IAC/C,MAAM,IAAI,GAAG,IAAI,GAAG,EAAU,CAAC;IAC/B,MAAM,QAAQ,GAAyB,EAAE,CAAC;IAC1C,KAAK,MAAM,KAAK,IAAI,IAAI,CAAC,QAAQ,CAAC,eAAe,CAAC,EAAE,CAAC;QACnD,MAAM,MAAM,GAAG,KAAK,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC;QAC9B,uEAAuE;QACvE,MAAM,IAAI,GAAG,CAAC,KAAK,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC,OAAO,CAAC,UAAU,EAAE,EAAE,CAAC,CAAC;QACtD,IAAI,IAAI,KAAK,EAAE;YAAE,SAAS;QAC1B,MAAM,GAAG,GAAG,GAAG,MAAM,IAAI,IAAI,EAAE,CAAC;QAChC,IAAI,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC;YAAE,SAAS;QAC5B,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;QACd,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,EAAE,IAAI,EAAE,CAAC,CAAC;IAClC,CAAC;IACD,OAAO,QAAQ,CAAC;AAClB,CAAC;AAQD;;;;;;;;GAQG;AACH,MAAM,UAAU,0BAA0B,CAAC,MAAiB,EAAE,IAAY;IACxE,MAAM,QAAQ,GAAG,oBAAoB,CAAC,IAAI,CAAC,CAAC;IAC5C,IAAI,QAAQ,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QAC1B,OAAO,EAAE,OAAO,EAAE,YAAY,EAAE,MAAM,EAAE,kHAAkH,EAAE,CAAC;IAC/J,CAAC;IAED,MAAM,QAAQ,GAAsD,EAAE,CAAC;IACvE,KAAK,MAAM,OAAO,IAAI,QAAQ,EAAE,CAAC;QAC/B,MAAM,UAAU,GAAuB,mBAAmB,CAAC,MAAM,EAAE,OAAO,CAAC,MAAM,EAAE,OAAO,CAAC,IAAI,CAAC,CAAC;QACjG,IAAI,UAAU,CAAC,OAAO,KAAK,UAAU;YAAE,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,EAAE,UAAU,CAAC,IAAI,CAAC,EAAE,EAAE,OAAO,EAAE,CAAC,CAAC;IAChG,CAAC;IAED,IAAI,QAAQ,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QAC1B,OAAO;YACL,OAAO,EAAE,WAAW;YACpB,MAAM,EAAE,kBAAkB,QAAQ,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,GAAG,CAAC,CAAC,MAAM,IAAI,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,4DAA4D;YAC7I,QAAQ;SACT,CAAC;IACJ,CAAC;IAED,MAAM,aAAa,GAAG,IAAI,GAAG,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC;IAC7D,IAAI,aAAa,CAAC,IAAI,GAAG,CAAC,EAAE,CAAC;QAC3B,OAAO;YACL,OAAO,EAAE,WAAW;YACpB,MAAM,EAAE,kBAAkB,aAAa,CAAC,IAAI,iKAAiK;YAC7M,QAAQ;SACT,CAAC;IACJ,CAAC;IAED,OAAO,EAAE,OAAO,EAAE,UAAU,EAAE,MAAM,EAAE,QAAQ,CAAC,CAAC,CAAE,CAAC,MAAM,EAAE,OAAO,EAAE,QAAQ,CAAC,CAAC,CAAE,CAAC,OAAO,EAAE,CAAC;AAC7F,CAAC"}

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

@@ -0,0 +1,70 @@
+/**
+ * The **observed** half of `frontend-caller.ts`'s deliberately structural
+ * answer — closing the gap that file's own doc comment names: "Playwright
+ * exposes an initiator chain that could narrow it; the network collector
+ * does not capture it today."
+ *
+ * `@descryhq-wq/runtime-browser`'s `frontend-initiator-capture.ts` now captures
+ * a real call-site stack for a `fetch()` request and attaches it to that
+ * request's `NETWORK_REQUEST` evidence. This file is what joins that stack
+ * to the graph: it resolves the stack's own site of interest
+ * (`primaryFrameLocation`, the identical rule every other stack-to-evidence
+ * join in this codebase already uses) to a `FUNCTION` node via
+ * `resolveSymbolNode`, and checks it against `resolveFrontendCallers`'s own
+ * structural candidate set for the endpoint in question.
+ *
+ * **Additive, not a replacement.** `resolveFrontendCallers` is untouched —
+ * every existing caller of it keeps exactly the outcomes it already had.
+ * This function calls it internally and only ever *adds* two outcomes on
+ * top: `observed`, when the stack resolves to a node the structural side
+ * already named as a candidate, and `structural-observed-conflict`, when it
+ * resolves to a real node the structural side did not name at all. Outside
+ * both — no stack, an unresolvable frame, an ambiguous or missing symbol —
+ * this returns exactly what `resolveFrontendCallers` alone would have, so
+ * every existing refusal discipline (`sole-structural-caller`, `ambiguous`,
+ * `not-found`) stands unchanged.
+ *
+ * **A disagreement is reported, never adjudicated.** When the resolved node
+ * is real but not among the structural candidates, that is the graph and
+ * the observation disagreeing — possibly because `USES_API` extraction
+ * missed a real call site (a dynamic call, a wrapper the adapter does not
+ * recognise), possibly because the resolved frame is itself wrong in some
+ * way this function cannot see. Both are worth a reader's attention;
+ * neither is silently preferred over the other. This is evidence detail
+ * within whichever of this project's five report categories the caller's
+ * own claim already lands in — not a sixth category, and not decided here.
+ */
+import type { IRNode } from "@descryy/ir";
+import type { SqlDriver } from "@descryy/core";
+import { type StackTrace } from "@descryy/runtime-contracts";
+import { type FrontendCallerResolution } from "./frontend-caller.ts";
+export type ObservedFrontendCallerResolution = FrontendCallerResolution | {
+    /** A real captured call-site stack resolved to a node the structural side already named for this endpoint. The genuinely observed answer, not the sole candidate the source admits. */
+    readonly outcome: "observed";
+    readonly node: IRNode;
+    /** Every structural candidate this observation was checked against, for audit — including when it is a single-element `sole-structural-caller` list. */
+    readonly structuralCandidates: readonly IRNode[];
+    readonly reason: string;
+} | {
+    /** A real captured call-site stack resolved to a real node, and that node is NOT among the structural candidates (possibly none at all) for this endpoint. */
+    readonly outcome: "structural-observed-conflict";
+    readonly structuralCandidates: readonly IRNode[];
+    readonly observedNode: IRNode;
+    readonly reason: string;
+};
+/**
+ * `stackTrace` is exactly `NETWORK_REQUEST.stackTrace` off the observed
+ * request that hit `endpointNodeId` — `null` whenever the collector could
+ * not attach one (no parser wired, header stripped in transit, nothing
+ * buffered for the id), which this function treats identically to "no
+ * observation was ever attempted": the structural answer, unchanged.
+ *
+ * `repo`/`repoRoot` are `resolveSymbolNode`'s own — the frontend repository
+ * the observed stack's frames are expected to belong to, since `FUNCTION`
+ * is repo-scoped and there is no honest default for it (see `symbol.ts`'s
+ * own doc comment).
+ */
+export declare function resolveObservedFrontendCaller(driver: SqlDriver, endpointNodeId: string, stackTrace: StackTrace | null, repo: string, options?: {
+    readonly repoRoot?: string;
+}): ObservedFrontendCallerResolution;
+//# sourceMappingURL=observed-frontend-caller.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"observed-frontend-caller.d.ts","sourceRoot":"","sources":["../src/observed-frontend-caller.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;AAEH,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AAC1C,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,eAAe,CAAC;AAC/C,OAAO,EAAwB,KAAK,UAAU,EAAE,MAAM,4BAA4B,CAAC;AAEnF,OAAO,EAA0B,KAAK,wBAAwB,EAAE,MAAM,sBAAsB,CAAC;AAG7F,MAAM,MAAM,gCAAgC,GACxC,wBAAwB,GACxB;IACE,uLAAuL;IACvL,QAAQ,CAAC,OAAO,EAAE,UAAU,CAAC;IAC7B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,wJAAwJ;IACxJ,QAAQ,CAAC,oBAAoB,EAAE,SAAS,MAAM,EAAE,CAAC;IACjD,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;CACzB,GACD;IACE,8JAA8J;IAC9J,QAAQ,CAAC,OAAO,EAAE,8BAA8B,CAAC;IACjD,QAAQ,CAAC,oBAAoB,EAAE,SAAS,MAAM,EAAE,CAAC;IACjD,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;CACzB,CAAC;AAQN;;;;;;;;;;;GAWG;AACH,wBAAgB,6BAA6B,CAC3C,MAAM,EAAE,SAAS,EACjB,cAAc,EAAE,MAAM,EACtB,UAAU,EAAE,UAAU,GAAG,IAAI,EAC7B,IAAI,EAAE,MAAM,EACZ,OAAO,GAAE;IAAE,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAA;CAAO,GAC3C,gCAAgC,CAwDlC"}

package/dist/observed-frontend-caller.js

@@ -0,0 +1,103 @@
+/**
+ * The **observed** half of `frontend-caller.ts`'s deliberately structural
+ * answer — closing the gap that file's own doc comment names: "Playwright
+ * exposes an initiator chain that could narrow it; the network collector
+ * does not capture it today."
+ *
+ * `@descryhq-wq/runtime-browser`'s `frontend-initiator-capture.ts` now captures
+ * a real call-site stack for a `fetch()` request and attaches it to that
+ * request's `NETWORK_REQUEST` evidence. This file is what joins that stack
+ * to the graph: it resolves the stack's own site of interest
+ * (`primaryFrameLocation`, the identical rule every other stack-to-evidence
+ * join in this codebase already uses) to a `FUNCTION` node via
+ * `resolveSymbolNode`, and checks it against `resolveFrontendCallers`'s own
+ * structural candidate set for the endpoint in question.
+ *
+ * **Additive, not a replacement.** `resolveFrontendCallers` is untouched —
+ * every existing caller of it keeps exactly the outcomes it already had.
+ * This function calls it internally and only ever *adds* two outcomes on
+ * top: `observed`, when the stack resolves to a node the structural side
+ * already named as a candidate, and `structural-observed-conflict`, when it
+ * resolves to a real node the structural side did not name at all. Outside
+ * both — no stack, an unresolvable frame, an ambiguous or missing symbol —
+ * this returns exactly what `resolveFrontendCallers` alone would have, so
+ * every existing refusal discipline (`sole-structural-caller`, `ambiguous`,
+ * `not-found`) stands unchanged.
+ *
+ * **A disagreement is reported, never adjudicated.** When the resolved node
+ * is real but not among the structural candidates, that is the graph and
+ * the observation disagreeing — possibly because `USES_API` extraction
+ * missed a real call site (a dynamic call, a wrapper the adapter does not
+ * recognise), possibly because the resolved frame is itself wrong in some
+ * way this function cannot see. Both are worth a reader's attention;
+ * neither is silently preferred over the other. This is evidence detail
+ * within whichever of this project's five report categories the caller's
+ * own claim already lands in — not a sixth category, and not decided here.
+ */
+import { primaryFrameLocation } from "@descryy/runtime-contracts";
+import { resolveFrontendCallers } from "./frontend-caller.js";
+import { resolveSymbolNode } from "./symbol.js";
+function structuralCandidatesOf(structural) {
+    if (structural.outcome === "sole-structural-caller")
+        return [structural.node];
+    if (structural.outcome === "ambiguous")
+        return structural.candidates;
+    return [];
+}
+/**
+ * `stackTrace` is exactly `NETWORK_REQUEST.stackTrace` off the observed
+ * request that hit `endpointNodeId` — `null` whenever the collector could
+ * not attach one (no parser wired, header stripped in transit, nothing
+ * buffered for the id), which this function treats identically to "no
+ * observation was ever attempted": the structural answer, unchanged.
+ *
+ * `repo`/`repoRoot` are `resolveSymbolNode`'s own — the frontend repository
+ * the observed stack's frames are expected to belong to, since `FUNCTION`
+ * is repo-scoped and there is no honest default for it (see `symbol.ts`'s
+ * own doc comment).
+ */
+export function resolveObservedFrontendCaller(driver, endpointNodeId, stackTrace, repo, options = {}) {
+    const structural = resolveFrontendCallers(driver, endpointNodeId);
+    const location = primaryFrameLocation(stackTrace);
+    // No stack, an empty stack, or one whose site of interest names nothing
+    // (a native/anonymous frame, or one this parser could not symbolicate at
+    // all) -- resolveSymbolNode has no name to search for either way, so the
+    // observation adds nothing usable. Same "no id, no functionName" fallback
+    // `resolveInitiatorStack` on the collector side already degrades to.
+    if (location === null || location.file === null || location.functionName === null) {
+        return structural;
+    }
+    const resolved = resolveSymbolNode(driver, location.line === null
+        ? { file: location.file, symbolName: location.functionName }
+        : { file: location.file, symbolName: location.functionName, line: location.line }, repo, options);
+    // Unresolved, ambiguous, or a line that does not fall inside the matched
+    // node's range: none of those is "the observed function", so none of
+    // them can upgrade or conflict with the structural claim. The existing
+    // structural-only outcome stands -- this function never invents a
+    // caller resolveSymbolNode itself refused to name.
+    if (resolved.outcome !== "resolved") {
+        return structural;
+    }
+    const structuralCandidates = structuralCandidatesOf(structural);
+    const isStructuralCandidate = structuralCandidates.some((candidate) => candidate.id === resolved.node.id);
+    if (isStructuralCandidate) {
+        return {
+            outcome: "observed",
+            node: resolved.node,
+            structuralCandidates,
+            reason: `"${resolved.node.name}" was resolved from a real call-site stack captured on the observed request, and it is ` +
+                `among the function(s) the graph's USES_API edge${structuralCandidates.length > 1 ? "s name" : " names"} for ` +
+                "this endpoint -- a genuinely observed answer, not the sole candidate the source admits.",
+        };
+    }
+    return {
+        outcome: "structural-observed-conflict",
+        structuralCandidates,
+        observedNode: resolved.node,
+        reason: `The observed request's call-site stack resolved to "${resolved.node.name}", which is NOT among the ` +
+            `function(s) the graph's USES_API edges name for this endpoint (${structuralCandidates.map((n) => n.name).join(", ") || "none"}). ` +
+            "This is a real disagreement between the static graph and what was actually observed -- reported as a " +
+            "conflict rather than silently trusted or discarded in either direction.",
+    };
+}
+//# sourceMappingURL=observed-frontend-caller.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"observed-frontend-caller.js","sourceRoot":"","sources":["../src/observed-frontend-caller.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;AAIH,OAAO,EAAE,oBAAoB,EAAmB,MAAM,4BAA4B,CAAC;AAEnF,OAAO,EAAE,sBAAsB,EAAiC,MAAM,sBAAsB,CAAC;AAC7F,OAAO,EAAE,iBAAiB,EAAE,MAAM,aAAa,CAAC;AAoBhD,SAAS,sBAAsB,CAAC,UAAoC;IAClE,IAAI,UAAU,CAAC,OAAO,KAAK,wBAAwB;QAAE,OAAO,CAAC,UAAU,CAAC,IAAI,CAAC,CAAC;IAC9E,IAAI,UAAU,CAAC,OAAO,KAAK,WAAW;QAAE,OAAO,UAAU,CAAC,UAAU,CAAC;IACrE,OAAO,EAAE,CAAC;AACZ,CAAC;AAED;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,6BAA6B,CAC3C,MAAiB,EACjB,cAAsB,EACtB,UAA6B,EAC7B,IAAY,EACZ,UAA0C,EAAE;IAE5C,MAAM,UAAU,GAAG,sBAAsB,CAAC,MAAM,EAAE,cAAc,CAAC,CAAC;IAElE,MAAM,QAAQ,GAAG,oBAAoB,CAAC,UAAU,CAAC,CAAC;IAClD,wEAAwE;IACxE,yEAAyE;IACzE,yEAAyE;IACzE,0EAA0E;IAC1E,qEAAqE;IACrE,IAAI,QAAQ,KAAK,IAAI,IAAI,QAAQ,CAAC,IAAI,KAAK,IAAI,IAAI,QAAQ,CAAC,YAAY,KAAK,IAAI,EAAE,CAAC;QAClF,OAAO,UAAU,CAAC;IACpB,CAAC;IAED,MAAM,QAAQ,GAAG,iBAAiB,CAChC,MAAM,EACN,QAAQ,CAAC,IAAI,KAAK,IAAI;QACpB,CAAC,CAAC,EAAE,IAAI,EAAE,QAAQ,CAAC,IAAI,EAAE,UAAU,EAAE,QAAQ,CAAC,YAAY,EAAE;QAC5D,CAAC,CAAC,EAAE,IAAI,EAAE,QAAQ,CAAC,IAAI,EAAE,UAAU,EAAE,QAAQ,CAAC,YAAY,EAAE,IAAI,EAAE,QAAQ,CAAC,IAAI,EAAE,EACnF,IAAI,EACJ,OAAO,CACR,CAAC;IAEF,yEAAyE;IACzE,qEAAqE;IACrE,uEAAuE;IACvE,kEAAkE;IAClE,mDAAmD;IACnD,IAAI,QAAQ,CAAC,OAAO,KAAK,UAAU,EAAE,CAAC;QACpC,OAAO,UAAU,CAAC;IACpB,CAAC;IAED,MAAM,oBAAoB,GAAG,sBAAsB,CAAC,UAAU,CAAC,CAAC;IAChE,MAAM,qBAAqB,GAAG,oBAAoB,CAAC,IAAI,CAAC,CAAC,SAAS,EAAE,EAAE,CAAC,SAAS,CAAC,EAAE,KAAK,QAAQ,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;IAE1G,IAAI,qBAAqB,EAAE,CAAC;QAC1B,OAAO;YACL,OAAO,EAAE,UAAU;YACnB,IAAI,EAAE,QAAQ,CAAC,IAAI;YACnB,oBAAoB;YACpB,MAAM,EACJ,IAAI,QAAQ,CAAC,IAAI,CAAC,IAAI,yFAAyF;gBAC/G,kDAAkD,oBAAoB,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,QAAQ,OAAO;gBAC9G,yFAAyF;SAC5F,CAAC;IACJ,CAAC;IAED,OAAO;QACL,OAAO,EAAE,8BAA8B;QACvC,oBAAoB;QACpB,YAAY,EAAE,QAAQ,CAAC,IAAI;QAC3B,MAAM,EACJ,uDAAuD,QAAQ,CAAC,IAAI,CAAC,IAAI,4BAA4B;YACrG,kEAAkE,oBAAoB,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,MAAM,KAAK;YACnI,uGAAuG;YACvG,yEAAyE;KAC5E,CAAC;AACJ,CAAC"}