@descryy/runtime-remote-log-ingestion 0.0.0

package/dist/correlator.d.ts

@@ -0,0 +1,67 @@
+/**
+ * Correlation between a captured browser/proxy request and an ingested
+ * remote log line (DEC-271's remote side). Follows the same pattern
+ * `backend-observation/correlator.ts`'s `correlateBackendEvidence` already
+ * establishes -- prefer a real shared identifier, never fall back to timing
+ * on its own -- rather than inventing a second correlation shape.
+ *
+ * Reuses `@descryy/runtime-contracts`' `Correlation`/`createCorrelation`
+ * directly: `method` is drawn from the same closed `CorrelationMethod`
+ * union everywhere else in this repo uses, so `isConfirmed` is derived the
+ * same way (`isStructuralCorrelation` -- true for `trace-id`/`request-id`,
+ * false for `timing-context-fallback`) and a reader who already knows that
+ * contract does not have to learn a second one for the remote case.
+ */
+import type { Correlation } from "@descryy/runtime-contracts";
+import type { IngestedLogLine } from "./log-line.ts";
+/**
+ * A captured browser/proxy request, reduced to the fields correlation
+ * needs. `timestamp` and `path` are always available -- every captured
+ * request has both; `traceId`/`requestId` are populated only when the
+ * capturing side actually found them (real headers, W3C `traceparent` --
+ * see `external-service-observation/header-correlation.ts`), null
+ * otherwise. `id` is caller-assigned (an `Evidence.evidenceId`, typically)
+ * -- this module never generates one, mirroring
+ * `correlateBackendEvidence`'s use of pre-existing `evidenceId`s rather
+ * than minting its own.
+ */
+export interface CapturedRequestRef {
+    readonly id: string;
+    readonly executionId: string;
+    readonly timestamp: string;
+    readonly path: string;
+    readonly traceId: string | null;
+    readonly requestId: string | null;
+}
+export interface CorrelateOptions {
+    /**
+     * Widest gap between the request's and the line's timestamp still
+     * considered for a timestamp+path match, in milliseconds. Default 5000 --
+     * generous enough for real network and log-flush latency between a
+     * request landing and its log line appearing, narrow enough not to pair
+     * unrelated activity in a busy log.
+     */
+    readonly windowMs?: number;
+}
+/**
+ * Best-effort correlation between one captured request and one ingested log
+ * line, in DEC-271's stated preference order:
+ *
+ * 1. a shared trace id (`method: "trace-id"`, confidence 1) -- the same
+ *    rule and confidence `correlateBackendEvidence` uses for the local case.
+ * 2. a shared request id (`method: "request-id"`, confidence 1).
+ * 3. the request's timestamp within `windowMs` of the line's **and** the
+ *    request's `path` appearing in the line's (already-redacted) text --
+ *    `method: "timing-context-fallback"`, confidence
+ *    `TIMESTAMP_PATH_CONFIDENCE`, `isConfirmed: false`. Both signals are
+ *    required together; timestamp proximity alone is not treated as
+ *    evidence of anything, per DEC-271's warning against inferring from
+ *    timing on its own.
+ *
+ * Returns `null` -- DEC-271's "not observable here" for this one
+ * request/line pair -- when none of the above hold: no shared identifier,
+ * and either the line carries no parseable timestamp or the path/window
+ * test fails. Never fabricates a match to fill the gap.
+ */
+export declare function correlateLogLine(request: CapturedRequestRef, line: IngestedLogLine, options?: CorrelateOptions): Correlation | null;
+//# sourceMappingURL=correlator.d.ts.map

package/dist/correlator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"correlator.d.ts","sourceRoot":"","sources":["../src/correlator.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAGH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,4BAA4B,CAAC;AAG9D,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,eAAe,CAAC;AAErD;;;;;;;;;;GAUG;AACH,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IAChC,QAAQ,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;CACnC;AAED,MAAM,WAAW,gBAAgB;IAC/B;;;;;;OAMG;IACH,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;CAC5B;AAmBD;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,kBAAkB,EAAE,IAAI,EAAE,eAAe,EAAE,OAAO,GAAE,gBAAqB,GAAG,WAAW,GAAG,IAAI,CAqCvI"}

package/dist/correlator.js

@@ -0,0 +1,89 @@
+/**
+ * Correlation between a captured browser/proxy request and an ingested
+ * remote log line (DEC-271's remote side). Follows the same pattern
+ * `backend-observation/correlator.ts`'s `correlateBackendEvidence` already
+ * establishes -- prefer a real shared identifier, never fall back to timing
+ * on its own -- rather than inventing a second correlation shape.
+ *
+ * Reuses `@descryy/runtime-contracts`' `Correlation`/`createCorrelation`
+ * directly: `method` is drawn from the same closed `CorrelationMethod`
+ * union everywhere else in this repo uses, so `isConfirmed` is derived the
+ * same way (`isStructuralCorrelation` -- true for `trace-id`/`request-id`,
+ * false for `timing-context-fallback`) and a reader who already knows that
+ * contract does not have to learn a second one for the remote case.
+ */
+import { randomUUID } from "node:crypto";
+import { createCorrelation } from "@descryy/runtime-contracts";
+const DEFAULT_WINDOW_MS = 5000;
+/**
+ * Confidence assigned to every `"timing-context-fallback"` match. Fixed
+ * rather than scaled by how close the two timestamps are -- DEC-271 asks
+ * for an honestly-stated tier, not a manufactured precision this signal
+ * doesn't actually have: there is no identifier behind it, only two
+ * independent weak cues (a clock and a substring search), so one
+ * deliberately-below-"confirmed" number stands for the whole tier rather
+ * than implying a false gradation within it. The structural distinction
+ * from a confirmed match (`isConfirmed: false`, via `isStructuralCorrelation`)
+ * is what actually matters; this number exists only so two
+ * `Correlation`s are never rendered as equally certain by a reader who
+ * looks at `confidence` alone.
+ */
+const TIMESTAMP_PATH_CONFIDENCE = 0.4;
+/**
+ * Best-effort correlation between one captured request and one ingested log
+ * line, in DEC-271's stated preference order:
+ *
+ * 1. a shared trace id (`method: "trace-id"`, confidence 1) -- the same
+ *    rule and confidence `correlateBackendEvidence` uses for the local case.
+ * 2. a shared request id (`method: "request-id"`, confidence 1).
+ * 3. the request's timestamp within `windowMs` of the line's **and** the
+ *    request's `path` appearing in the line's (already-redacted) text --
+ *    `method: "timing-context-fallback"`, confidence
+ *    `TIMESTAMP_PATH_CONFIDENCE`, `isConfirmed: false`. Both signals are
+ *    required together; timestamp proximity alone is not treated as
+ *    evidence of anything, per DEC-271's warning against inferring from
+ *    timing on its own.
+ *
+ * Returns `null` -- DEC-271's "not observable here" for this one
+ * request/line pair -- when none of the above hold: no shared identifier,
+ * and either the line carries no parseable timestamp or the path/window
+ * test fails. Never fabricates a match to fill the gap.
+ */
+export function correlateLogLine(request, line, options = {}) {
+    if (request.traceId !== null && request.traceId === line.traceId) {
+        return createCorrelation({
+            correlationId: randomUUID(),
+            executionId: request.executionId,
+            method: "trace-id",
+            confidence: 1,
+            evidenceIds: [request.id, line.lineId],
+        });
+    }
+    if (request.requestId !== null && request.requestId === line.requestId) {
+        return createCorrelation({
+            correlationId: randomUUID(),
+            executionId: request.executionId,
+            method: "request-id",
+            confidence: 1,
+            evidenceIds: [request.id, line.lineId],
+        });
+    }
+    // No clock on this line to window against -- not a weaker match, no
+    // match at all. Claiming one would be a guess this module refuses.
+    if (line.timestamp === null)
+        return null;
+    const windowMs = options.windowMs ?? DEFAULT_WINDOW_MS;
+    const deltaMs = Math.abs(new Date(request.timestamp).getTime() - new Date(line.timestamp).getTime());
+    if (deltaMs > windowMs)
+        return null;
+    if (!line.raw.includes(request.path))
+        return null;
+    return createCorrelation({
+        correlationId: randomUUID(),
+        executionId: request.executionId,
+        method: "timing-context-fallback",
+        confidence: TIMESTAMP_PATH_CONFIDENCE,
+        evidenceIds: [request.id, line.lineId],
+    });
+}
+//# sourceMappingURL=correlator.js.map

package/dist/correlator.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"correlator.js","sourceRoot":"","sources":["../src/correlator.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAEzC,OAAO,EAAE,iBAAiB,EAAE,MAAM,4BAA4B,CAAC;AAmC/D,MAAM,iBAAiB,GAAG,IAAI,CAAC;AAE/B;;;;;;;;;;;;GAYG;AACH,MAAM,yBAAyB,GAAG,GAAG,CAAC;AAEtC;;;;;;;;;;;;;;;;;;;GAmBG;AACH,MAAM,UAAU,gBAAgB,CAAC,OAA2B,EAAE,IAAqB,EAAE,UAA4B,EAAE;IACjH,IAAI,OAAO,CAAC,OAAO,KAAK,IAAI,IAAI,OAAO,CAAC,OAAO,KAAK,IAAI,CAAC,OAAO,EAAE,CAAC;QACjE,OAAO,iBAAiB,CAAC;YACvB,aAAa,EAAE,UAAU,EAAE;YAC3B,WAAW,EAAE,OAAO,CAAC,WAAW;YAChC,MAAM,EAAE,UAAU;YAClB,UAAU,EAAE,CAAC;YACb,WAAW,EAAE,CAAC,OAAO,CAAC,EAAE,EAAE,IAAI,CAAC,MAAM,CAAC;SACvC,CAAC,CAAC;IACL,CAAC;IAED,IAAI,OAAO,CAAC,SAAS,KAAK,IAAI,IAAI,OAAO,CAAC,SAAS,KAAK,IAAI,CAAC,SAAS,EAAE,CAAC;QACvE,OAAO,iBAAiB,CAAC;YACvB,aAAa,EAAE,UAAU,EAAE;YAC3B,WAAW,EAAE,OAAO,CAAC,WAAW;YAChC,MAAM,EAAE,YAAY;YACpB,UAAU,EAAE,CAAC;YACb,WAAW,EAAE,CAAC,OAAO,CAAC,EAAE,EAAE,IAAI,CAAC,MAAM,CAAC;SACvC,CAAC,CAAC;IACL,CAAC;IAED,oEAAoE;IACpE,mEAAmE;IACnE,IAAI,IAAI,CAAC,SAAS,KAAK,IAAI;QAAE,OAAO,IAAI,CAAC;IAEzC,MAAM,QAAQ,GAAG,OAAO,CAAC,QAAQ,IAAI,iBAAiB,CAAC;IACvD,MAAM,OAAO,GAAG,IAAI,CAAC,GAAG,CAAC,IAAI,IAAI,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC,OAAO,EAAE,GAAG,IAAI,IAAI,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC,OAAO,EAAE,CAAC,CAAC;IACrG,IAAI,OAAO,GAAG,QAAQ;QAAE,OAAO,IAAI,CAAC;IACpC,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,QAAQ,CAAC,OAAO,CAAC,IAAI,CAAC;QAAE,OAAO,IAAI,CAAC;IAElD,OAAO,iBAAiB,CAAC;QACvB,aAAa,EAAE,UAAU,EAAE;QAC3B,WAAW,EAAE,OAAO,CAAC,WAAW;QAChC,MAAM,EAAE,yBAAyB;QACjC,UAAU,EAAE,yBAAyB;QACrC,WAAW,EAAE,CAAC,OAAO,CAAC,EAAE,EAAE,IAAI,CAAC,MAAM,CAAC;KACvC,CAAC,CAAC;AACL,CAAC"}

package/dist/file-log-adapter.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Concrete adapter #1 for DEC-271's remote side: a log **file** the user
+ * points us at.
+ *
+ * **Chosen over a command-stdout adapter** (`RemoteLogLocation`'s other
+ * named-and-typed option) because it is the simpler case to build correctly
+ * and verify in this pass: deterministic content on disk, no child-process
+ * lifecycle, no question of how a running command's stdout encoding or
+ * buffering interacts with line splitting. A command adapter is the natural
+ * next one -- it would reuse `buildIngestedLogLine` unchanged and differ
+ * only in where the lines come from -- not built this pass.
+ *
+ * **One-shot, not a continuous tail.** This reads the file's contents as of
+ * the call; it does not follow appended writes. Stated rather than silently
+ * partial, per this repo's "honest degradation" rule: a caller that needs
+ * live tailing does not get it from this function today.
+ */
+import type { RedactionPolicy } from "@descryy/runtime-evidence-store";
+import { type IngestedLogLine } from "./log-line.ts";
+import type { RemoteLogSourceConfig } from "./log-source-config.ts";
+export interface FileLogSourceConfig extends RemoteLogSourceConfig {
+    readonly location: {
+        readonly kind: "file";
+        readonly path: string;
+    };
+}
+export interface FileLogAdapterOptions {
+    readonly config: FileLogSourceConfig;
+    readonly redactionPolicy?: RedactionPolicy;
+}
+/**
+ * Reads `config.location.path` and returns one `IngestedLogLine` per
+ * non-empty line, in file order. Every line has already been through
+ * `redact()` by the time it is returned -- see `log-line.ts`.
+ *
+ * A file that cannot be read (missing, permission denied) throws with the
+ * path and the underlying error in the message -- "not observable here" for
+ * this source, surfaced as a rejection a caller must handle, not a silent
+ * empty result indistinguishable from an empty log.
+ */
+export declare function ingestFileLog(options: FileLogAdapterOptions): Promise<readonly IngestedLogLine[]>;
+//# sourceMappingURL=file-log-adapter.d.ts.map

package/dist/file-log-adapter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"file-log-adapter.d.ts","sourceRoot":"","sources":["../src/file-log-adapter.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAGH,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,iCAAiC,CAAC;AAEvE,OAAO,EAAwB,KAAK,eAAe,EAAE,MAAM,eAAe,CAAC;AAC3E,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,wBAAwB,CAAC;AAEpE,MAAM,WAAW,mBAAoB,SAAQ,qBAAqB;IAChE,QAAQ,CAAC,QAAQ,EAAE;QAAE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;KAAE,CAAC;CACrE;AAED,MAAM,WAAW,qBAAqB;IACpC,QAAQ,CAAC,MAAM,EAAE,mBAAmB,CAAC;IACrC,QAAQ,CAAC,eAAe,CAAC,EAAE,eAAe,CAAC;CAC5C;AAED;;;;;;;;;GASG;AACH,wBAAsB,aAAa,CAAC,OAAO,EAAE,qBAAqB,GAAG,OAAO,CAAC,SAAS,eAAe,EAAE,CAAC,CAcvG"}

package/dist/file-log-adapter.js

@@ -0,0 +1,45 @@
+/**
+ * Concrete adapter #1 for DEC-271's remote side: a log **file** the user
+ * points us at.
+ *
+ * **Chosen over a command-stdout adapter** (`RemoteLogLocation`'s other
+ * named-and-typed option) because it is the simpler case to build correctly
+ * and verify in this pass: deterministic content on disk, no child-process
+ * lifecycle, no question of how a running command's stdout encoding or
+ * buffering interacts with line splitting. A command adapter is the natural
+ * next one -- it would reuse `buildIngestedLogLine` unchanged and differ
+ * only in where the lines come from -- not built this pass.
+ *
+ * **One-shot, not a continuous tail.** This reads the file's contents as of
+ * the call; it does not follow appended writes. Stated rather than silently
+ * partial, per this repo's "honest degradation" rule: a caller that needs
+ * live tailing does not get it from this function today.
+ */
+import { readFile } from "node:fs/promises";
+import { buildIngestedLogLine } from "./log-line.js";
+/**
+ * Reads `config.location.path` and returns one `IngestedLogLine` per
+ * non-empty line, in file order. Every line has already been through
+ * `redact()` by the time it is returned -- see `log-line.ts`.
+ *
+ * A file that cannot be read (missing, permission denied) throws with the
+ * path and the underlying error in the message -- "not observable here" for
+ * this source, surfaced as a rejection a caller must handle, not a silent
+ * empty result indistinguishable from an empty log.
+ */
+export async function ingestFileLog(options) {
+    const { config, redactionPolicy } = options;
+    let content;
+    try {
+        content = await readFile(config.location.path, "utf8");
+    }
+    catch (error) {
+        const detail = error instanceof Error ? error.message : String(error);
+        throw new Error(`remote-log-ingestion: could not read log file "${config.location.path}": ${detail}`);
+    }
+    return content
+        .split(/\r?\n/)
+        .filter((line) => line.length > 0)
+        .map((line) => buildIngestedLogLine(line, config, redactionPolicy));
+}
+//# sourceMappingURL=file-log-adapter.js.map

package/dist/file-log-adapter.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"file-log-adapter.js","sourceRoot":"","sources":["../src/file-log-adapter.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,OAAO,EAAE,QAAQ,EAAE,MAAM,kBAAkB,CAAC;AAG5C,OAAO,EAAE,oBAAoB,EAAwB,MAAM,eAAe,CAAC;AAY3E;;;;;;;;;GASG;AACH,MAAM,CAAC,KAAK,UAAU,aAAa,CAAC,OAA8B;IAChE,MAAM,EAAE,MAAM,EAAE,eAAe,EAAE,GAAG,OAAO,CAAC;IAC5C,IAAI,OAAe,CAAC;IACpB,IAAI,CAAC;QACH,OAAO,GAAG,MAAM,QAAQ,CAAC,MAAM,CAAC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC;IACzD,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,MAAM,MAAM,GAAG,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;QACtE,MAAM,IAAI,KAAK,CAAC,kDAAkD,MAAM,CAAC,QAAQ,CAAC,IAAI,MAAM,MAAM,EAAE,CAAC,CAAC;IACxG,CAAC;IAED,OAAO,OAAO;SACX,KAAK,CAAC,OAAO,CAAC;SACd,MAAM,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,MAAM,GAAG,CAAC,CAAC;SACjC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,oBAAoB,CAAC,IAAI,EAAE,MAAM,EAAE,eAAe,CAAC,CAAC,CAAC;AACxE,CAAC"}

package/dist/index.d.ts

@@ -0,0 +1,9 @@
+export type { RemoteLogLocation, RemoteLogFormat, RemoteLogSourceConfig } from "./log-source-config.ts";
+export { REMOTE_LOG_FORMATS } from "./log-source-config.ts";
+export type { IngestedLogLine } from "./log-line.ts";
+export { buildIngestedLogLine } from "./log-line.ts";
+export type { FileLogSourceConfig, FileLogAdapterOptions } from "./file-log-adapter.ts";
+export { ingestFileLog } from "./file-log-adapter.ts";
+export type { CapturedRequestRef, CorrelateOptions } from "./correlator.ts";
+export { correlateLogLine } from "./correlator.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,YAAY,EAAE,iBAAiB,EAAE,eAAe,EAAE,qBAAqB,EAAE,MAAM,wBAAwB,CAAC;AACxG,OAAO,EAAE,kBAAkB,EAAE,MAAM,wBAAwB,CAAC;AAE5D,YAAY,EAAE,eAAe,EAAE,MAAM,eAAe,CAAC;AACrD,OAAO,EAAE,oBAAoB,EAAE,MAAM,eAAe,CAAC;AAErD,YAAY,EAAE,mBAAmB,EAAE,qBAAqB,EAAE,MAAM,uBAAuB,CAAC;AACxF,OAAO,EAAE,aAAa,EAAE,MAAM,uBAAuB,CAAC;AAEtD,YAAY,EAAE,kBAAkB,EAAE,gBAAgB,EAAE,MAAM,iBAAiB,CAAC;AAC5E,OAAO,EAAE,gBAAgB,EAAE,MAAM,iBAAiB,CAAC"}

package/dist/index.js

@@ -0,0 +1,5 @@
+export { REMOTE_LOG_FORMATS } from "./log-source-config.js";
+export { buildIngestedLogLine } from "./log-line.js";
+export { ingestFileLog } from "./file-log-adapter.js";
+export { correlateLogLine } from "./correlator.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":"AACA,OAAO,EAAE,kBAAkB,EAAE,MAAM,wBAAwB,CAAC;AAG5D,OAAO,EAAE,oBAAoB,EAAE,MAAM,eAAe,CAAC;AAGrD,OAAO,EAAE,aAAa,EAAE,MAAM,uBAAuB,CAAC;AAGtD,OAAO,EAAE,gBAAgB,EAAE,MAAM,iBAAiB,CAAC"}

package/dist/log-line.d.ts

@@ -0,0 +1,51 @@
+/**
+ * One ingested log line, redacted before it is ever handed back to a
+ * caller (DEC-271: "log content is redacted before it reaches the model,
+ * not just before display -- the exposure is the read, not the render").
+ *
+ * Reuses `@descryy/runtime-evidence-store`'s `redact()` rather than
+ * reimplementing key-name/body/PII/command scanning -- the same reuse
+ * discipline `database-observation`'s and `browser`'s collectors already
+ * follow for evidence payloads. `redact()`'s own body-bearing-key
+ * convention (`raw`, documented there as the `LogCollector`'s payload key
+ * for captured text) is reused verbatim: every line is wrapped as
+ * `{ raw: line }` before redaction, so a JSON-shaped line gets `redact()`'s
+ * full key-name + text-scan treatment (parsed, walked, redacted key by
+ * key), and a plain-text line gets its text scanned for emails, card
+ * numbers and long tokens -- the same two paths `redactBodyString` already
+ * implements, not a new one.
+ */
+import type { RedactionStatus } from "@descryy/runtime-contracts";
+import { type RedactionPolicy } from "@descryy/runtime-evidence-store";
+import type { RemoteLogSourceConfig } from "./log-source-config.ts";
+export interface IngestedLogLine {
+    readonly lineId: string;
+    /** ISO 8601, or null when no timestamp could be read from the line -- a real absence, not a parse failure hidden as "now". */
+    readonly timestamp: string | null;
+    /** Post-redaction text. There is no path out of `buildIngestedLogLine` that returns pre-redaction content. */
+    readonly raw: string;
+    readonly traceId: string | null;
+    readonly requestId: string | null;
+    readonly redactionStatus: RedactionStatus;
+}
+/**
+ * Builds one `IngestedLogLine` from one raw text line plus the user's
+ * declared `RemoteLogSourceConfig`.
+ *
+ * Identifier extraction always runs against the **pre-redaction** text --
+ * a trace/request id is evidence metadata, not payload content, the same
+ * distinction `Evidence.traceId`/`requestId` draw by living outside
+ * `Evidence.payload` and therefore outside `redact()`'s reach entirely.
+ * Extracting after redaction would try to read an id out of a line that
+ * may already read `[REDACTED]` where the id was.
+ *
+ * Priority, weakest signal overridden by the strongest available, per
+ * DEC-271's "ask, don't guess": `extractCorrelationIds`'s generic
+ * `trace_id=`/`traceparent`/`request_id=` heuristic runs first as a
+ * baseline; a JSON line's own `requestId`/`request_id` field overrides it
+ * when present; and the user's declared `traceIdField`, when it names a
+ * real value on this line, wins over both -- it is the one signal the user
+ * actually told us about rather than one this module inferred.
+ */
+export declare function buildIngestedLogLine(rawLine: string, config: Pick<RemoteLogSourceConfig, "format" | "traceIdField">, redactionPolicy?: RedactionPolicy): IngestedLogLine;
+//# sourceMappingURL=log-line.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"log-line.d.ts","sourceRoot":"","sources":["../src/log-line.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAGH,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,4BAA4B,CAAC;AAClE,OAAO,EAAU,KAAK,eAAe,EAAE,MAAM,iCAAiC,CAAC;AAG/E,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,wBAAwB,CAAC;AAEpE,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,8HAA8H;IAC9H,QAAQ,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IAClC,8GAA8G;IAC9G,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IAChC,QAAQ,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IAClC,QAAQ,CAAC,eAAe,EAAE,eAAe,CAAC;CAC3C;AAkCD;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,oBAAoB,CAClC,OAAO,EAAE,MAAM,EACf,MAAM,EAAE,IAAI,CAAC,qBAAqB,EAAE,QAAQ,GAAG,cAAc,CAAC,EAC9D,eAAe,GAAE,eAAoB,GACpC,eAAe,CAoCjB"}

package/dist/log-line.js

@@ -0,0 +1,101 @@
+/**
+ * One ingested log line, redacted before it is ever handed back to a
+ * caller (DEC-271: "log content is redacted before it reaches the model,
+ * not just before display -- the exposure is the read, not the render").
+ *
+ * Reuses `@descryy/runtime-evidence-store`'s `redact()` rather than
+ * reimplementing key-name/body/PII/command scanning -- the same reuse
+ * discipline `database-observation`'s and `browser`'s collectors already
+ * follow for evidence payloads. `redact()`'s own body-bearing-key
+ * convention (`raw`, documented there as the `LogCollector`'s payload key
+ * for captured text) is reused verbatim: every line is wrapped as
+ * `{ raw: line }` before redaction, so a JSON-shaped line gets `redact()`'s
+ * full key-name + text-scan treatment (parsed, walked, redacted key by
+ * key), and a plain-text line gets its text scanned for emails, card
+ * numbers and long tokens -- the same two paths `redactBodyString` already
+ * implements, not a new one.
+ */
+import { randomUUID } from "node:crypto";
+import { redact } from "@descryy/runtime-evidence-store";
+import { extractCorrelationIds } from "@descryy/runtime-backend-observation";
+const ISO_TIMESTAMP = /\b\d{4}-\d{2}-\d{2}[T ]\d{2}:\d{2}:\d{2}(?:\.\d+)?(?:Z|[+-]\d{2}:?\d{2})?\b/;
+function parseTimestamp(text) {
+    const match = ISO_TIMESTAMP.exec(text);
+    if (match === null)
+        return null;
+    const parsed = new Date(match[0].replace(" ", "T"));
+    return Number.isNaN(parsed.getTime()) ? null : parsed.toISOString();
+}
+function tryParseJsonObject(text) {
+    try {
+        const parsed = JSON.parse(text);
+        return parsed !== null && typeof parsed === "object" && !Array.isArray(parsed) ? parsed : null;
+    }
+    catch {
+        return null;
+    }
+}
+function extractJsonField(record, field) {
+    const value = record[field];
+    return typeof value === "string" && value.length > 0 ? value : null;
+}
+function escapeRegExp(text) {
+    return text.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+function namedFieldFromText(text, field) {
+    const pattern = new RegExp(`\\b${escapeRegExp(field)}["']?\\s*[:=]\\s*["']?([0-9a-zA-Z-]{6,})["']?`, "i");
+    return pattern.exec(text)?.[1] ?? null;
+}
+/**
+ * Builds one `IngestedLogLine` from one raw text line plus the user's
+ * declared `RemoteLogSourceConfig`.
+ *
+ * Identifier extraction always runs against the **pre-redaction** text --
+ * a trace/request id is evidence metadata, not payload content, the same
+ * distinction `Evidence.traceId`/`requestId` draw by living outside
+ * `Evidence.payload` and therefore outside `redact()`'s reach entirely.
+ * Extracting after redaction would try to read an id out of a line that
+ * may already read `[REDACTED]` where the id was.
+ *
+ * Priority, weakest signal overridden by the strongest available, per
+ * DEC-271's "ask, don't guess": `extractCorrelationIds`'s generic
+ * `trace_id=`/`traceparent`/`request_id=` heuristic runs first as a
+ * baseline; a JSON line's own `requestId`/`request_id` field overrides it
+ * when present; and the user's declared `traceIdField`, when it names a
+ * real value on this line, wins over both -- it is the one signal the user
+ * actually told us about rather than one this module inferred.
+ */
+export function buildIngestedLogLine(rawLine, config, redactionPolicy = {}) {
+    const parsedRecord = config.format === "json-lines" ? tryParseJsonObject(rawLine) : null;
+    const generic = extractCorrelationIds(rawLine);
+    let traceId = generic.traceId;
+    let requestId = generic.requestId;
+    let timestamp = parseTimestamp(rawLine);
+    if (parsedRecord !== null) {
+        const tsField = extractJsonField(parsedRecord, "timestamp") ?? extractJsonField(parsedRecord, "time") ?? extractJsonField(parsedRecord, "@timestamp");
+        if (tsField !== null) {
+            const parsedDate = new Date(tsField);
+            if (!Number.isNaN(parsedDate.getTime()))
+                timestamp = parsedDate.toISOString();
+        }
+        const jsonRequestId = extractJsonField(parsedRecord, "requestId") ?? extractJsonField(parsedRecord, "request_id");
+        if (jsonRequestId !== null)
+            requestId = jsonRequestId;
+    }
+    if (config.traceIdField) {
+        const named = parsedRecord !== null ? extractJsonField(parsedRecord, config.traceIdField) : namedFieldFromText(rawLine, config.traceIdField);
+        if (named !== null)
+            traceId = named;
+    }
+    const { payload, redactionStatus } = redact({ raw: rawLine }, redactionPolicy);
+    const redactedRaw = payload.raw;
+    return {
+        lineId: randomUUID(),
+        timestamp,
+        raw: redactedRaw,
+        traceId,
+        requestId,
+        redactionStatus,
+    };
+}
+//# sourceMappingURL=log-line.js.map

package/dist/log-line.js.map

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

package/dist/log-source-config.d.ts

@@ -0,0 +1,65 @@
+/**
+ * The "ask, don't guess" input contract for remote log ingestion (DEC-271).
+ *
+ * For local/booted execution Descry injects its own proxy and needs to ask
+ * the user nothing. For remote environments (staging/preview/production,
+ * DEC-266) Descry does not own the infra and cannot inject anything -- the
+ * only mechanism left is ingesting whatever the target already has, and
+ * DEC-271's own "rejected: one universal mechanism" clause says that target
+ * is heterogeneous by nature (Datadog, CloudWatch, plain stdout, full
+ * OpenTelemetry, or nothing at all). So setup has to ask: where are the
+ * logs, what shape are they in, and is there a field that already carries a
+ * trace/request id.
+ *
+ * This file defines that shape only -- it is filled in by whatever asks the
+ * user (a CLI prompt, a UI form, elsewhere), never inferred or defaulted
+ * here. The logic that consumes it lives in the adapters
+ * (`file-log-adapter.ts` today) and in `correlator.ts`.
+ */
+/**
+ * What the user says they have. `file` and `command` are both plausible
+ * ("here's our log file" / "here's how we tail it") and named so a future
+ * adapter for either has an unambiguous slot; `url` covers a log-query API
+ * or a signed export link. Only `file` has a concrete adapter this pass --
+ * see `file-log-adapter.ts`'s own doc comment for why it was chosen over
+ * `command`, and why `url` isn't built at all yet.
+ */
+export type RemoteLogLocation = {
+    readonly kind: "file";
+    readonly path: string;
+} | {
+    readonly kind: "command";
+    readonly command: string;
+    readonly args?: readonly string[];
+} | {
+    readonly kind: "url";
+    readonly url: string;
+};
+export declare const REMOTE_LOG_FORMATS: readonly ["plain-text", "json-lines"];
+/**
+ * The two shapes this pass knows how to read. Not a claim these are the
+ * only shapes a real target log ever takes (a named convention such as
+ * "Heroku router format" or "Rails tagged logging" is a real future case)
+ * -- narrowed to what `buildIngestedLogLine` actually parses, honestly,
+ * rather than accepting a value it would silently mishandle.
+ */
+export type RemoteLogFormat = (typeof REMOTE_LOG_FORMATS)[number];
+export interface RemoteLogSourceConfig {
+    readonly location: RemoteLogLocation;
+    readonly format: RemoteLogFormat;
+    /**
+     * The field the user says already carries a trace/request id -- a JSON
+     * key for `"json-lines"`, or a `name=`/`name:` field for `"plain-text"`.
+     *
+     * `null`/absent when the user doesn't have one (or doesn't know), in
+     * which case correlation falls back first to `extractCorrelationIds`'s
+     * generic key-shape heuristic and, failing that, to a timestamp+path
+     * window -- both weaker than a declared field, and both disclosed via
+     * `Correlation.method`/`confidence` on the result, never silently
+     * promoted to look as certain as a field the user actually named. This is
+     * the same "ask rather than guess" principle DEC-266 applies to target
+     * URLs, applied here to trace identity.
+     */
+    readonly traceIdField?: string | null;
+}
+//# sourceMappingURL=log-source-config.d.ts.map

package/dist/log-source-config.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"log-source-config.d.ts","sourceRoot":"","sources":["../src/log-source-config.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH;;;;;;;GAOG;AACH,MAAM,MAAM,iBAAiB,GACzB;IAAE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;CAAE,GAChD;IAAE,QAAQ,CAAC,IAAI,EAAE,SAAS,CAAC;IAAC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,IAAI,CAAC,EAAE,SAAS,MAAM,EAAE,CAAA;CAAE,GACzF;IAAE,QAAQ,CAAC,IAAI,EAAE,KAAK,CAAC;IAAC,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAA;CAAE,CAAC;AAEnD,eAAO,MAAM,kBAAkB,uCAAwC,CAAC;AACxE;;;;;;GAMG;AACH,MAAM,MAAM,eAAe,GAAG,CAAC,OAAO,kBAAkB,CAAC,CAAC,MAAM,CAAC,CAAC;AAElE,MAAM,WAAW,qBAAqB;IACpC,QAAQ,CAAC,QAAQ,EAAE,iBAAiB,CAAC;IACrC,QAAQ,CAAC,MAAM,EAAE,eAAe,CAAC;IACjC;;;;;;;;;;;;OAYG;IACH,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CACvC"}

package/dist/log-source-config.js

@@ -0,0 +1,20 @@
+/**
+ * The "ask, don't guess" input contract for remote log ingestion (DEC-271).
+ *
+ * For local/booted execution Descry injects its own proxy and needs to ask
+ * the user nothing. For remote environments (staging/preview/production,
+ * DEC-266) Descry does not own the infra and cannot inject anything -- the
+ * only mechanism left is ingesting whatever the target already has, and
+ * DEC-271's own "rejected: one universal mechanism" clause says that target
+ * is heterogeneous by nature (Datadog, CloudWatch, plain stdout, full
+ * OpenTelemetry, or nothing at all). So setup has to ask: where are the
+ * logs, what shape are they in, and is there a field that already carries a
+ * trace/request id.
+ *
+ * This file defines that shape only -- it is filled in by whatever asks the
+ * user (a CLI prompt, a UI form, elsewhere), never inferred or defaulted
+ * here. The logic that consumes it lives in the adapters
+ * (`file-log-adapter.ts` today) and in `correlator.ts`.
+ */
+export const REMOTE_LOG_FORMATS = ["plain-text", "json-lines"];
+//# sourceMappingURL=log-source-config.js.map

package/dist/log-source-config.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"log-source-config.js","sourceRoot":"","sources":["../src/log-source-config.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAeH,MAAM,CAAC,MAAM,kBAAkB,GAAG,CAAC,YAAY,EAAE,YAAY,CAAU,CAAC"}

package/package.json

@@ -0,0 +1,31 @@
+{
+  "name": "@descryy/runtime-remote-log-ingestion",
+  "version": "0.0.0",
+  "type": "module",
+  "description": "Remote-environment log ingestion (DEC-271): for staging/preview/production, where Descry cannot inject a proxy into infra it doesn't own, ingest whatever the target already has -- logs, and trace ids if a field is declared -- and correlate best-effort against a captured browser/proxy request, with confidence disclosed rather than assumed.",
+  "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.0.0",
+    "@descryy/runtime-backend-observation": "0.0.0",
+    "@descryy/runtime-evidence-store": "0.0.0"
+  }
+}