@descryy/runtime-external-service-observation 0.1.0

package/dist/collector-version.d.ts

@@ -0,0 +1,10 @@
+/**
+ * `Evidence.collectorVersion`'s source for every collector in this package:
+ * this package's own `package.json` "version", read from the artifact
+ * itself rather than hand-duplicated into a second string that can drift
+ * from what actually shipped. Same idea as `nodeVersion` elsewhere in this
+ * repo (`process.version`, always known, never probed) applied to a
+ * package instead of the Node runtime.
+ */
+export declare const COLLECTOR_VERSION: string;
+//# sourceMappingURL=collector-version.d.ts.map

package/dist/collector-version.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"collector-version.d.ts","sourceRoot":"","sources":["../src/collector-version.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAMH,eAAO,MAAM,iBAAiB,EAAE,MAA6E,CAAC"}

package/dist/collector-version.js

@@ -0,0 +1,12 @@
+/**
+ * `Evidence.collectorVersion`'s source for every collector in this package:
+ * this package's own `package.json` "version", read from the artifact
+ * itself rather than hand-duplicated into a second string that can drift
+ * from what actually shipped. Same idea as `nodeVersion` elsewhere in this
+ * repo (`process.version`, always known, never probed) applied to a
+ * package instead of the Node runtime.
+ */
+import { createRequire } from "node:module";
+const require = createRequire(import.meta.url);
+export const COLLECTOR_VERSION = require("../package.json").version;
+//# sourceMappingURL=collector-version.js.map

package/dist/collector-version.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"collector-version.js","sourceRoot":"","sources":["../src/collector-version.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAE5C,MAAM,OAAO,GAAG,aAAa,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;AAE/C,MAAM,CAAC,MAAM,iBAAiB,GAAY,OAAO,CAAC,iBAAiB,CAAkC,CAAC,OAAO,CAAC"}

package/dist/fetch-instrumentation.d.ts

@@ -0,0 +1,61 @@
+/**
+ * `--import`-loaded preload: patches `globalThis.fetch` before the target
+ * application's own code runs, so every real outbound call the application
+ * issues through the bare global `fetch` is observed — proven directly (a
+ * probe script, not assumed): Node's global `fetch` is a single, mutable
+ * binding on `globalThis`, so a `--import` preload reassigning it here and
+ * an application's completely independent, later call to bare `fetch(...)`
+ * resolve to the same function. Same singleton-timing argument
+ * `sqlite-instrumentation.ts` (`@descryy/runtime-database-observation`,
+ * RT-141) already established for `node:sqlite`'s prototype, applied to a
+ * different kind of global.
+ *
+ * **Read, not write.** The wrapper calls the original `fetch` with the
+ * exact, untouched arguments it received — nothing about what leaves the
+ * process changes. Request/response bodies are never read here: `status`
+ * comes off the resolved `Response` before any body access, and describing
+ * the outbound request (`method`/`url`/headers) is done via the same
+ * `Request`/`Headers` normalisation `fetch` itself would do, on a
+ * side channel, not by touching the body stream passed to the real call.
+ *
+ * Deliberately minimal and import-free, like `sqlite-instrumentation.ts` and
+ * `test-runner`'s own `reporter.ts` — this runs inside the OBSERVED process,
+ * loaded by absolute path via `node --import`, never through this package's
+ * normal dependency graph. Interpretation (service identity, correlation
+ * ids) happens on the collector side, in the observing process, not here —
+ * this only captures.
+ *
+ * **The call-site stack is captured here and nowhere else.** It is the one
+ * fact only this process can supply: by the time the marker line reaches a
+ * collector it is text on a pipe, which is exactly why
+ * `ExternalRequestCollector` reported `stackTrace: null` for as long as this
+ * preload captured none. `observe_runtime`'s own header records the
+ * consequence — a backend-only run "resolves both kinds of node and writes no
+ * edge", because an edge needs a caller and an endpoint named by ONE
+ * observation and this one named only the endpoint. Capturing the stack at
+ * the call site is what makes an outbound call able to name its own caller.
+ *
+ * Raw text, deliberately unparsed. Parsing V8's format is
+ * `@descryy/runtime-adapter-typescript`'s job and belongs in the observing
+ * process, the same read-here/interpret-there split every marker in this
+ * repository already uses.
+ *
+ * The cost, stated rather than discovered: `new Error()` on every outbound
+ * call. That is a stack capture per request in a process that has opted into
+ * being observed by loading this preload; `Error.stackTraceLimit` is left
+ * exactly as the application set it, because raising it would be this file
+ * writing to the observed process's own configuration, which the paragraph
+ * above forbids.
+ *
+ * The marker prefix and the captured shape live in `request-marker.ts`, not
+ * here: this module has a module-scope effect and nothing that merely needs
+ * the vocabulary may be made to import it. See that file for the measurement
+ * behind that rule.
+ *
+ * One line of structured JSON per request, prefixed exactly like
+ * `sqlite-instrumentation.ts`'s own `DESCRY_DB_QUERY {json}` convention,
+ * itself following the benchmark harness's `BENCH_RESULT {json}` precedent
+ * (RT-072): scraping prose measures the prose, so nothing here is prose.
+ */
+export {};
+//# sourceMappingURL=fetch-instrumentation.d.ts.map

package/dist/fetch-instrumentation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"fetch-instrumentation.d.ts","sourceRoot":"","sources":["../src/fetch-instrumentation.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA0DG"}

package/dist/fetch-instrumentation.js

@@ -0,0 +1,137 @@
+/**
+ * `--import`-loaded preload: patches `globalThis.fetch` before the target
+ * application's own code runs, so every real outbound call the application
+ * issues through the bare global `fetch` is observed — proven directly (a
+ * probe script, not assumed): Node's global `fetch` is a single, mutable
+ * binding on `globalThis`, so a `--import` preload reassigning it here and
+ * an application's completely independent, later call to bare `fetch(...)`
+ * resolve to the same function. Same singleton-timing argument
+ * `sqlite-instrumentation.ts` (`@descryy/runtime-database-observation`,
+ * RT-141) already established for `node:sqlite`'s prototype, applied to a
+ * different kind of global.
+ *
+ * **Read, not write.** The wrapper calls the original `fetch` with the
+ * exact, untouched arguments it received — nothing about what leaves the
+ * process changes. Request/response bodies are never read here: `status`
+ * comes off the resolved `Response` before any body access, and describing
+ * the outbound request (`method`/`url`/headers) is done via the same
+ * `Request`/`Headers` normalisation `fetch` itself would do, on a
+ * side channel, not by touching the body stream passed to the real call.
+ *
+ * Deliberately minimal and import-free, like `sqlite-instrumentation.ts` and
+ * `test-runner`'s own `reporter.ts` — this runs inside the OBSERVED process,
+ * loaded by absolute path via `node --import`, never through this package's
+ * normal dependency graph. Interpretation (service identity, correlation
+ * ids) happens on the collector side, in the observing process, not here —
+ * this only captures.
+ *
+ * **The call-site stack is captured here and nowhere else.** It is the one
+ * fact only this process can supply: by the time the marker line reaches a
+ * collector it is text on a pipe, which is exactly why
+ * `ExternalRequestCollector` reported `stackTrace: null` for as long as this
+ * preload captured none. `observe_runtime`'s own header records the
+ * consequence — a backend-only run "resolves both kinds of node and writes no
+ * edge", because an edge needs a caller and an endpoint named by ONE
+ * observation and this one named only the endpoint. Capturing the stack at
+ * the call site is what makes an outbound call able to name its own caller.
+ *
+ * Raw text, deliberately unparsed. Parsing V8's format is
+ * `@descryy/runtime-adapter-typescript`'s job and belongs in the observing
+ * process, the same read-here/interpret-there split every marker in this
+ * repository already uses.
+ *
+ * The cost, stated rather than discovered: `new Error()` on every outbound
+ * call. That is a stack capture per request in a process that has opted into
+ * being observed by loading this preload; `Error.stackTraceLimit` is left
+ * exactly as the application set it, because raising it would be this file
+ * writing to the observed process's own configuration, which the paragraph
+ * above forbids.
+ *
+ * The marker prefix and the captured shape live in `request-marker.ts`, not
+ * here: this module has a module-scope effect and nothing that merely needs
+ * the vocabulary may be made to import it. See that file for the measurement
+ * behind that rule.
+ *
+ * One line of structured JSON per request, prefixed exactly like
+ * `sqlite-instrumentation.ts`'s own `DESCRY_DB_QUERY {json}` convention,
+ * itself following the benchmark harness's `BENCH_RESULT {json}` precedent
+ * (RT-072): scraping prose measures the prose, so nothing here is prose.
+ */
+import { REQUEST_MARKER } from "./request-marker.js";
+/** This module's own location, in both shapes a V8 frame can print it: an ESM frame stringifies a `file://` URL, a CJS one a plain path. */
+const SELF_URL = import.meta.url;
+const SELF_PATH = SELF_URL.startsWith("file://") ? SELF_URL.slice("file://".length) : SELF_URL;
+/**
+ * Frames belonging to this file are dropped **by file, not by count**.
+ * `primaryFrameIndex` is 0 for every V8 stack this project parses, so a
+ * single surviving wrapper frame would make every downstream resolution
+ * point at the instrumentation instead of at the code under observation --
+ * a failure that produces confident, well-formed, entirely wrong answers
+ * rather than an error. Matching on `import.meta.url` also survives this
+ * module being loaded from `.js` (the compiled preload, how it actually
+ * runs) or `.ts` (type stripping, how a test may run it).
+ */
+function callSiteStack() {
+    const raw = new Error().stack;
+    if (raw === undefined)
+        return null;
+    const lines = raw.split("\n");
+    const header = lines[0] ?? "Error";
+    const frames = lines.slice(1).filter((line) => !line.includes(SELF_URL) && !line.includes(SELF_PATH));
+    // Nothing but our own frames: no application call site was captured, which
+    // is `null` rather than a header line pretending to be a stack.
+    if (frames.length === 0)
+        return null;
+    return [header, ...frames].join("\n");
+}
+function emit(request) {
+    process.stdout.write(`${REQUEST_MARKER} ${JSON.stringify(request)}\n`);
+}
+function headersToObject(headers) {
+    const out = {};
+    for (const [name, value] of headers.entries())
+        out[name] = value;
+    return out;
+}
+/**
+ * `url`/`method`/`requestHeaders` off the call's own arguments, without
+ * touching the body -- a `Request` object already carries these structured;
+ * a `(input, init)` pair is normalised the same way `fetch` itself would,
+ * via the real `Headers` constructor rather than hand-parsed.
+ */
+function describeRequest(input, init) {
+    if (input instanceof Request) {
+        return { url: input.url, method: input.method, requestHeaders: headersToObject(input.headers) };
+    }
+    const url = typeof input === "string" ? input : input.toString();
+    const method = (init?.method ?? "GET").toUpperCase();
+    return { url, method, requestHeaders: headersToObject(new Headers(init?.headers)) };
+}
+// Guards against double-patching if this module is somehow loaded twice
+// (e.g. both `--import` and a transitive re-import) -- the second pass
+// would otherwise wrap an already-wrapped fetch and double-emit. Same
+// guard shape as sqlite-instrumentation.ts's own PATCHED symbol.
+const PATCHED = Symbol.for("descry.external-service-observation.fetch-patched");
+const target = globalThis;
+if (target[PATCHED] !== true) {
+    target[PATCHED] = true;
+    const original = globalThis.fetch;
+    globalThis.fetch = async function patchedFetch(input, init) {
+        const described = describeRequest(input, init);
+        // Captured BEFORE the call, not in the handlers below: after `await` the
+        // application's own frames are gone from the stack.
+        const stack = callSiteStack();
+        const start = performance.now();
+        try {
+            const response = await original(input, init);
+            emit({ ...described, status: response.status, durationMs: performance.now() - start, success: true, error: null, stack });
+            return response;
+        }
+        catch (error) {
+            const detail = error instanceof Error ? `${error.name}: ${error.message}` : String(error);
+            emit({ ...described, status: null, durationMs: performance.now() - start, success: false, error: detail, stack });
+            throw error;
+        }
+    };
+}
+//# sourceMappingURL=fetch-instrumentation.js.map

package/dist/fetch-instrumentation.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"fetch-instrumentation.js","sourceRoot":"","sources":["../src/fetch-instrumentation.ts"],"names":[],"mappings":"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"}

package/dist/header-correlation.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Correlation-id extraction from real HTTP headers — the same mechanism and
+ * the same closed set of header names as `extractHeaderCorrelationIds`
+ * (`@descryhq-wq/runtime-browser`'s `network-correlation.ts`).
+ *
+ * **Duplicated on purpose, not imported.** `browser` depends on Playwright
+ * to launch and drive a real browser — a real, heavy dependency this
+ * package has no other reason to carry, for a page-automation concern
+ * entirely unrelated to instrumenting a backend process's own outbound
+ * `fetch`. The function itself is small, pure, and reads a closed,
+ * unlikely-to-change set of conventional header names — the case this
+ * project's own `symbol.ts` distinguishes from (`toRepoRelative` is
+ * *shared* because its two callers must translate identically); these two
+ * copies have no such constraint, and importing across a Playwright
+ * dependency to avoid ten lines would be the worse coupling.
+ */
+export interface HeaderCorrelationIds {
+    readonly traceId: string | null;
+    readonly requestId: string | null;
+}
+export declare function extractHeaderCorrelationIds(headers: Readonly<Record<string, string>>): HeaderCorrelationIds;
+//# sourceMappingURL=header-correlation.d.ts.map

package/dist/header-correlation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"header-correlation.d.ts","sourceRoot":"","sources":["../src/header-correlation.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAIH,MAAM,WAAW,oBAAoB;IACnC,QAAQ,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IAChC,QAAQ,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;CACnC;AAUD,wBAAgB,2BAA2B,CAAC,OAAO,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,GAAG,oBAAoB,CAS3G"}

package/dist/header-correlation.js

@@ -0,0 +1,35 @@
+/**
+ * Correlation-id extraction from real HTTP headers — the same mechanism and
+ * the same closed set of header names as `extractHeaderCorrelationIds`
+ * (`@descryhq-wq/runtime-browser`'s `network-correlation.ts`).
+ *
+ * **Duplicated on purpose, not imported.** `browser` depends on Playwright
+ * to launch and drive a real browser — a real, heavy dependency this
+ * package has no other reason to carry, for a page-automation concern
+ * entirely unrelated to instrumenting a backend process's own outbound
+ * `fetch`. The function itself is small, pure, and reads a closed,
+ * unlikely-to-change set of conventional header names — the case this
+ * project's own `symbol.ts` distinguishes from (`toRepoRelative` is
+ * *shared* because its two callers must translate identically); these two
+ * copies have no such constraint, and importing across a Playwright
+ * dependency to avoid ten lines would be the worse coupling.
+ */
+const TRACEPARENT_PATTERN = /^([0-9a-f]{2})-([0-9a-f]{32})-([0-9a-f]{16})-([0-9a-f]{2})$/i;
+function firstHeader(headers, names) {
+    for (const name of names) {
+        const value = headers[name];
+        if (value !== undefined && value.length > 0)
+            return value;
+    }
+    return null;
+}
+export function extractHeaderCorrelationIds(headers) {
+    const explicitTraceId = firstHeader(headers, ["x-trace-id", "trace-id"]);
+    const traceparent = headers["traceparent"];
+    const w3cTraceId = traceparent !== undefined ? (TRACEPARENT_PATTERN.exec(traceparent)?.[2] ?? null) : null;
+    return {
+        traceId: explicitTraceId ?? w3cTraceId,
+        requestId: firstHeader(headers, ["x-request-id", "request-id"]),
+    };
+}
+//# sourceMappingURL=header-correlation.js.map

package/dist/header-correlation.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"header-correlation.js","sourceRoot":"","sources":["../src/header-correlation.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,MAAM,mBAAmB,GAAG,8DAA8D,CAAC;AAO3F,SAAS,WAAW,CAAC,OAAyC,EAAE,KAAwB;IACtF,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;QACzB,MAAM,KAAK,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;QAC5B,IAAI,KAAK,KAAK,SAAS,IAAI,KAAK,CAAC,MAAM,GAAG,CAAC;YAAE,OAAO,KAAK,CAAC;IAC5D,CAAC;IACD,OAAO,IAAI,CAAC;AACd,CAAC;AAED,MAAM,UAAU,2BAA2B,CAAC,OAAyC;IACnF,MAAM,eAAe,GAAG,WAAW,CAAC,OAAO,EAAE,CAAC,YAAY,EAAE,UAAU,CAAC,CAAC,CAAC;IACzE,MAAM,WAAW,GAAG,OAAO,CAAC,aAAa,CAAC,CAAC;IAC3C,MAAM,UAAU,GAAG,WAAW,KAAK,SAAS,CAAC,CAAC,CAAC,CAAC,mBAAmB,CAAC,IAAI,CAAC,WAAW,CAAC,EAAE,CAAC,CAAC,CAAC,IAAI,IAAI,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC;IAE3G,OAAO;QACL,OAAO,EAAE,eAAe,IAAI,UAAU;QACtC,SAAS,EAAE,WAAW,CAAC,OAAO,EAAE,CAAC,cAAc,EAAE,YAAY,CAAC,CAAC;KAChE,CAAC;AACJ,CAAC"}

package/dist/index.d.ts

@@ -0,0 +1,7 @@
+export { REQUEST_MARKER, type CapturedRequest } from "./request-marker.ts";
+export { parseRequestLine } from "./request-line-parser.ts";
+export { extractServiceIdentity } from "./service-identity.ts";
+export { extractHeaderCorrelationIds, type HeaderCorrelationIds } from "./header-correlation.ts";
+export type { ExternalRequestCollectorOptions } from "./request-collector.ts";
+export { createExternalRequestCollector, FETCH_PRELOAD_MODULE_PATH } from "./request-collector.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":"AAMA,OAAO,EAAE,cAAc,EAAE,KAAK,eAAe,EAAE,MAAM,qBAAqB,CAAC;AAC3E,OAAO,EAAE,gBAAgB,EAAE,MAAM,0BAA0B,CAAC;AAC5D,OAAO,EAAE,sBAAsB,EAAE,MAAM,uBAAuB,CAAC;AAC/D,OAAO,EAAE,2BAA2B,EAAE,KAAK,oBAAoB,EAAE,MAAM,yBAAyB,CAAC;AAEjG,YAAY,EAAE,+BAA+B,EAAE,MAAM,wBAAwB,CAAC;AAC9E,OAAO,EAAE,8BAA8B,EAAE,yBAAyB,EAAE,MAAM,wBAAwB,CAAC"}

package/dist/index.js

@@ -0,0 +1,12 @@
+// Deliberately NOT from `fetch-instrumentation.ts`: that module replaces
+// `globalThis.fetch` at module scope, and re-exporting a constant out of it
+// put that patch into every consumer of this package -- `query-marker.ts`'s
+// measured defect, which this package still had. The preload is loaded by
+// absolute path via `node --import`, inside the observed process, never
+// through this dependency graph.
+export { REQUEST_MARKER } from "./request-marker.js";
+export { parseRequestLine } from "./request-line-parser.js";
+export { extractServiceIdentity } from "./service-identity.js";
+export { extractHeaderCorrelationIds } from "./header-correlation.js";
+export { createExternalRequestCollector, FETCH_PRELOAD_MODULE_PATH } from "./request-collector.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,yEAAyE;AACzE,4EAA4E;AAC5E,4EAA4E;AAC5E,0EAA0E;AAC1E,wEAAwE;AACxE,iCAAiC;AACjC,OAAO,EAAE,cAAc,EAAwB,MAAM,qBAAqB,CAAC;AAC3E,OAAO,EAAE,gBAAgB,EAAE,MAAM,0BAA0B,CAAC;AAC5D,OAAO,EAAE,sBAAsB,EAAE,MAAM,uBAAuB,CAAC;AAC/D,OAAO,EAAE,2BAA2B,EAA6B,MAAM,yBAAyB,CAAC;AAGjG,OAAO,EAAE,8BAA8B,EAAE,yBAAyB,EAAE,MAAM,wBAAwB,CAAC"}

package/dist/request-collector.d.ts

@@ -0,0 +1,59 @@
+/**
+ * `ExternalRequestCollector` (plan §18 / checklist §18): translates
+ * `fetch-instrumentation.ts`'s captured requests into `EXTERNAL_REQUEST`
+ * Evidence. Same shape as `DatabaseQueryCollector`
+ * (`@descryy/runtime-database-observation`, RT-141) deliberately — a
+ * `ProcessOutputSource` in, `Evidence` out, streaming-first, a collector
+ * failure reported as evidence rather than swallowed — but for a different
+ * marker on the same stream.
+ *
+ * **What this collector does not do, named rather than silently absent:**
+ * no request/response body capture (the preload never reads either stream —
+ * see `fetch-instrumentation.ts`'s own "read, not write" note), no
+ * provider classification beyond a request's own hostname
+ * (`service-identity.ts`), and `graphNodeId` is always null — no resolver
+ * from a captured hostname to any graph node exists (nothing in the 15
+ * canonical node types names an external service). All real §18 rows, left
+ * open rather than guessed at, matching `DatabaseQueryCollector`'s own
+ * disclosure of the same shape of gap.
+ *
+ * ## The call-site stack, and why the parser is injected
+ *
+ * `stackTrace` used to be hard-null here, and `observe_runtime`'s own header
+ * gave the reason: *"it parses a log line the application printed and a
+ * printed line carries no stack."* The line is this package's own marker and
+ * the preload that writes it runs inside the calling process, so the stack
+ * was always available — nobody had captured it. It is captured now
+ * (`fetch-instrumentation.ts`), and this collector attaches it.
+ *
+ * Parsing it is **not** this package's job. V8's `Error.stack` format is one
+ * language's, and this collector observes the marker protocol, which is not.
+ * So a `StackTraceParser` is an option, supplied by whoever knows which
+ * runtime is being observed — `RuntimeAdapter.stackTraceParser` is exactly
+ * that value, already on the seam. Omitted, this collector behaves exactly as
+ * it did before the capture existed and **says so** in `capabilities()`:
+ * `stackCapture: unavailable`, with the reason. A half-wired capability that
+ * quietly reports nothing is the failure mode this project's honest-
+ * degradation rule exists to prevent.
+ */
+import type { Collector } from "@descryy/runtime-contracts";
+import type { ProcessOutputSource, StackTraceParser } from "@descryy/runtime-backend-observation";
+/** Absolute path to the compiled preload, for a caller building `node --import <this> <app>`. Never imported directly -- loaded by Node itself, in the observed process, before that process's own code runs. */
+export declare const FETCH_PRELOAD_MODULE_PATH: string;
+export interface ExternalRequestCollectorOptions {
+    readonly source: ProcessOutputSource;
+    /** Which owned system this collector's evidence should be attributed to (plan §16.7). Null when not applicable. */
+    readonly service?: string;
+    /**
+     * The observed runtime's own stack parser — `RuntimeAdapter.stackTraceParser`.
+     * Supplied by a caller that knows which language it launched; this package
+     * knows no language and must not (the IR boundary rule, one layer down).
+     *
+     * Omitted means captured stacks are not parsed and `stackTrace` stays
+     * `null`, which `capabilities()` reports as `stackCapture: unavailable`
+     * rather than leaving a reader to infer it from an absence.
+     */
+    readonly stackTraceParser?: StackTraceParser;
+}
+export declare function createExternalRequestCollector(options: ExternalRequestCollectorOptions): Collector;
+//# sourceMappingURL=request-collector.d.ts.map

package/dist/request-collector.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"request-collector.d.ts","sourceRoot":"","sources":["../src/request-collector.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqCG;AAGH,OAAO,KAAK,EAAE,SAAS,EAA+F,MAAM,4BAA4B,CAAC;AACzJ,OAAO,KAAK,EAAE,mBAAmB,EAAE,gBAAgB,EAAE,MAAM,sCAAsC,CAAC;AAOlG,iNAAiN;AACjN,eAAO,MAAM,yBAAyB,QAAwE,CAAC;AAE/G,MAAM,WAAW,+BAA+B;IAC9C,QAAQ,CAAC,MAAM,EAAE,mBAAmB,CAAC;IACrC,mHAAmH;IACnH,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;IAC1B;;;;;;;;OAQG;IACH,QAAQ,CAAC,gBAAgB,CAAC,EAAE,gBAAgB,CAAC;CAC9C;AAmCD,wBAAgB,8BAA8B,CAAC,OAAO,EAAE,+BAA+B,GAAG,SAAS,CA+GlG"}

package/dist/request-collector.js

@@ -0,0 +1,183 @@
+/**
+ * `ExternalRequestCollector` (plan §18 / checklist §18): translates
+ * `fetch-instrumentation.ts`'s captured requests into `EXTERNAL_REQUEST`
+ * Evidence. Same shape as `DatabaseQueryCollector`
+ * (`@descryy/runtime-database-observation`, RT-141) deliberately — a
+ * `ProcessOutputSource` in, `Evidence` out, streaming-first, a collector
+ * failure reported as evidence rather than swallowed — but for a different
+ * marker on the same stream.
+ *
+ * **What this collector does not do, named rather than silently absent:**
+ * no request/response body capture (the preload never reads either stream —
+ * see `fetch-instrumentation.ts`'s own "read, not write" note), no
+ * provider classification beyond a request's own hostname
+ * (`service-identity.ts`), and `graphNodeId` is always null — no resolver
+ * from a captured hostname to any graph node exists (nothing in the 15
+ * canonical node types names an external service). All real §18 rows, left
+ * open rather than guessed at, matching `DatabaseQueryCollector`'s own
+ * disclosure of the same shape of gap.
+ *
+ * ## The call-site stack, and why the parser is injected
+ *
+ * `stackTrace` used to be hard-null here, and `observe_runtime`'s own header
+ * gave the reason: *"it parses a log line the application printed and a
+ * printed line carries no stack."* The line is this package's own marker and
+ * the preload that writes it runs inside the calling process, so the stack
+ * was always available — nobody had captured it. It is captured now
+ * (`fetch-instrumentation.ts`), and this collector attaches it.
+ *
+ * Parsing it is **not** this package's job. V8's `Error.stack` format is one
+ * language's, and this collector observes the marker protocol, which is not.
+ * So a `StackTraceParser` is an option, supplied by whoever knows which
+ * runtime is being observed — `RuntimeAdapter.stackTraceParser` is exactly
+ * that value, already on the seam. Omitted, this collector behaves exactly as
+ * it did before the capture existed and **says so** in `capabilities()`:
+ * `stackCapture: unavailable`, with the reason. A half-wired capability that
+ * quietly reports nothing is the failure mode this project's honest-
+ * degradation rule exists to prevent.
+ */
+import { fileURLToPath } from "node:url";
+import { parseRequestLine } from "./request-line-parser.js";
+import { extractServiceIdentity } from "./service-identity.js";
+import { extractHeaderCorrelationIds } from "./header-correlation.js";
+import { COLLECTOR_VERSION } from "./collector-version.js";
+/** Absolute path to the compiled preload, for a caller building `node --import <this> <app>`. Never imported directly -- loaded by Node itself, in the observed process, before that process's own code runs. */
+export const FETCH_PRELOAD_MODULE_PATH = fileURLToPath(new URL("./fetch-instrumentation.js", import.meta.url));
+const EVENT_TYPE = "EXTERNAL_REQUEST";
+function computeCapabilities(hasStackParser) {
+    const reason = "ExternalRequestCollector observes EXTERNAL_REQUEST events only.";
+    const status = { availability: "unavailable", reason };
+    return {
+        domObservation: status,
+        consoleObservation: status,
+        networkObservation: status,
+        backendLogAccess: status,
+        // Real HTTP headers, structurally read (Headers/Request, not text
+        // parsed) -- the same mechanism and the same claim strength
+        // BrowserNetworkCollector already makes for its own captured requests.
+        distributedTrace: { availability: "available", reason: null },
+        sourceMapping: status,
+        // Real: the preload captures the application's own stack at the fetch
+        // call site, in the observed process, before the call leaves it. Claimed
+        // only when a parser was actually supplied to turn it into frames --
+        // capturing text nothing can read is not a capability.
+        stackCapture: hasStackParser
+            ? { availability: "available", reason: null }
+            : {
+                availability: "unavailable",
+                reason: "the fetch preload captures a call-site stack, but no StackTraceParser was supplied to this collector, " +
+                    "so it is not parsed and `stackTrace` stays null. Pass `RuntimeAdapter.stackTraceParser` for the observed runtime.",
+            },
+        processLifecycle: status,
+        databaseObservation: { availability: "unavailable", reason: "ExternalRequestCollector instruments the global fetch only; queries are DatabaseQueryCollector's to observe (RT-141)." },
+        externalServiceObservation: { availability: "available", reason: null },
+    };
+}
+export function createExternalRequestCollector(options) {
+    const capabilities = computeCapabilities(options.stackTraceParser !== undefined);
+    let consumeLoopDone;
+    let consumptionFailure = null;
+    /**
+     * `null` for every honest reason it can be: nothing captured, no parser
+     * supplied, or a parser that refused the text outright. A parser's `null`
+     * is its own contract ("not recognizable as this parser's format, never a
+     * best-effort guess") and is passed through rather than softened.
+     */
+    async function parseStack(request) {
+        if (request.stack === null || options.stackTraceParser === undefined)
+            return null;
+        return await options.stackTraceParser.parse(request.stack);
+    }
+    async function emitCapturedRequest(request, context) {
+        const { traceId, requestId } = extractHeaderCorrelationIds(request.requestHeaders);
+        const stackTrace = await parseStack(request);
+        context.emit({
+            timestamp: new Date().toISOString(),
+            source: "backend-process",
+            service: options.service ?? null,
+            process: options.source.processId,
+            eventType: EVENT_TYPE,
+            payload: {
+                raw: `${request.method} ${request.url}`,
+                url: request.url,
+                method: request.method,
+                service: extractServiceIdentity(request.url),
+                status: request.status,
+                durationMs: request.durationMs,
+                success: request.success,
+                error: request.error,
+            },
+            traceId,
+            requestId,
+            correlationId: null,
+            // No resolver from a captured hostname to a graph node exists --
+            // none of the 15 canonical node types names an external service.
+            graphNodeId: null,
+            sourceLocation: null,
+            stackTrace,
+            // The observation itself (a real captured call, real timing, real
+            // status/failure) is not probabilistic.
+            confidence: 1,
+            redactionStatus: "pending-redaction",
+            collectorVersion: COLLECTOR_VERSION,
+        });
+    }
+    async function consume(context) {
+        for await (const line of options.source.lines) {
+            const request = parseRequestLine(line.text);
+            if (request !== null)
+                await emitCapturedRequest(request, context);
+        }
+    }
+    return {
+        collectorId: `external-request-collector:${options.source.processId}`,
+        start(context) {
+            consumeLoopDone = consume(context).catch((error) => {
+                const detail = error instanceof Error ? `${error.name}: ${error.message}` : String(error);
+                consumptionFailure = detail;
+                try {
+                    context.emit({
+                        timestamp: new Date().toISOString(),
+                        source: "backend-process",
+                        service: options.service ?? null,
+                        process: options.source.processId,
+                        eventType: "COLLECTOR_ERROR",
+                        payload: {
+                            raw: `external request collector for process "${options.source.processId}" stopped consuming after an error: ${detail}`,
+                            collectorId: `external-request-collector:${options.source.processId}`,
+                            error: detail,
+                        },
+                        traceId: null,
+                        requestId: null,
+                        correlationId: null,
+                        graphNodeId: null,
+                        sourceLocation: null,
+                        stackTrace: null,
+                        confidence: 1,
+                        redactionStatus: "pending-redaction",
+                        collectorVersion: COLLECTOR_VERSION,
+                    });
+                }
+                catch (emitError) {
+                    console.error(`[external-request-collector:${options.source.processId}] consumption failed (${detail}) AND the failure could not be emitted: ${String(emitError)}`);
+                }
+            });
+            return Promise.resolve({ available: true });
+        },
+        async stop() {
+            await consumeLoopDone;
+        },
+        capabilities() {
+            if (consumptionFailure === null)
+                return capabilities;
+            return {
+                ...capabilities,
+                distributedTrace: {
+                    availability: "unavailable",
+                    reason: `consumption stopped early after an error (${consumptionFailure}); output after that point was never observed.`,
+                },
+            };
+        },
+    };
+}
+//# sourceMappingURL=request-collector.js.map

package/dist/request-collector.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"request-collector.js","sourceRoot":"","sources":["../src/request-collector.ts"],"names":[],"mappings":"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"}

package/dist/request-line-parser.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Reads one process-output line for the `REQUEST_MARKER` prefix.
+ *
+ * The marker comes from `request-marker.ts`, never from
+ * `fetch-instrumentation.ts` — importing the emitter to get a string would
+ * patch the parsing process's own `globalThis.fetch`. See `request-marker.ts`
+ * for the measurement. Everything else — the application's own real
+ * stdout/stderr — is not this parser's concern and is left alone; an
+ * external-request collector does not also try to be a log collector.
+ */
+import { REQUEST_MARKER, type CapturedRequest } from "./request-marker.ts";
+/**
+ * `null` for a non-matching line (ordinary application output) AND for a
+ * line that starts with the marker but fails to parse as one of this
+ * package's own captured requests — a malformed marker line is refused,
+ * never guessed at, the same distinction `parseQueryLine`
+ * (`@descryy/runtime-database-observation`) makes.
+ */
+export declare function parseRequestLine(line: string): CapturedRequest | null;
+export type { CapturedRequest };
+export { REQUEST_MARKER };
+//# sourceMappingURL=request-line-parser.d.ts.map

package/dist/request-line-parser.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"request-line-parser.d.ts","sourceRoot":"","sources":["../src/request-line-parser.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,EAAE,cAAc,EAAE,KAAK,eAAe,EAAE,MAAM,qBAAqB,CAAC;AAsB3E;;;;;;GAMG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,GAAG,eAAe,GAAG,IAAI,CAcrE;AAED,YAAY,EAAE,eAAe,EAAE,CAAC;AAChC,OAAO,EAAE,cAAc,EAAE,CAAC"}

package/dist/request-line-parser.js

@@ -0,0 +1,62 @@
+/**
+ * Reads one process-output line for the `REQUEST_MARKER` prefix.
+ *
+ * The marker comes from `request-marker.ts`, never from
+ * `fetch-instrumentation.ts` — importing the emitter to get a string would
+ * patch the parsing process's own `globalThis.fetch`. See `request-marker.ts`
+ * for the measurement. Everything else — the application's own real
+ * stdout/stderr — is not this parser's concern and is left alone; an
+ * external-request collector does not also try to be a log collector.
+ */
+import { REQUEST_MARKER } from "./request-marker.js";
+function isCapturedRequest(value) {
+    if (typeof value !== "object" || value === null)
+        return false;
+    const v = value;
+    if (typeof v.url !== "string" || typeof v.method !== "string")
+        return false;
+    if (typeof v.durationMs !== "number" || typeof v.success !== "boolean")
+        return false;
+    if (v.status !== null && typeof v.status !== "number")
+        return false;
+    if (v.error !== null && typeof v.error !== "string")
+        return false;
+    if (typeof v.requestHeaders !== "object" || v.requestHeaders === null)
+        return false;
+    // `stack` is the one field allowed to be absent. A marker line written by a
+    // preload from before call-site capture existed is a well-formed line that
+    // genuinely carries no stack -- normalised to `null` below, which is what
+    // "no stack was captured" already means everywhere downstream. Anything
+    // present but not a string is malformed and refused, same as every other
+    // field here.
+    if (v.stack !== undefined && v.stack !== null && typeof v.stack !== "string")
+        return false;
+    return Object.values(v.requestHeaders).every((value) => typeof value === "string");
+}
+/**
+ * `null` for a non-matching line (ordinary application output) AND for a
+ * line that starts with the marker but fails to parse as one of this
+ * package's own captured requests — a malformed marker line is refused,
+ * never guessed at, the same distinction `parseQueryLine`
+ * (`@descryy/runtime-database-observation`) makes.
+ */
+export function parseRequestLine(line) {
+    if (!line.startsWith(`${REQUEST_MARKER} `))
+        return null;
+    const json = line.slice(REQUEST_MARKER.length + 1);
+    let parsed;
+    try {
+        parsed = JSON.parse(json);
+    }
+    catch {
+        return null;
+    }
+    if (!isCapturedRequest(parsed))
+        return null;
+    // Absent `stack` becomes an explicit `null` so no consumer has to
+    // distinguish "the field was missing" from "nothing was captured" -- they
+    // are the same fact and only one of them is representable downstream.
+    return { ...parsed, stack: parsed.stack ?? null };
+}
+export { REQUEST_MARKER };
+//# sourceMappingURL=request-line-parser.js.map

package/dist/request-line-parser.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"request-line-parser.js","sourceRoot":"","sources":["../src/request-line-parser.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,EAAE,cAAc,EAAwB,MAAM,qBAAqB,CAAC;AAI3E,SAAS,iBAAiB,CAAC,KAAc;IACvC,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,KAAK,IAAI;QAAE,OAAO,KAAK,CAAC;IAC9D,MAAM,CAAC,GAAG,KAAgC,CAAC;IAC3C,IAAI,OAAO,CAAC,CAAC,GAAG,KAAK,QAAQ,IAAI,OAAO,CAAC,CAAC,MAAM,KAAK,QAAQ;QAAE,OAAO,KAAK,CAAC;IAC5E,IAAI,OAAO,CAAC,CAAC,UAAU,KAAK,QAAQ,IAAI,OAAO,CAAC,CAAC,OAAO,KAAK,SAAS;QAAE,OAAO,KAAK,CAAC;IACrF,IAAI,CAAC,CAAC,MAAM,KAAK,IAAI,IAAI,OAAO,CAAC,CAAC,MAAM,KAAK,QAAQ;QAAE,OAAO,KAAK,CAAC;IACpE,IAAI,CAAC,CAAC,KAAK,KAAK,IAAI,IAAI,OAAO,CAAC,CAAC,KAAK,KAAK,QAAQ;QAAE,OAAO,KAAK,CAAC;IAClE,IAAI,OAAO,CAAC,CAAC,cAAc,KAAK,QAAQ,IAAI,CAAC,CAAC,cAAc,KAAK,IAAI;QAAE,OAAO,KAAK,CAAC;IACpF,4EAA4E;IAC5E,2EAA2E;IAC3E,0EAA0E;IAC1E,wEAAwE;IACxE,yEAAyE;IACzE,cAAc;IACd,IAAI,CAAC,CAAC,KAAK,KAAK,SAAS,IAAI,CAAC,CAAC,KAAK,KAAK,IAAI,IAAI,OAAO,CAAC,CAAC,KAAK,KAAK,QAAQ;QAAE,OAAO,KAAK,CAAC;IAC3F,OAAO,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC,cAAyC,CAAC,CAAC,KAAK,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,OAAO,KAAK,KAAK,QAAQ,CAAC,CAAC;AAChH,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,gBAAgB,CAAC,IAAY;IAC3C,IAAI,CAAC,IAAI,CAAC,UAAU,CAAC,GAAG,cAAc,GAAG,CAAC;QAAE,OAAO,IAAI,CAAC;IACxD,MAAM,IAAI,GAAG,IAAI,CAAC,KAAK,CAAC,cAAc,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC;IACnD,IAAI,MAAe,CAAC;IACpB,IAAI,CAAC;QACH,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;IAC5B,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,IAAI,CAAC;IACd,CAAC;IACD,IAAI,CAAC,iBAAiB,CAAC,MAAM,CAAC;QAAE,OAAO,IAAI,CAAC;IAC5C,kEAAkE;IAClE,0EAA0E;IAC1E,sEAAsE;IACtE,OAAO,EAAE,GAAG,MAAM,EAAE,KAAK,EAAE,MAAM,CAAC,KAAK,IAAI,IAAI,EAAE,CAAC;AACpD,CAAC;AAGD,OAAO,EAAE,cAAc,EAAE,CAAC"}

package/dist/request-marker.d.ts

@@ -0,0 +1,51 @@
+/**
+ * The wire vocabulary shared by the two halves of external-service
+ * observation: the marker prefix and the shape that follows it.
+ *
+ * This module exists to be **free of side effects**, and that is its entire
+ * job. `fetch-instrumentation.ts` — the other holder of these names until now
+ * — replaces `globalThis.fetch` at module scope and writes to stdout, which
+ * is right for a `--import` preload inside an observed process and wrong
+ * everywhere else. `request-line-parser.ts` needed nothing from it but the
+ * string `"DESCRY_EXTERNAL_REQUEST"`, and importing a string is still
+ * importing a module: the patch and the stdout writer came along, through the
+ * package index, into every consumer.
+ *
+ * **This is `query-marker.ts`'s defect, one package over, and it was still
+ * open.** `@descryy/runtime-database-observation` found the identical shape,
+ * measured it into `@descryy/mcp`'s JSON-RPC transport — 14,906 marker lines
+ * in one `analyze` call — and carved the vocabulary out. Nothing did the same
+ * here, and nothing noticed, because nothing outside this repository imports
+ * this package yet. `observe_runtime` consuming this collector is precisely
+ * the change that would have noticed.
+ *
+ * So: the emitter imports the vocabulary, the parser imports the vocabulary,
+ * and neither imports the other. Anything added here must stay a constant or
+ * a type. A function with a module-scope effect would rebuild the same trap
+ * one file over.
+ */
+export declare const REQUEST_MARKER = "DESCRY_EXTERNAL_REQUEST";
+export interface CapturedRequest {
+    readonly url: string;
+    readonly method: string;
+    readonly requestHeaders: Readonly<Record<string, string>>;
+    /** `null` only when `success` is `false` -- the call never resolved to a response at all. */
+    readonly status: number | null;
+    readonly durationMs: number;
+    /** `true` iff `fetch` resolved rather than threw. An HTTP error status (4xx/5xx) is still `success: true` -- fetch itself does not reject on one. */
+    readonly success: boolean;
+    readonly error: string | null;
+    /**
+     * The **application's** own stack at the moment it called `fetch`, raw and
+     * unparsed, with the preload's own wrapper frames removed. `null` when the
+     * runtime produced no stack at all, or when nothing but the preload's own
+     * frames was in it.
+     *
+     * Raw text on purpose: parsing V8's format is
+     * `@descryy/runtime-adapter-typescript`'s job and belongs in the observing
+     * process, the same read-here/interpret-there split every marker in this
+     * repository already uses.
+     */
+    readonly stack: string | null;
+}
+//# sourceMappingURL=request-marker.d.ts.map

package/dist/request-marker.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"request-marker.d.ts","sourceRoot":"","sources":["../src/request-marker.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAOH,eAAO,MAAM,cAAc,4BAA8C,CAAC;AAE1E,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,cAAc,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;IAC1D,6FAA6F;IAC7F,QAAQ,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IAC/B,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,qJAAqJ;IACrJ,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;IAC1B,QAAQ,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IAC9B;;;;;;;;;;OAUG;IACH,QAAQ,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;CAC/B"}

package/dist/request-marker.js

@@ -0,0 +1,32 @@
+/**
+ * The wire vocabulary shared by the two halves of external-service
+ * observation: the marker prefix and the shape that follows it.
+ *
+ * This module exists to be **free of side effects**, and that is its entire
+ * job. `fetch-instrumentation.ts` — the other holder of these names until now
+ * — replaces `globalThis.fetch` at module scope and writes to stdout, which
+ * is right for a `--import` preload inside an observed process and wrong
+ * everywhere else. `request-line-parser.ts` needed nothing from it but the
+ * string `"DESCRY_EXTERNAL_REQUEST"`, and importing a string is still
+ * importing a module: the patch and the stdout writer came along, through the
+ * package index, into every consumer.
+ *
+ * **This is `query-marker.ts`'s defect, one package over, and it was still
+ * open.** `@descryy/runtime-database-observation` found the identical shape,
+ * measured it into `@descryy/mcp`'s JSON-RPC transport — 14,906 marker lines
+ * in one `analyze` call — and carved the vocabulary out. Nothing did the same
+ * here, and nothing noticed, because nothing outside this repository imports
+ * this package yet. `observe_runtime` consuming this collector is precisely
+ * the change that would have noticed.
+ *
+ * So: the emitter imports the vocabulary, the parser imports the vocabulary,
+ * and neither imports the other. Anything added here must stay a constant or
+ * a type. A function with a module-scope effect would rebuild the same trap
+ * one file over.
+ */
+import { RESERVED_MARKER_PREFIX } from "@descryy/runtime-contracts";
+// Derived, not spelled again: `RESERVED_MARKER_PREFIX` is what the
+// backend log collector skips on, so a marker that did not use it would
+// come back as the application's own log output.
+export const REQUEST_MARKER = `${RESERVED_MARKER_PREFIX}EXTERNAL_REQUEST`;
+//# sourceMappingURL=request-marker.js.map

package/dist/request-marker.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"request-marker.js","sourceRoot":"","sources":["../src/request-marker.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAEH,OAAO,EAAE,sBAAsB,EAAE,MAAM,4BAA4B,CAAC;AAEpE,mEAAmE;AACnE,wEAAwE;AACxE,iDAAiD;AACjD,MAAM,CAAC,MAAM,cAAc,GAAG,GAAG,sBAAsB,kBAAkB,CAAC"}

package/dist/service-identity.d.ts

@@ -0,0 +1,21 @@
+/**
+ * A captured request's "service identity" — the checklist's §18 own
+ * `service identity` row — is its URL's hostname, and nothing more.
+ *
+ * **Declared, never inferred.** This does not attempt to recognise "this
+ * hostname is Stripe" or classify a call into `authentication provider` /
+ * `payment provider` / etc. (§18's own "Potential integrations" list) —
+ * that would be a lookup table of well-known hosts this project has no
+ * source of truth for, guessed rather than read off anything the
+ * application declared. The hostname is a real, observed fact; a provider
+ * label would not be. If a consumer wants a friendlier name for a known
+ * host, that is a later, disclosed classification step layered on top of
+ * this, not something this function silently does.
+ *
+ * `null` for a URL that does not parse — refused rather than guessed, the
+ * same shape `extractTargetTable`
+ * (`@descryy/runtime-database-observation`) refuses a SQL statement it does
+ * not recognise.
+ */
+export declare function extractServiceIdentity(url: string): string | null;
+//# sourceMappingURL=service-identity.d.ts.map

package/dist/service-identity.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"service-identity.d.ts","sourceRoot":"","sources":["../src/service-identity.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,sBAAsB,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAMjE"}

package/dist/service-identity.js

@@ -0,0 +1,28 @@
+/**
+ * A captured request's "service identity" — the checklist's §18 own
+ * `service identity` row — is its URL's hostname, and nothing more.
+ *
+ * **Declared, never inferred.** This does not attempt to recognise "this
+ * hostname is Stripe" or classify a call into `authentication provider` /
+ * `payment provider` / etc. (§18's own "Potential integrations" list) —
+ * that would be a lookup table of well-known hosts this project has no
+ * source of truth for, guessed rather than read off anything the
+ * application declared. The hostname is a real, observed fact; a provider
+ * label would not be. If a consumer wants a friendlier name for a known
+ * host, that is a later, disclosed classification step layered on top of
+ * this, not something this function silently does.
+ *
+ * `null` for a URL that does not parse — refused rather than guessed, the
+ * same shape `extractTargetTable`
+ * (`@descryy/runtime-database-observation`) refuses a SQL statement it does
+ * not recognise.
+ */
+export function extractServiceIdentity(url) {
+    try {
+        return new URL(url).hostname;
+    }
+    catch {
+        return null;
+    }
+}
+//# sourceMappingURL=service-identity.js.map

package/dist/service-identity.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"service-identity.js","sourceRoot":"","sources":["../src/service-identity.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AACH,MAAM,UAAU,sBAAsB,CAAC,GAAW;IAChD,IAAI,CAAC;QACH,OAAO,IAAI,GAAG,CAAC,GAAG,CAAC,CAAC,QAAQ,CAAC;IAC/B,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,IAAI,CAAC;IACd,CAAC;AACH,CAAC"}

package/package.json

@@ -0,0 +1,35 @@
+{
+  "name": "@descryy/runtime-external-service-observation",
+  "version": "0.1.0",
+  "type": "module",
+  "description": "External service observation (plan §18, checklist §18): real EXTERNAL_REQUEST capture via client instrumentation, never parsed application logs. Client #1 is the global fetch.",
+  "license": "UNLICENSED",
+  "engines": {
+    "node": ">=22.5"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org",
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsc -b"
+  },
+  "dependencies": {
+    "@descryy/runtime-contracts": "0.1.0",
+    "@descryy/runtime-backend-observation": "0.1.0"
+  },
+  "devDependencies": {
+    "@descryy/runtime-controller": "*",
+    "@descryy/runtime-orchestrator": "*",
+    "@descryy/runtime-adapter-typescript": "*"
+  }
+}