@henols/c64-re-tools 2.0.0-rc.4 → 2.0.0-rc.5

package/src/knowledge/import.ts

@@ -6,7 +6,9 @@
 // that the snapshot no longer holds are closed. Rows of the user, the LLM or
 // another analyzer are never replaced: a finding that contradicts one is
 // reported as a conflict. Code against data is a contradiction; a different
-// name or a finer data type for the same kind of memory is not.
+// name or a finer data type for the same kind of memory is not. One exception
+// (D58): where a run executed an instruction start, a code finding replaces
+// the data of another analyzer, never of the user, the LLM or a heuristic.
 
 import { createHash } from "node:crypto";
 import type { DatabaseSync } from "node:sqlite";
@@ -28,7 +30,7 @@ import {
   type SymbolRow,
 } from "./read.ts";
 import { CODE_REGION_TYPES, DEFAULT_SPACE, REFERENCE_KINDS, REGION_TYPES, SYMBOL_KINDS, type Origin, type ReferenceKind, type RegionType, type Space, type SymbolKind } from "./schema.ts";
-import { Change, checkAddress, checkSpace, hex, subtract, SYMBOL_NAME, type AddressRange } from "./write.ts";
+import { Change, checkAddress, checkSpace, hex, subtract, SYMBOL_NAME, type AddressRange, type Evidence } from "./write.ts";
 
 export type { AddressRange };
 
@@ -47,6 +49,8 @@ export interface NormalizedFindings {
   regions: Array<{ start: number; end: number; type: RegionType }>;
   /** Owned and covered by their source address. */
   references: Array<{ from: number; to: number; kind: ReferenceKind }>;
+  /** True for an address where a coverage run executed an instruction start (D58). */
+  executed?: (address: number) => boolean;
 }
 
 export interface ImportContext {
@@ -57,6 +61,8 @@ export interface ImportContext {
   inputHash?: string;
   /** The analyzer's own version line. */
   toolVersion?: string;
+  /** What the import rests on besides the image, for example the coverage files. */
+  evidence?: Evidence[];
 }
 
 /** What a revision records about one analyzer run: the hash of the image bytes and, when the analyzer tells it, its version. */
@@ -204,7 +210,13 @@ function importSymbols(db: DatabaseSync, change: Change, findings: NormalizedFin
       result.symbols.suppressed++;
       continue;
     }
-    const current = symbolAt(db, finding.address, space);
+    let current = symbolAt(db, finding.address, space);
+    if (current !== undefined && isCode(finding.kind) && !isCode(current.kind) && YIELDS_TO_EXECUTED_CODE.has(current.origin) && findings.executed?.(finding.address) === true) {
+      // A run executed this address: the data symbol of another analyzer gives way (D58).
+      change.close("symbols", "space = ? AND address = ?", space, current.address);
+      result.symbols.retired++;
+      current = undefined;
+    }
     if (current !== undefined) {
       // A semantic or other-analyzer row stays; only a code/data disagreement matters.
       if (isCode(current.kind) !== isCode(finding.kind)) {
@@ -230,6 +242,15 @@ function importSymbols(db: DatabaseSync, change: Change, findings: NormalizedFin
 
 /** Analyzers whose regions a heuristic finding replaces where it lies (D44): user/LLM > heuristic > DXA/Ghidra. */
 const YIELDS_TO_HEURISTIC = new Set<Origin>(["dxa", "ghidra"]);
+/** Analyzers whose data gives way to a code finding over an executed instruction start (D58). */
+const YIELDS_TO_EXECUTED_CODE = new Set<Origin>(["dxa", "ghidra"]);
+
+/** True when an address in the range is an executed instruction start. */
+function holdsExecuted(findings: NormalizedFindings, start: number, end: number): boolean {
+  if (findings.executed === undefined) return false;
+  for (let address = start; address <= end; address++) if (findings.executed(address)) return true;
+  return false;
+}
 
 function importRegions(db: DatabaseSync, change: Change, findings: NormalizedFindings, coverage: AddressRange[], result: ImportResult): void {
   const { analyzer } = findings;
@@ -243,6 +264,16 @@ function importRegions(db: DatabaseSync, change: Change, findings: NormalizedFin
       }
     }
   }
+  // Executed code is evidence about its bytes (D58): another analyzer's data region under a code finding gives way where a run executed an instruction start.
+  for (const region of findings.regions.filter((candidate) => isCode(candidate.type))) {
+    for (const row of regionsOverlapping(db, region.start, region.end, space)) {
+      if (row.origin === analyzer || !YIELDS_TO_EXECUTED_CODE.has(row.origin) || isCode(row.type) || row.type === "dual-use") continue;
+      if (!holdsExecuted(findings, Math.max(row.start, region.start), Math.min(row.end, region.end))) continue;
+      change.close("regions", "space = ? AND start_address = ? AND end_address = ? AND origin = ?", space, row.start, row.end, row.origin);
+      for (const piece of subtract(row, [region])) change.insertRegion({ space, ...piece, type: row.type, ...(row.element === undefined ? {} : { element: row.element }), origin: row.origin });
+      result.regions.retired++;
+    }
+  }
   const conflictWith = (row: RegionRow, region: { start: number; end: number; type: RegionType }) => {
     // dual-use bytes are code at one time and data at another: neither finding contradicts them (D42).
     if (isCode(row.type) === isCode(region.type) || row.type === "dual-use") return;

package/src/knowledge/write.ts

@@ -436,8 +436,9 @@ function checkModule(request: ModuleRequest): void {
 
 function moduleStep(db: DatabaseSync, change: Change, origin: Origin, request: ModuleRequest): Step<ModuleRow> {
   const space = spaceOf(request);
-  const title = request.title?.trim();
   const existing = moduleAt(db, request.start, space);
+  // A module write without a title keeps the title it has (F-26).
+  const title = request.title === undefined ? existing?.title : request.title.trim();
   if (existing !== undefined && existing.file === request.file && existing.title === title) return { current: existing };
   const owner = moduleWithFile(db, request.file, space);
   if (owner !== undefined && owner.start !== request.start) {

package/src/mcp/main.ts

@@ -13,17 +13,18 @@ import { machineTools } from "./tools/machine.ts";
 import { mediaTools } from "./tools/media.ts";
 import { memoryTools } from "./tools/memory.ts";
 import { videoTools } from "./tools/video.ts";
+import { PACKAGE } from "../package.ts";
 
 const HELP = `c64-re-tools-mcp
 
 Usage:
-  npx -y --package=@henols/c64-re-tools@latest c64-re-tools-mcp
+  npx -y --package=${PACKAGE.name}@${PACKAGE.tag} c64-re-tools-mcp
   c64-re-tools-mcp --help
 
 Runs the stateful C64 MCP server on stdio. Each c64-re-tools-mcp process owns
 one C64 emulator, started by the Host Runtime (c64-re-tools-host) when this
 server starts and stopped when it exits. c64-re-tools install declares it for
-the agent, through npx with the latest version.
+the agent, through npx with the newest version of its channel.
 
 Environment:
   C64RT_VIDEO  pal (default) or ntsc; fixed for the life of the process.
@@ -42,32 +43,59 @@ function videoStandard(env: NodeJS.ProcessEnv): VideoStandard {
 }
 
 /**
- * One session for the life of the process (1 MCP = 1 session = 1 VICE).
- * It opens at start; if that fails before a session existed (for example the
- * host was not running yet), the next tool call tries again. Once a session
- * existed, its loss is final and reported by the session itself. Close stops
+ * One session at a time (1 MCP = 1 session = 1 VICE). It opens at start; if
+ * that fails (for example the host was not running yet), the next tool call
+ * tries again. When the host connection is lost, the next call opens a new
+ * session (D57). A lost session that the emulator answered first gives its
+ * machine-state-lost once, unless a pending call got it already. Close stops
  * an open that is still waiting for the host at once.
  */
 function sessionSource(): { get: SessionSource; close(): Promise<void> } {
   let opening: Promise<ViceSessionClient> | undefined;
+  let lostNotice: WireFailure | undefined;
   let closed = false;
   const stop = new AbortController();
   const open = () => {
     const started = performance.now();
-    opening = (async () => ViceSessionClient.open({ videoStandard: videoStandard(process.env), signal: stop.signal }))();
-    void opening.then(() => trace().event("session.opened", { ms: elapsedMs(started) }), () => {});
-    opening.catch((error: unknown) => {
+    const current = (async () => ViceSessionClient.open({ videoStandard: videoStandard(process.env), signal: stop.signal }))();
+    opening = current;
+    void current.then(
+      (client) => {
+        trace().event("session.opened", { ms: elapsedMs(started) });
+        void client.closed.then(() => drop(current, client));
+      },
+      () => {},
+    );
+    current.catch((error: unknown) => {
       log(`session not opened: ${error instanceof Error ? error.message : String(error)}`);
-      opening = undefined;
+      if (opening === current) opening = undefined;
     });
-    return opening;
+    return current;
+  };
+  /** Forgets a lost session, once; the next call opens a new one. */
+  const drop = (current: Promise<ViceSessionClient>, client: ViceSessionClient) => {
+    if (closed || opening !== current) return;
+    log("the connection to the host runtime was lost; the next call opens a new session");
+    opening = undefined;
+    if (client.answered) lostNotice = client.unreportedLoss;
   };
   open();
+  const get = async (): Promise<ViceSessionClient> => {
+    if (closed) throw new WireFailure("machine-unavailable", "The C64 session is shutting down.");
+    if (lostNotice !== undefined) {
+      const notice = lostNotice;
+      lostNotice = undefined;
+      throw notice;
+    }
+    const current = opening ?? open();
+    const client = await current;
+    if (!client.lost) return client;
+    // The loss is known here before the close event reaches drop.
+    drop(current, client);
+    return get();
+  };
   return {
-    get: () => {
-      if (closed) return Promise.reject(new WireFailure("machine-unavailable", "The C64 session is shutting down."));
-      return opening ?? open();
-    },
+    get,
     async close() {
       closed = true;
       stop.abort();

package/src/mcp/server.ts

@@ -8,7 +8,7 @@ import { CallToolRequestSchema, ListToolsRequestSchema, type CallToolResult, typ
 import { z } from "zod";
 
 import { formatC64Address, parseC64Address } from "../c64.ts";
-import type { ViceSessionClient } from "../host-client/vice-session.ts";
+import { LostBeforeAnswer, type ViceSessionClient } from "../host-client/vice-session.ts";
 import { shownMessage, WireFailure, type WireError } from "../protocol/messages.ts";
 import { COMPARISONS, CONDITION_REGISTERS, MEMORY_VIEWS, SPACES, type Condition } from "../protocol/vice.ts";
 import { elapsedMs, trace, type TraceFields } from "../trace.ts";
@@ -261,7 +261,14 @@ async function runCall(
   const parsed = tool.inputSchema.safeParse(args ?? {});
   if (!parsed.success) return errorResult({ code: "invalid-input", message: describeIssues(parsed.error) });
   try {
-    const output = await tool.run(parsed.data, await session());
+    let output: unknown;
+    try {
+      output = await tool.run(parsed.data, await session());
+    } catch (error) {
+      // A session that the emulator never answered had no machine state: the call goes again on a new session (D57).
+      if (!(error instanceof LostBeforeAnswer)) throw error;
+      output = await tool.run(parsed.data, await session());
+    }
     // The result goes out in the shape that the tool listing advertises: keys
     // that the output schema does not name are removed, and a result that does
     // not fit the schema is an internal failure.

package/src/mcp/tools/execution.ts

@@ -3,7 +3,7 @@
 import { z } from "zod";
 
 import { formatC64Address } from "../../c64.ts";
-import { COMPARISONS, EXECUTION_ACTIONS, MAX_EXECUTION_COUNT, MAX_TIMEOUT_FRAMES, RUN_STATES, STOP_REASONS, type RunTarget } from "../../protocol/vice.ts";
+import { COMPARISONS, EXECUTION_ACTIONS, MAX_EXECUTION_COUNT, MAX_TIMEOUT_FRAMES, RUN_STATES, SPACES, STOP_REASONS, type RunTarget } from "../../protocol/vice.ts";
 import { AddressInput, AddressOutput, Byte, ConditionInput, defineTool, MemoryViewInput, SpaceInput, toCondition } from "../server.ts";
 
 export const c64Execution = defineTool({
@@ -88,6 +88,7 @@ export const c64RunUntil = defineTool({
     "Kind raster stops at the first instruction at or after a raster line and cycle. If the machine is there now, it stops at the next frame's pass. " +
     `timeoutFrames (1 to ${MAX_TIMEOUT_FRAMES}, default 3000) limits the run in video frames. ` +
     "reached tells if the target occurred. stopReason tells why the CPU stopped: target, breakpoint, watchpoint, jam (a JAM opcode) or timeout. " +
+    "space tells which CPU stopped: c64, or drive8 for a stop in the disk drive. pc is the address in that space. " +
     "The CPU is always stopped after this tool.",
   inputSchema: z
     .object({
@@ -95,7 +96,7 @@ export const c64RunUntil = defineTool({
       timeoutFrames: z.number().int().min(1).max(MAX_TIMEOUT_FRAMES).default(3000),
     })
     .strict(),
-  outputSchema: z.object({ reached: z.boolean(), stopReason: z.enum(STOP_REASONS), state: z.enum(RUN_STATES), pc: AddressOutput }),
+  outputSchema: z.object({ reached: z.boolean(), stopReason: z.enum(STOP_REASONS), state: z.enum(RUN_STATES), pc: AddressOutput, space: z.enum(SPACES) }),
   readOnly: false,
   async run(input, session) {
     const { target: given } = input;

package/src/mcp/tools/input.ts

@@ -7,6 +7,8 @@ import { WireFailure } from "../../protocol/messages.ts";
 import { JOYSTICK_DIRECTIONS, MAX_KEYBOARD_BYTES } from "../../protocol/vice.ts";
 import { defineTool } from "../server.ts";
 
+const EMULATOR_FLAW = z.string().optional().describe("a known flaw of the emulator version that affects input, and the version that fixes it");
+
 export const c64Keyboard = defineTool({
   name: "c64_keyboard",
   title: "Type on the C64 keyboard",
@@ -16,7 +18,7 @@ export const c64Keyboard = defineTool({
     "No command presses one key of the keyboard matrix: for one specific key, ask the user to press it in the window. " +
     'Mode text types text, for example "RUN\\n". Letters of either case type the normal (unshifted) key. A line break types RETURN. ' +
     "Mode petscii types PETSCII codes 1 to 255 in bytes, for example [147] to clear the screen. " +
-    "This does not change the run state of the machine.",
+    "This does not change the run state of the machine. emulatorFlaw in the result names a known flaw of the emulator version that affects input, and the version that fixes it.",
   inputSchema: z
     .object({
       mode: z.enum(["text", "petscii"]),
@@ -24,7 +26,7 @@ export const c64Keyboard = defineTool({
       bytes: z.array(z.number().int().min(1).max(255)).min(1).optional().describe("mode petscii: PETSCII codes to type"),
     })
     .strict(),
-  outputSchema: z.object({ queuedBytes: z.number().int().min(1).max(MAX_KEYBOARD_BYTES) }),
+  outputSchema: z.object({ queuedBytes: z.number().int().min(1).max(MAX_KEYBOARD_BYTES), emulatorFlaw: EMULATOR_FLAW }),
   readOnly: false,
   async run(input, session) {
     let petscii: Uint8Array;
@@ -52,7 +54,7 @@ export const c64Joystick = defineTool({
   description:
     "Set the joystick in control port 1 or 2: a direction (or center) and the fire button. " +
     "The C64 sees this state until you change it. To release the joystick, set direction center and fire false. " +
-    "Most games read port 2. This does not change the run state of the machine.",
+    "Most games read port 2. This does not change the run state of the machine. emulatorFlaw in the result names a known flaw of the emulator version that affects input, and the version that fixes it.",
   inputSchema: z
     .object({
       port: z.union([z.literal(1), z.literal(2)]).describe("control port 1 or 2"),
@@ -60,7 +62,7 @@ export const c64Joystick = defineTool({
       fire: z.boolean().default(false),
     })
     .strict(),
-  outputSchema: z.object({ port: z.union([z.literal(1), z.literal(2)]), direction: z.enum(JOYSTICK_DIRECTIONS), fire: z.boolean() }),
+  outputSchema: z.object({ port: z.union([z.literal(1), z.literal(2)]), direction: z.enum(JOYSTICK_DIRECTIONS), fire: z.boolean(), emulatorFlaw: EMULATOR_FLAW }),
   readOnly: false,
   async run(input, session) {
     return session.joystick(input);

package/src/mcp/tools/media.ts

@@ -20,19 +20,20 @@ export const c64Autostart = defineTool({
   description:
     `Start a program, or a disk, tape or cartridge image, from the project (${list(AUTOSTART_TYPES)}). ` +
     "The C64 resets and loads the file. With run true (the default), it also runs the file. A disk image stays in drive 8. " +
-    "index selects a file on a disk image (default 0, the first file). " +
+    "Without index, a disk image loads like LOAD\"*\",8,1. index selects one directory entry by its number in the c64-disk directory list (0 is the first entry). " +
     "The machine runs when this tool returns, and the load continues.",
   inputSchema: z
     .object({
       path: ProjectPath,
-      index: z.number().int().min(0).max(0xffff).default(0).describe("file number on a disk image. 0 is the first file"),
+      index: z.number().int().min(0).max(0xfffe).optional().describe("directory entry of a disk image, 0 is the first entry. Without it, the first file loads as with LOAD\"*\""),
       run: z.boolean().default(true).describe("true runs the program after it loads"),
     })
     .strict(),
   outputSchema: z.object({ state: z.enum(RUN_STATES) }),
   readOnly: false,
   async run(input, session) {
-    return session.autostart(input);
+    // VICE numbers the directory entries from 1, and its 0 loads "*".
+    return session.autostart({ path: input.path, index: input.index === undefined ? 0 : input.index + 1, run: input.run });
   },
 });
 

package/src/native/discover.ts

@@ -69,10 +69,44 @@ export const VICE: ToolSpec = {
  */
 export const MIN_VICE = { major: 3, minor: 9 } as const;
 
-/** "x64sc (VICE 3.10)", "c1541 (VICE 3.9)" or "VICE 3.9.0": the major and minor version. */
-export function viceVersionOf(text: string): { major: number; minor: number } | undefined {
-  const match = /VICE (\d+)\.(\d+)/.exec(text);
-  return match === null ? undefined : { major: Number(match[1]), minor: Number(match[2]) };
+/** A VICE version; `revision` is the SVN revision of a build from VICE's source tree (nightly builds), absent for a release. */
+export interface ViceVersion {
+  major: number;
+  minor: number;
+  revision?: number;
+}
+
+/** "x64sc (VICE 3.10)", "c1541 (VICE 3.9)", "VICE 3.9.0" or "x64sc (VICE 3.10 SVN r45999)": the major and minor version, and the SVN revision. */
+export function viceVersionOf(text: string): ViceVersion | undefined {
+  const match = /VICE (\d+)\.(\d+)(?:[.\d]*)(?: SVN r(\d+))?/.exec(text);
+  if (match === null) return undefined;
+  return { major: Number(match[1]), minor: Number(match[2]), ...(match[3] === undefined ? {} : { revision: Number(match[3]) }) };
+}
+
+/**
+ * Known flaws of VICE versions that c64-re-tools still runs on (D56). A flaw
+ * is not worked around: it is named with the VICE version that fixes it.
+ * `upTo` is the last flawed major.minor; `fixedRevision` the first SVN
+ * revision with the fix, for builds from VICE's source tree.
+ */
+const VICE_FLAWS = [
+  {
+    upTo: { major: 3, minor: 10 },
+    fixedRevision: 45971,
+    text:
+      "VICE 3.10 and older hold bits 5-7 of CIA 1 ports A and B low with the joystick device that c64-re-tools uses (VICE bug #2202). " +
+      "$DC00 and $DC01 read $1F with no input. A program that waits for one key of the keyboard matrix (for example LDA $DC01 / CMP #$EF for SPACE) waits forever. " +
+      "A program that compares the full byte of a joystick port also waits forever. The fix is in the next VICE release, and in VICE nightly builds now (SVN r45971 or later). " +
+      "Install the latest VICE when this matters.",
+  },
+] as const;
+
+/** The known flaws of this VICE version, as text for a person or an agent. */
+export function viceFlaws(version: ViceVersion): string[] {
+  return VICE_FLAWS.filter((flaw) => {
+    const newer = version.major > flaw.upTo.major || (version.major === flaw.upTo.major && version.minor > flaw.upTo.minor);
+    return !newer && (version.revision === undefined || version.revision < flaw.fixedRevision);
+  }).map((flaw) => flaw.text);
 }
 
 export function isOlderThanMinimum(version: { major: number; minor: number }): boolean {

package/src/package.ts

@@ -0,0 +1,21 @@
+// The name, version and npm channel of this copy of c64-re-tools, for the npx
+// commands that refusals and help texts give. The package.json above src/ is
+// the package's own one; in an installed skill it is the skill's one, which
+// has the same name and version (distribution/plugin.ts).
+
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+
+/**
+ * The npm dist-tag that a version is published under: a prerelease
+ * (2.0.0-rc.1) goes to "next", a release to "latest".
+ */
+export function channelOf(version: string): "latest" | "next" {
+  return version.includes("-") ? "next" : "latest";
+}
+
+/** The name, version and dist-tag of this npm package, from its package.json. */
+export const PACKAGE = (() => {
+  const metadata = JSON.parse(readFileSync(join(import.meta.dirname, "..", "package.json"), "utf8")) as { name: string; version: string };
+  return { name: metadata.name, version: metadata.version, tag: channelOf(metadata.version) };
+})();

package/src/protocol/tools.ts

@@ -61,7 +61,7 @@ export type PetcatResult =
   | {
       decoded: true;
       loadAddress: number;
-      /** The address after the BASIC end marker; any bytes from here on are no BASIC. */
+      /** The first address that holds no BASIC: after a 00 00 end marker, or at a link whose high byte only is zero. */
       basicEnd: number;
       listing: string;
       lines: Array<{ number: number; text: string }>;
@@ -79,6 +79,8 @@ export interface ToolStatus {
   runs: boolean;
   /** What is wrong and what to do, when it is missing or does not run. */
   problem?: string;
+  /** Known flaws of this version, each with the version that fixes it (D56). The tool still runs. */
+  flaws?: string[];
 }
 
 export interface ToolOperations {
@@ -173,7 +175,8 @@ export function validateToolResult<O extends ToolOperation>(op: O, value: unknow
         typeof tool.name === "string" &&
         typeof tool.found === "boolean" &&
         typeof tool.runs === "boolean" &&
-        [tool.path, tool.version, tool.problem].every((field) => field === undefined || typeof field === "string");
+        [tool.path, tool.version, tool.problem].every((field) => field === undefined || typeof field === "string") &&
+        (tool.flaws === undefined || (Array.isArray(tool.flaws) && tool.flaws.every((flaw: unknown) => typeof flaw === "string")));
       if (!Array.isArray(tools) || !tools.every(isStatus) || attachments.length !== 0) throw new ProtocolError("host.status result is malformed");
       return value as unknown as ToolOperations[O]["result"];
     }
@@ -233,7 +236,8 @@ function isPetcatResult(value: Fields): boolean {
     isObject(handoff) &&
     isInteger(handoff.line, 0, 0xffff) &&
     ((handoff.kind === "sys" && isInteger(handoff.address, 0, 0xffff) && handoff.computed === undefined) ||
-      ((handoff.kind === "sys" || handoff.kind === "usr") && handoff.computed === true && handoff.address === undefined));
+      (handoff.kind === "sys" && handoff.computed === true && handoff.address === undefined && typeof handoff.expression === "string") ||
+      (handoff.kind === "usr" && handoff.computed === true && handoff.address === undefined));
   return (
     value.decoded === true &&
     isInteger(value.loadAddress, 0, 0xffff) &&

package/src/protocol/vice.ts

@@ -389,7 +389,9 @@ export interface RunUntilResult {
   reached: boolean;
   stopReason: StopReason;
   state: RunState;
+  /** The PC of the CPU in `space`: the CPU that stopped. */
   pc: number;
+  space: Space;
 }
 
 export interface ViceOperations {
@@ -414,15 +416,16 @@ export interface ViceOperations {
   runUntil: { params: { target: RunTarget; timeoutFrames: number }; result: RunUntilResult };
   /** Attachment: the PRG bytes, load address first. */
   programLoad: { params: { address?: number }; result: { state: RunState; loadAddress: number; size: number } };
-  /** Attachment: the program or image bytes; `type` is the file's extension. */
+  /** Attachment: the program or image bytes; `type` is the file's extension. `index` is VICE's file number: 0 loads "*", 1 is the first directory entry. */
   autostart: { params: { type: string; index: number; run: boolean }; result: { state: RunState } };
   /** Attachment: the disk image bytes; `type` is the file's extension. */
   diskAttach: { params: { type: string }; result: { attached: boolean } };
   /** pc is the reset vector when run is false: the CPU stops there. */
   reset: { params: { mode: ResetMode; run: boolean }; result: { state: RunState; pc?: number } };
   /** `data`: PETSCII bytes as lowercase hex. */
-  keyboard: { params: { data: string }; result: { queuedBytes: number } };
-  joystick: { params: JoystickState; result: JoystickState };
+  /** `emulatorFlaw`: a known flaw of the host's VICE version that this input meets (D56). */
+  keyboard: { params: { data: string }; result: { queuedBytes: number; emulatorFlaw?: string } };
+  joystick: { params: JoystickState; result: JoystickState & { emulatorFlaw?: string } };
   breakpoint: { params: BreakpointParams; result: Breakpoint | PointRemoved | { breakpoints: Breakpoint[] } };
   watchpoint: { params: WatchpointParams; result: Watchpoint | PointRemoved | { watchpoints: Watchpoint[] } };
   cpuHistory: { params: { limit: number; space: Space }; result: { entries: HistoryEntry[] } };
@@ -1031,7 +1034,8 @@ export function validateViceResult<O extends ViceOperation>(op: O, value: unknow
         typeof value.reached === "boolean" &&
         isOneOf(STOP_REASONS, value.stopReason) &&
         isOneOf(RUN_STATES, value.state) &&
-        isInteger(value.pc, 0, 0xffff);
+        isInteger(value.pc, 0, 0xffff) &&
+        isOneOf(SPACES, value.space);
       if (!ok) throw new ProtocolError("runUntil result is malformed");
       break;
     }
@@ -1060,7 +1064,7 @@ export function validateViceResult<O extends ViceOperation>(op: O, value: unknow
       break;
     }
     case "keyboard": {
-      if (!isInteger(value.queuedBytes, 1, MAX_KEYBOARD_BYTES)) throw new ProtocolError("keyboard result is malformed");
+      if (!isInteger(value.queuedBytes, 1, MAX_KEYBOARD_BYTES) || !(value.emulatorFlaw === undefined || typeof value.emulatorFlaw === "string")) throw new ProtocolError("keyboard result is malformed");
       break;
     }
     case "breakpoint": {
@@ -1265,7 +1269,11 @@ export function validateViceResult<O extends ViceOperation>(op: O, value: unknow
       break;
     }
     case "joystick": {
-      const ok = (value.port === 1 || value.port === 2) && isOneOf(JOYSTICK_DIRECTIONS, value.direction) && typeof value.fire === "boolean";
+      const ok =
+        (value.port === 1 || value.port === 2) &&
+        isOneOf(JOYSTICK_DIRECTIONS, value.direction) &&
+        typeof value.fire === "boolean" &&
+        (value.emulatorFlaw === undefined || typeof value.emulatorFlaw === "string");
       if (!ok) throw new ProtocolError("joystick result is malformed");
       break;
     }