@descryy/runtime-database-observation 0.0.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/graph-mapping.d.ts

@@ -0,0 +1,32 @@
+/**
+ * §10/§18's "graph correlation" row (RT-141's own disclosed gap, closed
+ * here): resolving an observed `DATABASE_QUERY`'s captured table name to
+ * the real `DATABASE_TABLE` graph node `resolveDatabaseTableNode`
+ * (`@descryy/runtime-graph-correlator`) already knows how to find.
+ *
+ * Same shape as `test-runner`'s own `resolveObservedTestCase`
+ * (`graph-mapping.ts`), deliberately: a thin per-package translation, not a
+ * new abstraction, and it does not call `EvidenceStore.attribute()` itself
+ * — that needs the evidence's real `evidenceId`, which only exists after
+ * `store.write()` has returned it, outside this collector's own reach, same
+ * as every other collector's `graphNodeId: null`. The caller that already
+ * holds both the store and the graph `driver` attributes; this only
+ * resolves.
+ */
+import type { SqlDriver } from "@descryy/core";
+import { type DatabaseTableResolution } from "@descryy/runtime-graph-correlator";
+import type { Evidence } from "@descryy/runtime-contracts";
+export type ObservedDatabaseQueryResolution = DatabaseTableResolution | {
+    readonly outcome: "no-table";
+    readonly reason: string;
+};
+/**
+ * Refuses (`"no-table"`, never throws) for anything that isn't
+ * `DATABASE_QUERY` evidence with a real `payload.table` — the same
+ * "wrong input, refuse rather than guess" shape every resolver in
+ * `graph-correlator` already uses.
+ */
+export declare function resolveObservedDatabaseQuery(driver: SqlDriver, evidence: Pick<Evidence, "eventType" | "payload">, options?: {
+    readonly limit?: number;
+}): ObservedDatabaseQueryResolution;
+//# sourceMappingURL=graph-mapping.d.ts.map

package/dist/graph-mapping.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"graph-mapping.d.ts","sourceRoot":"","sources":["../src/graph-mapping.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,eAAe,CAAC;AAC/C,OAAO,EAA4B,KAAK,uBAAuB,EAAE,MAAM,mCAAmC,CAAC;AAC3G,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,4BAA4B,CAAC;AAE3D,MAAM,MAAM,+BAA+B,GACvC,uBAAuB,GACvB;IAAE,QAAQ,CAAC,OAAO,EAAE,UAAU,CAAC;IAAC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAAC;AAE9D;;;;;GAKG;AACH,wBAAgB,4BAA4B,CAC1C,MAAM,EAAE,SAAS,EACjB,QAAQ,EAAE,IAAI,CAAC,QAAQ,EAAE,WAAW,GAAG,SAAS,CAAC,EACjD,OAAO,GAAE;IAAE,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAA;CAAO,GACxC,+BAA+B,CAkBjC"}

package/dist/graph-mapping.js

@@ -0,0 +1,41 @@
+/**
+ * §10/§18's "graph correlation" row (RT-141's own disclosed gap, closed
+ * here): resolving an observed `DATABASE_QUERY`'s captured table name to
+ * the real `DATABASE_TABLE` graph node `resolveDatabaseTableNode`
+ * (`@descryy/runtime-graph-correlator`) already knows how to find.
+ *
+ * Same shape as `test-runner`'s own `resolveObservedTestCase`
+ * (`graph-mapping.ts`), deliberately: a thin per-package translation, not a
+ * new abstraction, and it does not call `EvidenceStore.attribute()` itself
+ * — that needs the evidence's real `evidenceId`, which only exists after
+ * `store.write()` has returned it, outside this collector's own reach, same
+ * as every other collector's `graphNodeId: null`. The caller that already
+ * holds both the store and the graph `driver` attributes; this only
+ * resolves.
+ */
+import { resolveDatabaseTableNode } from "@descryy/runtime-graph-correlator";
+/**
+ * Refuses (`"no-table"`, never throws) for anything that isn't
+ * `DATABASE_QUERY` evidence with a real `payload.table` — the same
+ * "wrong input, refuse rather than guess" shape every resolver in
+ * `graph-correlator` already uses.
+ */
+export function resolveObservedDatabaseQuery(driver, evidence, options = {}) {
+    if (evidence.eventType !== "DATABASE_QUERY") {
+        return {
+            outcome: "no-table",
+            reason: `evidence.eventType is "${evidence.eventType}", not "DATABASE_QUERY" -- resolveObservedDatabaseQuery only knows how to map DatabaseQueryCollector evidence.`,
+        };
+    }
+    const payload = evidence.payload;
+    const table = typeof payload.table === "string" ? payload.table : null;
+    if (table === null) {
+        return {
+            outcome: "no-table",
+            reason: "evidence.payload.table is null or missing -- extractTargetTable could not name a table for this query " +
+                "(a JOIN, a comma-join, a CTE, or a statement it doesn't recognise).",
+        };
+    }
+    return resolveDatabaseTableNode(driver, table, options);
+}
+//# sourceMappingURL=graph-mapping.js.map

package/dist/graph-mapping.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"graph-mapping.js","sourceRoot":"","sources":["../src/graph-mapping.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAGH,OAAO,EAAE,wBAAwB,EAAgC,MAAM,mCAAmC,CAAC;AAO3G;;;;;GAKG;AACH,MAAM,UAAU,4BAA4B,CAC1C,MAAiB,EACjB,QAAiD,EACjD,UAAuC,EAAE;IAEzC,IAAI,QAAQ,CAAC,SAAS,KAAK,gBAAgB,EAAE,CAAC;QAC5C,OAAO;YACL,OAAO,EAAE,UAAU;YACnB,MAAM,EAAE,0BAA0B,QAAQ,CAAC,SAAS,gHAAgH;SACrK,CAAC;IACJ,CAAC;IACD,MAAM,OAAO,GAAG,QAAQ,CAAC,OAAuC,CAAC;IACjE,MAAM,KAAK,GAAG,OAAO,OAAO,CAAC,KAAK,KAAK,QAAQ,CAAC,CAAC,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC,CAAC,IAAI,CAAC;IACvE,IAAI,KAAK,KAAK,IAAI,EAAE,CAAC;QACnB,OAAO;YACL,OAAO,EAAE,UAAU;YACnB,MAAM,EACJ,wGAAwG;gBACxG,qEAAqE;SACxE,CAAC;IACJ,CAAC;IACD,OAAO,wBAAwB,CAAC,MAAM,EAAE,KAAK,EAAE,OAAO,CAAC,CAAC;AAC1D,CAAC"}

package/dist/index.d.ts

@@ -0,0 +1,8 @@
+export { extractTargetTable } from "./table-extraction.ts";
+export { QUERY_MARKER, type CapturedMethod, type CapturedQuery } from "./query-line-parser.ts";
+export { parseQueryLine } from "./query-line-parser.ts";
+export type { DatabaseQueryCollectorOptions } from "./query-collector.ts";
+export { createDatabaseQueryCollector, SQLITE_PRELOAD_MODULE_PATH } from "./query-collector.ts";
+export type { ObservedDatabaseQueryResolution } from "./graph-mapping.ts";
+export { resolveObservedDatabaseQuery } from "./graph-mapping.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,OAAO,EAAE,kBAAkB,EAAE,MAAM,uBAAuB,CAAC;AAE3D,OAAO,EAAE,YAAY,EAAE,KAAK,cAAc,EAAE,KAAK,aAAa,EAAE,MAAM,wBAAwB,CAAC;AAC/F,OAAO,EAAE,cAAc,EAAE,MAAM,wBAAwB,CAAC;AAExD,YAAY,EAAE,6BAA6B,EAAE,MAAM,sBAAsB,CAAC;AAC1E,OAAO,EAAE,4BAA4B,EAAE,0BAA0B,EAAE,MAAM,sBAAsB,CAAC;AAEhG,YAAY,EAAE,+BAA+B,EAAE,MAAM,oBAAoB,CAAC;AAC1E,OAAO,EAAE,4BAA4B,EAAE,MAAM,oBAAoB,CAAC"}

package/dist/index.js

@@ -0,0 +1,6 @@
+export { extractTargetTable } from "./table-extraction.js";
+export { QUERY_MARKER } from "./query-line-parser.js";
+export { parseQueryLine } from "./query-line-parser.js";
+export { createDatabaseQueryCollector, SQLITE_PRELOAD_MODULE_PATH } from "./query-collector.js";
+export { resolveObservedDatabaseQuery } from "./graph-mapping.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,OAAO,EAAE,kBAAkB,EAAE,MAAM,uBAAuB,CAAC;AAE3D,OAAO,EAAE,YAAY,EAA2C,MAAM,wBAAwB,CAAC;AAC/F,OAAO,EAAE,cAAc,EAAE,MAAM,wBAAwB,CAAC;AAGxD,OAAO,EAAE,4BAA4B,EAAE,0BAA0B,EAAE,MAAM,sBAAsB,CAAC;AAGhG,OAAO,EAAE,4BAA4B,EAAE,MAAM,oBAAoB,CAAC"}

package/dist/query-collector.d.ts

@@ -0,0 +1,32 @@
+/**
+ * `DatabaseQueryCollector` (plan §18 / checklist §14): translates
+ * `sqlite-instrumentation.ts`'s captured queries into `DATABASE_QUERY`
+ * Evidence. Same shape as `LogCollector` (`@descryy/runtime-backend-observation`)
+ * 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 transaction-boundary tracking (BEGIN/COMMIT/ROLLBACK are captured as
+ * ordinary queries, not grouped) — a real, still-open §14/§18 row.
+ *
+ * **`graphNodeId` on emitted evidence is still always null here, same as
+ * every other collector** (RT-076's own precedent, `test-runner-collector.ts`)
+ * — `graph-mapping.ts`'s `resolveObservedDatabaseQuery` is what a caller
+ * holding both the store and the graph driver uses to resolve a captured
+ * table name to the real `DATABASE_TABLE` node and attribute it, after
+ * `write()`, the same way `vertical-slice` already does for every other
+ * evidence type. The resolver itself (RT-146) is real; this collector
+ * simply isn't the one that calls it.
+ */
+import type { Collector } from "@descryy/runtime-contracts";
+import { type ProcessOutputSource } 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 SQLITE_PRELOAD_MODULE_PATH: string;
+export interface DatabaseQueryCollectorOptions {
+    readonly source: ProcessOutputSource;
+    /** Which owned system this collector's evidence should be attributed to (plan §16.7). Null when not applicable. */
+    readonly service?: string;
+}
+export declare function createDatabaseQueryCollector(options: DatabaseQueryCollectorOptions): Collector;
+//# sourceMappingURL=query-collector.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"query-collector.d.ts","sourceRoot":"","sources":["../src/query-collector.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAGH,OAAO,KAAK,EAAE,SAAS,EAAmF,MAAM,4BAA4B,CAAC;AAC7I,OAAO,EAAyB,KAAK,mBAAmB,EAAE,MAAM,sCAAsC,CAAC;AAMvG,iNAAiN;AACjN,eAAO,MAAM,0BAA0B,QAAyE,CAAC;AAEjH,MAAM,WAAW,6BAA6B;IAC5C,QAAQ,CAAC,MAAM,EAAE,mBAAmB,CAAC;IACrC,mHAAmH;IACnH,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;CAC3B;AA2BD,wBAAgB,4BAA4B,CAAC,OAAO,EAAE,6BAA6B,GAAG,SAAS,CAkG9F"}

package/dist/query-collector.js

@@ -0,0 +1,146 @@
+/**
+ * `DatabaseQueryCollector` (plan §18 / checklist §14): translates
+ * `sqlite-instrumentation.ts`'s captured queries into `DATABASE_QUERY`
+ * Evidence. Same shape as `LogCollector` (`@descryy/runtime-backend-observation`)
+ * 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 transaction-boundary tracking (BEGIN/COMMIT/ROLLBACK are captured as
+ * ordinary queries, not grouped) — a real, still-open §14/§18 row.
+ *
+ * **`graphNodeId` on emitted evidence is still always null here, same as
+ * every other collector** (RT-076's own precedent, `test-runner-collector.ts`)
+ * — `graph-mapping.ts`'s `resolveObservedDatabaseQuery` is what a caller
+ * holding both the store and the graph driver uses to resolve a captured
+ * table name to the real `DATABASE_TABLE` node and attribute it, after
+ * `write()`, the same way `vertical-slice` already does for every other
+ * evidence type. The resolver itself (RT-146) is real; this collector
+ * simply isn't the one that calls it.
+ */
+import { fileURLToPath } from "node:url";
+import { extractCorrelationIds } from "@descryy/runtime-backend-observation";
+import { parseQueryLine } from "./query-line-parser.js";
+import { extractTargetTable } from "./table-extraction.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 SQLITE_PRELOAD_MODULE_PATH = fileURLToPath(new URL("./sqlite-instrumentation.js", import.meta.url));
+const EVENT_TYPE = "DATABASE_QUERY";
+function computeCapabilities() {
+    const reason = "DatabaseQueryCollector observes DATABASE_QUERY events only.";
+    const status = { availability: "unavailable", reason };
+    return {
+        domObservation: status,
+        consoleObservation: status,
+        networkObservation: status,
+        backendLogAccess: status,
+        distributedTrace: {
+            availability: "degraded",
+            reason: "extracts trace-id/request-id from the query text itself (a declared SQL comment convention, same mechanism LogCollector uses on process output); does not observe application-level propagation.",
+        },
+        sourceMapping: status,
+        stackCapture: status,
+        processLifecycle: status,
+        // The field this collector's own RT-141 entry named as missing and
+        // deferred (RT-142) -- closed here (RT-146), alongside the field's
+        // own addition to the contract.
+        databaseObservation: { availability: "available", reason: null },
+        externalServiceObservation: { availability: "unavailable", reason: "DatabaseQueryCollector instruments node:sqlite only; outbound requests are ExternalRequestCollector's to observe (RT-146)." },
+    };
+}
+export function createDatabaseQueryCollector(options) {
+    const capabilities = computeCapabilities();
+    let consumeLoopDone;
+    let consumptionFailure = null;
+    function emitCapturedQuery(query, context) {
+        const { traceId, requestId } = extractCorrelationIds(query.sql);
+        context.emit({
+            timestamp: new Date().toISOString(),
+            source: "backend-process",
+            service: options.service ?? null,
+            process: options.source.processId,
+            eventType: EVENT_TYPE,
+            payload: {
+                raw: query.sql,
+                method: query.method,
+                durationMs: query.durationMs,
+                success: query.success,
+                error: query.error,
+                table: extractTargetTable(query.sql),
+            },
+            traceId,
+            requestId,
+            correlationId: null,
+            // Resolved later, by a caller holding the store and driver --
+            // resolveObservedDatabaseQuery (graph-mapping.ts), not here. Same
+            // split every other collector's graphNodeId already takes.
+            graphNodeId: null,
+            sourceLocation: null,
+            stackTrace: null,
+            // The observation itself (a real captured call, real timing, real
+            // success/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 query = parseQueryLine(line.text);
+            if (query !== null)
+                emitCapturedQuery(query, context);
+        }
+    }
+    return {
+        collectorId: `database-query-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: `database query collector for process "${options.source.processId}" stopped consuming after an error: ${detail}`,
+                            collectorId: `database-query-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(`[database-query-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=query-collector.js.map

package/dist/query-collector.js.map

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

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

@@ -0,0 +1,18 @@
+/**
+ * Reads one process-output line for `sqlite-instrumentation.ts`'s own
+ * `QUERY_MARKER` prefix. Everything else — the application's own real
+ * stdout/stderr — is not this parser's concern and is left alone; a
+ * database collector does not also try to be a log collector.
+ */
+import { QUERY_MARKER, type CapturedMethod, type CapturedQuery } from "./sqlite-instrumentation.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 queries — a malformed marker line is refused,
+ * never guessed at, the same "wrong shape, not a wrong value" distinction
+ * `test-runner`'s own `isNodeTestEvent` makes.
+ */
+export declare function parseQueryLine(line: string): CapturedQuery | null;
+export type { CapturedMethod, CapturedQuery };
+export { QUERY_MARKER };
+//# sourceMappingURL=query-line-parser.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"query-line-parser.d.ts","sourceRoot":"","sources":["../src/query-line-parser.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,YAAY,EAAE,KAAK,cAAc,EAAE,KAAK,aAAa,EAAE,MAAM,6BAA6B,CAAC;AAcpG;;;;;;GAMG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,GAAG,aAAa,GAAG,IAAI,CAUjE;AAED,YAAY,EAAE,cAAc,EAAE,aAAa,EAAE,CAAC;AAC9C,OAAO,EAAE,YAAY,EAAE,CAAC"}

package/dist/query-line-parser.js

@@ -0,0 +1,39 @@
+/**
+ * Reads one process-output line for `sqlite-instrumentation.ts`'s own
+ * `QUERY_MARKER` prefix. Everything else — the application's own real
+ * stdout/stderr — is not this parser's concern and is left alone; a
+ * database collector does not also try to be a log collector.
+ */
+import { QUERY_MARKER } from "./sqlite-instrumentation.js";
+function isCapturedQuery(value) {
+    if (typeof value !== "object" || value === null)
+        return false;
+    const v = value;
+    return (typeof v.sql === "string" &&
+        typeof v.method === "string" &&
+        typeof v.durationMs === "number" &&
+        typeof v.success === "boolean" &&
+        (v.error === null || typeof v.error === "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 queries — a malformed marker line is refused,
+ * never guessed at, the same "wrong shape, not a wrong value" distinction
+ * `test-runner`'s own `isNodeTestEvent` makes.
+ */
+export function parseQueryLine(line) {
+    if (!line.startsWith(`${QUERY_MARKER} `))
+        return null;
+    const json = line.slice(QUERY_MARKER.length + 1);
+    let parsed;
+    try {
+        parsed = JSON.parse(json);
+    }
+    catch {
+        return null;
+    }
+    return isCapturedQuery(parsed) ? parsed : null;
+}
+export { QUERY_MARKER };
+//# sourceMappingURL=query-line-parser.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"query-line-parser.js","sourceRoot":"","sources":["../src/query-line-parser.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,YAAY,EAA2C,MAAM,6BAA6B,CAAC;AAEpG,SAAS,eAAe,CAAC,KAAc;IACrC,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,KAAK,IAAI;QAAE,OAAO,KAAK,CAAC;IAC9D,MAAM,CAAC,GAAG,KAAgC,CAAC;IAC3C,OAAO,CACL,OAAO,CAAC,CAAC,GAAG,KAAK,QAAQ;QACzB,OAAO,CAAC,CAAC,MAAM,KAAK,QAAQ;QAC5B,OAAO,CAAC,CAAC,UAAU,KAAK,QAAQ;QAChC,OAAO,CAAC,CAAC,OAAO,KAAK,SAAS;QAC9B,CAAC,CAAC,CAAC,KAAK,KAAK,IAAI,IAAI,OAAO,CAAC,CAAC,KAAK,KAAK,QAAQ,CAAC,CAClD,CAAC;AACJ,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,cAAc,CAAC,IAAY;IACzC,IAAI,CAAC,IAAI,CAAC,UAAU,CAAC,GAAG,YAAY,GAAG,CAAC;QAAE,OAAO,IAAI,CAAC;IACtD,MAAM,IAAI,GAAG,IAAI,CAAC,KAAK,CAAC,YAAY,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC;IACjD,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,OAAO,eAAe,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,IAAI,CAAC;AACjD,CAAC;AAGD,OAAO,EAAE,YAAY,EAAE,CAAC"}

package/dist/sqlite-instrumentation.d.ts

@@ -0,0 +1,31 @@
+/**
+ * `--import`-loaded preload: patches `node:sqlite`'s `DatabaseSync`
+ * prototype before the target application's own code runs, so every real
+ * query the application issues through its own `import { DatabaseSync }
+ * from "node:sqlite"` is observed — proven directly (a probe script, not
+ * assumed): Node's built-in modules are a process-wide singleton, so a
+ * `--import` preload patching `DatabaseSync.prototype` here and an
+ * application's completely separate `import` of the same built-in later
+ * see the same prototype object.
+ *
+ * Deliberately minimal and import-free, like `test-runner`'s own
+ * `reporter.ts` — this runs inside the OBSERVED process, not this
+ * package's own, and is loaded by absolute path via `node --import`, never
+ * through this package's normal dependency graph. Interpretation (target
+ * table, correlation ids) happens on the collector side, in the observing
+ * process, not here — this only captures.
+ *
+ * One line of structured JSON per query, prefixed exactly like the
+ * benchmark harness's own `BENCH_RESULT {json}` convention (RT-072):
+ * scraping prose measures the prose, so nothing here is prose.
+ */
+export declare const QUERY_MARKER = "DESCRY_DB_QUERY";
+export type CapturedMethod = "exec" | "prepare" | "run" | "get" | "all";
+export interface CapturedQuery {
+    readonly sql: string;
+    readonly method: CapturedMethod;
+    readonly durationMs: number;
+    readonly success: boolean;
+    readonly error: string | null;
+}
+//# sourceMappingURL=sqlite-instrumentation.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"sqlite-instrumentation.d.ts","sourceRoot":"","sources":["../src/sqlite-instrumentation.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAIH,eAAO,MAAM,YAAY,oBAAoB,CAAC;AAE9C,MAAM,MAAM,cAAc,GAAG,MAAM,GAAG,SAAS,GAAG,KAAK,GAAG,KAAK,GAAG,KAAK,CAAC;AAExE,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,MAAM,EAAE,cAAc,CAAC;IAChC,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;IAC1B,QAAQ,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;CAC/B"}

package/dist/sqlite-instrumentation.js

@@ -0,0 +1,68 @@
+/**
+ * `--import`-loaded preload: patches `node:sqlite`'s `DatabaseSync`
+ * prototype before the target application's own code runs, so every real
+ * query the application issues through its own `import { DatabaseSync }
+ * from "node:sqlite"` is observed — proven directly (a probe script, not
+ * assumed): Node's built-in modules are a process-wide singleton, so a
+ * `--import` preload patching `DatabaseSync.prototype` here and an
+ * application's completely separate `import` of the same built-in later
+ * see the same prototype object.
+ *
+ * Deliberately minimal and import-free, like `test-runner`'s own
+ * `reporter.ts` — this runs inside the OBSERVED process, not this
+ * package's own, and is loaded by absolute path via `node --import`, never
+ * through this package's normal dependency graph. Interpretation (target
+ * table, correlation ids) happens on the collector side, in the observing
+ * process, not here — this only captures.
+ *
+ * One line of structured JSON per query, prefixed exactly like the
+ * benchmark harness's own `BENCH_RESULT {json}` convention (RT-072):
+ * scraping prose measures the prose, so nothing here is prose.
+ */
+import { DatabaseSync } from "node:sqlite";
+export const QUERY_MARKER = "DESCRY_DB_QUERY";
+function emit(query) {
+    process.stdout.write(`${QUERY_MARKER} ${JSON.stringify(query)}\n`);
+}
+function timed(sql, method, run) {
+    const start = performance.now();
+    try {
+        const result = run();
+        emit({ sql, method, durationMs: performance.now() - start, success: true, error: null });
+        return result;
+    }
+    catch (error) {
+        const detail = error instanceof Error ? `${error.name}: ${error.message}` : String(error);
+        emit({ sql, method, durationMs: performance.now() - start, success: false, error: detail });
+        throw error;
+    }
+}
+// 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 method and double-emit.
+const PATCHED = Symbol.for("descry.database-observation.sqlite-patched");
+const target = DatabaseSync.prototype;
+if (target[PATCHED] !== true) {
+    target[PATCHED] = true;
+    const originalExec = DatabaseSync.prototype.exec;
+    DatabaseSync.prototype.exec = function patchedExec(sql, ...rest) {
+        return timed(sql, "exec", () => originalExec.call(this, sql, ...rest));
+    };
+    const originalPrepare = DatabaseSync.prototype.prepare;
+    DatabaseSync.prototype.prepare = function patchedPrepare(sql) {
+        const stmt = timed(sql, "prepare", () => originalPrepare.call(this, sql));
+        const stmtTarget = stmt;
+        for (const method of ["run", "get", "all"]) {
+            const original = stmtTarget[method];
+            stmtTarget[method] = function patchedStatementMethod(...args) {
+                return timed(sql, method, () => original.apply(stmt, args));
+            };
+        }
+        // `iterate()` deliberately left unwrapped: it returns a lazy generator,
+        // so "duration" would mean the time to build the iterator, not the
+        // time to consume it -- a different, misleading number under the same
+        // name. Disclosed here rather than measured wrong.
+        return stmt;
+    };
+}
+//# sourceMappingURL=sqlite-instrumentation.js.map

package/dist/sqlite-instrumentation.js.map

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

package/dist/table-extraction.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Extracts the single target table a DML statement names — deliberately
+ * not a SQL parser, same reasoning `adapter-sql`'s `parse.ts` gives for
+ * its own DDL-only scope: a bounded reader that recognises a few shapes
+ * and refuses (`null`) on everything else is honest; a reader that guesses
+ * at a JOIN or a subquery is not.
+ *
+ * `adapter-sql` (descry-adapters) reads CREATE/ALTER — schema declaration.
+ * This reads INSERT/UPDATE/DELETE/SELECT — a different problem (which
+ * table did a query at RUNTIME actually touch), so its own small reader
+ * rather than a false shared abstraction over two different questions.
+ *
+ * **Refused, not guessed, for:** a JOIN anywhere in the statement (which
+ * table is "the" table is genuinely ambiguous), a comma-separated FROM
+ * list (old-style implicit join, same ambiguity), a subquery in FROM, a
+ * CTE (`WITH ... AS`), and anything this reader does not recognise the
+ * shape of at all. The wrong-table negative control this package's tests
+ * assert on is exactly this: a two-table JOIN must resolve to `null`, not
+ * to either table picked arbitrarily.
+ */
+/**
+ * `null` for anything not recognised as exactly one of INSERT/UPDATE/
+ * DELETE/SELECT with a single, unambiguous target table. Never a partial
+ * or best-effort name.
+ */
+export declare function extractTargetTable(sql: string): string | null;
+//# sourceMappingURL=table-extraction.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"table-extraction.d.ts","sourceRoot":"","sources":["../src/table-extraction.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AA8BH;;;;GAIG;AACH,wBAAgB,kBAAkB,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAmB7D"}

package/dist/table-extraction.js

@@ -0,0 +1,67 @@
+/**
+ * Extracts the single target table a DML statement names — deliberately
+ * not a SQL parser, same reasoning `adapter-sql`'s `parse.ts` gives for
+ * its own DDL-only scope: a bounded reader that recognises a few shapes
+ * and refuses (`null`) on everything else is honest; a reader that guesses
+ * at a JOIN or a subquery is not.
+ *
+ * `adapter-sql` (descry-adapters) reads CREATE/ALTER — schema declaration.
+ * This reads INSERT/UPDATE/DELETE/SELECT — a different problem (which
+ * table did a query at RUNTIME actually touch), so its own small reader
+ * rather than a false shared abstraction over two different questions.
+ *
+ * **Refused, not guessed, for:** a JOIN anywhere in the statement (which
+ * table is "the" table is genuinely ambiguous), a comma-separated FROM
+ * list (old-style implicit join, same ambiguity), a subquery in FROM, a
+ * CTE (`WITH ... AS`), and anything this reader does not recognise the
+ * shape of at all. The wrong-table negative control this package's tests
+ * assert on is exactly this: a two-table JOIN must resolve to `null`, not
+ * to either table picked arbitrarily.
+ */
+const IDENTIFIER = String.raw `(?:\[[^\]]+\]|"[^"]+"|` + "`[^`]+`" + String.raw `|[A-Za-z_][A-Za-z0-9_]*)`;
+const QUALIFIED = `${IDENTIFIER}(?:\\.${IDENTIFIER})?`;
+const INSERT_INTO = new RegExp(`^\\s*INSERT\\s+INTO\\s+(${QUALIFIED})`, "i");
+const UPDATE = new RegExp(`^\\s*UPDATE\\s+(${QUALIFIED})`, "i");
+const DELETE_FROM = new RegExp(`^\\s*DELETE\\s+FROM\\s+(${QUALIFIED})`, "i");
+const SELECT_FROM = new RegExp(`\\bFROM\\s+(${QUALIFIED})`, "i");
+/** Anywhere in the statement — a JOIN or a CTE makes "the" target table an unresolvable question, not a hard one. */
+const AMBIGUOUS = /\bJOIN\b|\bWITH\b\s+[\w"`[]/i;
+function unquote(identifier) {
+    return identifier.replace(/^["`[]|["`\]]$/g, "");
+}
+/** Last segment of a possibly schema-qualified name (`main.widgets` -> `widgets`), matching `adapter-sql`'s own convention for the same question. */
+function unqualify(raw) {
+    const parts = raw.split(".").map(unquote);
+    return parts.at(-1) ?? raw;
+}
+/** A comma directly after the FROM target, before any keyword, is the old-style implicit-join list — the same ambiguity a JOIN is, spelled differently. */
+function hasCommaJoinAfter(sql, matchEnd) {
+    const rest = sql.slice(matchEnd);
+    const nextKeyword = /^\s*(,|WHERE|GROUP|ORDER|LIMIT|JOIN|;|$)/i.exec(rest);
+    return nextKeyword !== null && nextKeyword[1] === ",";
+}
+/**
+ * `null` for anything not recognised as exactly one of INSERT/UPDATE/
+ * DELETE/SELECT with a single, unambiguous target table. Never a partial
+ * or best-effort name.
+ */
+export function extractTargetTable(sql) {
+    const trimmed = sql.trim();
+    if (AMBIGUOUS.test(trimmed))
+        return null;
+    const insert = INSERT_INTO.exec(trimmed);
+    if (insert !== null)
+        return unqualify(insert[1]);
+    const update = UPDATE.exec(trimmed);
+    if (update !== null)
+        return unqualify(update[1]);
+    const del = DELETE_FROM.exec(trimmed);
+    if (del !== null)
+        return unqualify(del[1]);
+    const select = SELECT_FROM.exec(trimmed);
+    if (select !== null && !hasCommaJoinAfter(trimmed, select.index + select[0].length)) {
+        return unqualify(select[1]);
+    }
+    return null;
+}
+//# sourceMappingURL=table-extraction.js.map

package/dist/table-extraction.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"table-extraction.js","sourceRoot":"","sources":["../src/table-extraction.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,MAAM,UAAU,GAAG,MAAM,CAAC,GAAG,CAAA,wBAAwB,GAAG,SAAS,GAAG,MAAM,CAAC,GAAG,CAAA,0BAA0B,CAAC;AACzG,MAAM,SAAS,GAAG,GAAG,UAAU,SAAS,UAAU,IAAI,CAAC;AAEvD,MAAM,WAAW,GAAG,IAAI,MAAM,CAAC,2BAA2B,SAAS,GAAG,EAAE,GAAG,CAAC,CAAC;AAC7E,MAAM,MAAM,GAAG,IAAI,MAAM,CAAC,mBAAmB,SAAS,GAAG,EAAE,GAAG,CAAC,CAAC;AAChE,MAAM,WAAW,GAAG,IAAI,MAAM,CAAC,2BAA2B,SAAS,GAAG,EAAE,GAAG,CAAC,CAAC;AAC7E,MAAM,WAAW,GAAG,IAAI,MAAM,CAAC,eAAe,SAAS,GAAG,EAAE,GAAG,CAAC,CAAC;AAEjE,qHAAqH;AACrH,MAAM,SAAS,GAAG,8BAA8B,CAAC;AAEjD,SAAS,OAAO,CAAC,UAAkB;IACjC,OAAO,UAAU,CAAC,OAAO,CAAC,iBAAiB,EAAE,EAAE,CAAC,CAAC;AACnD,CAAC;AAED,qJAAqJ;AACrJ,SAAS,SAAS,CAAC,GAAW;IAC5B,MAAM,KAAK,GAAG,GAAG,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC;IAC1C,OAAO,KAAK,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,IAAI,GAAG,CAAC;AAC7B,CAAC;AAED,2JAA2J;AAC3J,SAAS,iBAAiB,CAAC,GAAW,EAAE,QAAgB;IACtD,MAAM,IAAI,GAAG,GAAG,CAAC,KAAK,CAAC,QAAQ,CAAC,CAAC;IACjC,MAAM,WAAW,GAAG,2CAA2C,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IAC3E,OAAO,WAAW,KAAK,IAAI,IAAI,WAAW,CAAC,CAAC,CAAC,KAAK,GAAG,CAAC;AACxD,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,kBAAkB,CAAC,GAAW;IAC5C,MAAM,OAAO,GAAG,GAAG,CAAC,IAAI,EAAE,CAAC;IAC3B,IAAI,SAAS,CAAC,IAAI,CAAC,OAAO,CAAC;QAAE,OAAO,IAAI,CAAC;IAEzC,MAAM,MAAM,GAAG,WAAW,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;IACzC,IAAI,MAAM,KAAK,IAAI;QAAE,OAAO,SAAS,CAAC,MAAM,CAAC,CAAC,CAAE,CAAC,CAAC;IAElD,MAAM,MAAM,GAAG,MAAM,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;IACpC,IAAI,MAAM,KAAK,IAAI;QAAE,OAAO,SAAS,CAAC,MAAM,CAAC,CAAC,CAAE,CAAC,CAAC;IAElD,MAAM,GAAG,GAAG,WAAW,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;IACtC,IAAI,GAAG,KAAK,IAAI;QAAE,OAAO,SAAS,CAAC,GAAG,CAAC,CAAC,CAAE,CAAC,CAAC;IAE5C,MAAM,MAAM,GAAG,WAAW,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;IACzC,IAAI,MAAM,KAAK,IAAI,IAAI,CAAC,iBAAiB,CAAC,OAAO,EAAE,MAAM,CAAC,KAAK,GAAG,MAAM,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,EAAE,CAAC;QACpF,OAAO,SAAS,CAAC,MAAM,CAAC,CAAC,CAAE,CAAC,CAAC;IAC/B,CAAC;IAED,OAAO,IAAI,CAAC;AACd,CAAC"}

package/package.json

@@ -0,0 +1,35 @@
+{
+  "name": "@descryy/runtime-database-observation",
+  "version": "0.0.0",
+  "type": "module",
+  "description": "Database query observation (plan §18, checklist §14): real DATABASE_QUERY capture via driver instrumentation, never parsed application logs. Driver #1 is node:sqlite.",
+  "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": "*",
+    "@descryy/runtime-backend-observation": "*",
+    "@descryy/runtime-graph-correlator": "*"
+  },
+  "devDependencies": {
+    "@descryy/runtime-controller": "*",
+    "@descryy/runtime-orchestrator": "*"
+  }
+}