@henols/vice-mcp 0.2.2 → 0.2.3

package/anno-types.ts

@@ -111,7 +111,7 @@ import { existsSync, lstatSync, readlinkSync, realpathSync } from "node:fs";
 import { basename, dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
 
 import { OPCODES } from "./disasm-opcodes.ts";
-import { ViceError, type ViceErrorOptions } from "./vice.ts";
+import { ViceError, type ViceErrorOptions } from "./vice-errors.ts";
 
 /**
  * The on-disk schema version every store file carries in `anno_meta`. A
@@ -182,8 +182,158 @@ import { ViceError, type ViceErrorOptions } from "./vice.ts";
  * exist, and it would put new code into a module six hardening rounds went
  * into. Stating the difference is the point: this one is a choice, not an
  * impossibility.
+ *
+ * ---------------------------------------------------------------------------
+ * VERSION 4, 2026-09-10 (EVID-02) -- THE DECISION IS `reaffirm-refusal`, AND
+ * THE FACTUAL BASIS IS TRANSCRIBED HERE RATHER THAN LEFT IN A PLANNING
+ * DIRECTORY, for the same reason VERSION 3's paragraph gives.
+ *
+ * WHAT THE BUMP BUYS: `anno_evid_exec`, the durable, run-identity-keyed table
+ * that records ONE fact per row -- an address was OBSERVED EXECUTING during a
+ * specific run -- so a later session can query accumulated runtime evidence
+ * instead of re-running the program. See `anno-store.ts`'s `DDL` and its
+ * `insertExecObservations` / `listExecObservations` / `listObservedRuns` /
+ * `deleteExecObservationsForRun`.
+ *
+ * THE OPTION SELECTED, BY NAME: `reaffirm-refusal`. The strict-equality
+ * refusal inside `openStore` stays exactly as VERSION 3 left it -- a
+ * version-3 store does not open under this `SCHEMA_VERSION`, no migration arm
+ * is written, and the single-witness property (one comparison site, no
+ * second write of `anno_meta.schema_version`) is unchanged.
+ *
+ * THE FACTUAL CHECK, RUN 2026-09-10, SCOPE ONE DEVELOPMENT MACHINE:
+ *   1. `find / -xdev -name '*.annostore'`, with `.git` directories excluded --
+ *      empty. The broader `find "$HOME" -name '*.annostore'` (closing the `-xdev`
+ *      mount-boundary gap) found five hits, all inside a dated (2026-08-27)
+ *      scratch probe cache (`~/.cache/gsd-probe/c4/...`), with
+ *      fixture-pattern names (`t-half`, `t-zero`, `t-tail-100`, `p`, `proj`)
+ *      and one file zero bytes -- synthetic test fixtures, not a real
+ *      project's store.
+ *   2. `git log --oneline --diff-filter=A -- '*.annostore'` -- empty. No
+ *      `.annostore` has ever been added to this repository's history.
+ *   3. Release tags versus when the store landed: `anno-store.ts` was added
+ *      by `4c9cea3c` (2026-08-27). `v0.7.0` (2026-09-01) and `v0.8.0`
+ *      (2026-09-06) BOTH POSTDATE that landing and the VERSION 3 bump
+ *      itself. **THIS CORRECTS THE VERSION 3 PARAGRAPH ABOVE**: its stated
+ *      justification -- "the last release tag (`v0.5.0`, 2026-08-25)
+ *      PREDATES the store entirely -- so no tagged release has ever shipped
+ *      a store at all" -- was true when written (2026-08-29) and is STALE
+ *      now. Two tagged releases since then could, in principle, have shipped
+ *      a working store to a real user.
+ *   4. Nothing outside that dated scratch/probe cache directory, and nothing
+ *      tracked in git, was found on this machine.
+ *
+ * THE RE-AFFIRMATION IS MADE DESPITE THAT CORRECTION, on the strength of the
+ * observed NULL RESULT (zero real stores found), not on the strength of the
+ * now-stale "no release ever shipped one" framing. What changed since VERSION
+ * 3 is the *possibility* of a field store, not an observation of one, and the
+ * two directions' costs are asymmetric in reversibility: re-affirming refusal
+ * STAYS REVERSIBLE -- a migration arm can be added later, at version 5,
+ * against real evidence -- while shipping a mutating open path now adds a
+ * half-reasoned migration to a module that also has a corruption-refusal
+ * path, exactly where silent corruption lives, inside a plan whose actual job
+ * is an evidence table rather than a schema-migration redesign. House style
+ * settles the shape too: this project's standing pattern for a mismatched or
+ * missing external state is DETECT, THEN REFUSE BY NAME WITH THE REMEDY IN
+ * THE MESSAGE (`CLAUDE.md`'s "external tools are never auto-installed"
+ * constraint states the same discipline for a different kind of missing
+ * state) -- `openStore`'s refusal message is extended to name that remedy
+ * explicitly and to say the refused file is left untouched, so a user who
+ * hits it is not left inferring either fact.
+ *
+ * THE FACTUAL BASIS IS ONE MACHINE ONLY, and the limit travels with the
+ * decision: this is not a global guarantee that no field store exists --
+ * exactly the scope VERSION 3's own paragraph already accepted once.
+ *
+ * THE VERSION 1 PARAGRAPH ABOVE IS STILL THE PRECEDENT THIS IS MEASURED
+ * AGAINST, and this refusal is, again, a CHOICE and not an impossibility:
+ * version 4 COULD be given a migration arm and deliberately is not, for the
+ * reasons above.
+ *
+ * THE REVERSAL CONDITION, RECORDED SO THIS DOES NOT QUIETLY HARDEN INTO
+ * PRECEDENT: a migration arm at version 5 is justified if a real, non-scratch
+ * `.annostore` file is found in the field -- a user's own project, a bug
+ * report attaching one, or a support request -- or if a documented
+ * distribution channel is shown to have shipped a version-3 or version-4
+ * store to users who have not yet upgraded past it. Absent that evidence, the
+ * refusal stays the default.
+ *
+ * ---------------------------------------------------------------------------
+ * VERSION 5, 2026-09-11 (BUILD-07) -- THE DECISION IS `reaffirm-refusal`, THE
+ * SAME OPTION VERSION 4 SELECTED, AND THE FACTUAL BASIS IS TRANSCRIBED HERE
+ * RATHER THAN LEFT IN A PLANNING DIRECTORY, for the same reason every prior
+ * version's paragraph gives.
+ *
+ * WHAT THE BUMP BUYS: `anno_excluded_range`, the durable record of a
+ * user-requested exclusion -- its extent AND the reason the user gave -- so
+ * the export can emit the range's real bytes tagged with a visible marker
+ * comment instead of a hole, which is `BUILD-07`'s whole invariant: an
+ * exclusion is a RECORDED, VISIBLE fact, never a silent drop. See
+ * `anno-store.ts`'s `DDL` and its three verbs, `addExcludedRange` /
+ * `listExcludedRanges` / `removeExcludedRange`.
+ *
+ * THE OPTION SELECTED, BY NAME: `reaffirm-refusal`. The strict-equality
+ * refusal inside `openStore` stays EXACTLY as VERSION 4 left it -- this bump
+ * does not touch that comparison site at all: a version-4 store does not open
+ * under this `SCHEMA_VERSION`, no migration arm is written, and the
+ * single-witness property (one comparison site, no second write of
+ * `anno_meta.schema_version`) is unchanged.
+ *
+ * THE FACTUAL CHECK, RUN 2026-09-11, SCOPE ONE DEVELOPMENT MACHINE -- the
+ * same three checks VERSION 4 ran, re-run rather than inherited, with the
+ * REAL results transcribed as of today:
+ *   1. `find "$HOME" -name '*.annostore'`, with `.git` directories excluded --
+ *      SIX hits, not VERSION 4's five. The same five fixture-pattern files
+ *      inside the dated (2026-08-27) scratch probe cache (`t-half`, `t-zero`,
+ *      `t-tail-100`, `p`, `proj`) are still present, UNCHANGED. The SIXTH is
+ *      NEW since VERSION 4's check: `.c64-re-tools/phase45-scratch/
+ *      tracer.annostore`, inside THIS repository's own gitignored scratch
+ *      directory, timestamped 2026-09-10 -- its path and name identify it as
+ *      Phase 45's own tracer/scratch fixture, not a real consuming project's
+ *      store. Six real files, zero real stores.
+ *   2. `git log --oneline --diff-filter=A -- '*.annostore'` -- still empty.
+ *      No `.annostore` has ever been added to this repository's tracked
+ *      history.
+ *   3. Release tags versus when the store landed: `anno-store.ts` was added
+ *      by `4c9cea3c` (2026-08-27). Since VERSION 4's check, ONE MORE tagged
+ *      release has been cut -- `v0.9.0` (2026-09-10) -- joining `v0.7.0`
+ *      (2026-09-01) and `v0.8.0` (2026-09-06). All THREE now postdate the
+ *      store's landing and VERSION 3's original bump, so three tagged
+ *      releases, not two, could in principle have shipped a working store to
+ *      a real user. No result differs in KIND from VERSION 4's; the count of
+ *      possible-exposure releases has grown by one, consistent with time
+ *      having passed rather than with any new evidence of a real store.
+ *
+ * THE RE-AFFIRMATION IS MADE ON THE SAME BASIS VERSION 4 USED: the observed
+ * NULL RESULT (zero real, non-scratch stores found across six candidate
+ * files), not on a claim that no release could have shipped one. The new
+ * sixth file changes nothing about that null result -- it is this project's
+ * OWN scratch output, in a directory this project's own tooling writes to and
+ * that ships nothing.
+ *
+ * WHY A NEW TABLE WAS CHOSEN OVER A NULLABLE `excluded`/`exclusion_reason`
+ * COLUMN PAIR ON `anno_range`, recorded because it is the one part of this
+ * decision that is structural rather than stylistic: an exclusion's extent is
+ * chosen by the USER and has no reason to coincide with a typed range's
+ * boundaries, so a column on `anno_range` would force `retype()`'s carve to
+ * split, duplicate, or lose an exclusion's reason every time a range boundary
+ * moved underneath it -- `retype()` knows nothing about exclusions today and
+ * a column would force it to. A separate table keeps the user's own words
+ * independent of the store's typing churn entirely. This also happens to
+ * match the project's existing preference (`anno_evid_exec` at VERSION 4 over
+ * widening `anno_range`), but that precedent is the WEAKER of the two
+ * arguments -- the structural one above is the one that would still hold even
+ * if this project had no such precedent.
+ *
+ * THE REVERSAL CONDITION, RECORDED SO THIS DOES NOT QUIETLY HARDEN INTO
+ * PRECEDENT: a migration arm at version 6 is justified if a real, non-scratch
+ * `.annostore` is found in the field -- a user's own project, a bug report
+ * attaching one, or a support request -- or if a documented distribution
+ * channel is shown to have shipped a version-4 or version-5 store to users
+ * who have not yet upgraded past it. Absent that evidence the refusal stays
+ * the default.
  */
-export const SCHEMA_VERSION = 3;
+export const SCHEMA_VERSION = 5;
 
 /** The 6510's address space, inclusive at both ends. */
 export const ADDRESS_MIN = 0x0000;
@@ -464,6 +614,23 @@ export interface ScopeRow {
   endInclusive: number;
 }
 
+/** One user-requested exclusion as the store holds it, added at
+ * `SCHEMA_VERSION` 5 (`BUILD-07`). Both ends are INCLUSIVE, matching every
+ * other range-shaped row this store persists. There is no `bank` column,
+ * because an exclusion is a statement about a span of the SUBJECT PROGRAM the
+ * user asked to leave out of the rebuild -- not a memory view -- and there is
+ * no confidence, verdict, grade or severity column, because this row holds
+ * WHAT THE USER ASKED FOR and nothing the tool concluded about it. A
+ * judgement column here would be the exact "tool is the decider" shape
+ * `BUILD-05`'s 2026-09-10 rewording removed: the store answers "what did the
+ * user record", never "should this range be excluded". */
+export interface ExcludedRangeRow {
+  id: number;
+  start: number;
+  endInclusive: number;
+  reason: string;
+}
+
 /** One project-local enum as the store holds it. `variants` is keyed by the
  * numeric-string forms the schema names -- decimal, `0x`/`$` hex, `0b`/`%`
  * binary -- and its values are variant names. */
@@ -505,6 +672,81 @@ export interface XrefRow {
   bank: number | null;
 }
 
+/**
+ * The three memory regions `memmapshow` reports an execute observation
+ * against, `SCHEMA_VERSION` 4 (EVID-01). This is the ONE place this
+ * vocabulary is written down.
+ *
+ * ALL THREE ARE INCLUDED DELIBERATELY, not for symmetry: `AccessFlags`
+ * (`textmon-memmap.ts`) carries `read`/`write`/`execute` as three
+ * INDEPENDENT bits per region, and dropping any one of the three regions
+ * here would discard a genuine positive observation the wire already
+ * reported -- `io.execute` is exactly as real a fact as `ram.execute`.
+ */
+export const EVID_SOURCE_BANKS = Object.freeze(["ram", "rom", "io"] as const);
+
+/** One of the three evidence source banks. */
+export type EvidSourceBank = (typeof EVID_SOURCE_BANKS)[number];
+
+/**
+ * The runtime evidence layer's own classification of an address, `SCHEMA_VERSION`
+ * 4 (EVID-04). This is a TYPE-LEVEL control, not a runtime check: the union has
+ * exactly two members and NO `"data"` member exists for a caller to return,
+ * mistakenly or otherwise.
+ *
+ * THIS IS THE SAME DISCIPLINE `textmon-memmap.ts` STATES FOR ITSELF, carried
+ * forward rather than re-derived: that module's own header forbids adding
+ * "a field, key, label or enum member anywhere in this module or its answer
+ * types that classifies an address as DATA on the strength of never having
+ * been observed" (`textmon-memmap.ts:32-38`). `BlockClass`'s three-valued
+ * union (`"code" | "data" | "undefined"`, `block-class.ts`) is the byte-derived
+ * classifier's own vocabulary and is DELIBERATELY NOT REUSED here: that union
+ * exists to name a byte-derived guess, and this one exists to name only what
+ * was actually witnessed executing. `"unobserved"` means exactly "no
+ * execution was ever recorded at this address" -- never "this address is
+ * data" -- and no code path in this layer may treat the two as
+ * interchangeable (see the ban on deriving `data` from absence, Pitfall 3 in
+ * this phase's research).
+ */
+export type RuntimeExecClass = "code" | "unobserved";
+
+/**
+ * One runtime-execution observation as the store holds it (`anno_evid_exec`,
+ * `SCHEMA_VERSION` 4). Keyed by the bare run-identity triple
+ * `(imageSha256, argvDigest, seed)` plus `address` plus `sourceBank` -- the
+ * `no-change` assumption-delta decision plan 43-01's live A/B selected
+ * (`docs/phase43-instrumentation-perturbation-ab.md`): there is no
+ * `run_class` discriminator column, because instrumentation was measured
+ * `no-perturbation` at anchor hit depths 10 and 50.
+ *
+ * A row here asserts exactly ONE fact: this address was observed executing,
+ * in this source bank, during this run. There is no `bank`-reserved column
+ * (unlike the annotation tables) and no nullable column -- every field is a
+ * fact this table is licensed to assert, or the row does not exist.
+ */
+export interface EvidExecRow {
+  id: number;
+  imageSha256: string;
+  argvDigest: string;
+  seed: string;
+  address: number;
+  sourceBank: EvidSourceBank;
+}
+
+/**
+ * One distinct run identity's accumulated observation count, as
+ * `listObservedRuns()` reports it. `observationCount` is a COUNT, never a
+ * percentage or rate -- see `listObservedRuns`'s own doc comment in
+ * `anno-store.ts` for the denominator this count is a fraction of (EVID-04:
+ * a count with no denominator invites the reading "the rest is data").
+ */
+export interface ObservedRunRow {
+  imageSha256: string;
+  argvDigest: string;
+  seed: string;
+  observationCount: number;
+}
+
 /** What `resolveSplitTargets()` returns: the entry count, the resolved 16-bit
  * targets in table order, and whether this layout produces cross-references at
  * all. Nothing here is ever written to disk. */
@@ -1300,6 +1542,37 @@ export function assertAccessKind(value: unknown): XrefAccessKind {
   return assertMember(value, XREF_ACCESS_KINDS, "access kind");
 }
 
+/** Narrows an unvalidated argument to an `EvidSourceBank`, or throws
+ * `AnnoTypeError` carrying the offending value and all three valid members. */
+export function assertEvidSourceBank(value: unknown): EvidSourceBank {
+  return assertMember(value, EVID_SOURCE_BANKS, "source bank");
+}
+
+/** Exactly 64 lowercase hex characters -- the shape `argvDigest()`
+ * (`capture-predicate.ts`) and a sha256 image hash both already produce.
+ * Refuses anything else BY NAME, including a correctly-shaped but
+ * UPPERCASE digest, rather than lower-casing it silently: two callers
+ * disagreeing on case is exactly the kind of divergence a store write must
+ * not launder into agreement. */
+export function assertRunIdentityDigest(value: unknown, what: string): string {
+  if (typeof value === "string" && /^[0-9a-f]{64}$/.test(value)) {
+    return value;
+  }
+  throw new AnnoTypeError(
+    `${what} ${JSON.stringify(value)} is not exactly 64 lowercase hex characters -- expected a sha256 hex digest such as argvDigest() or an image hash produces`,
+    { dataType: value },
+  );
+}
+
+/** A non-empty string. `seed` is not a digest and carries no shape beyond
+ * that -- REPRO-04's run-identity composite treats it as an opaque token. */
+export function assertRunIdentitySeed(value: unknown): string {
+  if (typeof value === "string" && value.length > 0) {
+    return value;
+  }
+  throw new AnnoTypeError(`seed ${JSON.stringify(value)} is not a non-empty string`, { dataType: value });
+}
+
 /** The legal-identifier shape, quoted from the schema's own sentence
  * (`anno-tools.ts:246-251`): "starts with a letter or underscore, followed by
  * letters/digits/underscores only". Used for label names and for project-enum