@descryy/core 0.1.0

package/dist/query/verification-status.js

@@ -0,0 +1,163 @@
+/**
+ * The static half of `verification_status` — `ai-tool-contract.md` §5.6, §8
+ * endpoint 13; AI layer §19/§20 (`Verification status` moved off the
+ * confidence axis); `ai-layer-plan.md` §2 (the trigger → stage mask), §4
+ * technique 6 (a dedicated tool, not appended to every response).
+ *
+ * ## Scope boundary — read this before assuming more than this module builds
+ *
+ * A complete `Verification status` also depends on **which pipeline stages
+ * ran under which trigger mask** (`ai-layer-plan.md` §2: the fast path skips
+ * stages 8-13 entirely) — that is runtime information about one specific
+ * run, and it does not exist in `descry-core`. This repo is the static
+ * knowledge plane; there is no live run here to ask "did stage 9 actually
+ * execute against this file." **This module builds the static half only:**
+ * what a static reading of the graph and a language's declared capabilities
+ * can determine about analysability and resolution. Combining that with the
+ * runtime half — which stages actually ran — is `descry-runtime`/the
+ * pipeline's job, not this one's.
+ *
+ * ## Output shape: `@descryy/ir`'s `VerificationStatus`, not a parallel one
+ *
+ * `packages/ir/src/finding.ts` already defines the shared shape two
+ * repositories (the pipeline and the desktop golden-report test) assert
+ * against — `{ exercised: string[], notExercised: UntestedScope[] }`. This
+ * module produces exactly that, deliberately, rather than a second
+ * "coverage" record: two structures answering the same question would be
+ * exactly the kind of divergence `finding.ts`'s own module doc warns about
+ * for `Finding` itself, one level down.
+ *
+ * An `exercised` entry is `"<ref> (R<resolution>)"` — the scope item's
+ * identifier plus the real resolution level the graph actually holds for it,
+ * because a present node's resolution is a fact worth keeping even though
+ * `VerificationStatus.exercised` is typed as bare strings; see
+ * {@link formatExercised} for the exact grammar and
+ * {@link resolutionOfExercised} for the matching parser. A present item's
+ * resolution is reported as-is and is **never filtered against the
+ * requested check's `minResolution`** — whether R1 is "enough" for a given
+ * claim is a judgement for something above this layer (rule 3's cap, or G4),
+ * not a fact this function may assert.
+ *
+ * ## Hard constraint: no report category, ever
+ *
+ * §19's five report categories (`confirmed` / `strongly supported` /
+ * `unconfirmed` / `not analysable` / `unsupported`) are assigned at G4,
+ * above this surface (`ai-tool-contract.md` §1.2 draws the same line for
+ * result states). This module returns only the raw coverage facts —
+ * reachable-or-not, resolution, a named reason — and never the literal
+ * category vocabulary; a test asserts none of the five strings ever appear
+ * in the output.
+ *
+ * ## Reuses `tiers/certify.ts`'s capability comparison, not a second one
+ *
+ * "Does this language's declared `CapabilityMatrix` cover what a check
+ * needs" is the same question `certify.ts`'s `checkCapability` already
+ * answers for a whole adapter's tier. {@link capabilityGaps} restates that
+ * comparison — declared node/edge types, declared `maxResolution` — at
+ * per-scope-item granularity rather than adapter-wide, so the two never
+ * quietly disagree about what "this language's capabilities satisfy this
+ * requirement" means. It is a restatement rather than an import because
+ * `certify.ts`'s function also folds in precision-draw attestation and
+ * corpus conformance, both properties of a *published tier*, not of one live
+ * scope item — pulling those in here would answer a different question than
+ * the one being asked.
+ *
+ * ## Why this never looks up capabilities by language itself
+ *
+ * `ScopeItem.capabilities` is supplied by the caller, already resolved, per
+ * item — never looked up here from a `language` string. A `Map.get(item.
+ * language)` shape inside `packages/core/src/query/` would be exactly the
+ * IR-boundary leak `descry-boundary/no-language-branch` exists to catch
+ * (architecture principle 7 / `CLAUDE.md` rule 1): deciding behaviour from
+ * *which* language a node came from, not merely from whether one is known.
+ * `certify.ts` holds the same discipline one layer up — it takes one
+ * `GateEvidence` per call and never builds a language-keyed registry inside
+ * `packages/core` either. Resolving "which capabilities apply to this
+ * item's language" is the caller's job, done above this boundary; `language`
+ * is read here only for disclosure (naming it in a reason string), never for
+ * a branch, comparison or lookup.
+ */
+/** `certify.ts`'s own `missing()`, restated: what `wanted` names that `have` does not declare. */
+function missing(wanted, have) {
+    if (wanted === undefined)
+        return [];
+    const present = new Set(have);
+    return wanted.filter((w) => !present.has(w));
+}
+/**
+ * The same comparison `tiers/certify.ts`'s `checkCapability` makes — declared
+ * node/edge types, declared resolution ceiling — restated at one scope
+ * item's granularity. Empty when `caps` declares everything `check` asks
+ * for (which does not, by itself, mean the item was reachable — see the
+ * caller in {@link computeVerificationStatus}).
+ */
+function capabilityGaps(caps, check) {
+    const gaps = [];
+    const nodeGap = missing(check.nodeTypes, caps.nodeTypes);
+    if (nodeGap.length > 0)
+        gaps.push(`capabilities() declares no ${nodeGap.join(", ")}`);
+    const edgeGap = missing(check.edgeTypes, caps.edgeTypes);
+    if (edgeGap.length > 0)
+        gaps.push(`capabilities() declares no ${edgeGap.join(", ")}`);
+    if (check.minResolution !== undefined && caps.maxResolution < check.minResolution) {
+        gaps.push(`maxResolution is R${caps.maxResolution}, below R${check.minResolution}`);
+    }
+    return gaps;
+}
+/** The grammar `computeVerificationStatus` writes `exercised` entries in — see {@link resolutionOfExercised} for the inverse. */
+function formatExercised(ref, resolution) {
+    return `${ref} (R${resolution})`;
+}
+const EXERCISED_PATTERN = /^(.*) \(R([0-4])\)$/;
+/** Parses an `exercised` entry back into its ref and resolution. `null` if `entry` was not produced by {@link formatExercised}. */
+export function resolutionOfExercised(entry) {
+    const m = EXERCISED_PATTERN.exec(entry);
+    if (m === null)
+        return null;
+    return { ref: m[1], resolution: Number(m[2]) };
+}
+/**
+ * Compute the static half of `VerificationStatus` for a scope.
+ *
+ * Per item, one of three outcomes — see the module header for the full
+ * reasoning:
+ *
+ * 1. **Present in the graph** → `exercised`, carrying its real resolution.
+ * 2. **Absent, no capabilities supplied** → `notExercised`, naming the
+ *    language (or that none could be determined).
+ * 3. **Absent, capabilities supplied** → `notExercised`, naming the specific
+ *    declared gap against `check` when there is one, or — the honest edge
+ *    case — that a registered adapter declares everything asked for and a
+ *    static capability comparison alone cannot say why the item is still
+ *    absent.
+ */
+export function computeVerificationStatus(scope, check = {}) {
+    const exercised = [];
+    const notExercised = [];
+    for (const item of scope) {
+        if (item.node !== null) {
+            exercised.push(formatExercised(item.ref, item.node.resolution));
+            continue;
+        }
+        if (item.capabilities === undefined) {
+            notExercised.push({
+                scope: item.ref,
+                reason: item.language === null
+                    ? "this item's language could not be determined, so no adapter can be attributed to it"
+                    : `no adapter is registered for "${item.language}"`,
+            });
+            continue;
+        }
+        const gaps = capabilityGaps(item.capabilities, check);
+        notExercised.push({
+            scope: item.ref,
+            reason: gaps.length > 0
+                ? gaps.join("; ")
+                : `an adapter is registered${item.language === null ? "" : ` for "${item.language}"`} and declares ` +
+                    "everything this check asks for, but this item was not found in the graph — a static capability " +
+                    "comparison cannot say why",
+        });
+    }
+    return { exercised, notExercised };
+}
+//# sourceMappingURL=verification-status.js.map

package/dist/query/verification-status.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"verification-status.js","sourceRoot":"","sources":["../../src/query/verification-status.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8EG;AA8CH,kGAAkG;AAClG,SAAS,OAAO,CAAI,MAAgC,EAAE,IAAkB;IACtE,IAAI,MAAM,KAAK,SAAS;QAAE,OAAO,EAAE,CAAC;IACpC,MAAM,OAAO,GAAG,IAAI,GAAG,CAAC,IAAI,CAAC,CAAC;IAC9B,OAAO,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC;AAC/C,CAAC;AAED;;;;;;GAMG;AACH,SAAS,cAAc,CAAC,IAAsB,EAAE,KAAoB;IAClE,MAAM,IAAI,GAAa,EAAE,CAAC;IAE1B,MAAM,OAAO,GAAG,OAAO,CAAC,KAAK,CAAC,SAAS,EAAE,IAAI,CAAC,SAAS,CAAC,CAAC;IACzD,IAAI,OAAO,CAAC,MAAM,GAAG,CAAC;QAAE,IAAI,CAAC,IAAI,CAAC,8BAA8B,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;IAEtF,MAAM,OAAO,GAAG,OAAO,CAAC,KAAK,CAAC,SAAS,EAAE,IAAI,CAAC,SAAS,CAAC,CAAC;IACzD,IAAI,OAAO,CAAC,MAAM,GAAG,CAAC;QAAE,IAAI,CAAC,IAAI,CAAC,8BAA8B,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;IAEtF,IAAI,KAAK,CAAC,aAAa,KAAK,SAAS,IAAI,IAAI,CAAC,aAAa,GAAG,KAAK,CAAC,aAAa,EAAE,CAAC;QAClF,IAAI,CAAC,IAAI,CAAC,qBAAqB,IAAI,CAAC,aAAa,YAAY,KAAK,CAAC,aAAa,EAAE,CAAC,CAAC;IACtF,CAAC;IAED,OAAO,IAAI,CAAC;AACd,CAAC;AAED,iIAAiI;AACjI,SAAS,eAAe,CAAC,GAAW,EAAE,UAA2B;IAC/D,OAAO,GAAG,GAAG,MAAM,UAAU,GAAG,CAAC;AACnC,CAAC;AAED,MAAM,iBAAiB,GAAG,qBAAqB,CAAC;AAEhD,mIAAmI;AACnI,MAAM,UAAU,qBAAqB,CAAC,KAAa;IACjD,MAAM,CAAC,GAAG,iBAAiB,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;IACxC,IAAI,CAAC,KAAK,IAAI;QAAE,OAAO,IAAI,CAAC;IAC5B,OAAO,EAAE,GAAG,EAAE,CAAC,CAAC,CAAC,CAAE,EAAE,UAAU,EAAE,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC,CAAoB,EAAE,CAAC;AACrE,CAAC;AAED;;;;;;;;;;;;;;GAcG;AACH,MAAM,UAAU,yBAAyB,CACvC,KAA2B,EAC3B,QAAuB,EAAE;IAEzB,MAAM,SAAS,GAAa,EAAE,CAAC;IAC/B,MAAM,YAAY,GAAoB,EAAE,CAAC;IAEzC,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;QACzB,IAAI,IAAI,CAAC,IAAI,KAAK,IAAI,EAAE,CAAC;YACvB,SAAS,CAAC,IAAI,CAAC,eAAe,CAAC,IAAI,CAAC,GAAG,EAAE,IAAI,CAAC,IAAI,CAAC,UAAU,CAAC,CAAC,CAAC;YAChE,SAAS;QACX,CAAC;QAED,IAAI,IAAI,CAAC,YAAY,KAAK,SAAS,EAAE,CAAC;YACpC,YAAY,CAAC,IAAI,CAAC;gBAChB,KAAK,EAAE,IAAI,CAAC,GAAG;gBACf,MAAM,EACJ,IAAI,CAAC,QAAQ,KAAK,IAAI;oBACpB,CAAC,CAAC,qFAAqF;oBACvF,CAAC,CAAC,iCAAiC,IAAI,CAAC,QAAQ,GAAG;aACxD,CAAC,CAAC;YACH,SAAS;QACX,CAAC;QAED,MAAM,IAAI,GAAG,cAAc,CAAC,IAAI,CAAC,YAAY,EAAE,KAAK,CAAC,CAAC;QACtD,YAAY,CAAC,IAAI,CAAC;YAChB,KAAK,EAAE,IAAI,CAAC,GAAG;YACf,MAAM,EACJ,IAAI,CAAC,MAAM,GAAG,CAAC;gBACb,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC;gBACjB,CAAC,CAAC,2BAA2B,IAAI,CAAC,QAAQ,KAAK,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,SAAS,IAAI,CAAC,QAAQ,GAAG,gBAAgB;oBAClG,iGAAiG;oBACjG,2BAA2B;SAClC,CAAC,CAAC;IACL,CAAC;IAED,OAAO,EAAE,SAAS,EAAE,YAAY,EAAE,CAAC;AACrC,CAAC"}

package/dist/recording/index.d.ts

@@ -0,0 +1,26 @@
+/**
+ * The recording store: open it, start a run, record its calls, read them back
+ * in order. See `schema.ts`'s module header for why this is a store of its
+ * own rather than tables added to `../store`.
+ */
+import type { OpenOptions, SqlDriver } from "../store/driver/driver.ts";
+export interface OpenRecordingStoreOptions extends OpenOptions {
+    /** Swap the backend, same as `openStore` — same driver interface, DEC-018. */
+    readonly driver?: SqlDriver;
+}
+export interface RecordingStore {
+    readonly driver: SqlDriver;
+    /** True when this call created the schema, rather than opening an existing store. */
+    readonly created: boolean;
+    close(): void;
+}
+/** Open (or create) a recording store at `path`, or `":memory:"` for a throwaway one. */
+export declare function openRecordingStore(path: string, options?: OpenRecordingStoreOptions): RecordingStore;
+export { RecordingSchemaVersionError, migrateRecording } from "./migrate.ts";
+export { RECORDING_SCHEMA_VERSION, SCHEMA_SQL as RECORDING_SCHEMA_SQL } from "./schema.ts";
+export { startRun, recordCall } from "./writer.ts";
+export type { RunStamp, StartRunOptions, ToolCallRecord, RecordCallOptions, RecordCallResult } from "./writer.ts";
+export { readRun } from "./reader.ts";
+export type { RecordedCall, RecordedRun } from "./reader.ts";
+export { createRecordingRedactor, redactSecretsInText } from "./redact.ts";
+//# sourceMappingURL=index.d.ts.map

package/dist/recording/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/recording/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAGH,OAAO,KAAK,EAAE,WAAW,EAAE,SAAS,EAAE,MAAM,2BAA2B,CAAC;AAGxE,MAAM,WAAW,yBAA0B,SAAQ,WAAW;IAC5D,8EAA8E;IAC9E,QAAQ,CAAC,MAAM,CAAC,EAAE,SAAS,CAAC;CAC7B;AAED,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,MAAM,EAAE,SAAS,CAAC;IAC3B,qFAAqF;IACrF,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;IAC1B,KAAK,IAAI,IAAI,CAAC;CACf;AAED,yFAAyF;AACzF,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,GAAE,yBAA8B,GAAG,cAAc,CAcxG;AAED,OAAO,EAAE,2BAA2B,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAC;AAC7E,OAAO,EAAE,wBAAwB,EAAE,UAAU,IAAI,oBAAoB,EAAE,MAAM,aAAa,CAAC;AAE3F,OAAO,EAAE,QAAQ,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AACnD,YAAY,EAAE,QAAQ,EAAE,eAAe,EAAE,cAAc,EAAE,iBAAiB,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AAElH,OAAO,EAAE,OAAO,EAAE,MAAM,aAAa,CAAC;AACtC,YAAY,EAAE,YAAY,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAE7D,OAAO,EAAE,uBAAuB,EAAE,mBAAmB,EAAE,MAAM,aAAa,CAAC"}

package/dist/recording/index.js

@@ -0,0 +1,30 @@
+/**
+ * The recording store: open it, start a run, record its calls, read them back
+ * in order. See `schema.ts`'s module header for why this is a store of its
+ * own rather than tables added to `../store`.
+ */
+import { NodeSqliteDriver } from "../store/driver/node-sqlite.js";
+import { migrateRecording } from "./migrate.js";
+/** Open (or create) a recording store at `path`, or `":memory:"` for a throwaway one. */
+export function openRecordingStore(path, options = {}) {
+    const driver = options.driver ?? new NodeSqliteDriver();
+    const openOptions = {
+        ...(options.wal === undefined ? {} : { wal: options.wal }),
+        ...(options.readOnly === undefined ? {} : { readOnly: options.readOnly }),
+    };
+    driver.open(path, openOptions);
+    try {
+        const { created } = migrateRecording(driver);
+        return { driver, created, close: () => driver.close() };
+    }
+    catch (error) {
+        driver.close();
+        throw error;
+    }
+}
+export { RecordingSchemaVersionError, migrateRecording } from "./migrate.js";
+export { RECORDING_SCHEMA_VERSION, SCHEMA_SQL as RECORDING_SCHEMA_SQL } from "./schema.js";
+export { startRun, recordCall } from "./writer.js";
+export { readRun } from "./reader.js";
+export { createRecordingRedactor, redactSecretsInText } from "./redact.js";
+//# sourceMappingURL=index.js.map

package/dist/recording/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/recording/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAE,gBAAgB,EAAE,MAAM,gCAAgC,CAAC;AAElE,OAAO,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAC;AAchD,yFAAyF;AACzF,MAAM,UAAU,kBAAkB,CAAC,IAAY,EAAE,UAAqC,EAAE;IACtF,MAAM,MAAM,GAAG,OAAO,CAAC,MAAM,IAAI,IAAI,gBAAgB,EAAE,CAAC;IACxD,MAAM,WAAW,GAAgB;QAC/B,GAAG,CAAC,OAAO,CAAC,GAAG,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,GAAG,EAAE,OAAO,CAAC,GAAG,EAAE,CAAC;QAC1D,GAAG,CAAC,OAAO,CAAC,QAAQ,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,QAAQ,EAAE,OAAO,CAAC,QAAQ,EAAE,CAAC;KAC1E,CAAC;IACF,MAAM,CAAC,IAAI,CAAC,IAAI,EAAE,WAAW,CAAC,CAAC;IAC/B,IAAI,CAAC;QACH,MAAM,EAAE,OAAO,EAAE,GAAG,gBAAgB,CAAC,MAAM,CAAC,CAAC;QAC7C,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,KAAK,EAAE,GAAG,EAAE,CAAC,MAAM,CAAC,KAAK,EAAE,EAAE,CAAC;IAC1D,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,MAAM,CAAC,KAAK,EAAE,CAAC;QACf,MAAM,KAAK,CAAC;IACd,CAAC;AACH,CAAC;AAED,OAAO,EAAE,2BAA2B,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAC;AAC7E,OAAO,EAAE,wBAAwB,EAAE,UAAU,IAAI,oBAAoB,EAAE,MAAM,aAAa,CAAC;AAE3F,OAAO,EAAE,QAAQ,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAGnD,OAAO,EAAE,OAAO,EAAE,MAAM,aAAa,CAAC;AAGtC,OAAO,EAAE,uBAAuB,EAAE,mBAAmB,EAAE,MAAM,aAAa,CAAC"}

package/dist/recording/migrate.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Schema creation and version enforcement for the recording store.
+ *
+ * Mirrors `../store/migrate.ts`'s shape deliberately (create-if-absent, then
+ * verify) but not its recovery path: the graph store's `dropDerived()` exists
+ * because a version mismatch there means "rebuild from source." There is no
+ * source to rebuild a recorded call from, so a mismatch here has exactly one
+ * safe response — refuse to open — and no `dropDerived` equivalent is
+ * provided.
+ */
+import { type SqlDriver } from "../store/driver/driver.ts";
+export declare class RecordingSchemaVersionError extends Error {
+    readonly name = "RecordingSchemaVersionError";
+    readonly found: number;
+    readonly expected: number;
+    constructor(found: number, expected: number);
+}
+/** Create the schema if absent, then verify this build can read the store. */
+export declare function migrateRecording(driver: SqlDriver): {
+    created: boolean;
+};
+//# sourceMappingURL=migrate.d.ts.map

package/dist/recording/migrate.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"migrate.d.ts","sourceRoot":"","sources":["../../src/recording/migrate.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,EAAe,KAAK,SAAS,EAAE,MAAM,2BAA2B,CAAC;AAGxE,qBAAa,2BAA4B,SAAQ,KAAK;IACpD,SAAkB,IAAI,iCAAiC;IACvD,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;gBAEd,KAAK,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM;CAS5C;AAmBD,8EAA8E;AAC9E,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,SAAS,GAAG;IAAE,OAAO,EAAE,OAAO,CAAA;CAAE,CAkBxE"}

package/dist/recording/migrate.js

@@ -0,0 +1,51 @@
+/**
+ * Schema creation and version enforcement for the recording store.
+ *
+ * Mirrors `../store/migrate.ts`'s shape deliberately (create-if-absent, then
+ * verify) but not its recovery path: the graph store's `dropDerived()` exists
+ * because a version mismatch there means "rebuild from source." There is no
+ * source to rebuild a recorded call from, so a mismatch here has exactly one
+ * safe response — refuse to open — and no `dropDerived` equivalent is
+ * provided.
+ */
+import { DriverError } from "../store/driver/driver.js";
+import { RECORDING_SCHEMA_VERSION, SCHEMA_SQL } from "./schema.js";
+export class RecordingSchemaVersionError extends Error {
+    name = "RecordingSchemaVersionError";
+    found;
+    expected;
+    constructor(found, expected) {
+        super(`recording store was written under schema version ${found}, this build expects ${expected}. ` +
+            `Unlike the graph store, recorded calls have no source to rebuild from — this store cannot ` +
+            `be migrated automatically.`);
+        this.found = found;
+        this.expected = expected;
+    }
+}
+function readMeta(driver, key) {
+    return driver.prepare("SELECT key, value FROM recording_meta WHERE key = ?").get(key)?.value;
+}
+function writeMeta(driver, key, value) {
+    driver
+        .prepare("INSERT INTO recording_meta (key, value) VALUES (?, ?) ON CONFLICT(key) DO UPDATE SET value = excluded.value")
+        .run(key, value);
+}
+/** Create the schema if absent, then verify this build can read the store. */
+export function migrateRecording(driver) {
+    return driver.transaction(() => {
+        driver.exec(SCHEMA_SQL);
+        const stored = readMeta(driver, "schema_version");
+        if (stored === undefined) {
+            writeMeta(driver, "schema_version", String(RECORDING_SCHEMA_VERSION));
+            return { created: true };
+        }
+        const found = Number(stored);
+        if (!Number.isInteger(found)) {
+            throw new DriverError(`recording_meta.schema_version is not an integer: ${stored}`);
+        }
+        if (found !== RECORDING_SCHEMA_VERSION)
+            throw new RecordingSchemaVersionError(found, RECORDING_SCHEMA_VERSION);
+        return { created: false };
+    });
+}
+//# sourceMappingURL=migrate.js.map

package/dist/recording/migrate.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"migrate.js","sourceRoot":"","sources":["../../src/recording/migrate.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,EAAE,WAAW,EAAkB,MAAM,2BAA2B,CAAC;AACxE,OAAO,EAAE,wBAAwB,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAEnE,MAAM,OAAO,2BAA4B,SAAQ,KAAK;IAClC,IAAI,GAAG,6BAA6B,CAAC;IAC9C,KAAK,CAAS;IACd,QAAQ,CAAS;IAE1B,YAAY,KAAa,EAAE,QAAgB;QACzC,KAAK,CACH,oDAAoD,KAAK,wBAAwB,QAAQ,IAAI;YAC3F,4FAA4F;YAC5F,4BAA4B,CAC/B,CAAC;QACF,IAAI,CAAC,KAAK,GAAG,KAAK,CAAC;QACnB,IAAI,CAAC,QAAQ,GAAG,QAAQ,CAAC;IAC3B,CAAC;CACF;AAOD,SAAS,QAAQ,CAAC,MAAiB,EAAE,GAAW;IAC9C,OAAO,MAAM,CAAC,OAAO,CAAU,qDAAqD,CAAC,CAAC,GAAG,CAAC,GAAG,CAAC,EAAE,KAAK,CAAC;AACxG,CAAC;AAED,SAAS,SAAS,CAAC,MAAiB,EAAE,GAAW,EAAE,KAAa;IAC9D,MAAM;SACH,OAAO,CACN,6GAA6G,CAC9G;SACA,GAAG,CAAC,GAAG,EAAE,KAAK,CAAC,CAAC;AACrB,CAAC;AAED,8EAA8E;AAC9E,MAAM,UAAU,gBAAgB,CAAC,MAAiB;IAChD,OAAO,MAAM,CAAC,WAAW,CAAC,GAAG,EAAE;QAC7B,MAAM,CAAC,IAAI,CAAC,UAAU,CAAC,CAAC;QAExB,MAAM,MAAM,GAAG,QAAQ,CAAC,MAAM,EAAE,gBAAgB,CAAC,CAAC;QAClD,IAAI,MAAM,KAAK,SAAS,EAAE,CAAC;YACzB,SAAS,CAAC,MAAM,EAAE,gBAAgB,EAAE,MAAM,CAAC,wBAAwB,CAAC,CAAC,CAAC;YACtE,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,CAAC;QAC3B,CAAC;QAED,MAAM,KAAK,GAAG,MAAM,CAAC,MAAM,CAAC,CAAC;QAC7B,IAAI,CAAC,MAAM,CAAC,SAAS,CAAC,KAAK,CAAC,EAAE,CAAC;YAC7B,MAAM,IAAI,WAAW,CAAC,oDAAoD,MAAM,EAAE,CAAC,CAAC;QACtF,CAAC;QACD,IAAI,KAAK,KAAK,wBAAwB;YAAE,MAAM,IAAI,2BAA2B,CAAC,KAAK,EAAE,wBAAwB,CAAC,CAAC;QAE/G,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE,CAAC;IAC5B,CAAC,CAAC,CAAC;AACL,CAAC"}

package/dist/recording/reader.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Reads over the recording store — the replay path.
+ *
+ * `readRun` is deliberately the only read here: replay needs the whole run,
+ * in order, with nothing summarised out. A caller wanting "just the last
+ * call" or "just this tool's calls" can filter `readRun`'s result; a second
+ * entry point that pre-filters would be a second place the ordering guarantee
+ * has to be re-proven.
+ */
+import type { SqlDriver } from "../store/driver/driver.ts";
+import type { RunStamp, ToolCallRecord } from "./writer.ts";
+export interface RecordedCall extends ToolCallRecord {
+    readonly seq: number;
+    readonly recordedAt: number;
+}
+export interface RecordedRun {
+    readonly runId: string;
+    readonly startedAt: number;
+    readonly stamp: RunStamp;
+    readonly promptVersion: string | null;
+    readonly modelId: string | null;
+    /** Ordered by `seq` ascending — the order the calls actually happened in. */
+    readonly calls: readonly RecordedCall[];
+}
+/** The full run, calls ordered by `seq`. `undefined` if no such run was started. */
+export declare function readRun(driver: SqlDriver, runId: string): RecordedRun | undefined;
+//# sourceMappingURL=reader.d.ts.map

package/dist/recording/reader.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"reader.d.ts","sourceRoot":"","sources":["../../src/recording/reader.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAIH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,2BAA2B,CAAC;AAC3D,OAAO,KAAK,EAAE,QAAQ,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAE5D,MAAM,WAAW,YAAa,SAAQ,cAAc;IAClD,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;CAC7B;AAED,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,KAAK,EAAE,QAAQ,CAAC;IACzB,QAAQ,CAAC,aAAa,EAAE,MAAM,GAAG,IAAI,CAAC;IACtC,QAAQ,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IAChC,6EAA6E;IAC7E,QAAQ,CAAC,KAAK,EAAE,SAAS,YAAY,EAAE,CAAC;CACzC;AA4CD,oFAAoF;AACpF,wBAAgB,OAAO,CAAC,MAAM,EAAE,SAAS,EAAE,KAAK,EAAE,MAAM,GAAG,WAAW,GAAG,SAAS,CA4BjF"}

package/dist/recording/reader.js

@@ -0,0 +1,55 @@
+/**
+ * Reads over the recording store — the replay path.
+ *
+ * `readRun` is deliberately the only read here: replay needs the whole run,
+ * in order, with nothing summarised out. A caller wanting "just the last
+ * call" or "just this tool's calls" can filter `readRun`'s result; a second
+ * entry point that pre-filters would be a second place the ordering guarantee
+ * has to be re-proven.
+ */
+import { isToolClass } from "@descryy/ir";
+function rowToCall(row) {
+    if (!isToolClass(row.class)) {
+        // Only reachable if something wrote around recordCall, which is exactly
+        // the case worth failing loudly on rather than coercing.
+        throw new Error(`recorded call at seq ${row.seq} has an unknown class: ${row.class}`);
+    }
+    const toolClass = row.class;
+    return {
+        seq: row.seq,
+        tool: row.tool,
+        toolVersion: row.tool_version,
+        class: toolClass,
+        arguments: JSON.parse(row.arguments),
+        result: JSON.parse(row.result),
+        durationMs: row.duration_ms,
+        cost: row.cost,
+        recordedAt: row.recorded_at,
+    };
+}
+/** The full run, calls ordered by `seq`. `undefined` if no such run was started. */
+export function readRun(driver, runId) {
+    const run = driver
+        .prepare(`SELECT id, started_at, commit_sha, built_at, ir_schema_version, prompt_version, model_id
+         FROM recorded_runs WHERE id = ?`)
+        .get(runId);
+    if (run === undefined)
+        return undefined;
+    const rows = driver
+        .prepare(`SELECT seq, tool, tool_version, class, arguments, result, duration_ms, cost, recorded_at
+         FROM recorded_calls WHERE run_id = ? ORDER BY seq ASC`)
+        .all(runId);
+    return {
+        runId: run.id,
+        startedAt: run.started_at,
+        stamp: {
+            commitSha: run.commit_sha,
+            builtAt: run.built_at,
+            irSchemaVersion: run.ir_schema_version,
+        },
+        promptVersion: run.prompt_version,
+        modelId: run.model_id,
+        calls: rows.map(rowToCall),
+    };
+}
+//# sourceMappingURL=reader.js.map

package/dist/recording/reader.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"reader.js","sourceRoot":"","sources":["../../src/recording/reader.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,EAAE,WAAW,EAAkB,MAAM,aAAa,CAAC;AA0C1D,SAAS,SAAS,CAAC,GAAY;IAC7B,IAAI,CAAC,WAAW,CAAC,GAAG,CAAC,KAAK,CAAC,EAAE,CAAC;QAC5B,wEAAwE;QACxE,yDAAyD;QACzD,MAAM,IAAI,KAAK,CAAC,wBAAwB,GAAG,CAAC,GAAG,0BAA0B,GAAG,CAAC,KAAK,EAAE,CAAC,CAAC;IACxF,CAAC;IACD,MAAM,SAAS,GAAc,GAAG,CAAC,KAAK,CAAC;IACvC,OAAO;QACL,GAAG,EAAE,GAAG,CAAC,GAAG;QACZ,IAAI,EAAE,GAAG,CAAC,IAAI;QACd,WAAW,EAAE,GAAG,CAAC,YAAY;QAC7B,KAAK,EAAE,SAAS;QAChB,SAAS,EAAE,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,SAAS,CAAY;QAC/C,MAAM,EAAE,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,MAAM,CAAY;QACzC,UAAU,EAAE,GAAG,CAAC,WAAW;QAC3B,IAAI,EAAE,GAAG,CAAC,IAAI;QACd,UAAU,EAAE,GAAG,CAAC,WAAW;KAC5B,CAAC;AACJ,CAAC;AAED,oFAAoF;AACpF,MAAM,UAAU,OAAO,CAAC,MAAiB,EAAE,KAAa;IACtD,MAAM,GAAG,GAAG,MAAM;SACf,OAAO,CACN;yCACmC,CACpC;SACA,GAAG,CAAC,KAAK,CAAC,CAAC;IACd,IAAI,GAAG,KAAK,SAAS;QAAE,OAAO,SAAS,CAAC;IAExC,MAAM,IAAI,GAAG,MAAM;SAChB,OAAO,CACN;+DACyD,CAC1D;SACA,GAAG,CAAC,KAAK,CAAC,CAAC;IAEd,OAAO;QACL,KAAK,EAAE,GAAG,CAAC,EAAE;QACb,SAAS,EAAE,GAAG,CAAC,UAAU;QACzB,KAAK,EAAE;YACL,SAAS,EAAE,GAAG,CAAC,UAAU;YACzB,OAAO,EAAE,GAAG,CAAC,QAAQ;YACrB,eAAe,EAAE,GAAG,CAAC,iBAAiB;SACvC;QACD,aAAa,EAAE,GAAG,CAAC,cAAc;QACjC,OAAO,EAAE,GAAG,CAAC,QAAQ;QACrB,KAAK,EAAE,IAAI,CAAC,GAAG,CAAC,SAAS,CAAC;KAC3B,CAAC;AACJ,CAAC"}

package/dist/recording/redact.d.ts

@@ -0,0 +1,63 @@
+/**
+ * A concrete implementation for `writer.ts`'s `RecordCallOptions.redact` seam.
+ *
+ * ## Why this exists
+ *
+ * `schema.ts` and `writer.ts`'s module headers both say the same thing: the
+ * `redact` option is a documented seam, and until something is plugged into
+ * it every row this store writes is exactly what the tool call carried,
+ * including secrets. That was true because nothing in this repository ever
+ * built a redactor — not because building one needs work outside this
+ * repo's scope. This file is that redactor.
+ *
+ * ## Literal substring replacement, never a pattern
+ *
+ * Ported from descry-desktop's `packages/session/src/redact.ts`
+ * (`redactSecrets`) — the model-client redaction seam's own implementation,
+ * the one place in the four-repo split this logic already existed and was
+ * already tested. That file's doc comment states the reason plainly and it
+ * applies here unchanged: **a secret is arbitrary text and must never be
+ * interpreted as a pattern.** A regex-based "looks like an API key" detector
+ * is a recall play — it guesses, and a wrong guess either redacts real data
+ * that was not a secret or misses a secret shaped unlike the pattern.
+ * `CLAUDE.md`'s "precision over recall, when in doubt omit" applies to
+ * redaction exactly as it applies to a graph edge: only redact a value the
+ * caller can actually name as a secret.
+ *
+ * There is no shared package between `descry-core` and `descry-desktop`
+ * today (DEC-001's four-repo split names no fifth "shared utilities" repo),
+ * so this is a deliberate duplication of the minimal literal-substitution
+ * logic rather than a new cross-repo dependency edge. If a third call site
+ * needs this, that is the trigger to extract a shared package — not before.
+ *
+ * ## Why this is still opt-in, not automatic inside `recordCall`
+ *
+ * `recordCall` has no way to know, on its own, which strings in an
+ * arbitrary `arguments`/`result` payload are secrets — that is exactly the
+ * "arbitrary text, not a pattern" problem above. Only a caller holding the
+ * deployment's actual configured secret values (an API key, a token, a DB
+ * password) can supply that list, the same division of responsibility
+ * `createPromptRedactor` uses on the model-client side. Wiring this
+ * redactor into a live `recordCall` call site — the MCP server's tool
+ * dispatch, or `descry-runtime`'s — with real configured secret values is
+ * separate work (the same "P3, the tool boundary" wiring the module headers
+ * already point at), not something this file can do for a caller that does
+ * not exist yet in this repo.
+ */
+import type { ToolCallRecord } from "./writer.ts";
+/**
+ * Replace every occurrence of each secret value in `text` with a fixed
+ * marker. Literal substring replacement, not regex — see this file's module
+ * header for why.
+ */
+export declare function redactSecretsInText(text: string, secretValues: readonly string[]): string;
+/**
+ * Builds a `redact` function for `recordCall`'s seam (`RecordCallOptions`),
+ * given the secret values known at the call site — whatever the caller's own
+ * configuration surface can name as sensitive. Walks both `arguments` and
+ * `result` in full, since a secret passed in can just as easily be echoed
+ * back in a tool's result (an error message quoting the bad input, for
+ * instance) as it can appear in the arguments themselves.
+ */
+export declare function createRecordingRedactor(secretValues: readonly string[]): (call: ToolCallRecord) => ToolCallRecord;
+//# sourceMappingURL=redact.d.ts.map

package/dist/recording/redact.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"redact.d.ts","sourceRoot":"","sources":["../../src/recording/redact.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6CG;AAEH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAIlD;;;;GAIG;AACH,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,MAAM,EAAE,YAAY,EAAE,SAAS,MAAM,EAAE,GAAG,MAAM,CAOzF;AAsBD;;;;;;;GAOG;AACH,wBAAgB,uBAAuB,CACrC,YAAY,EAAE,SAAS,MAAM,EAAE,GAC9B,CAAC,IAAI,EAAE,cAAc,KAAK,cAAc,CAM1C"}

package/dist/recording/redact.js

@@ -0,0 +1,98 @@
+/**
+ * A concrete implementation for `writer.ts`'s `RecordCallOptions.redact` seam.
+ *
+ * ## Why this exists
+ *
+ * `schema.ts` and `writer.ts`'s module headers both say the same thing: the
+ * `redact` option is a documented seam, and until something is plugged into
+ * it every row this store writes is exactly what the tool call carried,
+ * including secrets. That was true because nothing in this repository ever
+ * built a redactor — not because building one needs work outside this
+ * repo's scope. This file is that redactor.
+ *
+ * ## Literal substring replacement, never a pattern
+ *
+ * Ported from descry-desktop's `packages/session/src/redact.ts`
+ * (`redactSecrets`) — the model-client redaction seam's own implementation,
+ * the one place in the four-repo split this logic already existed and was
+ * already tested. That file's doc comment states the reason plainly and it
+ * applies here unchanged: **a secret is arbitrary text and must never be
+ * interpreted as a pattern.** A regex-based "looks like an API key" detector
+ * is a recall play — it guesses, and a wrong guess either redacts real data
+ * that was not a secret or misses a secret shaped unlike the pattern.
+ * `CLAUDE.md`'s "precision over recall, when in doubt omit" applies to
+ * redaction exactly as it applies to a graph edge: only redact a value the
+ * caller can actually name as a secret.
+ *
+ * There is no shared package between `descry-core` and `descry-desktop`
+ * today (DEC-001's four-repo split names no fifth "shared utilities" repo),
+ * so this is a deliberate duplication of the minimal literal-substitution
+ * logic rather than a new cross-repo dependency edge. If a third call site
+ * needs this, that is the trigger to extract a shared package — not before.
+ *
+ * ## Why this is still opt-in, not automatic inside `recordCall`
+ *
+ * `recordCall` has no way to know, on its own, which strings in an
+ * arbitrary `arguments`/`result` payload are secrets — that is exactly the
+ * "arbitrary text, not a pattern" problem above. Only a caller holding the
+ * deployment's actual configured secret values (an API key, a token, a DB
+ * password) can supply that list, the same division of responsibility
+ * `createPromptRedactor` uses on the model-client side. Wiring this
+ * redactor into a live `recordCall` call site — the MCP server's tool
+ * dispatch, or `descry-runtime`'s — with real configured secret values is
+ * separate work (the same "P3, the tool boundary" wiring the module headers
+ * already point at), not something this file can do for a caller that does
+ * not exist yet in this repo.
+ */
+const REDACTED = "[REDACTED]";
+/**
+ * Replace every occurrence of each secret value in `text` with a fixed
+ * marker. Literal substring replacement, not regex — see this file's module
+ * header for why.
+ */
+export function redactSecretsInText(text, secretValues) {
+    let result = text;
+    for (const value of secretValues) {
+        if (value.length === 0)
+            continue; // an empty value would "redact" every character
+        result = result.split(value).join(REDACTED);
+    }
+    return result;
+}
+/**
+ * Walks arbitrary JSON-shaped data — exactly what `ToolCallRecord.arguments`
+ * and `.result` are typed as (`unknown`) — replacing every string leaf via
+ * `redactSecretsInText`. Non-string leaves (numbers, booleans, null) pass
+ * through untouched: a secret value the caller supplied is text, by
+ * definition, so there is nothing to compare a number against.
+ */
+function redactDeep(value, secretValues) {
+    if (typeof value === "string")
+        return redactSecretsInText(value, secretValues);
+    if (Array.isArray(value))
+        return value.map((item) => redactDeep(item, secretValues));
+    if (value !== null && typeof value === "object") {
+        const out = {};
+        for (const [key, entry] of Object.entries(value)) {
+            out[key] = redactDeep(entry, secretValues);
+        }
+        return out;
+    }
+    return value;
+}
+/**
+ * Builds a `redact` function for `recordCall`'s seam (`RecordCallOptions`),
+ * given the secret values known at the call site — whatever the caller's own
+ * configuration surface can name as sensitive. Walks both `arguments` and
+ * `result` in full, since a secret passed in can just as easily be echoed
+ * back in a tool's result (an error message quoting the bad input, for
+ * instance) as it can appear in the arguments themselves.
+ */
+export function createRecordingRedactor(secretValues) {
+    return (call) => ({
+        ...call,
+        arguments: redactDeep(call.arguments, secretValues),
+        result: redactDeep(call.result, secretValues),
+    });
+}
+//# sourceMappingURL=redact.js.map

package/dist/recording/redact.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"redact.js","sourceRoot":"","sources":["../../src/recording/redact.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6CG;AAIH,MAAM,QAAQ,GAAG,YAAY,CAAC;AAE9B;;;;GAIG;AACH,MAAM,UAAU,mBAAmB,CAAC,IAAY,EAAE,YAA+B;IAC/E,IAAI,MAAM,GAAG,IAAI,CAAC;IAClB,KAAK,MAAM,KAAK,IAAI,YAAY,EAAE,CAAC;QACjC,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC;YAAE,SAAS,CAAC,gDAAgD;QAClF,MAAM,GAAG,MAAM,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;IAC9C,CAAC;IACD,OAAO,MAAM,CAAC;AAChB,CAAC;AAED;;;;;;GAMG;AACH,SAAS,UAAU,CAAC,KAAc,EAAE,YAA+B;IACjE,IAAI,OAAO,KAAK,KAAK,QAAQ;QAAE,OAAO,mBAAmB,CAAC,KAAK,EAAE,YAAY,CAAC,CAAC;IAC/E,IAAI,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC;QAAE,OAAO,KAAK,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,UAAU,CAAC,IAAI,EAAE,YAAY,CAAC,CAAC,CAAC;IACrF,IAAI,KAAK,KAAK,IAAI,IAAI,OAAO,KAAK,KAAK,QAAQ,EAAE,CAAC;QAChD,MAAM,GAAG,GAA4B,EAAE,CAAC;QACxC,KAAK,MAAM,CAAC,GAAG,EAAE,KAAK,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,KAAgC,CAAC,EAAE,CAAC;YAC5E,GAAG,CAAC,GAAG,CAAC,GAAG,UAAU,CAAC,KAAK,EAAE,YAAY,CAAC,CAAC;QAC7C,CAAC;QACD,OAAO,GAAG,CAAC;IACb,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,uBAAuB,CACrC,YAA+B;IAE/B,OAAO,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC;QAChB,GAAG,IAAI;QACP,SAAS,EAAE,UAAU,CAAC,IAAI,CAAC,SAAS,EAAE,YAAY,CAAC;QACnD,MAAM,EAAE,UAAU,CAAC,IAAI,CAAC,MAAM,EAAE,YAAY,CAAC;KAC9C,CAAC,CAAC;AACL,CAAC"}

package/dist/recording/schema.d.ts

@@ -0,0 +1,41 @@
+/**
+ * The call-recording schema — `ai-tool-contract.md` §6, rule 5: "every call is
+ * recorded" (§41.15), the basis of replay (`ai-layer-plan.md` §9 layer 6,
+ * §12's reproducibility requirement).
+ *
+ * A separate store from `../store` on purpose, not an extra table bolted onto
+ * the graph schema:
+ *
+ * 1. **The two version numbers move for unrelated reasons.** `IR_SCHEMA_VERSION`
+ *    bumps when the graph's own shape changes; this schema bumps when the
+ *    recording format changes. Coupling them would force a recording-format
+ *    change to carry a graph rebuild, and vice versa.
+ * 2. **Nothing here is "derived."** DEC-017's derived/earned split exists
+ *    because derived rows can be regenerated from source. A recorded call is a
+ *    fact about one already-finished execution — there is no source to
+ *    regenerate it from, ever. Every table below is earned in DEC-017's sense,
+ *    and the version check refuses on mismatch rather than offering a
+ *    `dropDerived()`-equivalent: there is nothing safe to drop.
+ * 3. Same reasoning DEC-018 gives for the graph store applies here unchanged:
+ *    `node:sqlite` behind the existing `SqlDriver` interface, not a second
+ *    persistence technology. This module imports the driver, it does not
+ *    reinvent one.
+ *
+ * ## Unredacted material — read before wiring this to a live tool boundary
+ *
+ * Contract §6: redaction happens *at the tool boundary, before the model
+ * call*. **This store holds whatever `arguments` and `result` it is given,
+ * verbatim, unless a redactor was supplied.** `recordCall`'s `redact` option
+ * (`writer.ts`) is the seam; `redact.ts`'s `createRecordingRedactor` is a
+ * real, tested implementation of it, given the caller's own configured
+ * secret values. No live call site in this repo constructs and passes one
+ * today — recording is not yet wired into the MCP server's or
+ * `descry-runtime`'s actual tool dispatch — so every row written by this
+ * repo's current callers is still unredacted. Treat a database file under
+ * this schema as containing the same sensitive material the tool calls
+ * themselves carried, until whoever wires the live call path passes a
+ * redactor built from real secret values.
+ */
+export declare const RECORDING_SCHEMA_VERSION = 1;
+export declare const SCHEMA_SQL = "\n-- ---------------------------------------------------------------------------\n-- recording_meta \u2014 same role as the graph store's graph_meta: identity of the\n-- store itself, checked before anything else is trusted.\n-- ---------------------------------------------------------------------------\nCREATE TABLE IF NOT EXISTS recording_meta (\n  key   TEXT PRIMARY KEY,\n  value TEXT NOT NULL\n) STRICT;\n\n-- ---------------------------------------------------------------------------\n-- recorded_runs \u2014 one row per AI-layer run. The graph stamp (commit_sha,\n-- built_at, ir_schema_version) is captured ONCE here, per \u00A712: replay needs to\n-- know what graph the run saw, not re-derive it from the first call.\n--\n-- prompt_version and model_id are present and nullable, never a column that\n-- does not exist: \u00A73's rule that \"a missing field and a null field read\n-- identically to a careless caller, and only one of them is honest\" applies\n-- to a database column exactly as it applies to the wire envelope. No model\n-- calls exist yet in this repo, so both are null on every row written today \u2014\n-- that is a true statement about the current build, not a gap in the schema.\n--\n-- next_seq is the ordering counter writer.ts increments atomically with\n-- every insert into recorded_calls, so \"what order did these calls happen in\"\n-- is answerable without trusting wall-clock timestamps, which two calls in the\n-- same millisecond cannot distinguish.\n-- ---------------------------------------------------------------------------\nCREATE TABLE IF NOT EXISTS recorded_runs (\n  id                TEXT    PRIMARY KEY,\n  started_at        INTEGER NOT NULL,\n  commit_sha        TEXT,\n  built_at          TEXT,\n  ir_schema_version INTEGER,\n  prompt_version    TEXT,\n  model_id          TEXT,\n  next_seq          INTEGER NOT NULL DEFAULT 0\n) STRICT;\n\n-- ---------------------------------------------------------------------------\n-- recorded_calls \u2014 one row per tool call. (run_id, seq) is the primary key\n-- rather than an autoincrement id: ordering within a run is the whole point of\n-- seq, and a composite key makes \"give me run X in order\" a primary-key range\n-- scan instead of a sort.\n--\n-- arguments and result are stored as canonicalJson of exactly what the\n-- caller passed \u2014 the full envelope, not a summary. Dropping a field here\n-- (say, disclosures, or the resolution level buried in graph) would make\n-- this store unable to reproduce whatever the finding drew from that field,\n-- which is the one failure mode replay exists to rule out.\n-- ---------------------------------------------------------------------------\nCREATE TABLE IF NOT EXISTS recorded_calls (\n  run_id       TEXT    NOT NULL REFERENCES recorded_runs(id) ON DELETE CASCADE,\n  seq          INTEGER NOT NULL,\n  tool         TEXT    NOT NULL,\n  tool_version TEXT    NOT NULL,\n  class        TEXT    NOT NULL,\n  arguments    TEXT    NOT NULL,\n  result       TEXT    NOT NULL,\n  duration_ms  INTEGER NOT NULL,\n  cost         REAL,\n  recorded_at  INTEGER NOT NULL,\n  PRIMARY KEY (run_id, seq)\n) STRICT;\n";
+//# sourceMappingURL=schema.d.ts.map

package/dist/recording/schema.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"schema.d.ts","sourceRoot":"","sources":["../../src/recording/schema.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqCG;AAEH,eAAO,MAAM,wBAAwB,IAAI,CAAC;AAE1C,eAAO,MAAM,UAAU,kmGA+DtB,CAAC"}