@henols/vice-mcp 0.2.2 → 0.2.4

package/anno-register.ts

@@ -207,6 +207,165 @@ export const ANNO_VERB_REGISTER: readonly AnnoVerbRegisterEntry[] = Object.freez
       "instead is what lets MCP-01's zero-caller clause hold without losing a capability.",
   },
 
+  {
+    verb: "anno_exclude_range",
+    kind: "unclassified",
+    consumers: [
+      { path: "src/mcp/vice/anno-store.ts", symbol: "addExcludedRange" },
+      { path: "src/mcp/vice/anno-tools.ts", symbol: "anno_exclude_range" },
+    ],
+    requirements: ["BUILD-05", "BUILD-07"],
+    rationale:
+      "BUILD-05 requires that any exclusion be one the user asked for, made explicit and recorded rather than " +
+      "silently applied. BUILD-07 requires a user-requested exclusion be emitted as a recorded excluded range " +
+      "rather than a hole. Both clauses presuppose a route by which the user STATES the request. Without this " +
+      "verb the store persists a table no caller on this surface can write -- a stored capability with no " +
+      "route, which is the same shape anno_add_scope's own entry was written against. The surface is the right " +
+      "home rather than the CLI because an exclusion is a small bounded piece of state a session sets while " +
+      "looking at a range, not a filesystem artefact.",
+    note:
+      "This verb's existence is what makes the requirement's 'never the tool's' clause CHECKABLE rather than " +
+      "aspirational. As long as the only way a range can be excluded is a user calling this verb, there is no " +
+      "code path by which the tool excludes anything on its own judgement. The alternative rejected: a " +
+      "confidence or verdict threshold inside the exporter would have 'implemented' the same user-visible " +
+      "outcome and would have made the tool the decider -- the failure mode the 2026-09-10 rewording of " +
+      "BUILD-05 removed.",
+  },
+  {
+    verb: "anno_include_range",
+    kind: "unclassified",
+    consumers: [
+      { path: "src/mcp/vice/anno-store.ts", symbol: "removeExcludedRange" },
+      { path: "src/mcp/vice/anno-tools.ts", symbol: "anno_include_range" },
+    ],
+    requirements: ["BUILD-07"],
+    rationale:
+      "The inverse of the overlap refusal, on the same terms anno_remove_scope's entry states: the store " +
+      "refuses any exclusion overlapping an existing one, so a single transposed end would otherwise make a " +
+      "whole region permanently unexcludable, with the only route back being a revert through the bounded " +
+      "snapshot ring. A write verb whose mistakes cannot be undone is a data-loss surface even when every " +
+      "individual refusal is correct, so the inverse ships in the same phase as the refusal.",
+    note:
+      "The measured mechanism, not an asserted risk: the snapshot ring is bounded at MAX_SNAPSHOT_REVISIONS, so " +
+      "a mistake that is not directly undoable becomes permanently undoable after that many further writes.",
+  },
+  {
+    verb: "anno_import_ghidra_export",
+    kind: "unclassified",
+    consumers: [
+      { path: "src/mcp/vice/anno-import.ts", symbol: "importGhidraExport" },
+      { path: "src/mcp/vice/anno-tools.ts", symbol: "anno_import_ghidra_export" },
+    ],
+    requirements: ["IMP-01", "IMP-02"],
+    rationale:
+      "The manifest's five absorbed upstream procedures predate this store having any Ghidra-derived import path " +
+      "at all, so the derivation is silent about a verb that did not exist when the manifest was written. IMP-01 " +
+      "requires a container-side importer reading a host-written transfer file through the store's single seam, " +
+      "and IMP-02 requires that transfer file to be transient evidence -- digested, consumed and deleted in the " +
+      "same call, never a second on-disk model. This verb is the only route either requirement has: without it, " +
+      "a Ghidra export sits on disk as a file no curated verb ever reads.",
+  },
+  {
+    verb: "anno_join_memmap",
+    kind: "unclassified",
+    consumers: [
+      { path: "src/mcp/vice/anno-join.ts", symbol: "runMemmapJoin" },
+      { path: "src/mcp/vice/anno-tools.ts", symbol: "anno_join_memmap" },
+    ],
+    requirements: ["AUTO-01"],
+    rationale:
+      "AUTO-01 requires machine addresses to annotate themselves into the store mechanically -- no agent call, no " +
+      "queue walk and no skill invocation anywhere in the loop -- by joining stored cross-references against " +
+      "c64-memory-mapping's memmap.json. The manifest's five procedures never describe this join at all, because " +
+      "it answers a question this project's own store creates (what does a stored cross-reference's target " +
+      "address MEAN against the published memory map), not one upstream's absorbed procedures ever asked. Without " +
+      "this verb the annotation the join produces has no route onto the surface at all.",
+  },
+  {
+    verb: "anno_evid_ingest",
+    kind: "unclassified",
+    consumers: [
+      { path: "src/mcp/vice/evid-ingest.ts", symbol: "ingestAccessMap" },
+      { path: "src/mcp/vice/anno-tools.ts", symbol: "anno_evid_ingest" },
+    ],
+    requirements: ["EVID-01", "EVID-04"],
+    rationale:
+      "EVID-01 requires what the emulator observed executing to become durable, accumulating rows in `.annostore`, " +
+      "keyed by run identity, so a later session queries the evidence instead of re-running the program. EVID-04 " +
+      "requires the write path be unable to state, imply or render that an address is data on the strength of " +
+      "never having been observed executing. The manifest's five absorbed upstream procedures predate this store " +
+      "having any runtime-evidence table at all, so the derivation is silent about a verb that did not exist when " +
+      "the manifest was written. This verb is the ONE place a parsed memmapshow access map becomes store rows: " +
+      "without it, an observed execute bit has no route onto the surface at all, and EVID-01's own goal (query the " +
+      "evidence instead of re-running the program) is unreachable.",
+  },
+  {
+    verb: "anno_evid_disagreements",
+    kind: "unclassified",
+    consumers: [
+      { path: "src/mcp/vice/evid-reconcile.ts", symbol: "reconcileObservedExecution" },
+      { path: "src/mcp/vice/anno-tools.ts", symbol: "anno_evid_disagreements" },
+    ],
+    requirements: ["EVID-03", "EVID-04"],
+    rationale:
+      "EVID-03 requires a user be able to ask where the byte-derived block classification and the observed-execution " +
+      "evidence disagree, and get the disagreements first, with the block table never silently overwritten and " +
+      "agreement reported as a count rather than a wall of rows. EVID-04 requires that no summary this surface " +
+      "produces can state, imply or render that a never-observed address is data, and that every count carries the " +
+      "denominator it is a fraction of. This verb is the ONE place `reconcileObservedExecution()`'s pure join is " +
+      "reached from the MCP surface: without it, the reconciliation module a prior plan built has no caller at all, " +
+      "and EVID-03's own goal (a user can ask) is unreachable.",
+  },
+  {
+    verb: "anno_evid_runs",
+    kind: "unclassified",
+    consumers: [
+      { path: "src/mcp/vice/anno-store.ts", symbol: "listObservedRuns" },
+      { path: "src/mcp/vice/anno-tools.ts", symbol: "anno_evid_runs" },
+    ],
+    requirements: ["EVID-04"],
+    rationale:
+      "EVID-04 requires that any summary carry the denominator it is a fraction of and that a union across however " +
+      "many runs never be presented as exhaustive. This verb is the ONE surface route to `listObservedRuns()`'s " +
+      "per-run observation counts and their shared denominator, so a later session can see what evidence a store " +
+      "already holds -- across however many runs contributed -- without re-running the program and without ever " +
+      "reading the counts as coverage of the image.",
+  },
+  {
+    verb: "anno_evid_reset",
+    kind: "unclassified",
+    consumers: [
+      { path: "src/mcp/vice/anno-store.ts", symbol: "deleteExecObservationsForRun" },
+      { path: "src/mcp/vice/anno-tools.ts", symbol: "anno_evid_reset" },
+    ],
+    requirements: ["EVID-05"],
+    rationale:
+      "EVID-05 requires that a bracket can be reset and re-measured without a previous run's observations leaking " +
+      "into it. This verb is the store-side half of that reset (beside plan 43-03's emulator-side `vice_memmap_zap`): " +
+      "it derives the run identity through the same `runIdentityFrom()` `anno_evid_ingest` uses and deletes only " +
+      "that identity's rows, leaving every other identity and the byte-derived block table untouched. Without it, " +
+      "`deleteExecObservationsForRun()` -- the store function EVID-05's own requirement asks for -- has no route " +
+      "onto the surface at all.",
+  },
+  {
+    verb: "anno_hazard_report",
+    kind: "unclassified",
+    consumers: [
+      { path: "src/mcp/vice/anno-hazard-report.ts", symbol: "buildHazardReport" },
+      { path: "src/mcp/vice/anno-tools.ts", symbol: "anno_hazard_report" },
+    ],
+    requirements: ["BUILD-04"],
+    rationale:
+      "A movement-blocking construction must be askable and enumerable, with its detection mechanism and its " +
+      "detection strength reported beside it, and with a third undecided outcome that is never rendered as " +
+      "clean. This verb is the ONE place the pure hazard-report function is reached from the surface: without " +
+      "it, the module a prior task built has no caller at all, and the goal it exists for (a user can ask what " +
+      "blocks a program's code from being moved) is unreachable. The manifest's five absorbed upstream " +
+      "procedures predate any movement-hazard concept in this store at all, so the derivation is silent about a " +
+      "verb that answers a question upstream never asked. This verb opens no new store table and writes " +
+      "nothing -- it is a derived query over tables the surface already writes through other verbs.",
+  },
+
   // --- manifest-deviation: classified, routed, and answering differently ---
   {
     verb: "anno_save_project",