@henols/vice-mcp 0.2.2 → 0.2.4

package/anno-tools.ts

@@ -77,9 +77,10 @@
 //
 // `anno_batch_execute` IS THE ONE SANCTIONED NESTED-ARGUMENT VERB ON THIS
 // SURFACE, AND NO SECOND MAY JOIN IT. A meta-tool that takes an arbitrary tool
-// name inside its own arguments is precisely the smuggling shape `vice.ts`'s
-// `DENY_LIST` exists to close: the outer name passes the gate while the inner
-// name never sees it. This one verb earns the exception by being the only
+// name inside its own arguments is precisely the confused-deputy shape a
+// generic meta-tool surface this project closed once had, with an
+// outer-name-only refusal array: the outer name passes the gate while the
+// inner name never sees it. This one verb earns the exception by being the only
 // route to the multi-edit pass an annotation run actually performs, and it
 // pays for it with `assertAnnoBatch()` below -- a recursive, DEPTH-CAPPED
 // pre-validator that refuses the WHOLE batch, before any store is opened, if
@@ -134,19 +135,28 @@ import { existsSync, readFileSync, statSync } from "node:fs";
 import { extname } from "node:path";
 
 import {
+  addExcludedRange,
   addScope,
   applyEnumUsage,
+  applyWrite,
   clearEnumUsage,
   closeStore,
   createProjectEnum,
   currentRevision,
+  deleteExecObservationsForRun,
+  insertExecObservations,
   listComments,
   listEnumUsage,
+  listExcludedRanges,
+  listExecObservations,
   listLabels,
+  listObservedRuns,
   listProjectEnums,
   listRanges,
   listScopes,
+  listXrefs,
   openStore,
+  removeExcludedRange,
   removeScope,
   setComment,
   setDataType,
@@ -158,6 +168,7 @@ import {
   AnnoRevisionArgumentError,
   AnnoStoreError,
   AnnoStorePathError,
+  AnnoStoreStaleRevisionError,
   assertCommentText,
   assertCommentType,
   assertDataType,
@@ -166,13 +177,39 @@ import {
   assertLegalLabel,
   assertRangeShape,
   parseStoreAddress,
+  parseVariantKey,
   storePathWithinWorkspace,
 } from "./anno-types.ts";
-import type { AnnoStoreErrorOptions, CommentRow, LabelRow } from "./anno-types.ts";
+import type { AnnoStoreErrorOptions, CommentRow, EnumUsageRow, LabelRow, ProjectEnumRow } from "./anno-types.ts";
 import { crossReferencesTo, searchAnnotations } from "./anno-derive.ts";
 import { composeAddressDetails } from "./anno-details.ts";
 import { decode } from "./disasm-decoder.ts";
+import type { Instruction } from "./disasm-decoder.ts";
 import { render } from "./disasm-renderer.ts";
+// D-16's SECOND renderer (plan 45-05): `anno-export-asm.ts` carries the
+// proof (a real-ACME byte-diff oracle), this file carries the readability --
+// both call decomposeRegisterValue(), the ONE owning decoder, and NEITHER
+// decodes a bit itself. `REGISTER_ENUM_NAME_RE` below is deliberately a
+// SEPARATE, small predicate from `anno-export-asm.ts`'s own copy: D-16 names
+// two renderers, each owning its own substitution glue, and only the decoder
+// itself is shared. `hasRegBitsEntry()` is likewise shared (45-REVIEW CR-01,
+// fixed 2026-09-11): both renderers gate the decoder attempt on TABLE
+// MEMBERSHIP, not name shape alone, via this one exported predicate -- a
+// second, locally-derived membership test would be exactly the kind of
+// "two answers to one question" this file's own header elsewhere refuses.
+import { decomposeRegisterValue, hasRegBitsEntry, type RegisterDecomposition } from "./anno-enum-gen.ts";
+import { importGhidraExport } from "./anno-import.ts";
+import type { ConstWriteFact } from "./anno-import.ts";
+import { runMemmapJoin } from "./anno-join.ts";
+import { accessMapRanges, parseAccessMap } from "./textmon-memmap.ts";
+import { ingestAccessMap, runIdentityFrom, type IngestRunIdentity } from "./evid-ingest.ts";
+import { reconcileObservedExecution } from "./evid-reconcile.ts";
+// The pure, read-only movement-hazard report. Declares its own
+// input shapes and never reads a store, a file or a tool on its own behalf --
+// the SAME caller-fetches-everything split `anno-coverage.ts`'s own header
+// states for the coverage instrument, and exactly why the store re-point
+// below is a CALLER-side change and nothing more.
+import { buildHazardReport } from "./anno-hazard-report.ts";
 import { flatImageOrigin, parsePrg } from "./prg-image.ts";
 import { repoRoot } from "./repo-root.ts";
 
@@ -322,6 +359,22 @@ function assertMaxResults(name: string, args: unknown, batchIndex?: number): num
   return raw as number;
 }
 
+/** `anno_evid_disagreements`'s own OPTIONAL `max_results` (plan 43-06).
+ * Unlike every other list-returning verb (`assertMaxResults` above, REQUIRED
+ * with no default), an unbounded disagreement report is the ordinary case: a
+ * sound store often disagrees nowhere at all, and forcing a ceiling on a
+ * legitimately small or empty answer would buy nothing. When SUPPLIED, the
+ * bound and refusal wording are the SAME as `assertMaxResults`'s -- this is
+ * not a second, looser rule, only an optional one. */
+function assertOptionalMaxResults(name: string, args: unknown, batchIndex?: number): number | undefined {
+  const raw = argBag(args).max_results;
+  if (raw === undefined) return undefined;
+  if (typeof raw !== "number" || !Number.isInteger(raw) || raw <= 0) {
+    refuseArg(name, "max_results", `"max_results" must be a positive integer when supplied, got ${JSON.stringify(raw)}.`, batchIndex);
+  }
+  return raw as number;
+}
+
 /** Requires a present argument and hands it to `parseStoreAddress` -- the ONE
  * address parser, which owns the `$`/`0x` forms and the deliberate refusal of
  * an unprefixed numeric string. Absence is a DIFFERENT fact from malformity,
@@ -587,6 +640,53 @@ export const ANNO_TOOL_DEFINITIONS: readonly AnnoToolDefinition[] = [
       required: ["store", "start_address", "end_address"],
     },
   },
+  {
+    name: "anno_exclude_range",
+    description:
+      "Records the user's request to leave an inclusive span out, WITH the reason, as a durable row (BUILD-05/BUILD-07). " +
+      "RECORDING AN EXCLUSION DOES NOT REMOVE ANYTHING: the export still emits every byte of that span; the record is " +
+      "what makes the request VISIBLE in the output instead of invisible as a gap. What gets reversed, kept or left out " +
+      "is the end-user's decision, and this verb is how the user states it -- it is not the tool deciding. An " +
+      "overlapping span is REFUSED naming both spans; two records that merely TOUCH at a boundary are disjoint and both " +
+      "accepted; an identical repeat SUCCEEDS reporting `changed: false`; the same extent with a DIFFERENT reason is " +
+      "REFUSED rather than overwriting the stored reason. MIND THE ENDS: one transposed end makes every later exclusion " +
+      "overlapping that start refuse -- use anno_include_range to undo it rather than burning revisions off the 32-deep " +
+      "snapshot ring.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        ...STORE_PROPERTY,
+        start_address: { description: "Start of the excluded span, INCLUSIVE. Integer, \"$hex\" or \"0x\" string." },
+        end_address: { description: "End of the excluded span, INCLUSIVE." },
+        reason: {
+          type: "string",
+          description:
+            "Why the user asked for this span to be left out. REQUIRED and must be non-empty: a reason column " +
+            "satisfied by an empty string records that something was excluded and loses WHY.",
+        },
+        ...BASE_REVISION_PROPERTY,
+      },
+      required: ["store", "start_address", "end_address", "reason"],
+    },
+  },
+  {
+    name: "anno_include_range",
+    description:
+      "Removes the exclusion whose span is EXACTLY start_address..end_address -- the exact inverse of anno_exclude_range. " +
+      "Both stored ends must match exactly, because a record is never trimmed, split or partially removed. Read the " +
+      "stored spans with anno_exclude_range's sibling read (the excludedRanges list on either verb's own success body) " +
+      "first if you are unsure. Removing an exclusion that is not there SUCCEEDS and reports `changed: false`.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        ...STORE_PROPERTY,
+        start_address: { description: "Start of the exclusion to remove, INCLUSIVE. Must match the stored start exactly." },
+        end_address: { description: "End of the exclusion to remove, INCLUSIVE. Must match the stored end exactly." },
+        ...BASE_REVISION_PROPERTY,
+      },
+      required: ["store", "start_address", "end_address"],
+    },
+  },
   {
     name: "anno_get_symbols",
     description:
@@ -765,7 +865,11 @@ export const ANNO_TOOL_DEFINITIONS: readonly AnnoToolDefinition[] = [
       "fail to reassemble. The extent is bounded by the SAME byte cap that governs anno_read_region -- one cap, both " +
       "views, so there is no per-view rule to get subtly wrong -- and defaults to that cap when end_address is " +
       "omitted. A wider range is REFUSED by name with the cap and the requested width in the message, never " +
-      "silently truncated.",
+      "silently truncated. A register write bound to a project enum (via anno_apply_enum_usage) renders through " +
+      "its named member instead of a hex literal -- a single-field register as `#<enum>_<VARIANT>`, or, for a " +
+      "multi-field register, as its bits OR-ed together by name (`#D018_SELECT..0 | D018_CHARACTER..2 | " +
+      "D018_VIDEO..0`) with a trailing comment naming every field and its decoded value, so a bound write reads " +
+      "the same way here as it does in the exported ACME source.",
     inputSchema: {
       type: "object",
       properties: {
@@ -936,6 +1040,283 @@ export const ANNO_TOOL_DEFINITIONS: readonly AnnoToolDefinition[] = [
       required: ["store", "calls"],
     },
   },
+  {
+    name: "anno_import_ghidra_export",
+    description:
+      "Imports a host-written Ghidra export transfer file (GhidraStructExport.java's `## `-delimited format) into " +
+      "the store, writing one anno_xref row per surviving `## REFERENCES` line and DELETING the transfer file once " +
+      "every write has durably committed. Costs one store open and one close. REFUSES, writes nothing and deletes " +
+      "nothing: on a malformed, truncated or digest-mismatched export (naming the section and the offending line), " +
+      "on an export_path that resolves outside the workspace root, or on an absent transfer file. Reports " +
+      "referencesSeen, xrefsWritten, xrefsAlreadyPresent (duplicate references are deduped, never double-counted), " +
+      "and kindsSeenNotImported -- reference types this store's four-member vocabulary does not carry, dropped and " +
+      "counted rather than refused, because a real corpus binary carries ordinary jump and call references " +
+      "constantly. Every written row's bank column is null: this verb does not resolve bank state itself. Also " +
+      "reports constWrites -- the export's `## CONST_WRITES` facts (recovered $01/$D011/$D018/$DD00 stores), always " +
+      "present (possibly empty). The transfer file naming them is DELETED by this same call (IMP-02), so this " +
+      "return value is the only place they survive: pass the SAME constWrites array, unchanged, to a following " +
+      "anno_join_memmap call's own const_writes argument to activate bank-state resolution (AUTO-04/AUTO-05) and " +
+      "VIC-register graphics-range derivation (AUTO-06/AUTO-07) for this image.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        ...STORE_PROPERTY,
+        export_path: {
+          type: "string",
+          description:
+            "Absolute or workspace-relative path to the host-written transfer file. CONSUMED AND DELETED by a " +
+            "successful call -- refused if it resolves outside the workspace root, including via a symlink.",
+        },
+        sha256: {
+          type: "string",
+          description:
+            "Optional sha256 digest the producer reported for the transfer file's bytes. When supplied, a mismatch " +
+            "against the file's own computed digest refuses the whole call before anything is read further -- a " +
+            "corruption/drift detector, never a security boundary.",
+        },
+        ...BASE_REVISION_PROPERTY,
+      },
+      required: ["store", "export_path"],
+    },
+  },
+  {
+    name: "anno_join_memmap",
+    description:
+      "The mechanical join: reads every distinct cross-reference target the store already holds, skips addresses " +
+      "inside the supplied image's own loaded range (those are program addresses, never looked up), and annotates " +
+      "every remaining address with the narrowest c64-memory-mapping/memmap.json entry containing it. No agent " +
+      "call, no queue walk and no skill invocation anywhere in this call. Reports addressesConsidered, annotated, " +
+      "skippedInImage, skippedNoMapEntry, declined and commentsChanged, plus a per-address decisions array naming " +
+      "the outcome and, for every skip, WHY. Running this twice over an unchanged store reports commentsChanged: 0 " +
+      "on the second run -- re-running a join pass is not an error. Passing const_writes (typically the SAME " +
+      "constWrites array anno_import_ghidra_export just returned for this image, unchanged) additionally activates " +
+      "bank-state resolution: a $01-conditional address (AUTO-04) declines with a named reason rather than " +
+      "guessing when the reaching processor-port value is absent or disagreeing (AUTO-05), and VIC-register " +
+      "graphics ranges are derived and written back (AUTO-06/AUTO-07, graphics_map_index selects which of several " +
+      "derived combinations when more than one exists, default 0). Omitting const_writes entirely is a complete " +
+      "no-op for both of these -- every address resolves exactly as if this argument did not exist.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        ...STORE_PROPERTY,
+        ...IMAGE_PROPERTY,
+        ...BASE_REVISION_PROPERTY,
+        const_writes: {
+          type: "array",
+          items: {
+            type: "object",
+            properties: {
+              store_address: { type: "integer", description: "The instruction's own address that performed the store." },
+              target_address: { type: "integer", description: "The watched hardware address ($0001/$D011/$D018/$DD00) written to." },
+              value: { type: "integer", description: "The compile-time constant value written." },
+            },
+            required: ["store_address", "target_address", "value"],
+          },
+          description:
+            "Optional recovered const-write facts (AUTO-04/AUTO-05/AUTO-06/AUTO-07) -- pass back the constWrites " +
+            "array anno_import_ghidra_export returned for the SAME image, unchanged. Supplying it (even []) " +
+            "activates bank-state resolution and graphics-range derivation/write-back; omitting it entirely is a " +
+            "complete no-op for both.",
+        },
+        graphics_map_index: {
+          type: "integer",
+          description:
+            "Which of several derived VIC-register-value combinations to write back as graphics ranges, when " +
+            "const_writes yields more than one distinct combination (D-37-27: several valid maps are never merged " +
+            "into one). Defaults to 0. Consulted ONLY when const_writes is supplied at all. Out of range for the " +
+            "derived map count REFUSES the whole call rather than silently clamping or picking a default.",
+        },
+      },
+      required: ["store", "image"],
+    },
+  },
+  {
+    name: "anno_evid_ingest",
+    description:
+      "Turns one raw memmapshow reply plus one run identity into durable runtime-execution evidence rows, so a later " +
+      "session can query what the emulator actually executed instead of re-running the program. Writes a row ONLY for " +
+      "an OBSERVED execute bit: an address memmapshow mentioned with read or write access but no execute gets NO row, " +
+      "and an address the reply never mentioned at all gets NO row either -- an address with no row is the ABSENCE of " +
+      "an assertion, never an assertion that the address is data. Requires the EXACT launch argv and digests it itself " +
+      "(argv_digest is never accepted as an argument), so a caller cannot invent a run identity. A memmapshow reply " +
+      "this surface cannot parse is REFUSED, naming its refusal code and offending line, rather than partially " +
+      "absorbed -- nothing is written on a refusal. Re-ingesting the SAME reply for the SAME run identity succeeds " +
+      "and reports changed:false with observationsWritten:0 -- re-running an ingest pass is not an error. Every count " +
+      "in the answer carries a denominator (addressesQueried) beside it; no percentage is ever reported.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        ...STORE_PROPERTY,
+        memmap_text: {
+          type: "string",
+          description:
+            "The raw memmapshow reply exactly as the text monitor returned it -- never a pre-parsed object. A reply " +
+            "this parser cannot decode is REFUSED, naming its refusal code and offending line; nothing is written.",
+        },
+        image_sha256: {
+          type: "string",
+          description:
+            "The program image this run executed, named by the sha256 digest of its own bytes -- exactly 64 " +
+            "lowercase hex characters. This verb does not read image bytes itself and accepts no path to one.",
+        },
+        argv: {
+          type: "array",
+          items: { type: "string" },
+          description:
+            "The EXACT emulator launch argument vector, including argv[0] -- a different binary is a different " +
+            "launch. This verb digests it itself; a pre-computed digest is never accepted, so a caller cannot invent " +
+            "a run identity.",
+        },
+        seed: {
+          type: "string",
+          description: "The determinism seed the launch pinned. A non-empty string; not a digest and carries no shape beyond that.",
+        },
+        ...BASE_REVISION_PROPERTY,
+      },
+      required: ["store", "memmap_text", "image_sha256", "argv", "seed"],
+    },
+  },
+  {
+    name: "anno_evid_disagreements",
+    description:
+      "Answers where the byte-derived block classification and the observed-execution evidence DISAGREE, with the " +
+      "disagreements reported FIRST: an address the block table calls 'data' at which the emulator was observed " +
+      "executing is proof a byte-derived guess was wrong, from a source (real execution) that never saw the guess. " +
+      "Agreement (block table says 'code', evidence confirms it) is reported as agreementCount ONLY -- never as rows, " +
+      "because a wall of agreeing rows would bury the one output this query exists to surface. An address the block " +
+      "table covers with NO observation anywhere is blockCoveredNeverObservedCount, and is NOT evidence that the " +
+      "address is data -- an address never observed executing proves nothing. Two further counts " +
+      "(observedOutsideAnyBlockCount, observedAtUndefinedBlockCount) name evidence about addresses the block table " +
+      "does not classify as code or data at all, so the denominator can never quietly drop real evidence. This verb " +
+      "READS the block table and the runtime evidence table; it writes to NEITHER, and a repeated call never changes " +
+      "either. Optional image_sha256/argv_digest/seed scope the question to ONE run identity's observations rather " +
+      "than the union across every run that has ever contributed -- supply all three together or none; a partial " +
+      "identity is refused. max_results bounds the returned disagreements array only, and is OPTIONAL (an empty or " +
+      "small disagreement report is the ordinary, sound case, so no ceiling is forced); the true disagreement count " +
+      "and whether truncation occurred are always reported beside it. Every count in the answer carries denominator " +
+      "beside it; no percentage or rate is ever formed.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        ...STORE_PROPERTY,
+        max_results: {
+          type: "integer",
+          description:
+            "Optional bound on the returned disagreements array only. Unlike every other list-returning anno_* verb, " +
+            "this is NOT required -- an empty or small disagreement report is the ordinary, sound case. When " +
+            "supplied, must be a positive integer.",
+        },
+        image_sha256: {
+          type: "string",
+          description:
+            "Optional run-identity filter: the program image this run executed, exactly 64 lowercase hex characters. " +
+            "Supply image_sha256, argv_digest AND seed together to scope to one run, or omit all three to see the " +
+            "union across every run this store holds.",
+        },
+        argv_digest: {
+          type: "string",
+          description:
+            "Optional run-identity filter: the exact digest anno_evid_ingest/anno_evid_runs already computed for a " +
+            "run's launch argv, exactly 64 lowercase hex characters. Never invented by a caller -- pass back what " +
+            "anno_evid_runs reported. Required alongside image_sha256/seed when filtering by run identity.",
+        },
+        seed: {
+          type: "string",
+          description:
+            "Optional run-identity filter: the determinism seed that run's launch pinned. A non-empty string. " +
+            "Required alongside image_sha256/argv_digest when filtering by run identity.",
+        },
+      },
+      required: ["store"],
+    },
+  },
+  {
+    name: "anno_evid_runs",
+    description:
+      "Answers every run identity the store holds an observed-execution row for, with its accumulated observation " +
+      "count and the denominator that count is a fraction of -- so a later session can see what evidence already " +
+      "exists without re-running the program. However many runs contribute observations, their union is NEVER " +
+      "exhaustive coverage of the image: observationCount is a count against denominator, never a rate, and this " +
+      "verb forms no percentage from it.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        ...STORE_PROPERTY,
+      },
+      required: ["store"],
+    },
+  },
+  {
+    name: "anno_evid_reset",
+    description:
+      "Clears every observed-execution row for ONE run identity, so that bracket can be re-measured from nothing. " +
+      "Touches no other run identity's rows and no row of the byte-derived block table. Requires the EXACT launch " +
+      "argv and digests it itself (a pre-computed digest is never accepted), so a caller cannot invent a run identity " +
+      "-- the same discipline anno_evid_ingest uses. A run identity holding no observations SUCCEEDS and reports " +
+      "changed:false and observationsRemoved:0 -- resetting an empty bracket is the ordinary thing, not a mistake. " +
+      "Clearing the emulator's own accumulated access map is a DIFFERENT operation, reached through vice_memmap_zap " +
+      "-- a caller re-measuring a bracket from nothing does BOTH: vice_memmap_zap on the emulator side, " +
+      "anno_evid_reset on the store side.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        ...STORE_PROPERTY,
+        image_sha256: {
+          type: "string",
+          description:
+            "The program image this run executed, named by the sha256 digest of its own bytes -- exactly 64 " +
+            "lowercase hex characters. This verb does not read image bytes itself and accepts no path to one.",
+        },
+        argv: {
+          type: "array",
+          items: { type: "string" },
+          description:
+            "The EXACT emulator launch argument vector, including argv[0] -- a different binary is a different " +
+            "launch. This verb digests it itself; a pre-computed digest is never accepted, so a caller cannot invent " +
+            "a run identity.",
+        },
+        seed: {
+          type: "string",
+          description: "The determinism seed the launch pinned. A non-empty string; not a digest and carries no shape beyond that.",
+        },
+        ...BASE_REVISION_PROPERTY,
+      },
+      required: ["store", "image_sha256", "argv", "seed"],
+    },
+  },
+  {
+    name: "anno_hazard_report",
+    description:
+      "Enumerates what blocks a program's code or data from being MOVED, relocated, rebased or stripped, across " +
+      "the movement-hazard constructions this surface can detect from decoded bytes alone. It REPORTS " +
+      "and changes NOTHING: it never removes, strips, relocates or rebases any part of the image, and it never " +
+      "emits an instruction, flag or field a caller could act on as an automatic relocation -- the operator " +
+      "decides what happens to the bytes it describes. Each finding carries its own detection mechanism and a " +
+      "detection-strength token (observed-corroborated, static-shape-matched, static-signature-only) -- a " +
+      "SEPARATE, smaller vocabulary from this store's own five-grade confidence grades, answering a different " +
+      "question (how strong is this ONE static signal, never what does this address classify as). Every checked " +
+      "region reports exactly one of three outcomes -- hazard-reported, no-signal, unclassified -- and NONE of " +
+      "them is a safety claim: a region with no finding is explicitly NOT a claim that the region is safe to " +
+      "move, clean, or hazard-free, only that nothing this report knows how to look for fired there. " +
+      "Always-emitted named limits (for example, a self-modification through a runtime-computed pointer is " +
+      "undetected by construction) accompany every answer. Opens the store READ-ONLY and reads no other table: " +
+      "this verb creates nothing and writes nothing.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        ...STORE_PROPERTY,
+        ...IMAGE_PROPERTY,
+        max_results: {
+          type: "integer",
+          description:
+            "Optional bound on the returned findings array only. Unlike most list-returning anno_* verbs, this is " +
+            "NOT required -- an empty or small finding set is the ordinary, sound case. When supplied, must be a " +
+            "positive integer.",
+        },
+      },
+      required: ["store", "image"],
+    },
+  },
 ];
 
 /** The allow-list, DERIVED from the definitions above rather than hand-typed
@@ -1005,6 +1386,33 @@ function assertScopeArgs(name: string, args: unknown, batchIndex?: number): void
   assertBaseRevisionArg(name, args, batchIndex);
 }
 
+/** Shared validator for `anno_exclude_range` / `anno_include_range`, called
+ * from `assertVerbArgs()` by two arms so the direct route and
+ * `anno_batch_execute`'s inner loop cannot diverge (mirrors `assertScopeArgs`
+ * exactly). "byte" selects the same two span shape rules a scope uses --
+ * an exclusion is not a table. `reason` is required ONLY for the setter: the
+ * unsetter names an existing record by its span alone. This layer refuses an
+ * absent, non-string or empty/whitespace-only reason at the surface; the
+ * store's own `assertCommentText()` re-checks the full comment-text
+ * vocabulary at write time (T-46-01) -- this is not a second, divergent rule,
+ * only an earlier gate on the same three malformed shapes. */
+function assertExcludedRangeArgs(name: string, args: unknown, batchIndex?: number): void {
+  assertStoreArg(name, args, batchIndex);
+  assertSpanArgs(name, args, "byte", batchIndex);
+  if (name === "anno_exclude_range") {
+    const reason = argBag(args).reason;
+    if (typeof reason !== "string" || reason.trim() === "") {
+      refuseArg(
+        name,
+        "reason",
+        `"reason" must be a non-empty string stating why the user asked for this span to be left out, got ${JSON.stringify(reason)}.`,
+        batchIndex,
+      );
+    }
+  }
+  assertBaseRevisionArg(name, args, batchIndex);
+}
+
 function assertGetCommentsArgs(args: unknown, batchIndex?: number): void {
   assertStoreArg("anno_get_comments", args, batchIndex);
   assertMaxResults("anno_get_comments", args, batchIndex);
@@ -1097,6 +1505,222 @@ function assertSaveProjectArgs(args: unknown, batchIndex?: number): void {
   assertStoreArg("anno_save_project", args, batchIndex);
 }
 
+function assertImportGhidraExportArgs(args: unknown, batchIndex?: number): void {
+  assertStoreArg("anno_import_ghidra_export", args, batchIndex);
+  const bag = argBag(args);
+  if (typeof bag.export_path !== "string" || bag.export_path.trim() === "") {
+    refuseArg("anno_import_ghidra_export", "export_path", '"export_path" is required and must be a non-empty string.', batchIndex);
+  }
+  if (bag.sha256 !== undefined && (typeof bag.sha256 !== "string" || bag.sha256.trim() === "")) {
+    refuseArg("anno_import_ghidra_export", "sha256", '"sha256" must be a non-empty string when supplied.', batchIndex);
+  }
+  assertBaseRevisionArg("anno_import_ghidra_export", args, batchIndex);
+}
+
+/** Validates one `const_writes[i]` element against the wire shape declared on
+ * `anno_join_memmap`'s own schema, and narrows it to a `ConstWriteFact`
+ * (CR-01 fix). Each of the three fields is required and must be a
+ * non-negative integer -- these are ALREADY-RESOLVED facts a caller is
+ * round-tripping from a prior anno_import_ghidra_export call, never an
+ * agent-typed address, so there is no `$`/`0x` ambiguity to route through
+ * `parseStoreAddress()` here. */
+function assertConstWriteFactArg(name: string, raw: unknown, index: number, batchIndex?: number): ConstWriteFact {
+  if (!isPlainObject(raw)) {
+    refuseArg(
+      name,
+      "const_writes",
+      `"const_writes[${index}]" must be an object with store_address/target_address/value fields, got ${JSON.stringify(raw)}.`,
+      batchIndex,
+    );
+  }
+  const bag = raw as Record<string, unknown>;
+  for (const key of ["store_address", "target_address", "value"] as const) {
+    const value = bag[key];
+    if (typeof value !== "number" || !Number.isInteger(value) || value < 0) {
+      refuseArg(
+        name,
+        "const_writes",
+        `"const_writes[${index}].${key}" must be a non-negative integer, got ${JSON.stringify(value)}.`,
+        batchIndex,
+      );
+    }
+  }
+  return {
+    storeAddress: bag.store_address as number,
+    targetAddress: bag.target_address as number,
+    value: bag.value as number,
+  };
+}
+
+/** Validates the optional `const_writes` array, returning `undefined` when
+ * omitted -- OMISSION, not emptiness, is what `runMemmapJoin()` treats as
+ * "skip the bank-state/graphics machinery entirely" (D-37-24's own
+ * documented activation switch), so this must not default an absent
+ * argument to `[]`. */
+function assertConstWritesArg(name: string, args: unknown, batchIndex?: number): ConstWriteFact[] | undefined {
+  const raw = argBag(args).const_writes;
+  if (raw === undefined) return undefined;
+  if (!Array.isArray(raw)) {
+    refuseArg(name, "const_writes", `"const_writes" must be an array when supplied, got ${JSON.stringify(raw)}.`, batchIndex);
+  }
+  return raw.map((entry, i) => assertConstWriteFactArg(name, entry, i, batchIndex));
+}
+
+/** Validates the optional `graphics_map_index` argument. */
+function assertGraphicsMapIndexArg(name: string, args: unknown, batchIndex?: number): number | undefined {
+  const raw = argBag(args).graphics_map_index;
+  if (raw === undefined) return undefined;
+  if (typeof raw !== "number" || !Number.isInteger(raw) || raw < 0) {
+    refuseArg(
+      name,
+      "graphics_map_index",
+      `"graphics_map_index" must be a non-negative integer when supplied, got ${JSON.stringify(raw)}.`,
+      batchIndex,
+    );
+  }
+  return raw;
+}
+
+function assertJoinMemmapArgs(args: unknown, batchIndex?: number): void {
+  assertStoreArg("anno_join_memmap", args, batchIndex);
+  assertImageArg("anno_join_memmap", args, batchIndex);
+  assertBaseRevisionArg("anno_join_memmap", args, batchIndex);
+  assertConstWritesArg("anno_join_memmap", args, batchIndex);
+  assertGraphicsMapIndexArg("anno_join_memmap", args, batchIndex);
+}
+
+/** The run-identity digest shape: exactly 64 lowercase hex characters. This
+ * module's own copy of the check (mirroring `evid-ingest.ts`'s identical,
+ * deliberately un-imported copy): `image_sha256` never reaches a digest
+ * function here, so there is nothing to route through a shared regex, and a
+ * caller-visible refusal must fire BEFORE any store is opened -- before
+ * `evid-ingest.ts`'s own `runIdentityFrom()` ever runs. */
+const EVID_DIGEST_RE = /^[0-9a-f]{64}$/;
+
+/** `anno_evid_ingest`'s own argument assertion, wired into `assertVerbArgs`
+ * beside `anno_join_memmap`'s. Refuses BY NAME, before any store is opened: a
+ * non-string/empty `memmap_text`, an `image_sha256` that is not exactly 64
+ * lowercase hex characters, an `argv` that is not a non-empty array of
+ * strings, and a `seed` that is not a non-empty string (T-43-21). */
+function assertEvidIngestArgs(args: unknown, batchIndex?: number): void {
+  assertStoreArg("anno_evid_ingest", args, batchIndex);
+  assertBaseRevisionArg("anno_evid_ingest", args, batchIndex);
+  const bag = argBag(args);
+  if (typeof bag.memmap_text !== "string" || bag.memmap_text.trim() === "") {
+    refuseArg(
+      "anno_evid_ingest",
+      "memmap_text",
+      `"memmap_text" must be a non-empty string carrying the raw memmapshow reply, got ${JSON.stringify(bag.memmap_text)}.`,
+      batchIndex,
+    );
+  }
+  if (typeof bag.image_sha256 !== "string" || !EVID_DIGEST_RE.test(bag.image_sha256)) {
+    refuseArg(
+      "anno_evid_ingest",
+      "image_sha256",
+      `"image_sha256" must be exactly 64 lowercase hex characters, got ${JSON.stringify(bag.image_sha256)}.`,
+      batchIndex,
+    );
+  }
+  if (!Array.isArray(bag.argv) || bag.argv.length === 0 || bag.argv.some((entry) => typeof entry !== "string")) {
+    refuseArg(
+      "anno_evid_ingest",
+      "argv",
+      `"argv" must be a non-empty array of strings naming the exact emulator launch argument vector, got ${JSON.stringify(bag.argv)}.`,
+      batchIndex,
+    );
+  }
+  if (typeof bag.seed !== "string" || bag.seed.length === 0) {
+    refuseArg("anno_evid_ingest", "seed", `"seed" must be a non-empty string, got ${JSON.stringify(bag.seed)}.`, batchIndex);
+  }
+}
+
+/** `anno_evid_disagreements`'s own argument assertion (plan 43-06). The
+ * three run-identity filters are ALL-OR-NONE, mirroring
+ * `listExecObservations()`'s own rule in `anno-store.ts` exactly: a partial
+ * identity would silently widen the match to every run sharing the supplied
+ * field, which is not what "filter by run identity" means. */
+function assertEvidDisagreementsArgs(args: unknown, batchIndex?: number): void {
+  assertStoreArg("anno_evid_disagreements", args, batchIndex);
+  assertOptionalMaxResults("anno_evid_disagreements", args, batchIndex);
+  const bag = argBag(args);
+  const filterFieldsGiven = [bag.image_sha256, bag.argv_digest, bag.seed].filter((v) => v !== undefined).length;
+  if (filterFieldsGiven > 0 && filterFieldsGiven < 3) {
+    refuseArg(
+      "anno_evid_disagreements",
+      "image_sha256",
+      "a run-identity filter requires image_sha256, argv_digest AND seed together -- a partial identity would " +
+        "silently widen the match to every run sharing the supplied field(s).",
+      batchIndex,
+    );
+  }
+  if (filterFieldsGiven === 3) {
+    if (typeof bag.image_sha256 !== "string" || !EVID_DIGEST_RE.test(bag.image_sha256)) {
+      refuseArg(
+        "anno_evid_disagreements",
+        "image_sha256",
+        `"image_sha256" must be exactly 64 lowercase hex characters, got ${JSON.stringify(bag.image_sha256)}.`,
+        batchIndex,
+      );
+    }
+    if (typeof bag.argv_digest !== "string" || !EVID_DIGEST_RE.test(bag.argv_digest)) {
+      refuseArg(
+        "anno_evid_disagreements",
+        "argv_digest",
+        `"argv_digest" must be exactly 64 lowercase hex characters, got ${JSON.stringify(bag.argv_digest)}.`,
+        batchIndex,
+      );
+    }
+    if (typeof bag.seed !== "string" || bag.seed.length === 0) {
+      refuseArg("anno_evid_disagreements", "seed", `"seed" must be a non-empty string, got ${JSON.stringify(bag.seed)}.`, batchIndex);
+    }
+  }
+}
+
+/** `anno_evid_runs`'s own argument assertion (plan 43-06): just the
+ * universal `store` argument, since this verb takes no other input. */
+function assertEvidRunsArgs(args: unknown, batchIndex?: number): void {
+  assertStoreArg("anno_evid_runs", args, batchIndex);
+}
+
+/** `anno_evid_reset`'s own argument assertion (plan 43-06), the SAME shape
+ * as `assertEvidIngestArgs` minus `memmap_text` -- refuses BY NAME, before
+ * any store is opened: an `image_sha256` that is not exactly 64 lowercase
+ * hex characters, an `argv` that is not a non-empty array of strings, and a
+ * `seed` that is not a non-empty string. */
+function assertEvidResetArgs(args: unknown, batchIndex?: number): void {
+  assertStoreArg("anno_evid_reset", args, batchIndex);
+  assertBaseRevisionArg("anno_evid_reset", args, batchIndex);
+  const bag = argBag(args);
+  if (typeof bag.image_sha256 !== "string" || !EVID_DIGEST_RE.test(bag.image_sha256)) {
+    refuseArg(
+      "anno_evid_reset",
+      "image_sha256",
+      `"image_sha256" must be exactly 64 lowercase hex characters, got ${JSON.stringify(bag.image_sha256)}.`,
+      batchIndex,
+    );
+  }
+  if (!Array.isArray(bag.argv) || bag.argv.length === 0 || bag.argv.some((entry) => typeof entry !== "string")) {
+    refuseArg(
+      "anno_evid_reset",
+      "argv",
+      `"argv" must be a non-empty array of strings naming the exact emulator launch argument vector, got ${JSON.stringify(bag.argv)}.`,
+      batchIndex,
+    );
+  }
+  if (typeof bag.seed !== "string" || bag.seed.length === 0) {
+    refuseArg("anno_evid_reset", "seed", `"seed" must be a non-empty string, got ${JSON.stringify(bag.seed)}.`, batchIndex);
+  }
+}
+
+/** `anno_hazard_report`'s own argument assertion. Reuses the shared store,
+ * image and optional-max-results assertions rather than inlining a fourth
+ * check -- this verb has no argument shape of its own beyond those three. */
+function assertHazardReportArgs(args: unknown, batchIndex?: number): void {
+  assertStoreArg("anno_hazard_report", args, batchIndex);
+  assertImageArg("anno_hazard_report", args, batchIndex);
+  assertOptionalMaxResults("anno_hazard_report", args, batchIndex);
+}
 
 // ---------------------------------------------------------------------------
 // THE ONE SIZE CAP, GOVERNING BOTH VIEWS (T-29-25).
@@ -1109,12 +1733,17 @@ function assertSaveProjectArgs(args: unknown, batchIndex?: number): void {
 // the disassembly view at the cap is the worst case, since the hexdump view of
 // the same byte count renders far less text.
 //
-// THE CAP IS THE ONLY BOUND THERE IS FOR THIS FAMILY. `vice-proxy.ts`'s
-// `wrapPossiblyChunked()` splits an oversized answer across a continuation
-// sequence, but `buildViceTool()` calls `run` DIRECTLY, so nothing on this
-// surface is chunked; and the client's own inline-response ceiling was measured
-// at 40-60 KB, far below the proxy's 500,000-character output cap. That is why
-// the second mitigation -- `max_results` REQUIRED with no default on every
+// THIS CAP IS NOT THE ONLY BOUND FOR THIS FAMILY, BUT IT REMAINS THE
+// LOAD-BEARING ONE. `vice-proxy.ts`'s `wrapPossiblyChunked()` runs at the
+// proxy's single tools/call choke point -- the one place every registered
+// tool's result is checked before it reaches the wire -- so an over-cap
+// answer from this family crosses that same override exactly like any
+// other tool's, and is split across a continuation sequence rather than
+// delivered whole. That does not make this cap redundant: the client's own
+// inline-response ceiling was measured at 40-60 KB, far below the proxy's
+// 500,000-character output cap, so a result that never trips the proxy's
+// split can still be far too large to be useful. That is why the second
+// mitigation -- `max_results` REQUIRED with no default on every
 // list-returning verb, with the true total returned beside the truncated list
 // -- is not optional either.
 // ---------------------------------------------------------------------------
@@ -1399,12 +2028,21 @@ function assertVerbArgs(name: string, args: unknown, batchIndex?: number): void
   if (name === "anno_set_data_type") return assertSetDataTypeArgs(args, batchIndex);
   if (name === "anno_add_scope") return assertScopeArgs("anno_add_scope", args, batchIndex);
   if (name === "anno_remove_scope") return assertScopeArgs("anno_remove_scope", args, batchIndex);
+  if (name === "anno_exclude_range") return assertExcludedRangeArgs("anno_exclude_range", args, batchIndex);
+  if (name === "anno_include_range") return assertExcludedRangeArgs("anno_include_range", args, batchIndex);
   if (name === "anno_get_comments") return assertGetCommentsArgs(args, batchIndex);
   if (name === "anno_get_blocks") return assertGetBlocksArgs(args, batchIndex);
   if (name === "anno_create_project_enum") return assertCreateEnumArgs(args, batchIndex);
   if (name === "anno_update_project_enum") return assertUpdateEnumArgs(args, batchIndex);
   if (name === "anno_apply_enum_usage") return assertApplyEnumUsageArgs(args, batchIndex);
   if (name === "anno_save_project") return assertSaveProjectArgs(args, batchIndex);
+  if (name === "anno_import_ghidra_export") return assertImportGhidraExportArgs(args, batchIndex);
+  if (name === "anno_join_memmap") return assertJoinMemmapArgs(args, batchIndex);
+  if (name === "anno_evid_ingest") return assertEvidIngestArgs(args, batchIndex);
+  if (name === "anno_evid_disagreements") return assertEvidDisagreementsArgs(args, batchIndex);
+  if (name === "anno_evid_runs") return assertEvidRunsArgs(args, batchIndex);
+  if (name === "anno_evid_reset") return assertEvidResetArgs(args, batchIndex);
+  if (name === "anno_hazard_report") return assertHazardReportArgs(args, batchIndex);
   if (name === "anno_disassemble") return assertDisassembleArgs(args, batchIndex);
   if (name === "anno_read_region") return assertReadRegionArgs(args, batchIndex);
   if (name === "anno_get_binary_info") return assertBinaryInfoArgs(args, batchIndex);
@@ -1424,7 +2062,7 @@ function assertVerbArgs(name: string, args: unknown, batchIndex?: number): void
 
 /**
  * The allow-list gate. Its body's FIRST check is set membership (see WHAT NOT
- * TO DO above, and `vice.ts`'s `DENY_LIST` precedent inverted into an
+ * TO DO above, and the same confused-deputy precedent inverted into an
  * allow-list): a `name` outside `CURATED_ANNO_TOOLS` is refused outright,
  * before any argument is inspected, so an unknown verb can never reach a
  * validator that might coincidentally accept its payload. Only then are the
@@ -1493,7 +2131,7 @@ function resolveStoreArg(name: string, args: unknown): string {
  * takes the existence-check-plus-inode-guard route below. Derived from nothing
  * -- it is a hand-listed property of each verb, and a verb missing from here is
  * merely opened writably, never wrongly refused. */
-const READ_ONLY_ANNO_VERBS: readonly string[] = Object.freeze([
+export const READ_ONLY_ANNO_VERBS: readonly string[] = Object.freeze([
   "anno_get_symbols",
   "anno_get_comments",
   "anno_get_blocks",
@@ -1504,6 +2142,9 @@ const READ_ONLY_ANNO_VERBS: readonly string[] = Object.freeze([
   "anno_get_cross_references",
   "anno_search",
   "anno_get_address_details",
+  "anno_evid_disagreements",
+  "anno_evid_runs",
+  "anno_hazard_report",
 ]);
 
 /** Refuses an absent store BY NAME, returning the inode the later guard
@@ -1627,6 +2268,31 @@ function dispatchScope(name: string, handle: AnnoStoreHandle, args: unknown): un
   };
 }
 
+/** One dispatcher serving `anno_exclude_range` / `anno_include_range`,
+ * modelled on `dispatchScope()`. `excludedRanges` rides on EVERY successful
+ * body, including when it is empty, for the same reason `dispatchSetDataType`'s
+ * own disclosures do: the resulting state is a fact the caller is told, not
+ * the absence of a field it has to know to look for. */
+function dispatchExcludedRange(name: string, handle: AnnoStoreHandle, args: unknown): unknown {
+  const bag = argBag(args);
+  const span = {
+    start: bag.start_address as number | string,
+    endInclusive: bag.end_address as number | string,
+    baseRevision: assertBaseRevisionArg(name, args),
+  };
+  const written =
+    name === "anno_exclude_range"
+      ? addExcludedRange(handle, { ...span, reason: bag.reason as string })
+      : removeExcludedRange(handle, span);
+  return {
+    store: handle.path,
+    start_address: parseStoreAddress(bag.start_address, { what: "start_address" }),
+    end_address: parseStoreAddress(bag.end_address, { what: "end_address" }),
+    ...written,
+    excludedRanges: listExcludedRanges(handle),
+  };
+}
+
 function dispatchGetComments(handle: AnnoStoreHandle, args: unknown): unknown {
   const maxResults = assertMaxResults("anno_get_comments", args);
   const bag = argBag(args);
@@ -1737,6 +2403,273 @@ function dispatchSaveProject(handle: AnnoStoreHandle): unknown {
   };
 }
 
+/** Enforces `base_revision` as a whole-call precondition rather than
+ * threading it through each of the many writes `importGhidraExport()` and
+ * `runMemmapJoin()` may issue: both verbs commit several writes per call, and
+ * a single up-front comparison against the revision the caller computed its
+ * batch against is the coherent point to apply an optimistic-concurrency
+ * guard for a multi-write verb -- checked BEFORE anything is written, exactly
+ * like every other refusal on this surface. */
+function assertNotStale(name: string, handle: AnnoStoreHandle, baseRevision: number | undefined): void {
+  if (baseRevision === undefined) return;
+  const rev = currentRevision(handle);
+  if (baseRevision !== rev) {
+    throw new AnnoStoreStaleRevisionError(
+      `${name} refused: base revision ${baseRevision} is not the current on-disk revision ${rev}. Nothing was written.`,
+      { baseRevision, currentRevision: rev },
+    );
+  }
+}
+
+function dispatchImportGhidraExport(handle: AnnoStoreHandle, args: unknown): unknown {
+  const bag = argBag(args);
+  const baseRevision = assertBaseRevisionArg("anno_import_ghidra_export", args);
+  assertNotStale("anno_import_ghidra_export", handle, baseRevision);
+  const exportPath = resolveExportPathArg(bag.export_path as string);
+  return importGhidraExport(handle, {
+    exportPath,
+    expectedSha256: bag.sha256 as string | undefined,
+  });
+}
+
+/** `resolveWorkspacePath()` itself, never a second hand-rolled resolve-and-
+ * prefix-test (T-37-01) -- but its underlying `AnnoStorePathError` message
+ * says "store path ... is outside the workspace root", unaware of which
+ * higher-level argument it was protecting, because `store` and `image` both
+ * reuse the same generic wording. Wrapped here so a refusal on `export_path`
+ * NAMES the argument rather than reading identically to a `store` refusal. */
+function resolveExportPathArg(raw: string): string {
+  try {
+    return resolveWorkspacePath(raw);
+  } catch (err) {
+    if (err instanceof AnnoStorePathError) {
+      throw new AnnoStorePathError(`anno_import_ghidra_export refused: export_path ${err.message}`, {
+        path: err.path,
+        workspaceRoot: err.workspaceRoot,
+      });
+    }
+    throw err;
+  }
+}
+
+function dispatchJoinMemmap(handle: AnnoStoreHandle, args: unknown): unknown {
+  const baseRevision = assertBaseRevisionArg("anno_join_memmap", args);
+  assertNotStale("anno_join_memmap", handle, baseRevision);
+  const image = loadImage("anno_join_memmap", args);
+  // CR-01 fix: `const_writes`/`graphics_map_index` are threaded into
+  // `runMemmapJoin()` exactly as its own `RunMemmapJoinArgs` documents --
+  // OMISSION (not `[]`) is what keeps every pre-existing call (no
+  // const_writes at all) a byte-identical no-op for the bank-state and
+  // graphics machinery.
+  const constWrites = assertConstWritesArg("anno_join_memmap", args);
+  const graphicsMapIndex = assertGraphicsMapIndexArg("anno_join_memmap", args);
+  return runMemmapJoin(handle, {
+    imageOrigin: image.origin,
+    imageByteLength: image.body.length,
+    ...(constWrites !== undefined ? { constWrites } : {}),
+    ...(graphicsMapIndex !== undefined ? { graphicsMapIndex } : {}),
+  });
+}
+
+/**
+ * `anno_evid_ingest`'s dispatch arm (EVID-01, EVID-04, plan 43-05). Calls
+ * `parseAccessMap()` -- THE ONE PARSE -- then `ingestAccessMap()` from
+ * `evid-ingest.ts`; on a refusal it throws inside the `ViceError` family
+ * (never absorbs a drifted reply, T-43-22); on success it writes the WHOLE
+ * observation array through ONE `insertExecObservations()` call, so the
+ * write is one transaction through the store's single commit site
+ * (T-43-26). `observationsWritten` is `insertExecObservations()`'s own
+ * `insertedCount` (WR-02) -- counted row-by-row INSIDE that same
+ * transaction, never from a separate pre-write read -- not the size of the
+ * array handed in: re-ingesting the identical reply must report
+ * `observationsWritten: 0` even though the same-shaped array was passed
+ * again.
+ *
+ * `denominator` travels beside every count this answer reports
+ * (`addressesQueried`, the parsed map's own projection) -- a bare
+ * `observationsWritten` would invite the reading "the rest is data", which
+ * is why the denominator is never omitted. No percentage is ever formed
+ * here.
+ */
+function dispatchEvidIngest(handle: AnnoStoreHandle, args: unknown): unknown {
+  const bag = argBag(args);
+  const baseRevision = assertBaseRevisionArg("anno_evid_ingest", args);
+
+  const parsed = parseAccessMap(bag.memmap_text as string);
+  const identity: IngestRunIdentity = {
+    imageSha256: bag.image_sha256 as string,
+    argv: bag.argv as string[],
+    seed: bag.seed as string,
+  };
+  const ingested = ingestAccessMap(parsed, identity);
+  if (!ingested.ok) {
+    throw new AnnoToolArgumentError(`anno_evid_ingest refused: ${ingested.message}`, {
+      toolName: "anno_evid_ingest",
+      argument: "memmap_text",
+    });
+  }
+
+  const ranges = parsed.ok ? accessMapRanges(parsed.value) : undefined;
+  const addressesWithRecordedAccess = ranges?.addressesWithRecordedAccess ?? 0;
+  const addressesQueried = ranges?.addressesQueried ?? 0;
+
+  // A reply that recorded no execution anywhere is a real, legitimate
+  // answer -- not an error -- but `insertExecObservations` refuses an EMPTY
+  // observations array, so that zero-write case is reported directly here
+  // rather than calling a store function built to refuse it. WR-01: it is
+  // still routed through `applyWrite()` with a no-op mutator (rather than
+  // returning early on `currentRevision(handle)` alone) so a stale
+  // `base_revision` is refused on THIS path exactly as it would be on the
+  // non-empty path below -- every other write verb in this store enforces
+  // staleness through `applyWrite()`'s own check, and a caller relying on
+  // that contract must not get a silent success here instead.
+  if (ingested.observations.length === 0) {
+    const { revision } = applyWrite(handle, () => false, { baseRevision });
+    return {
+      store: handle.path,
+      revision,
+      changed: false,
+      observationsWritten: 0,
+      addressesWithRecordedAccess,
+      addressesQueried,
+      denominator: addressesQueried,
+    };
+  }
+
+  // WR-02: `observationsWritten` is the COUNT `insertExecObservations()`
+  // itself returns, counted row-by-row INSIDE its own `applyWrite`
+  // transaction -- never a `listExecObservations()` read taken before that
+  // transaction opens. A separately-derived pre-read can be overtaken by a
+  // concurrent writer to the same run identity between the read and this
+  // call's own commit, overstating how many rows THIS call actually added;
+  // counting inside the transaction that performs the insert is the one
+  // place this number can be exact.
+  const written = insertExecObservations(handle, {
+    imageSha256: ingested.runIdentity.imageSha256,
+    argvDigest: ingested.runIdentity.argvDigest,
+    seed: ingested.runIdentity.seed,
+    observations: ingested.observations.map((o) => ({ address: o.address, sourceBank: o.sourceBank })),
+    baseRevision,
+  });
+
+  return {
+    store: handle.path,
+    revision: written.revision,
+    changed: written.changed,
+    observationsWritten: written.insertedCount,
+    addressesWithRecordedAccess,
+    addressesQueried,
+    denominator: addressesQueried,
+  };
+}
+
+/**
+ * `anno_evid_disagreements`'s dispatch arm (EVID-03/EVID-04, plan 43-06).
+ * Fetches BOTH sides HERE -- `listExecObservations()` and `listRanges()` --
+ * so `reconcileObservedExecution()` (`evid-reconcile.ts`) is never handed a
+ * store to open itself; that pure module's own header states it must never
+ * fetch either side.
+ *
+ * The byte-derived ranges are mapped through `blocksFromStore()`, reached by
+ * a LAZY `await import("./anno-cli.ts")` -- the same lazy pattern
+ * `vice-proxy.ts:307` already uses to reach `runAnnoCli`, so this file's own
+ * static import graph (and therefore the MCP server's startup cost) is
+ * unchanged: `anno-cli.ts` drags in `anno-coverage.ts`, `anno-memmap-render.ts`
+ * and `anno-export-asm.ts`, none of which this verb needs. The mapping
+ * itself is NOT re-implemented here: a second `RangeRow` -> `BlockEntry` site
+ * would be a second answer to "what class is this address", which is
+ * exactly the boundary `block-class.ts` (and `blocksFromStore()`'s own
+ * comment) exists to keep at one.
+ *
+ * `max_results` (optional, `assertOptionalMaxResults`) bounds the RETURNED
+ * `disagreements` array only -- `agreementCount` and every other bucket are
+ * already counts, never rows, so there is nothing else to truncate.
+ * `reconciliation`'s own key order is preserved by spreading it before
+ * re-assigning `disagreements`: JS does not move an existing key to the end
+ * of an object literal on reassignment, so `disagreements` stays the FIRST
+ * key after `store` (EVID-03).
+ */
+async function dispatchEvidDisagreements(handle: AnnoStoreHandle, args: unknown): Promise<unknown> {
+  const maxResults = assertOptionalMaxResults("anno_evid_disagreements", args);
+  const bag = argBag(args);
+  const hasRunFilter = bag.image_sha256 !== undefined;
+  const observations = listExecObservations(
+    handle,
+    hasRunFilter ? { imageSha256: bag.image_sha256, argvDigest: bag.argv_digest, seed: bag.seed } : {},
+  );
+  // Lazy, deliberately: see this function's own doc comment above for why a
+  // static top-level import of anno-cli.ts must never appear in this file.
+  const { blocksFromStore } = await import("./anno-cli.ts");
+  const blocks = blocksFromStore(listRanges(handle));
+  const reconciliation = reconcileObservedExecution({ blocks, observations });
+  const disagreements = maxResults === undefined ? reconciliation.disagreements : reconciliation.disagreements.slice(0, maxResults);
+  return {
+    store: handle.path,
+    ...reconciliation,
+    disagreements,
+    returned: disagreements.length,
+    matched: reconciliation.disagreements.length,
+    truncated: reconciliation.disagreements.length > disagreements.length,
+  };
+}
+
+/** `anno_evid_runs`'s dispatch arm (plan 43-06): `listObservedRuns()`'s own
+ * answer, carried through UNCHANGED beside `store` -- its `denominator` is
+ * reported exactly as that function computed it, never re-derived here. */
+function dispatchEvidRuns(handle: AnnoStoreHandle, args: unknown): unknown {
+  void args; // this verb takes no argument beyond the universal `store`
+  return { store: handle.path, ...listObservedRuns(handle) };
+}
+
+/**
+ * `anno_evid_reset`'s dispatch arm (EVID-05, plan 43-06): the store-side
+ * half of a bracket reset, beside plan 43-03's emulator-side
+ * `vice_memmap_zap`. Derives the run identity through `runIdentityFrom()`
+ * from `evid-ingest.ts` -- the SAME single digest site `anno_evid_ingest`
+ * uses -- never a second hashing site here, and never a caller-supplied
+ * digest. `observationsRemoved` is read from a `listExecObservations()`
+ * query taken BEFORE the delete, so the answer names exactly how many rows
+ * this call removed rather than leaving a caller to infer it from `changed`
+ * alone. `baseRevision` is threaded straight into
+ * `deleteExecObservationsForRun()`, which enforces staleness itself through
+ * `applyWrite()` -- the same "let the store's own write sequence check it"
+ * discipline `dispatchEvidIngest()` above already uses, so there is no
+ * second, redundant `assertNotStale()` call here.
+ */
+function dispatchEvidReset(handle: AnnoStoreHandle, args: unknown): unknown {
+  const bag = argBag(args);
+  const baseRevision = assertBaseRevisionArg("anno_evid_reset", args);
+  const identity = runIdentityFrom({
+    imageSha256: bag.image_sha256 as string,
+    argv: bag.argv as string[],
+    seed: bag.seed as string,
+  });
+  const existing = listExecObservations(handle, {
+    imageSha256: identity.imageSha256,
+    argvDigest: identity.argvDigest,
+    seed: identity.seed,
+  });
+  const written = deleteExecObservationsForRun(handle, {
+    imageSha256: identity.imageSha256,
+    argvDigest: identity.argvDigest,
+    seed: identity.seed,
+    baseRevision,
+  });
+  return {
+    store: handle.path,
+    revision: written.revision,
+    changed: written.changed,
+    observationsRemoved: existing.length,
+    // `denominator` travels beside `observationsRemoved` for the same reason
+    // it travels beside every other count this evidence layer reports
+    // (EVID-04, plan 43-07's own structural guard): a bare count invites the
+    // reading "the rest is data". The bracket this call reset held exactly
+    // `existing.length` rows before the delete, so that is what
+    // `observationsRemoved` is a fraction of -- a full reset makes the two
+    // numbers equal, but the field is never omitted just because it agrees.
+    denominator: existing.length,
+  };
+}
 
 // ---------------------------------------------------------------------------
 // The image loader (D-07). The store holds annotations and never bytes, so
@@ -1871,7 +2804,175 @@ function hexdump(bytes: Uint8Array, start: number): string[] {
   return lines;
 }
 
-function dispatchDisassemble(args: unknown): unknown {
+/** The SAME shape `registerKeyFor().slice(1)` produces (uppercase, exactly
+ * four hex digits) -- `anno-export-asm.ts`'s own `REGISTER_ENUM_NAME_RE`
+ * comment explains why an enum usage is only a CANDIDATE for the decoder
+ * when its name has this shape, and why that check is not centralised: two
+ * renderers, two small local copies of this one shape predicate, one shared
+ * decoder. Kept in sync by inspection (both are one line) rather than by
+ * import, per D-16's own "two renderers" design.
+ *
+ * SHAPE ALONE IS NOT ENOUGH (45-REVIEW CR-01, fixed 2026-09-11): the call
+ * site below also requires `hasRegBitsEntry()` -- imported from
+ * `anno-enum-gen.ts` above, the ONE shared membership predicate, NOT a third
+ * local copy -- to confirm `anno-regbits.json` actually covers the register
+ * before attempting the decoder at all. */
+const REGISTER_ENUM_NAME_RE = /^[0-9A-F]{4}$/;
+
+/** `#$XX` -> `#<replacement>` on the ASSEMBLER-VISIBLE half of `line`, the
+ * same confinement `anno-export-asm.ts`'s `substituteImmediateEnum()` uses
+ * (never rewriting inside a trailing `;` comment, where a renderer's own
+ * NOTE text could coincidentally contain the same hex digits). A rendered
+ * line that does not carry the expected literal is a disagreement between
+ * this function and `disasm-renderer.ts`, and it is refused rather than
+ * silently left unchanged. */
+function substituteReadableImmediate(line: string, value: number, replacement: string, address: number): string {
+  const literal = `#$${(value & 0xff).toString(16).padStart(2, "0")}`;
+  const separatorIndex = line.indexOf("  ; ");
+  const directiveHalf = separatorIndex >= 0 ? line.slice(0, separatorIndex) : line;
+  const commentHalf = separatorIndex >= 0 ? line.slice(separatorIndex) : "";
+  const at = directiveHalf.indexOf(literal);
+  if (at < 0) {
+    throw new AnnoStoreError(
+      `anno_disassemble: the instruction at $${address.toString(16).padStart(4, "0")} carries an enum usage, but its rendered line does ` +
+        `not contain the immediate literal ${literal} this renderer expected to replace. Refusing rather than emitting a line whose ` +
+        "substitution silently did nothing.",
+    );
+  }
+  return `${directiveHalf.slice(0, at)}#${replacement}${directiveHalf.slice(at + literal.length)}${commentHalf}`;
+}
+
+/** Appends `comment` as a trailing `;`-comment on `line`, joining it with any
+ * EXISTING trailing comment (a `disasm-renderer.ts` note, e.g. an NMOS
+ * page-wrap warning) via `" | "` -- the SAME separator `formatNotesComment()`
+ * already uses to join multiple notes on one instruction, so a line with
+ * both a note and a decoded register comment reads as one vocabulary rather
+ * than two different join styles on one line. */
+function appendReadableComment(line: string, comment: string): string {
+  const separatorIndex = line.indexOf("  ; ");
+  if (separatorIndex < 0) return `${line}  ; ${comment}`;
+  return `${line} | ${comment}`;
+}
+
+/**
+ * D-16's SECOND renderer (plan 45-05): the READABILITY half. `anno-export-
+ * asm.ts` carries the proof (a real-ACME byte-diff oracle); this is what a
+ * Claude session actually reads. Calls `decomposeRegisterValue()` -- the ONE
+ * owning decoder -- for exactly the same reason: this function decodes
+ * NOTHING itself.
+ *
+ * BYTE-IDENTICAL TO `render()`'S OWN OUTPUT when the store carries no enum
+ * usage inside the decoded range at all (the fast-path return below), and
+ * for every instruction `usageByAddress` does not cover even when it does --
+ * D-16 widens what a bound instruction shows; it does not touch anything
+ * else `render()` already produces.
+ *
+ * THE LINE-INDEX MAPPING THIS RELIES ON: `render(instructions, { origin })`
+ * is called here WITHOUT `showSymbols`, so `resolveSymbol()` (`disasm-
+ * renderer.ts`) always returns `undefined` and its own symbol-header loop
+ * never emits a line -- the header is EXACTLY `"!cpu 6510"` then `"* =
+ * $XXXX"`, two lines, and `instructions[i]` maps to `lines[HEADER_LINES +
+ * i]` with no other possible offset. A future caller of this function that
+ * ever passes `showSymbols: true` would break that mapping silently; this
+ * function does not, and does not need to for the readability job D-16 gives
+ * it.
+ */
+function renderDisassembleListing(handle: AnnoStoreHandle, instructions: readonly Instruction[], origin: number): string {
+  const baseListing = render(instructions as Instruction[], { origin });
+
+  const usageByAddress = new Map<number, EnumUsageRow>();
+  for (const row of listEnumUsage(handle)) usageByAddress.set(row.address, row);
+  if (usageByAddress.size === 0) return baseListing;
+
+  const enumsByName = new Map<string, ProjectEnumRow>();
+  for (const row of listProjectEnums(handle)) enumsByName.set(row.name, row);
+
+  const HEADER_LINES = 2;
+  const lines = baseListing.split("\n");
+
+  instructions.forEach((instr, index) => {
+    const usage = usageByAddress.get(instr.address);
+    if (usage === undefined) return;
+
+    // THE SAME REFUSAL SHAPE THE EXPORT BOUNDARY RAISES (`anno-export-
+    // asm.ts`'s own enum-substitution block) for the same conditions, not a
+    // silently plain listing for a store row this readable surface cannot
+    // honour.
+    const project = enumsByName.get(usage.enumName);
+    if (project === undefined) {
+      throw new AnnoStoreError(
+        `anno_disassemble: the enum usage at $${instr.address.toString(16).padStart(4, "0")} names enum ${JSON.stringify(usage.enumName)}, ` +
+          "which the store holds no definition for. Refusing to render a readable operand whose vocabulary is missing.",
+      );
+    }
+    const role = instr.operand?.role;
+    if (role !== "immediate" || !instr.acmeExpressible) {
+      throw new AnnoStoreError(
+        `anno_disassemble: the enum usage at $${instr.address.toString(16).padStart(4, "0")} names enum ${JSON.stringify(usage.enumName)}, but ` +
+          "the instruction there is not an assembler-visible IMMEDIATE operand -- an enum renders on the immediate operand only. Refusing " +
+          "rather than rendering a readable line with no substitution.",
+      );
+    }
+
+    // D-16: attempted ONLY when BOTH (45-REVIEW CR-01, fixed 2026-09-11) the
+    // enum's name has the register-key shape -- see `REGISTER_ENUM_NAME_RE`'s
+    // own comment for why a name that does not (e.g. a hand-authored
+    // `viccolor`) is never a candidate -- AND `anno-regbits.json` actually
+    // has a table entry for it (`hasRegBitsEntry()`). A register-shaped name
+    // for a register the table does not cover (e.g. `D020`) is not a
+    // decomposition failure; it falls through to the single-symbol shape
+    // below with no decomposition attempted at all.
+    let decomposition: RegisterDecomposition | undefined;
+    if (REGISTER_ENUM_NAME_RE.test(usage.enumName) && hasRegBitsEntry(`$${usage.enumName}`)) {
+      try {
+        // `Number("0x...")`, never `parseInt()` -- this file's own guard
+        // (anno-tools.test.ts) forbids a second, divergent numeric-parsing
+        // rule beside the store's own. `usage.enumName` is already proven
+        // to match REGISTER_ENUM_NAME_RE (four hex digits) above.
+        decomposition = decomposeRegisterValue(Number(`0x${usage.enumName}`), instr.operand!.value);
+      } catch (err) {
+        throw new AnnoStoreError(
+          `anno_disassemble: decomposing the enum usage at $${instr.address.toString(16).padStart(4, "0")} (enum ` +
+            `${JSON.stringify(usage.enumName)}) against its bit-name table failed: ${err instanceof Error ? err.message : String(err)}`,
+        );
+      }
+    }
+
+    const lineIndex = HEADER_LINES + index;
+    const currentLine = lines[lineIndex]!;
+
+    if (decomposition !== undefined && decomposition.multiField) {
+      // D-17: OR-ed named constants AND the decoded comment -- both, exactly
+      // as the export renders them, so a Claude session reading this listing
+      // sees what the export proves.
+      const orExpression = decomposition.terms.map((term) => term.name).join(" | ");
+      const substituted = substituteReadableImmediate(currentLine, instr.operand!.value, orExpression, instr.address);
+      lines[lineIndex] = appendReadableComment(substituted, decomposition.comment);
+      return;
+    }
+
+    // THE EXISTING SINGLE-SYMBOL SHAPE (D-16: not replaced) -- a single-field
+    // register, an enum usage whose name is not register-shaped at all, OR
+    // (45-REVIEW CR-01) a register-shaped name for a register
+    // `anno-regbits.json` has no entry for (e.g. `D020`).
+    let matched: string | undefined;
+    for (const [key, variantName] of Object.entries(project.variants)) {
+      if (parseVariantKey(key) === instr.operand!.value) matched = variantName;
+    }
+    if (matched === undefined) {
+      throw new AnnoStoreError(
+        `anno_disassemble: enum ${JSON.stringify(usage.enumName)} is bound to the immediate operand at ` +
+          `$${instr.address.toString(16).padStart(4, "0")}, whose value is $${(instr.operand!.value & 0xff).toString(16).padStart(2, "0")}, ` +
+          "and the enum has no variant for that value.",
+      );
+    }
+    lines[lineIndex] = substituteReadableImmediate(currentLine, instr.operand!.value, `${usage.enumName}_${matched}`, instr.address);
+  });
+
+  return lines.join("\n");
+}
+
+function dispatchDisassemble(handle: AnnoStoreHandle, args: unknown): unknown {
   const image = loadImage("anno_disassemble", args);
   const bag = argBag(args);
   const start = parseStoreAddress(bag.address, { what: "address" });
@@ -1897,7 +2998,51 @@ function dispatchDisassemble(args: unknown): unknown {
     address: start,
     end_address: requestedEnd,
     instructions: instructions.length,
-    listing: render(instructions, { origin: start }),
+    listing: renderDisassembleListing(handle, instructions, start),
+  };
+}
+
+/**
+ * `anno_hazard_report`'s dispatch arm. Fetches EVERY input here -- the
+ * byte-derived ranges, labels, comments, cross-references, execution
+ * observations and the image bytes -- and hands them to `buildHazardReport()`
+ * exactly once; the pure module itself never fetches any of it (see its own
+ * header). The byte-derived ranges are mapped through `blocksFromStore()`,
+ * reached by the SAME lazy `await import("./anno-cli.ts")`
+ * `dispatchEvidDisagreements()` already uses above, so this file's own static
+ * import graph -- and therefore the MCP server's startup cost -- stays
+ * unchanged: `anno-cli.ts` drags in `anno-coverage.ts`, `anno-memmap-render.ts`
+ * and `anno-export-asm.ts`, none of which this verb needs either. The mapping
+ * itself is NOT re-implemented here, for the same reason `dispatchEvidDisagreements`
+ * states for itself.
+ */
+async function dispatchHazardReport(handle: AnnoStoreHandle, args: unknown): Promise<unknown> {
+  const maxResults = assertOptionalMaxResults("anno_hazard_report", args);
+  const image = loadImage("anno_hazard_report", args);
+  const { blocksFromStore } = await import("./anno-cli.ts");
+  const ranges = blocksFromStore(listRanges(handle));
+  const symbols = listLabels(handle);
+  const comments = listComments(handle);
+  const xrefs = listXrefs(handle);
+  const execObservations = listExecObservations(handle);
+  const report = buildHazardReport({
+    bytes: image.body,
+    origin: image.origin,
+    symbols,
+    comments,
+    ranges,
+    xrefs,
+    execObservations,
+  });
+  const findings = maxResults === undefined ? report.findings : report.findings.slice(0, maxResults);
+  return {
+    store: handle.path,
+    image: image.path,
+    ...report,
+    findings,
+    returned: findings.length,
+    matched: report.findings.length,
+    truncated: report.truncated || report.findings.length > findings.length,
   };
 }
 
@@ -2043,13 +3188,21 @@ async function dispatch(name: string, args: unknown, handle: AnnoStoreHandle): P
   if (name === "anno_set_comment") return dispatchSetComment(handle, args);
   if (name === "anno_set_data_type") return dispatchSetDataType(handle, args);
   if (name === "anno_add_scope" || name === "anno_remove_scope") return dispatchScope(name, handle, args);
+  if (name === "anno_exclude_range" || name === "anno_include_range") return dispatchExcludedRange(name, handle, args);
   if (name === "anno_get_comments") return dispatchGetComments(handle, args);
   if (name === "anno_get_blocks") return dispatchGetBlocks(handle, args);
   if (name === "anno_create_project_enum") return dispatchCreateProjectEnum(handle, args);
   if (name === "anno_update_project_enum") return dispatchUpdateProjectEnum(handle, args);
   if (name === "anno_apply_enum_usage") return dispatchApplyEnumUsage(handle, args);
   if (name === "anno_save_project") return dispatchSaveProject(handle);
-  if (name === "anno_disassemble") return dispatchDisassemble(args);
+  if (name === "anno_import_ghidra_export") return dispatchImportGhidraExport(handle, args);
+  if (name === "anno_join_memmap") return dispatchJoinMemmap(handle, args);
+  if (name === "anno_evid_ingest") return dispatchEvidIngest(handle, args);
+  if (name === "anno_evid_disagreements") return dispatchEvidDisagreements(handle, args);
+  if (name === "anno_evid_runs") return dispatchEvidRuns(handle, args);
+  if (name === "anno_evid_reset") return dispatchEvidReset(handle, args);
+  if (name === "anno_disassemble") return dispatchDisassemble(handle, args);
+  if (name === "anno_hazard_report") return dispatchHazardReport(handle, args);
   if (name === "anno_read_region") return dispatchReadRegion(args);
   if (name === "anno_get_binary_info") return dispatchBinaryInfo(args);
   if (name === "anno_get_cross_references") return dispatchCrossReferences(handle, args);