@henols/vice-mcp 0.2.1 → 0.2.3

package/anno-register.ts

@@ -0,0 +1,399 @@
+// anno-register.ts -- the ONE authoritative, committed record of WHY a verb on
+// the `anno_*` surface exists when the Phase 19 upstream procedure manifest
+// does not classify it, and of the one verb whose route deliberately answers
+// something OTHER than what the manifest's upstream contract described.
+//
+// WHY THIS FILE EXISTS (MCP-01, D-08). `MCP-01`'s whole claim is that the tool
+// surface is DERIVED rather than CHOSEN: every verb the manifest disposes
+// `curated` or `adapt-to-address-input` has a route, every verb it disposes
+// `omit` is absent, and the verb with zero callers anywhere is not carried.
+// `anno-derivation.test.ts` checks that half mechanically. This file is the
+// OTHER half, and without it the derivation is a half-truth: four verbs on the
+// surface appear in no manifest procedure at all, and one of them --
+// `anno_search` -- is POSITIVELY REQUIRED by `STORE-06`. A derivation with an
+// unrecorded remainder is not a derivation; it is a derivation plus an
+// unwritten allow-list.
+//
+// D-08 rejected the alternative explicitly, and the reason is worth restating
+// where it will be read: the manifest could have been amended to carry these
+// four names, and must not be. It describes UPSTREAM at a pinned commit, and it
+// carries its own re-sync trigger and per-procedure sha256 digests. Writing this
+// project's verbs into it makes it describe US, and the next re-hash against a
+// real upstream clone would then be comparing a record that had been quietly
+// edited to agree with the thing it was supposed to audit.
+//
+// WHAT THIS IS THE ONE AUTHORITATIVE PLACE FOR:
+//   - every surface verb the manifest does not classify, with the named
+//     consumers and the cited requirement ids that justify its existence;
+//   - every surface verb the manifest DOES classify but whose route answers
+//     something other than upstream's contract, recorded as a deviation so a
+//     later reader does not mistake a deliberate reporting route for an
+//     oversight.
+// Nothing else in the repo may hold a second copy of this judgement. A consumer
+// that needs it in another shape imports `ANNO_VERB_REGISTER` and reshapes it.
+//
+// WHAT MAKES THIS AN OBLIGATION RATHER THAN A DOCUMENT: `anno-register.test.ts`
+// enumerates the surface, subtracts the manifest-classified names, and FAILS --
+// naming the offending verb -- the moment a verb has no entry. D-08's wording is
+// literal and is the wording the failure uses: a verb added later with no named
+// consumer FAILS rather than being reviewed.
+//
+// WHAT NOT TO DO, named concretely:
+//   - AN ENTRY CITING NO REQUIREMENT ID AND NO CONSUMER IS NOT AN ENTRY. The
+//     enforcing test reports it by name. Do not "temporarily" add a verb with a
+//     rationale and nothing else; a rationale is prose, and prose is what this
+//     register exists to stop being the whole basis.
+//   - Do not let this grow into an unbounded allow-list. Every entry added here
+//     makes "derived from the manifest" a little more decorative. Four entries
+//     and one deviation is the measured state at the time of writing; a fifth is
+//     a decision, not paperwork.
+//   - CITATION DISCIPLINE, carried over verbatim in intent from
+//     `module-classification.ts`: `path` is ALWAYS repository-root-relative,
+//     never relative to this directory, because consumers legitimately live
+//     under `.planning/`, `scripts/` and `src/skills/` as well as beside this
+//     file. `symbol` names what the consumer actually TAKES from the verb (an
+//     imported binding, a store entry point, or -- for a documentation consumer
+//     -- the identifier the cited line names); it is a CITATION, never a
+//     justification. `line` is OPTIONAL AND ADVISORY: where present the
+//     enforcing test asserts that line of that file contains `symbol` and never
+//     trusts the number, so OMIT IT RATHER THAN GUESS.
+//
+// Deliberately a plain `.ts` module and never a `.test.ts` file, for the reason
+// `module-classification.ts` gives: importing a `.test.ts` module for its
+// exports also re-runs every `test(...)` it registers, as an import side effect.
+// This module imports nothing at all.
+
+/** One cited consumer of a registered verb. See the header's citation
+ * discipline: `path` is repository-root-relative, `symbol` is a citation and
+ * never a justification, and `line` is optional and advisory -- omit it rather
+ * than guess. */
+export interface AnnoVerbConsumer {
+  path: string;
+  symbol: string;
+  line?: number;
+}
+
+/**
+ * The two reasons a verb is in this register, kept DISTINGUISHABLE on purpose:
+ * a reader must be able to tell "this verb has no manifest classification" from
+ * "this verb has one and we answered it differently".
+ *
+ *   - "unclassified": the manifest's five procedures never mention the upstream
+ *     name this verb derives from, so the derivation says nothing about it. Its
+ *     existence rests entirely on the consumers and requirement ids below.
+ *   - "manifest-deviation": the manifest DOES classify it, and it has a route,
+ *     so the derivation check is satisfied -- but the route answers something
+ *     other than what upstream's contract described. Recorded so the difference
+ *     is a decision on the record rather than something a reader discovers by
+ *     calling the verb and being surprised.
+ */
+export type AnnoVerbEntryKind = "unclassified" | "manifest-deviation";
+
+/**
+ * One registered verb.
+ *
+ * `verb` is the EXACT surface tool name, including the family prefix, because
+ * the enforcing test compares it as a literal string against
+ * `ANNO_TOOL_DEFINITIONS[].name` in both directions.
+ *
+ * `consumers` and `requirements` are the BASIS. At least one of each is
+ * required -- not "one or the other", which is the weaker rule
+ * `module-classification.ts` could afford because its subject was a module that
+ * already existed. A verb is a public surface commitment; D-08 asks for a named
+ * consumer AND a cited requirement, and the enforcing test asks for both.
+ *
+ * `rationale` states, in terms of what the verb DOES, why it is on the surface.
+ *
+ * `note` carries anything the basis cannot say -- a consequence measured
+ * elsewhere, or the shape of the recorded finding this entry discharges.
+ */
+export interface AnnoVerbRegisterEntry {
+  verb: string;
+  kind: AnnoVerbEntryKind;
+  consumers: readonly AnnoVerbConsumer[];
+  requirements: readonly string[];
+  rationale: string;
+  note?: string;
+}
+
+export const ANNO_VERB_REGISTER: readonly AnnoVerbRegisterEntry[] = Object.freeze([
+  // --- unclassified: the manifest's five procedures never name these ---
+  {
+    verb: "anno_add_scope",
+    kind: "unclassified",
+    consumers: [
+      { path: "src/mcp/vice/anno-store.ts", symbol: "addScope" },
+      { path: "src/mcp/vice/anno-tools.ts", symbol: "anno_add_scope" },
+    ],
+    requirements: ["STORE-01"],
+    rationale:
+      "Scopes are one of the five things STORE-01 requires the store to hold -- labels, comments, per-range " +
+      "data typing, scopes and project enums -- and four of those five reached the surface through a " +
+      "manifest-classified verb. Scopes did not, because the absorbed upstream procedures never used them: " +
+      "they are how a routine's local symbols are kept out of the global namespace, which is an EXPORT-side " +
+      "concern the procedures had no reason to touch. Without this verb the store persists a table no caller " +
+      "on this surface can write, which is a stored capability with no route -- exactly the shape STORE-01 " +
+      "was written against.",
+  },
+  {
+    verb: "anno_remove_scope",
+    kind: "unclassified",
+    consumers: [
+      { path: "src/mcp/vice/anno-store.ts", symbol: "removeScope" },
+      { path: ".planning/phases/28-the-store-core/28-REVIEW.md", symbol: "removeScope" },
+    ],
+    requirements: ["STORE-01"],
+    rationale:
+      "The inverse of the overlap refusal, and the register's clearest case of a verb existing because a " +
+      "recorded finding demanded it rather than because a procedure used it. 28-REVIEW's round-6 WARNING is " +
+      "the named consumer: the store refuses any scope overlapping an existing one, and had no removal verb " +
+      "for a scope, a label, a comment, a cross-reference or an enum. 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 consequence, which is why this is not merely tidiness: `anno_add_scope($1000, $ffff)` -- " +
+      "ONE TRANSPOSED END, arriving from a transport whose validator returns its input unchanged -- makes " +
+      "every future scope from $1000 upward permanently unaddable. The only route back was `revertTo`, and " +
+      "the snapshot ring is bounded at MAX_SNAPSHOT_REVISIONS: 32 further writes and the store's own " +
+      "published floor refuses, by name, the revision that would undo it.",
+  },
+  {
+    verb: "anno_search",
+    kind: "unclassified",
+    consumers: [
+      { path: "src/mcp/vice/anno-derive.ts", symbol: "searchAnnotations" },
+      { path: "src/mcp/vice/anno-tools.ts", symbol: "anno_search" },
+      // Re-pointed at the v0.7.0 close, 2026-09-01: `/gsd-complete-milestone`
+      // `git rm`s `.planning/REQUIREMENTS.md` and archives it under
+      // `milestones/<version>-REQUIREMENTS.md`. The cited text is unchanged --
+      // this names the file STORE-06 is actually declared in today, so
+      // DIRECTION 5's "every path exists" check stays a real check.
+      { path: ".planning/milestones/v0.7.0-REQUIREMENTS.md", symbol: "STORE-06" },
+    ],
+    requirements: ["STORE-06"],
+    rationale:
+      "POSITIVELY REQUIRED by STORE-06, which names search across labels, comments and instructions as one " +
+      "of its two halves and says in terms that it is built on the surviving decoders with the old route " +
+      "gone rather than kept as a fallback. The manifest cannot classify it: the upstream call it derives " +
+      "from appears in no absorbed procedure, so the derivation is silent and the requirement is the whole " +
+      "basis. That is the second of the two admissible bases and not a weaker one -- it is the strongest " +
+      "kind of entry this register holds, because a requirement id is checkable against a committed document " +
+      "whereas a consumer can be deleted by the next refactor.",
+    note:
+      "This entry is load-bearing for a check in another file. The skill-coverage script's non-vacuity " +
+      "control is re-pointed onto this verb (C-5): it is STORE-06's named requirement AND it lives here, so " +
+      "if it ever silently leaves the surface, BOTH the coverage control and this register's completeness " +
+      "relation fire. Do not remove this entry to make a count come out.",
+  },
+  {
+    verb: "anno_update_project_enum",
+    kind: "unclassified",
+    consumers: [
+      { path: "src/mcp/vice/anno-store.ts", symbol: "updateProjectEnum" },
+      { path: "src/mcp/vice/anno-tools.ts", symbol: "anno_update_project_enum" },
+    ],
+    requirements: ["STORE-01"],
+    rationale:
+      "Project enums are STORE-01's fifth stored kind. The manifest classifies creation and application " +
+      "(both `curated`, from the routine and symbol procedures) but not update, because the absorbed " +
+      "procedures create an enum once from a fresh reading and never revise one. This project does revise " +
+      "them: the register-bit and enum generators emit a variant set from a data file, and a regenerated " +
+      "set must be able to REPLACE an earlier one rather than collide with it. Without update, the only " +
+      "route to a corrected variant set is delete-and-recreate -- and delete is the one verb with zero " +
+      "callers anywhere, which MCP-01 requires this surface not to carry.",
+    note:
+      "This is the entry that explains why the absent delete verb costs nothing. The delete route existed " +
+      "upstream to support exactly the delete-and-recreate cycle update makes unnecessary; carrying update " +
+      "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",
+    kind: "manifest-deviation",
+    consumers: [
+      { path: "src/mcp/vice/anno-store.ts", symbol: "currentRevision" },
+      { path: "src/mcp/vice/anno-tools.ts", symbol: "anno_save_project" },
+    ],
+    requirements: ["STORE-04", "MCP-04"],
+    rationale:
+      "The manifest disposes this verb `curated` in two procedures and it has a route, so the derivation " +
+      "check is satisfied -- but THE ROUTE PERFORMS NO WRITE. It reports the store's current revision and " +
+      "states the no-write property in its own body. Upstream's contract was an explicit flush of unsaved " +
+      "editor state; this store has none, because STORE-04 makes every mutating verb commit and fsync its " +
+      "own write before it returns. Durability belongs to the store, not to a verb an agent has to remember " +
+      "to call. Recorded HERE, as a deviation, because a route that reports rather than writes is precisely " +
+      "what a later reader would otherwise diagnose as an oversight and 'fix'.",
+    note:
+      "Routed honestly rather than refused, which is the MCP-04 half. Refusing an absorbed procedure's own " +
+      "step would break the procedures this project inherited for no gain; answering it with the revision " +
+      "gives the caller something genuinely useful -- the value a subsequent compare-and-swap needs, and the " +
+      "confirmation that a pass advanced the store as far as expected.",
+  },
+]);
+
+/** The registered entry for a verb, or `undefined`. Exported so a consumer
+ * asking "why is this verb here?" reads the record rather than re-deriving it,
+ * and so the enforcing test and any later caller share one lookup. */
+export function annoRegisterEntryFor(verb: string): AnnoVerbRegisterEntry | undefined {
+  return ANNO_VERB_REGISTER.find((entry) => entry.verb === verb);
+}