@descryy/runtime-evidence-store 0.0.0

package/dist/evidence-store.d.ts

@@ -0,0 +1,204 @@
+/**
+ * Evidence store (plan §13; plan §36 gate 9 "evidence persistence").
+ * Persistence keyed by executionId, backed by `node:sqlite` — mirrors
+ * descry-core's choice (CLAUDE.md: "node:sqlite behind a driver
+ * interface") for the same reason: zero native deps, no node-gyp-per-
+ * platform distribution problem. A full swappable-driver abstraction
+ * (descry-core's `SqlDriver`) is skipped here — one table, no real
+ * swap-target in view — but the row-rehydration pattern is kept:
+ * `node:sqlite` returns null-prototype row objects, which trips up
+ * `JSON.stringify` and structural-equality checks in ways that are easy to
+ * miss, so every row is spread into a plain object before use.
+ *
+ * `node:sqlite` is experimental in this Node version and prints an
+ * `ExperimentalWarning`. descry-core's own policy is to suppress that only
+ * at a CLI entrypoint, never in library code or tests — this package has
+ * no entrypoint of its own, so nothing here suppresses it.
+ */
+import { type Evidence, type EvidenceSource, type RuntimeEventType } from "@descryy/runtime-contracts";
+import { type RedactionPolicy } from "./redaction.ts";
+import { type EnvironmentFingerprint, type RecordedExecution, type Replay } from "./replay.ts";
+export interface EvidenceStoreOptions {
+    /** A file path, or ":memory:" for tests. Persistence across process restarts (plan §36 gate 9) requires a real path. */
+    readonly path: string;
+    /** Omit for the restricted default (RedactionPolicy's own defaults) -- a caller opts into anything looser, never the reverse. */
+    readonly redactionPolicy?: RedactionPolicy;
+    /**
+     * How long evidence survives a purgeExpired() call, in milliseconds
+     * since its own `timestamp`. Null/omitted: no retention limit, nothing
+     * is ever purged automatically -- purgeExpired() is only ever called
+     * explicitly by a caller, never on a timer this store owns itself.
+     * Orthogonal to replay (plan §30, not built here): retention controls
+     * how long evidence is kept, not what a replay does with what remains.
+     */
+    readonly retentionMs?: number;
+}
+export type EvidenceInput = Omit<Evidence, "evidenceId" | "redactionStatus">;
+/**
+ * Criteria for `EvidenceStore.query`. Every field combines with AND, and
+ * every match is exact — see `query`'s own header for why `executionId` is
+ * required-but-nullable rather than optional.
+ */
+export interface EvidenceQuery {
+    /** Required. `null` is a deliberate statement that a cross-execution answer is wanted; there is no honest default. */
+    readonly executionId: string | null;
+    readonly traceId?: string;
+    readonly requestId?: string;
+    readonly correlationId?: string;
+    readonly service?: string;
+    readonly source?: EvidenceSource;
+    readonly eventType?: RuntimeEventType;
+    readonly graphNodeId?: string;
+    /** Matches `sourceLocation.file` exactly. Evidence with no resolved location never matches. */
+    readonly sourceFile?: string;
+    /** Matches `sourceLocation.line` exactly. */
+    readonly sourceLine?: number;
+    /** Inclusive lower bound on `timestamp` (ISO-8601). */
+    readonly from?: string;
+    /** Inclusive upper bound on `timestamp` (ISO-8601). */
+    readonly to?: string;
+    readonly limit?: number;
+}
+export declare class EvidenceStore {
+    #private;
+    constructor(options: EvidenceStoreOptions);
+    /**
+     * The only way to persist evidence. Redaction runs here, unconditionally
+     * — `EvidenceInput` has no `redactionStatus` field a caller could set,
+     * so there is no way to write a record claiming redaction happened
+     * without redact() actually having run. This is the structural
+     * guarantee plan §28 asks for: "raw runtime evidence must not
+     * automatically become unrestricted AI context."
+     */
+    write(input: EvidenceInput): Evidence;
+    /** Every item this execution produced, oldest first — retrievable after the execution has ended, as long as the store is reopened against the same file (plan §36 gate 9). */
+    getByExecution(executionId: string): Evidence[];
+    getById(evidenceId: string): Evidence | null;
+    /**
+     * Every row whose enum fields this build cannot interpret (§3).
+     *
+     * The explicit runtime path for an unknown event. Reads the raw columns
+     * without rehydrating, so it works on precisely the store that `query()`
+     * refuses — a caller that hits the refusal can call this to learn which
+     * rows, which fields and which values, instead of having a throw and no
+     * next step.
+     *
+     * Deliberately reports rather than repairs. Rewriting an unknown
+     * `event_type` to something this build knows would be inventing an
+     * observation, and deleting the row would destroy evidence that a newer
+     * build can read perfectly well.
+     */
+    integrityCheck(): readonly {
+        readonly evidenceId: string;
+        readonly field: string;
+        readonly value: string;
+    }[];
+    /**
+     * Persist the execution behind an `executionId` (§24).
+     *
+     * **The configuration is redacted on the way in, and that is not an
+     * over-application of §20.** Every one of §20's rows is about an evidence
+     * payload, but `configuration.services[x].command` is a command line, and
+     * a command line is one of the classic places a credential travels:
+     * `node server.mjs --api-key=…`. The same `redact()` the evidence write
+     * path uses runs here, on the same terms, and `redactedKeys` reports what
+     * it caught rather than leaving a caller to guess.
+     *
+     * Re-recording the same `executionId` replaces the row. An execution is
+     * recorded once by the component that owns it; a second record for the
+     * same id is a re-run of that recording, not a second execution.
+     */
+    recordExecution(input: {
+        readonly executionId: string;
+        readonly application: string;
+        readonly repository: string;
+        readonly commit: string;
+        readonly configuration: unknown;
+        readonly recordedAt?: string;
+        readonly environment?: EnvironmentFingerprint;
+    }): RecordedExecution;
+    getExecution(executionId: string): RecordedExecution | null;
+    /**
+     * Replay an execution's evidence (§24).
+     *
+     * **Replays evidence, not the application.** Nothing is spawned, driven or
+     * reissued; this returns what was recorded, in recorded order, so
+     * correlation, findings and an evidence package can be re-derived without
+     * booting anything. A replay that quietly re-executed would produce a *new*
+     * observation while claiming to reproduce an old one.
+     *
+     * Throws for an unrecorded execution rather than returning an empty
+     * replay. Evidence rows can exist for an `executionId` that was never
+     * recorded — that is precisely the pre-§24 state — and answering with
+     * "here is your replay, minus the execution" would present the gap as a
+     * result.
+     */
+    replay(executionId: string, currentEnvironment?: EnvironmentFingerprint): Replay;
+    /**
+     * Record that correlation resolved this evidence to a graph node.
+     *
+     * **Written because the correlation was never durable, and that made two
+     * of the evidence package's four selection tiers inert.** Found by
+     * mutation, not by reading: `assembleEvidencePackage`'s tier 2 queries
+     * `graphNodeId`, and a mutation that dropped the execution scope from that
+     * query changed nothing at all — because in the real pipeline no stored row
+     * has a `graphNodeId` to match. `graphNodeId` was set in memory at
+     * composition time, on a copy, and thrown away with the array that held it.
+     * Every downstream question of the form "what else named this node" was
+     * therefore answerable only for evidence some caller happened to still be
+     * holding.
+     *
+     * **Refuses to re-attribute to a different node.** One observation
+     * genuinely can name two graph entities (RT-052's backend exception names
+     * the endpoint in its text and the function in its stack), and the answer
+     * to that is `EvidenceAttribution` passed alongside the evidence — an
+     * output of correlation, not a property of the observation. Letting this
+     * method overwrite would silently discard the first correlation and leave
+     * the store asserting the second as if it were the only one. Idempotent
+     * for the same node, so re-running a correlation pass is safe.
+     *
+     * Throws for an unknown `evidenceId`: a caller attributing evidence this
+     * store does not hold has a bug, and writing nothing would hide it.
+     */
+    attribute(evidenceId: string, graphNodeId: string): void;
+    /**
+     * The general query surface (§19).
+     *
+     * Before this, the store answered two questions — by id and by execution —
+     * and §19 asks for six axes: trace, service, graph node, source location,
+     * time, and execution. **Five of the six did not exist**, which is
+     * invisible from "evidence persistence works" and was found by auditing
+     * the checklist rather than by anything failing.
+     *
+     * **`executionId` is required and may be explicitly `null`, and that is
+     * the load-bearing design choice here.** Every other field is optional.
+     * Evidence not leaking between executions is a guarantee this repo
+     * enforces elsewhere (`composeFinding` excludes foreign executions with a
+     * named reason), and a query is the obvious way to lose it: ask for a
+     * trace id and quietly receive a prior run's evidence too. Making the
+     * field optional-with-a-default would mean the safe behaviour depends on
+     * remembering to pass something, which is how the default gets forgotten
+     * exactly once. Passing `null` is a deliberate statement that a
+     * cross-execution answer is wanted — the same discipline
+     * `resolveSymbolNode` applies to `repo`, where there is no honest default
+     * either.
+     *
+     * Criteria combine with AND. An empty criteria object plus a null
+     * execution returns everything, which is a real request (a store dump)
+     * and is spelled out rather than reachable by accident.
+     */
+    query(criteria: EvidenceQuery): Evidence[];
+    /**
+     * Deletes every row whose own `timestamp` is older than `retentionMs`
+     * (constructor option) relative to `now` (defaults to the real current
+     * time; overridable so a test can purge without a real sleep). Never
+     * called automatically -- no timer, no call from `write()` -- a caller
+     * decides when retention actually runs. Throws rather than silently
+     * no-op-ing if `retentionMs` was never configured: a caller explicitly
+     * asking to purge with no policy in place is a configuration mistake
+     * worth surfacing, not masking.
+     */
+    purgeExpired(now?: Date): number;
+    close(): void;
+}
+//# sourceMappingURL=evidence-store.d.ts.map

package/dist/evidence-store.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"evidence-store.d.ts","sourceRoot":"","sources":["../src/evidence-store.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAIH,OAAO,EAIL,KAAK,QAAQ,EACb,KAAK,cAAc,EACnB,KAAK,gBAAgB,EACtB,MAAM,4BAA4B,CAAC;AACpC,OAAO,EAAU,KAAK,eAAe,EAAE,MAAM,gBAAgB,CAAC;AAC9D,OAAO,EAGL,KAAK,sBAAsB,EAC3B,KAAK,iBAAiB,EACtB,KAAK,MAAM,EAEZ,MAAM,aAAa,CAAC;AAErB,MAAM,WAAW,oBAAoB;IACnC,wHAAwH;IACxH,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,iIAAiI;IACjI,QAAQ,CAAC,eAAe,CAAC,EAAE,eAAe,CAAC;IAC3C;;;;;;;OAOG;IACH,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;CAC/B;AAED,MAAM,MAAM,aAAa,GAAG,IAAI,CAAC,QAAQ,EAAE,YAAY,GAAG,iBAAiB,CAAC,CAAC;AAsB7E;;;;GAIG;AACH,MAAM,WAAW,aAAa;IAC5B,sHAAsH;IACtH,QAAQ,CAAC,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;IACpC,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,aAAa,CAAC,EAAE,MAAM,CAAC;IAChC,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,MAAM,CAAC,EAAE,cAAc,CAAC;IACjC,QAAQ,CAAC,SAAS,CAAC,EAAE,gBAAgB,CAAC;IACtC,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAC9B,+FAA+F;IAC/F,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;IAC7B,6CAA6C;IAC7C,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;IAC7B,uDAAuD;IACvD,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IACvB,uDAAuD;IACvD,QAAQ,CAAC,EAAE,CAAC,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;CACzB;AAED,qBAAa,aAAa;;gBAKZ,OAAO,EAAE,oBAAoB;IA8DzC;;;;;;;OAOG;IACH,KAAK,CAAC,KAAK,EAAE,aAAa,GAAG,QAAQ;IAiDrC,8KAA8K;IAC9K,cAAc,CAAC,WAAW,EAAE,MAAM,GAAG,QAAQ,EAAE;IAO/C,OAAO,CAAC,UAAU,EAAE,MAAM,GAAG,QAAQ,GAAG,IAAI;IAK5C;;;;;;;;;;;;;OAaG;IACH,cAAc,IAAI,SAAS;QACzB,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;QAC5B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;QACvB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;KACxB,EAAE;IA0BH;;;;;;;;;;;;;;OAcG;IACH,eAAe,CAAC,KAAK,EAAE;QACrB,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;QAC7B,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;QAC7B,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;QAC5B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;QACxB,QAAQ,CAAC,aAAa,EAAE,OAAO,CAAC;QAChC,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;QAC7B,QAAQ,CAAC,WAAW,CAAC,EAAE,sBAAsB,CAAC;KAC/C,GAAG,iBAAiB;IA2CrB,YAAY,CAAC,WAAW,EAAE,MAAM,GAAG,iBAAiB,GAAG,IAAI;IAiB3D;;;;;;;;;;;;;;OAcG;IACH,MAAM,CAAC,WAAW,EAAE,MAAM,EAAE,kBAAkB,CAAC,EAAE,sBAAsB,GAAG,MAAM;IAuDhF;;;;;;;;;;;;;;;;;;;;;;;;;OAyBG;IACH,SAAS,CAAC,UAAU,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,GAAG,IAAI;IAgBxD;;;;;;;;;;;;;;;;;;;;;;;;;OAyBG;IACH,KAAK,CAAC,QAAQ,EAAE,aAAa,GAAG,QAAQ,EAAE;IA4D1C;;;;;;;;;OASG;IACH,YAAY,CAAC,GAAG,GAAE,IAAiB,GAAG,MAAM;IAS5C,KAAK,IAAI,IAAI;CAGd"}