@henols/vice-mcp 0.2.2 → 0.2.3

package/anno-store.ts

@@ -138,11 +138,17 @@ import {
   assertCommentType,
   assertDataType,
   assertEnumName,
+  assertEvidSourceBank,
   assertLabelKind,
   assertLegalLabel,
   assertRangeShape,
+  assertRunIdentityDigest,
+  assertRunIdentitySeed,
   isSplitDataType,
   splitEntryAddressPairs,
+  ADDRESS_MAX,
+  ADDRESS_MIN,
+  AnnoCommentError,
   AnnoCommentGradeError,
   AnnoLabelError,
   AnnoRangeShapeError,
@@ -162,9 +168,13 @@ import {
   type CommentType,
   type ContradictedComment,
   type DataType,
+  type EvidExecRow,
+  type EvidSourceBank,
+  type ExcludedRangeRow,
   type LabelKind,
   type LabelRow,
   type EnumUsageRow,
+  type ObservedRunRow,
   type ProjectEnumRow,
   type RangeRow,
   type ScopeRow,
@@ -179,7 +189,7 @@ import { CONFIDENCE_GRADES, parseConfidencePrefix, AnnoConfidenceGradeError } fr
 // decide "rethrow unchanged" versus "wrap". Every `Anno*Error` in `anno-types.ts`
 // already extends it, so nothing new enters the module graph -- `anno-types.ts`
 // imports the same class from the same file.
-import { ViceError } from "./vice.ts";
+import { ViceError } from "./vice-errors.ts";
 
 /**
  * What every write entry point in this module returns.
@@ -241,6 +251,29 @@ export interface AnnoWriteResult {
  * that NOTHING in this module interprets and no code path reads except the row
  * mapper in `listRanges()`. It is reserved, and every row written today has it
  * null.
+ *
+ * AT `SCHEMA_VERSION` 4 (EVID-01/EVID-02), ONE MORE TABLE IS ADDED:
+ * `anno_evid_exec`, the durable runtime-execution evidence table. See
+ * `anno-types.ts`'s `SCHEMA_VERSION` doc comment for what the bump buys and
+ * the decided, dated fate of an existing version-3 store (`reaffirm-refusal`
+ * -- no migration arm). `anno_evid_exec` carries NO `bank` column and NO
+ * nullable column at all: unlike the annotation tables above, every field on
+ * a row here is a fact the runtime evidence layer is licensed to assert, or
+ * the row does not exist. Its run-identity key is the bare triple
+ * `(image_sha256, argv_digest, seed)`, selected by plan 43-01's live A/B
+ * (`docs/phase43-instrumentation-perturbation-ab.md`, verdict
+ * `no-perturbation`) -- there is deliberately no `run_class` column.
+ *
+ * AT `SCHEMA_VERSION` 5 (`BUILD-07`), ONE MORE TABLE IS ADDED:
+ * `anno_excluded_range`, the durable record of a user-requested exclusion --
+ * its extent and the reason the user gave. See `anno-types.ts`'s
+ * `SCHEMA_VERSION` doc comment for what the bump buys, why a table was chosen
+ * over a column on `anno_range`, and the decided, dated fate of an existing
+ * version-4 store (`reaffirm-refusal` -- no migration arm). `reason` is `not
+ * null`: an exclusion with no reason is a hole with a row in front of it.
+ * `anno_excluded_range` carries NO `bank` column, for the same reason
+ * `ExcludedRangeRow`'s own doc comment gives -- an exclusion is a statement
+ * about the subject program, not a memory view.
  */
 export const DDL = `
 create table anno_meta (
@@ -307,11 +340,31 @@ create table anno_snapshot (
   revision integer primary key
 );
 
+create table anno_evid_exec (
+  id integer primary key autoincrement,
+  image_sha256 text not null,
+  argv_digest text not null,
+  seed text not null,
+  address integer not null,
+  source_bank text not null,
+  unique(image_sha256, argv_digest, seed, address, source_bank)
+);
+
+create table anno_excluded_range (
+  id integer primary key autoincrement,
+  start integer not null,
+  end_inclusive integer not null,
+  reason text not null,
+  unique(start, end_inclusive)
+);
+
 create index anno_range_end_start on anno_range(end_inclusive, start);
 create index anno_label_address on anno_label(address);
 create index anno_comment_address on anno_comment(address);
 create index anno_enum_usage_address on anno_enum_usage(address);
 create index anno_xref_to on anno_xref(to_address);
+create index anno_evid_exec_address on anno_evid_exec(address);
+create index anno_excluded_range_start on anno_excluded_range(start);
 `;
 
 /** An open store: the connection, the resolved store path, and the directory
@@ -539,7 +592,19 @@ export function openStore(
 
   if (meta.schema_version !== SCHEMA_VERSION) {
     db.close();
-    throw new AnnoStoreCorruptError(`${resolved}: schema_version ${meta.schema_version}, expected ${SCHEMA_VERSION}`, { path: resolved });
+    // NAMES THE REMEDY AND DENIES NOTHING IS LOST (EVID-02's checkpoint,
+    // condition 2). This build refuses rather than upgrades -- see
+    // `anno-types.ts`'s `SCHEMA_VERSION` doc comment for the decided,
+    // dated reason -- and the refusal happens BEFORE any write, so the
+    // file on disk is exactly what it was a moment ago: its labels,
+    // comments and enums are not lost, only unreadable by this build.
+    throw new AnnoStoreCorruptError(
+      `${resolved}: schema_version ${meta.schema_version}, expected ${SCHEMA_VERSION} -- refusing to open rather than upgrade. This file is ` +
+        `left exactly as it was: nothing on it is read, rewritten or deleted by this refusal. Open it with a build whose SCHEMA_VERSION is ` +
+        `${meta.schema_version} to read it (see anno-types.ts's SCHEMA_VERSION doc comment for what changed at each version), or hand-copy ` +
+        `its rows into a fresh store at this build's version.`,
+      { path: resolved },
+    );
   }
 
   // WR-04, THE LAST KNOWN FAMILY ESCAPE IN THIS FUNCTION. The two blocks either
@@ -3091,6 +3156,197 @@ export function removeScope(
   return { revision, changed: result };
 }
 
+/**
+ * Records a user-requested exclusion of `start..endInclusive`, with `reason`
+ * stating WHY the user asked for it -- added at `SCHEMA_VERSION` 5
+ * (`BUILD-07`).
+ *
+ * RECORDING AN EXCLUSION CHANGES NOTHING ABOUT WHICH BYTES THE EXPORT EMITS.
+ * The exporter still walks this range's full byte span and emits a real
+ * block, tagged with a visible marker comment, rather than a hole -- that is
+ * `BUILD-07`'s whole invariant. An exporter implementation that skipped the
+ * block on seeing an exclusion row would satisfy the word "exclude" and fail
+ * the requirement outright: this table is a RECORD, never a filter, and the
+ * store answers "what did the user record", never "should this range be
+ * excluded".
+ *
+ * `reason` is validated through `assertCommentText()` -- the ONE comment-text
+ * vocabulary this store has -- BEFORE the write opens, and an empty or
+ * whitespace-only reason is refused with its own message: a `not null`
+ * column satisfied by `""` records that something was excluded and loses WHY,
+ * which is precisely the half of criterion 2 this record exists to carry.
+ *
+ * IDEMPOTENCE FIRST, inside the transaction and BEFORE the overlap check, the
+ * same shape `addScope` uses: an identical repeat -- same extent, same reason
+ * -- is an accepted NO-OP reporting `changed: false`. The SAME extent with a
+ * DIFFERENT reason is REFUSED rather than silently overwritten -- the stored
+ * reason is left exactly as it was, and the route to change it is to remove
+ * the record with `removeExcludedRange` and add it again. Silently replacing
+ * what somebody wrote and reporting success is the failure mode this store's
+ * comment and label verbs already refuse.
+ *
+ * OVERLAP IS REFUSED using `addScope()`'s EXACT predicate --
+ * `start <= ? and end_inclusive >= ?` with the two arguments TRANSPOSED, and
+ * `order by id limit 1` so the message is reproducible -- so adjacency falls
+ * out of the `>=` rather than a second rule: two exclusion records that
+ * merely TOUCH at a boundary are disjoint and both accepted, and they stay
+ * TWO records. The incoming record is NEVER trimmed or split; a caller
+ * wanting a disjoint span reads `listExcludedRanges()` first, or removes the
+ * conflicting record with `removeExcludedRange`.
+ */
+export function addExcludedRange(
+  handle: AnnoStoreHandle,
+  args: { start: number | string; endInclusive: number | string; reason: string; baseRevision?: number },
+): AnnoWriteResult {
+  const start = parseStoreAddress(args.start, { what: "start" });
+  const endInclusive = parseStoreAddress(args.endInclusive, { what: "endInclusive" });
+  assertRangeShape(start, endInclusive, "byte");
+
+  const reason = assertCommentText(args.reason, { what: "exclusion reason" });
+  if (reason.trim() === "") {
+    throw new AnnoCommentError(
+      `exclusion reason is empty or whitespace-only -- a "reason" column satisfied by an empty string records that something was excluded ` +
+        `and loses WHY, which is precisely the half of BUILD-07's criterion 2 this record exists to carry. Supply the reason the user gave.`,
+      { reason: "empty reason" },
+    );
+  }
+
+  const { revision, result } = applyWrite(
+    handle,
+    (db) => {
+      // IDEMPOTENCE FIRST, `addScope`'s own shape: read the existing row
+      // inside the transaction and BEFORE the overlap check, because a
+      // byte-identical exclusion overlaps itself and would otherwise be
+      // refused rather than accepted as the no-op an identical repeat requires.
+      const identical = db
+        .prepare("select id, reason from anno_excluded_range where start = ? and end_inclusive = ?")
+        .get(start, endInclusive) as { id: number; reason: string } | undefined;
+      if (identical) {
+        if (identical.reason === reason) return false;
+        throw new AnnoRangeShapeError(
+          `exclusion ${start}..${endInclusive} ($${start.toString(16).padStart(4, "0")}..$${endInclusive.toString(16).padStart(4, "0")}) ` +
+            `is already recorded (id=${identical.id}) with a DIFFERENT reason -- the stored reason is left EXACTLY as it was. Refusing rather ` +
+            `than silently overwriting what somebody wrote: remove the record with removeExcludedRange and add it again to change the reason.`,
+          { start, endInclusive },
+        );
+      }
+
+      // TWO EXCLUSIONS OVERLAP IFF each starts at or before the other ends.
+      // ADJACENCY FALLS OUT OF THE `>=`, `addScope()`'s exact predicate: an
+      // existing exclusion ending at exactly `start - 1` fails
+      // `end_inclusive >= start`, so touching is not overlapping. `order by id
+      // limit 1` reports the FIRST conflicting row so the message is
+      // reproducible.
+      const overlapper = db
+        .prepare("select id, start, end_inclusive from anno_excluded_range where start <= ? and end_inclusive >= ? order by id limit 1")
+        .get(endInclusive, start) as { id: number; start: number; end_inclusive: number } | undefined;
+      if (overlapper) {
+        throw new AnnoRangeShapeError(
+          `exclusion ${start}..${endInclusive} ($${start.toString(16).padStart(4, "0")}..$${endInclusive.toString(16).padStart(4, "0")}) ` +
+            `overlaps the existing exclusion id=${overlapper.id} ${overlapper.start}..${overlapper.end_inclusive} ` +
+            `($${overlapper.start.toString(16).padStart(4, "0")}..$${overlapper.end_inclusive.toString(16).padStart(4, "0")}) -- the incoming ` +
+            `record is NOT trimmed and NOT split: supply a range disjoint from every existing exclusion. Two exclusions that merely TOUCH at a ` +
+            `boundary are disjoint and both accepted. Read listExcludedRanges() first, or removeExcludedRange the conflicting record.`,
+          { start, endInclusive },
+        );
+      }
+
+      db.prepare("insert into anno_excluded_range(start, end_inclusive, reason) values (?, ?, ?)").run(start, endInclusive, reason);
+      return true;
+    },
+    { baseRevision: args.baseRevision },
+  );
+  return { revision, changed: result };
+}
+
+/** Every recorded exclusion, in ascending `id` order -- insertion order,
+ * matching `listScopes()` and `listRanges()`. A consumer needing address
+ * order sorts it itself, because a second ordering in the store would be a
+ * second answer to the same question. `anno_excluded_range` has no `bank`
+ * column, in the same shape `listScopes()`'s own doc comment uses for the
+ * same absence: an exclusion is a statement about the subject program, not a
+ * memory view. */
+export function listExcludedRanges(handle: AnnoStoreHandle): ExcludedRangeRow[] {
+  const rows = handle.db.prepare("select id, start, end_inclusive, reason from anno_excluded_range order by id").all() as {
+    id: number;
+    start: number;
+    end_inclusive: number;
+    reason: string;
+  }[];
+  return rows.map((row) => ({ id: row.id, start: row.start, endInclusive: row.end_inclusive, reason: row.reason }));
+}
+
+/**
+ * Removes the exclusion whose span is EXACTLY `start..endInclusive`, and
+ * returns `changed: false` when NO exclusion overlaps that span at all --
+ * the exact inverse of `addExcludedRange`, following `removeScope()`.
+ *
+ * THE SPAN MUST MATCH EXACTLY -- both ends, as stored. A record is never
+ * trimmed, split, or partially removed: a span that PARTIALLY OVERLAPS an
+ * existing record (but does not match it end-for-end) is REFUSED BY NAME
+ * rather than silently ignored, because a partial removal would leave a
+ * shape nothing downstream can express, while reporting success. This is
+ * stricter than `removeScope()`, which reports a mismatched span as a plain
+ * no-op -- an exclusion's reason makes a near-miss removal more dangerous to
+ * treat as "nothing happened", since a caller who meant to clear the record
+ * would otherwise walk away believing it gone. A caller that does not know
+ * the stored span reads it from `listExcludedRanges()` first.
+ *
+ * REMOVING A SPAN THAT DOES NOT OVERLAP ANYTHING STORED IS AN ACCEPTED NO-OP
+ * reporting `changed: false`, matching `removeScope`'s own direction: an
+ * inverse that refuses when there is genuinely nothing to undo makes "undo
+ * this" conditional on knowing whether it was ever done.
+ */
+export function removeExcludedRange(
+  handle: AnnoStoreHandle,
+  args: { start: number | string; endInclusive: number | string; baseRevision?: number },
+): AnnoWriteResult {
+  const start = parseStoreAddress(args.start, { what: "start" });
+  const endInclusive = parseStoreAddress(args.endInclusive, { what: "endInclusive" });
+  // The SAME non-split shape check `addExcludedRange`/`removeScope` use, and
+  // for the same reason: an exclusion is not a table, so the split-table
+  // even-count rule must not apply to it.
+  assertRangeShape(start, endInclusive, "byte");
+
+  const { revision, result } = applyWrite(
+    handle,
+    (db) => {
+      const existing = db.prepare("select id from anno_excluded_range where start = ? and end_inclusive = ?").get(start, endInclusive) as
+        | { id: number }
+        | undefined;
+      if (existing) {
+        db.prepare("delete from anno_excluded_range where id = ?").run(existing.id);
+        return true;
+      }
+
+      // NO EXACT MATCH. Before reporting the ordinary "nothing to undo"
+      // no-op, check whether the incoming span PARTIALLY overlaps a stored
+      // record -- the same overlap predicate `addExcludedRange` uses. That
+      // case is refused BY NAME rather than treated as a no-op, because the
+      // caller plainly meant to remove something that exists and a silent
+      // no-op would misreport the outcome.
+      const overlapper = db
+        .prepare("select id, start, end_inclusive from anno_excluded_range where start <= ? and end_inclusive >= ? order by id limit 1")
+        .get(endInclusive, start) as { id: number; start: number; end_inclusive: number } | undefined;
+      if (overlapper) {
+        throw new AnnoRangeShapeError(
+          `removeExcludedRange: ${start}..${endInclusive} ($${start.toString(16).padStart(4, "0")}..${endInclusive
+            .toString(16)
+            .padStart(4, "0")}) does not EXACTLY match the existing exclusion id=${overlapper.id} ${overlapper.start}..${overlapper.end_inclusive} ` +
+            `($${overlapper.start.toString(16).padStart(4, "0")}..$${overlapper.end_inclusive.toString(16).padStart(4, "0")}), which it ` +
+            `partially overlaps -- a record is never trimmed, split, or partially removed, because that would leave a shape nothing downstream ` +
+            `can express while reporting success. Read listExcludedRanges() first to find the exact stored span.`,
+          { start, endInclusive },
+        );
+      }
+
+      return false;
+    },
+    { baseRevision: args.baseRevision },
+  );
+  return { revision, changed: result };
+}
+
 /**
  * Validates one project enum's variants mapping and returns it with its KEYS
  * VERBATIM.
@@ -3406,6 +3662,266 @@ export function listEnumUsage(handle: AnnoStoreHandle): EnumUsageRow[] {
   }));
 }
 
+// ---------------------------------------------------------------------------
+// THE RUNTIME EVIDENCE TABLE (`anno_evid_exec`, `SCHEMA_VERSION` 4, EVID-01).
+// One raw shape used by all three functions below.
+// ---------------------------------------------------------------------------
+
+/** One `anno_evid_exec` row exactly as the column names read on disk --
+ * `snake_case`, matching every other raw-row shape in this module.
+ *
+ * A `type` ALIAS RATHER THAN AN `interface`, and that is load-bearing rather
+ * than stylistic: `node:sqlite`'s `all()` returns `Record<string,
+ * SQLOutputValue>[]`, and casting that to a NAMED `interface` fails TS's
+ * type-assertion comparability check ("neither type sufficiently overlaps")
+ * even though the shapes are identical -- a `type` alias to the same object
+ * shape is accepted. Measured against this exact query shape during this
+ * plan's own implementation. */
+type RawEvidExecRow = {
+  id: number;
+  image_sha256: string;
+  argv_digest: string;
+  seed: string;
+  address: number;
+  source_bank: string;
+};
+
+/** `RawEvidExecRow` -> `EvidExecRow`, the one mapping site both read functions
+ * below share, so the two never drift into disagreeing about the shape. */
+function toEvidExecRow(row: RawEvidExecRow): EvidExecRow {
+  return {
+    id: row.id,
+    imageSha256: row.image_sha256,
+    argvDigest: row.argv_digest,
+    seed: row.seed,
+    address: row.address,
+    sourceBank: row.source_bank as EvidSourceBank,
+  };
+}
+
+/**
+ * Inserts one or more runtime-execution observations for one run identity,
+ * keyed `(imageSha256, argvDigest, seed, address, sourceBank)` -- the
+ * `no-change` composite plan 43-01's live A/B selected, with no `run_class`
+ * discriminator (`docs/phase43-instrumentation-perturbation-ab.md`).
+ *
+ * EVERY FIELD IS VALIDATED BEFORE THE FIRST STATEMENT RUNS, and every
+ * refusal is a named `AnnoTypeError`/`AnnoAddressError` carrying the
+ * offending value and the valid domain -- this module's existing refusal
+ * register, never a fresh one. A caller-supplied `imageSha256`/`argvDigest`
+ * that is not exactly 64 lowercase hex characters, a `seed` that is empty,
+ * an `address` outside `ADDRESS_MIN..ADDRESS_MAX`, or a `sourceBank` outside
+ * the frozen three is refused BEFORE the write transaction opens, so a bad
+ * argument never reaches SQL and never partially inserts the rest of the
+ * batch.
+ *
+ * THE WHOLE INSERT IS ONE `applyWrite` CALLBACK (T-43-09): every observation
+ * in `args.observations` is written -- or skipped -- inside the SAME
+ * transaction that `commitTransaction` commits, so a kill mid-ingest leaves
+ * the set fully committed or fully absent, never a partial row set.
+ *
+ * AN OBSERVATION ALREADY PRESENT IS SKIPPED, NOT RE-INSERTED (EVID-01's
+ * idempotent re-ingest): the existing row is selected first, by the full
+ * unique key, and the insert only runs when it is absent. `changed` is
+ * `false` exactly when every observation in this call was already present --
+ * the same `changed`-is-the-only-no-op-signal contract `AnnoWriteResult`
+ * states for every other write entry point in this module. `revision` still
+ * advances by exactly one on every accepted call, no-op or not, for the same
+ * reason.
+ *
+ * `insertedCount` (WR-02) IS COUNTED INSIDE THIS SAME TRANSACTION, never
+ * derived from a separate read taken before `applyWrite` opens it: a caller
+ * that wants "how many of these rows were actually new" must not be handed a
+ * number computed from a `listExecObservations()` snapshot that a concurrent
+ * writer to the SAME run identity could have moved past between that read
+ * and this insert's own commit. Counting the per-row `existing`/insert
+ * branch already taken above is the one place this number can be exact.
+ */
+export interface InsertExecObservationsResult extends AnnoWriteResult {
+  insertedCount: number;
+}
+
+export function insertExecObservations(
+  handle: AnnoStoreHandle,
+  args: {
+    imageSha256: unknown;
+    argvDigest: unknown;
+    seed: unknown;
+    observations: readonly { address: unknown; sourceBank: unknown }[];
+    baseRevision?: number;
+  },
+): InsertExecObservationsResult {
+  const imageSha256 = assertRunIdentityDigest(args.imageSha256, "imageSha256");
+  const argvDigest = assertRunIdentityDigest(args.argvDigest, "argvDigest");
+  const seed = assertRunIdentitySeed(args.seed);
+
+  if (!Array.isArray(args.observations) || args.observations.length === 0) {
+    throw new AnnoTypeError(`observations must be a non-empty array, got ${JSON.stringify(args.observations)}`, {
+      dataType: args.observations,
+    });
+  }
+  // VALIDATED IN FULL BEFORE THE FIRST STATEMENT, per this function's own
+  // doc comment: a bad entry at index 9 must not leave entries 0..8 written.
+  const parsedObservations = args.observations.map((obs) => ({
+    address: parseStoreAddress((obs as { address: unknown }).address, { what: "address" }),
+    sourceBank: assertEvidSourceBank((obs as { sourceBank: unknown }).sourceBank),
+  }));
+
+  const { revision, result } = applyWrite(
+    handle,
+    (db) => {
+      let insertedCount = 0;
+      for (const obs of parsedObservations) {
+        const existing = db
+          .prepare("select id from anno_evid_exec where image_sha256 = ? and argv_digest = ? and seed = ? and address = ? and source_bank = ?")
+          .get(imageSha256, argvDigest, seed, obs.address, obs.sourceBank) as { id: number } | undefined;
+        if (existing) continue;
+        db.prepare("insert into anno_evid_exec(image_sha256, argv_digest, seed, address, source_bank) values (?, ?, ?, ?, ?)").run(
+          imageSha256,
+          argvDigest,
+          seed,
+          obs.address,
+          obs.sourceBank,
+        );
+        insertedCount++;
+      }
+      return insertedCount;
+    },
+    { baseRevision: args.baseRevision },
+  );
+  return { revision, changed: result > 0, insertedCount: result };
+}
+
+/** One shape used by `listExecObservations`'s four fixed queries below. */
+type EvidRunIdentityFilter = { imageSha256: string; argvDigest: string; seed: string };
+
+/**
+ * Every runtime-execution observation, in ascending ADDRESS then `id` order,
+ * with optional filters on `address` and on the full run identity. Never a
+ * `select *` -- every column is named.
+ *
+ * A RUN-IDENTITY FILTER IS ALL THREE FIELDS TOGETHER OR NONE. A partial
+ * identity (the seed alone, say) would silently widen the match to every
+ * image/argv pair that happens to share it, which is not what "filter by run
+ * identity" means -- refused BY NAME rather than accepted as a wider query
+ * nobody asked for.
+ */
+export function listExecObservations(
+  handle: AnnoStoreHandle,
+  opts: { address?: number | string; imageSha256?: unknown; argvDigest?: unknown; seed?: unknown } = {},
+): EvidExecRow[] {
+  const hasAddress = opts.address !== undefined;
+  const identityFieldsGiven = [opts.imageSha256, opts.argvDigest, opts.seed].filter((v) => v !== undefined).length;
+  if (identityFieldsGiven > 0 && identityFieldsGiven < 3) {
+    throw new AnnoTypeError(
+      "listExecObservations: a run-identity filter requires imageSha256, argvDigest AND seed together -- a partial identity would silently widen the match",
+      { dataType: { imageSha256: opts.imageSha256, argvDigest: opts.argvDigest, seed: opts.seed } },
+    );
+  }
+  const hasIdentity = identityFieldsGiven === 3;
+
+  const address = hasAddress ? parseStoreAddress(opts.address as number | string, { what: "address" }) : undefined;
+  const identity: EvidRunIdentityFilter | undefined = hasIdentity
+    ? {
+        imageSha256: assertRunIdentityDigest(opts.imageSha256, "imageSha256"),
+        argvDigest: assertRunIdentityDigest(opts.argvDigest, "argvDigest"),
+        seed: assertRunIdentitySeed(opts.seed),
+      }
+    : undefined;
+
+  let rows: RawEvidExecRow[];
+  if (address !== undefined && identity !== undefined) {
+    rows = handle.db
+      .prepare(
+        "select id, image_sha256, argv_digest, seed, address, source_bank from anno_evid_exec where address = ? and image_sha256 = ? and argv_digest = ? and seed = ? order by address, id",
+      )
+      .all(address, identity.imageSha256, identity.argvDigest, identity.seed) as RawEvidExecRow[];
+  } else if (address !== undefined) {
+    rows = handle.db
+      .prepare("select id, image_sha256, argv_digest, seed, address, source_bank from anno_evid_exec where address = ? order by address, id")
+      .all(address) as RawEvidExecRow[];
+  } else if (identity !== undefined) {
+    rows = handle.db
+      .prepare(
+        "select id, image_sha256, argv_digest, seed, address, source_bank from anno_evid_exec where image_sha256 = ? and argv_digest = ? and seed = ? order by address, id",
+      )
+      .all(identity.imageSha256, identity.argvDigest, identity.seed) as RawEvidExecRow[];
+  } else {
+    rows = handle.db
+      .prepare("select id, image_sha256, argv_digest, seed, address, source_bank from anno_evid_exec order by address, id")
+      .all() as RawEvidExecRow[];
+  }
+
+  return rows.map(toEvidExecRow);
+}
+
+/**
+ * Every distinct run identity with an `anno_evid_exec` row, its accumulated
+ * observation count, and the `denominator` those counts are a fraction of
+ * (EVID-04).
+ *
+ * WHY A DENOMINATOR IS RETURNED AT ALL, AND WHY IT NEVER FORMS A PERCENTAGE
+ * ITSELF. A bare count invites the reading "the rest is data" -- exactly the
+ * soundness violation EVID-04 forbids (see `RuntimeExecClass`'s own doc
+ * comment in `anno-types.ts`). `denominator` is `ADDRESS_MAX - ADDRESS_MIN +
+ * 1`, read from `anno-types.ts`'s own constants rather than the literal
+ * `65536` -- a caller comparing a run's `observationCount` against it forms
+ * its own fraction, and there is deliberately no rounding site in this
+ * module to do that division for them (see this file's `toFixed` census in
+ * this task's own acceptance criteria).
+ */
+export function listObservedRuns(handle: AnnoStoreHandle): { runs: ObservedRunRow[]; denominator: number } {
+  const rows = handle.db
+    .prepare(
+      "select image_sha256, argv_digest, seed, count(*) as observation_count from anno_evid_exec group by image_sha256, argv_digest, seed order by image_sha256, argv_digest, seed",
+    )
+    .all() as { image_sha256: string; argv_digest: string; seed: string; observation_count: number }[];
+  return {
+    runs: rows.map((row) => ({
+      imageSha256: row.image_sha256,
+      argvDigest: row.argv_digest,
+      seed: row.seed,
+      observationCount: row.observation_count,
+    })),
+    denominator: ADDRESS_MAX - ADDRESS_MIN + 1,
+  };
+}
+
+/**
+ * Deletes every `anno_evid_exec` row for one run identity -- a bracket
+ * reset (EVID-05). A run identity holding no rows returns `changed: false`
+ * and is NOT an error: resetting an empty bracket is the ordinary thing,
+ * matching `clearEnumUsage`'s own direction for the identical case.
+ *
+ * THIS IS THE MODULE'S FIFTH ROW-DELETING STATEMENT. `removeScope`'s doc
+ * block (`anno-store.ts`) states the count as four; this one supersedes it.
+ * The count is written in prose, deliberately without spelling the SQL
+ * prefix a census greps for, so a `grep` over this module counts STATEMENTS
+ * and not the sentences describing them. This statement runs inside the
+ * write sequence's transaction, so a refusal raised anywhere in the
+ * sequence rolls it back with everything else -- and a refusal here can
+ * only come from validating the run-identity arguments themselves, since
+ * deleting zero rows is success, not an error.
+ */
+export function deleteExecObservationsForRun(
+  handle: AnnoStoreHandle,
+  args: { imageSha256: unknown; argvDigest: unknown; seed: unknown; baseRevision?: number },
+): AnnoWriteResult {
+  const imageSha256 = assertRunIdentityDigest(args.imageSha256, "imageSha256");
+  const argvDigest = assertRunIdentityDigest(args.argvDigest, "argvDigest");
+  const seed = assertRunIdentitySeed(args.seed);
+
+  const { revision, result } = applyWrite(
+    handle,
+    (db) => {
+      const info = db.prepare("delete from anno_evid_exec where image_sha256 = ? and argv_digest = ? and seed = ?").run(imageSha256, argvDigest, seed);
+      return Number(info.changes) > 0;
+    },
+    { baseRevision: args.baseRevision },
+  );
+  return { revision, changed: result };
+}
+
 /**
  * Records ONE NON-DERIVABLE cross-reference.
  *