@henols/vice-mcp 0.2.2 → 0.2.3

package/stock-run-until.ts

@@ -49,6 +49,10 @@ import { parseAddress } from "./stock-address.ts";
 import { stockAnswer, isErrorText, convertWireError, type StockSessionHandler } from "./stock-handler.ts";
 import { readProgramCounter } from "./stock-timing.ts";
 import { runStateFor } from "./stock-runstate.ts";
+// The reproducible-run protocol (REPRO-02). Imported for exactly one branch
+// below -- this module is the ONLY non-test caller of runReproducible() in the
+// tree, which is the single-seam property REPRO-02 requires.
+import { runReproducible, REPRODUCIBLE_RUN_REQUIRED_SIBLINGS } from "./stock-reproducible-run.ts";
 
 /** True iff `value` is a well-formed, generic JSON object -- not null, not
  * an array. Matches this module tree's own isPlainObject() convention
@@ -74,6 +78,24 @@ export const RUN_UNTIL_DEFAULT_TIMEOUT_MS = 30000;
  * value is. */
 export const RUN_UNTIL_MAX_TIMEOUT_MS = 600000;
 
+/** EVERY argument name `vice_run_until` accepts, and the ONLY definition of
+ * that set. Anything else is refused BY NAME (see handleRunUntil below).
+ *
+ * Hoisted to module scope and EXPORTED so `D-13`'s no-sub-flags rule is
+ * ASSERTED rather than merely stated: `stock-reproducible-run.test.ts` pins
+ * this array with a single `assert.deepEqual`, which is what makes a future
+ * `skip_reset`, `no_anchor` or `reset_only` a RED TEST rather than a review
+ * comment. Shipping a "protocol without the reset" option would ship exactly
+ * the second route `REPRO-02` exists to prevent a caller forgetting -- and the
+ * reset-removed CONTROL this phase records red is produced by an evidence
+ * script calling `runReproducible()`'s pieces directly, never by a published
+ * flag.
+ *
+ * `reproducible` and `frame_anchor` are STOCK-ONLY and both OPTIONAL: the fork
+ * manifest's tool list is frozen byte-identical from v0.1.x, and stock may add
+ * optional parameters but never removes, retypes, or newly-requires one. */
+export const RUN_UNTIL_KEYS: readonly string[] = ["address", "cycles", "timeout_ms", "reproducible", "frame_anchor"];
+
 /** Narrows an emitted `event` item to a CHECKPOINT_INFO event -- checked on
  * the parsed item's own `.type` discriminant, never on response type alone
  * (CHECKPOINT_INFO (0x11) shares a response type with a legitimate command
@@ -152,7 +174,6 @@ export const handleRunUntil: StockSessionHandler = async (args, session, _deps)
   // stock-timing.ts). Accepting them silently means a typo -- `timeoutMs` for
   // `timeout_ms`, `addr` for `address` -- runs with the DEFAULT bound and
   // reports a confident answer, and the caller has no way to tell.
-  const RUN_UNTIL_KEYS = ["address", "cycles", "timeout_ms"];
   const unexpectedKeys = Object.keys(args).filter((key) => !RUN_UNTIL_KEYS.includes(key));
   if (unexpectedKeys.length > 0) {
     return isErrorText(
@@ -223,6 +244,84 @@ export const handleRunUntil: StockSessionHandler = async (args, session, _deps)
     }
   }
 
+  // D-12: `reproducible` is a BOOLEAN. Any other type is refused naming the
+  // offending value -- never coerced. `reproducible: "false"` is truthy in
+  // JavaScript, so a coercing gate would run the whole protocol (including the
+  // hard reset) for a caller who wrote the string "false" meaning to disable
+  // it. Refusing is the only reading that cannot be wrong.
+  if (args.reproducible !== undefined && typeof args.reproducible !== "boolean") {
+    return isErrorText(
+      `vice_run_until: reproducible must be a boolean, got ${JSON.stringify(args.reproducible)} -- it is not coerced, because ` +
+        `the string "false" is truthy in JavaScript and coercing it would run the whole protocol (hard reset included) for a ` +
+        `caller who meant to disable it.`,
+    );
+  }
+
+  // `frame_anchor` goes through parseAddress with a `what:` label, exactly as
+  // `address` does, so a malformed anchor is refused with the same wording a
+  // malformed target gets rather than a second, divergent message.
+  let frameAnchor: number | undefined;
+  if (args.frame_anchor !== undefined) {
+    try {
+      frameAnchor = parseAddress(args.frame_anchor, { what: "vice_run_until frame_anchor" });
+    } catch (err) {
+      return isErrorText(`vice_run_until: ${describeError(err)}`);
+    }
+  }
+
+  // An ACCEPTED-AND-IGNORED argument is the exact defect the by-name gate above
+  // exists to prevent, so `frame_anchor` without `reproducible` is refused
+  // rather than silently dropped. It is not merely inert: a caller who supplies
+  // an anchor has asked for the anchored protocol, and answering from the
+  // ordinary path would report a confident `reached: true` for a run that was
+  // never anchored to a frame at all.
+  if (args.frame_anchor !== undefined && args.reproducible !== true) {
+    return isErrorText(
+      `vice_run_until: "frame_anchor" has no meaning without "reproducible": true -- the frame anchor is armed by the ` +
+        `reproducible protocol and by nothing else, so on the ordinary path this argument would be accepted and IGNORED while ` +
+        `the answer still reported a stop. Refused rather than dropped. Pass reproducible: true to run the anchored protocol, ` +
+        `or remove "frame_anchor".`,
+    );
+  }
+
+  // ---------------------------------------------------------------------
+  // THE ONE CALL SITE of the reproducible-run protocol (`REPRO-02`).
+  //
+  // One procedure, one branch, no sub-flags. `reproducible` is a
+  // WHOLE-PROCEDURE switch: absent or false takes the pre-existing path below
+  // COMPLETELY unchanged and never reaches runReproducible(). There is no
+  // second tool and no partial mode, because a second route is a route a
+  // caller can forget it took.
+  //
+  // Do not restructure the path below to "share" steps with the procedure. The
+  // reproducible sequence's ordering IS its content -- arm both while halted,
+  // hard reset, exactly one resume -- and a shared helper is how a step gets
+  // lifted out of that ordering by a later edit that looks like a cleanup.
+  // ---------------------------------------------------------------------
+  if (args.reproducible === true) {
+    // D-14's refusal, in the `cycles`-refusal register: it refuses whenever the
+    // protocol is requested without its required sibling, and it explains WHY
+    // refusing beats degrading rather than just reporting that a field is
+    // missing.
+    //
+    // The required name is read from REPRODUCIBLE_RUN_REQUIRED_SIBLINGS, not
+    // repeated as a literal here -- a second copy is how the message and the
+    // gate drift apart after a rename.
+    if (frameAnchor === undefined) {
+      return isErrorText(
+        `vice_run_until: reproducible: true requires ${REPRODUCIBLE_RUN_REQUIRED_SIBLINGS.join(", ")} -- an address executed ` +
+          `once per frame, whose hit count IS the frame term of the stop identity (PC, hit_count, (LIN, CYC)). No default is ` +
+          `supplied because the once-per-frame site is RELEASE-SPECIFIC: a cracked release almost always takes over the IRQ, ` +
+          `so no KERNAL site -- $EA31 included -- is safe to guess, and an anchor that never executes would bound out as a ` +
+          `timeout while looking like a wedge. Refusing beats silently degrading to a two-term stop identity: (LIN, CYC) is a ` +
+          `WITHIN-FRAME position, not a monotonic clock, so without the frame term two stops one whole frame apart certify as ` +
+          `the same stop. Pass frame_anchor, or drop reproducible to run the ordinary unanchored path.`,
+      );
+    }
+    const { result } = await runReproducible(session, { address, frameAnchor, timeoutMs, timeoutClamped });
+    return result;
+  }
+
   // Arm a temporary, stopping exec checkpoint at `address`. This is this
   // codebase's first caller in this tree to pass the temporary flag as
   // true: VICE itself auto-deletes a temporary checkpoint the instant it

package/stock-symbols.ts

@@ -19,9 +19,9 @@
 // Node's `fs` inside the MCP server's OWN process; there is no wire
 // filename argument at all, so the translation does not apply and applying
 // it would read the wrong file (or nothing). hostpath-consumers.test.ts's
-// closed five-member production consumer set (containerpath.ts,
-// install-resources.ts, stock-paths.ts, vice-proxy.ts, vice-sync.ts) must
-// stay exactly five -- this module joining it would fail that test outright.
+// closed four-member production consumer set (containerpath.ts,
+// install-resources.ts, stock-paths.ts, vice-proxy.ts) must stay exactly
+// four -- this module joining it would fail that test outright.
 //
 // The confirmed input format is a VICE label file, one `al C:xxxx .Name`
 // line per symbol, verified against ACME's `--vicelabels` output via
@@ -53,7 +53,7 @@
 import { readFileSync, realpathSync, statSync } from "node:fs";
 import { resolve, sep } from "node:path";
 
-import { ViceError, type ViceErrorOptions } from "./vice.ts";
+import { ViceError, type ViceErrorOptions } from "./vice-errors.ts";
 import { repoRoot } from "./repo-root.ts";
 import { parseAddress, setSymbolResolver, type SymbolResolver } from "./stock-address.ts";
 import { derivedAnswer, isErrorText } from "./stock-handler.ts";

package/stock-timing.ts

@@ -45,7 +45,7 @@ import {
   type ParsedCpuHistoryEntry,
   type StockProtocolError,
 } from "./stock-protocol.ts";
-import { MachineRestartedError } from "./vice.ts";
+import { MachineRestartedError } from "./vice-errors.ts";
 import { clampCpuHistoryCount, type StockConnectSession } from "./stock-connect.ts";
 import { registerCatalogFor } from "./stock-registers.ts";
 import { stockAnswer, convertWireError, isErrorText, type StockSessionHandler, type StockOkResult } from "./stock-handler.ts";

package/stop-oracle.ts

@@ -0,0 +1,167 @@
+// stop-oracle.ts -- the ONE authoritative place in this repo holding the
+// STOP-IDENTITY comparison: whether two stops of the same protocol, on the same
+// release, are the SAME stop. The oracle is the three-term
+// `(PC, hit_count, (LIN, CYC))`, expressed here as its four scalar terms.
+//
+// WHAT THIS MODULE CERTIFIES, AND WHY THAT DETERMINES ITS SHAPE: it certifies a
+// STOP. The captured 64K is the DEPENDENT VARIABLE -- the thing whose
+// reproducibility is being claimed on the strength of the stop being identical.
+// So the capture must never become a conjunct of the stop's own identity. If it
+// did, two runs that stopped in genuinely different places could be certified
+// "the same stop" because their memory happened to agree, and a capture would be
+// participating in certifying itself. That circularity, once it has certified a
+// capture, cannot be laundered back out of that capture's record -- which is why
+// it is barred by SHAPE rather than by convention (`CAP-03`, `D-26`):
+//
+//   1. This module takes NO image buffer. No exported function here declares a
+//      byte-array parameter of any kind, and `capture-seam.test.ts` asserts that
+//      from this module's own exported signatures, over stripped code, with a
+//      planted oracle-shaped module as its positive control.
+//   2. This module imports NOTHING from `capture-predicate.ts`, on any route,
+//      static or dynamic -- and that module imports nothing from here. Both
+//      directions are asserted, because the circularity is symmetric and a
+//      one-directional guard leaves half of it open.
+//
+// This module performs NO filesystem and NO network I/O, imports nothing at all,
+// and holds no module-level mutable state. It is four scalars in, one record
+// out.
+//
+// WHY FOUR TERMS AND NOT TWO: `(LIN, CYC)` is a WITHIN-FRAME position, not a
+// monotonic clock -- stock VICE's binary monitor has no monotonic cycle register
+// below 3.10 -- so two stops one whole frame apart can carry identical
+// `(LIN, CYC)`. `PC` and `hit_count` are what distinguish them, and the frame
+// term is what distinguishes two stops at the same PC and hit count within a
+// frame. Each term is load-bearing for a different confusion, and dropping any
+// one of them silently widens what counts as "the same stop".
+//
+// WHAT NOT TO DO:
+//   - Never add a parameter carrying capture bytes, a byte array, a memory
+//     image, or a value DERIVED from one (a digest, a differing-address count,
+//     an equivalence verdict). The derived-scalar route is the realistic one and
+//     the structural assertions cannot see it: a caller that reads the capture
+//     and passes a digest in here has reintroduced the circularity through a
+//     `number`. It is recorded as an accepted limit rather than left implicit.
+//   - Never import `capture-predicate.ts` here, and never reach it dynamically.
+//   - Never ship a two-term mode flag. `GATE-01`'s pre-mapped
+//     `ORACLE_NECESSITY: unproven` narrowing is implementable by READING
+//     `differingTerms` and treating the frame entries as recorded-not-fatal;
+//     `frameTermAsserted` records which form the comparison used and does not
+//     select one. `D-13`'s no-sub-flags rule is about the run protocol, and the
+//     same reasoning applies here -- a published second mode is a second route a
+//     caller can forget it took.
+//   - Never substitute a zero, a null or a sentinel for a term the caller did
+//     not supply. A partial stop record is REFUSED, naming the term and the
+//     side. Silently passing on a partial record is the one failure this module
+//     must not have: it would certify two stops as identical on the strength of
+//     the terms that happened to be present.
+//   - Never hardcode a wire register id for `PC`, `LIN` or `CYC` anywhere near
+//     this module. Register ids are not stable across builds, and
+//     `stock-timing.ts`'s `registerCatalogFor()` is the only route from a
+//     register NAME to its id. This module takes already-read numbers and never
+//     touches a wire.
+
+/** The four scalar terms of the three-term stop-identity oracle
+ * `(PC, hit_count, (LIN, CYC))`. The frame term is a pair, which is why four
+ * scalars express three terms.
+ *
+ * Ordering is normative: `differingTerms` below is reported in this order, so a
+ * reader comparing two transcripts sees the terms in the same sequence every
+ * time. */
+export const ORACLE_TERMS = ["pc", "hitCount", "line", "cycle"] as const;
+
+/** One member of `ORACLE_TERMS`. */
+export type OracleTerm = (typeof ORACLE_TERMS)[number];
+
+/** One stop, as its four already-read scalar terms. No bytes, by design -- see
+ * this module's header. */
+export interface StopIdentity {
+  /** The program counter at the stop. */
+  pc: number;
+  /** The checkpoint's hit count at the stop. */
+  hitCount: number;
+  /** `LIN` -- the raster line. Half of the frame term. */
+  line: number;
+  /** `CYC` -- the cycle within the raster line. The other half. */
+  cycle: number;
+}
+
+/** Raised when a stop record cannot be compared. Carries the term and the side
+ * so a caller's failure output names both rather than paraphrasing. */
+export class StopOracleError extends Error {
+  readonly term: string;
+  readonly side: string;
+  constructor(message: string, term: string, side: string) {
+    super(message);
+    this.name = "StopOracleError";
+    this.term = term;
+    this.side = side;
+  }
+}
+
+/** The verdict. */
+export interface StopIdentityComparison {
+  /** True iff every term in `ORACLE_TERMS` agrees. */
+  identical: boolean;
+  /** Which terms differ, ordered as `ORACLE_TERMS` is. */
+  differingTerms: string[];
+  /** Whether the frame term participated in the verdict.
+   *
+   * `true` for every comparison this function performs: all four terms are
+   * asserted, always. The field exists so `GATE-01`'s pre-mapped
+   * `ORACLE_NECESSITY: unproven` narrowing is implementable without a rewrite --
+   * under that narrowing the frame term is RECORDED but not ASSERTED, and a
+   * caller expresses it by reading `differingTerms` and treating the
+   * `line`/`cycle` entries as recorded rather than fatal. It RECORDS which form
+   * the comparison used; it never selects one. */
+  frameTermAsserted: boolean;
+}
+
+/** Every term of one side, validated. Throws naming the term and the side
+ * rather than returning a partial record: there is no honest way to compare
+ * stops when a term is absent, and no sentinel that would not be a lie. */
+function requireTerms(record: StopIdentity, side: string): void {
+  if (record === null || typeof record !== "object") {
+    throw new StopOracleError(
+      `compareStopIdentity: side ${side} is not a stop record -- expected an object carrying ${ORACLE_TERMS.join(", ")}`,
+      "(whole record)",
+      side,
+    );
+  }
+  for (const term of ORACLE_TERMS) {
+    const value: unknown = record[term];
+    if (typeof value !== "number" || !Number.isFinite(value) || !Number.isInteger(value)) {
+      throw new StopOracleError(
+        `compareStopIdentity: term "${term}" is absent or not a finite integer on side ${side} ` +
+          `(got ${JSON.stringify(value)}) -- refusing rather than passing on a partial stop record, which ` +
+          `would certify two stops as identical on the strength of the terms that happened to be present`,
+        term,
+        side,
+      );
+    }
+  }
+}
+
+/** Compare two stops under the three-term oracle.
+ *
+ * Symmetric in its arguments: the verdict and `differingTerms` depend only on
+ * WHICH terms disagree, never on which record was passed first. Two stops with
+ * identical `pc` and `hitCount` whose frame position is one frame apart compare
+ * NOT identical -- that is the frame term doing its job, and it is the whole
+ * reason a two-term oracle is insufficient. */
+export function compareStopIdentity(a: StopIdentity, b: StopIdentity): StopIdentityComparison {
+  requireTerms(a, "a");
+  requireTerms(b, "b");
+
+  // Built by walking ORACLE_TERMS, so the reported order IS the declared order
+  // and cannot drift from it after an edit.
+  const differingTerms: string[] = [];
+  for (const term of ORACLE_TERMS) {
+    if (a[term] !== b[term]) differingTerms.push(term);
+  }
+
+  return {
+    identical: differingTerms.length === 0,
+    differingTerms,
+    frameTermAsserted: true,
+  };
+}