@descryy/runtime-evidence-store 0.3.0 → 0.4.0

package/LICENSE

@@ -0,0 +1,6 @@
+Copyright (c) Descry
+
+All rights reserved. This software is proprietary and confidential.
+No license, express or implied, to reproduce, distribute, modify, or
+create derivative works is granted except as explicitly agreed in
+writing.

package/dist/evidence-store.d.ts

@@ -1,44 +1,31 @@
 /**
- * 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.
+ * Evidence store, keyed by executionId, backed by `node:sqlite` (mirrors
+ * descry-core's driver choice: zero native deps, no node-gyp problem). No
+ * swappable-driver abstraction here — one table, no swap target — but the
+ * row-rehydration pattern is kept: `node:sqlite` returns null-prototype
+ * rows, which trips up `JSON.stringify` and equality checks, 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.
+ * `node:sqlite` prints an `ExperimentalWarning`; suppressed only at a CLI
+ * entrypoint by policy, and this package has none, so nothing suppresses it here.
  */
 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. */
+    /** A file path, or ":memory:" for tests. Persistence across restarts 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. */
+    /** Omit for the restricted default — 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.
+     * How long evidence survives a `purgeExpired()` call, in ms since its
+     * `timestamp`. Null/omitted: never purged automatically — purge only
+     * runs when a caller explicitly calls it, never on a timer this store owns.
      */
     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.
- */
+/** Criteria for `EvidenceStore.query`. Every field combines with AND, every match exact — see `query`'s header for why `executionId` is required-but-nullable. */
 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;
@@ -63,30 +50,22 @@ export declare class EvidenceStore {
     #private;
     constructor(options: EvidenceStoreOptions);
     /**
-     * The only way to persist evidence. Redaction runs here, unconditionally
+     * 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."
+     * so there's no way to write a record claiming redaction happened
+     * without it actually running (§28's structural guarantee).
      */
     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). */
+    /** Every item this execution produced, oldest first — retrievable after the execution ends, as long as the store reopens against the same file. */
     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.
+     * Every row whose enum fields this build can't interpret. Reads raw
+     * columns without rehydrating, so it works on the store that `query()`
+     * refuses — gives a caller a next step instead of just a throw. Reports
+     * rather than repairs: rewriting an unknown value would invent an
+     * observation, and deleting the row would destroy evidence a newer build
+     * can read fine.
      */
     integrityCheck(): readonly {
         readonly evidenceId: string;
@@ -94,19 +73,15 @@ export declare class EvidenceStore {
         readonly value: string;
     }[];
     /**
-     * Persist the execution behind an `executionId` (§24).
+     * Persist the execution behind an `executionId`.
      *
-     * **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.
+     * The configuration is redacted on the way in too —
+     * `configuration.services[x].command` is a command line, a classic place
+     * a credential travels. Same `redact()` as the evidence write path;
+     * `redactedKeys` reports what it caught.
      *
-     * 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.
+     * Re-recording the same `executionId` replaces the row — a second record
+     * is a re-run of that recording, not a second execution.
      */
     recordExecution(input: {
         readonly executionId: string;
@@ -137,84 +112,51 @@ export declare class EvidenceStore {
     orphanedExecutionIds(): readonly string[];
     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.
+     * Replay an execution's evidence. Replays evidence, not the application —
+     * nothing is spawned, driven or reissued, just returned in recorded
+     * order. A replay that 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 — evidence rows can exist for an id that was never recorded,
+     * 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.
+     * Written because correlation was never durable — `graphNodeId` was set
+     * in memory at composition time, on a copy, and thrown away with it,
+     * making two of the evidence package's four selection tiers inert.
+     * Found by mutation testing, not by reading.
      *
-     * Throws for an unknown `evidenceId`: a caller attributing evidence this
-     * store does not hold has a bug, and writing nothing would hide it.
+     * Refuses to re-attribute to a different node: one observation can
+     * genuinely name two graph entities (RT-052), and that's expressed as an
+     * `EvidenceAttribution` alongside the evidence, not by overwriting the
+     * stored one. Idempotent for the same node. Throws for an unknown
+     * `evidenceId` — a caller bug, not something to write around silently.
      */
     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.
+     * The general query surface. Before this, the store answered two
+     * questions (by id, by execution); five of six needed axes didn't exist.
      *
-     * **`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.
+     * `executionId` is required and may be explicitly `null` — the
+     * load-bearing choice here. Making it optional-with-a-default risks a
+     * caller forgetting it and silently leaking evidence across executions;
+     * passing `null` is a deliberate statement that a cross-execution answer
+     * is wanted, same discipline `resolveSymbolNode` applies to `repo`.
      *
-     * 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.
+     * Criteria combine with AND. Empty criteria + null execution returns
+     * everything — a real request (store dump), spelled out on purpose.
      */
     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.
+     * Deletes rows older than `retentionMs` relative to `now` (overridable
+     * for tests). Never called automatically. Throws rather than no-op-ing
+     * if `retentionMs` was never configured — purging with no policy is a
+     * config mistake worth surfacing.
      */
     purgeExpired(now?: Date): number;
     close(): void;

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

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