@henols/vice-mcp 0.1.9 → 0.1.11

package/resources/vice-broker.mjs

@@ -29,8 +29,17 @@ import { join, basename, resolve as resolvePath } from "node:path";
 import { fileURLToPath } from "node:url";
 import { spawn as nodeSpawn } from "node:child_process";
 import { containerGuardReport, containerGuardEnforce } from "./container-guard.mjs";
-import { createBrokerState, nextFreePort, countReady, countTotal, countLaunching, atCapacity, resolveBasePort, } from "./broker-state.mjs";
-import { acquirePortAndLaunch, maintainWarmFloor, probeReady, runBrokerPass, withCrashSupervision, } from "./broker-launch.mjs";
+import { createBrokerState, nextFreePort, countReady, countTotal, countLaunching, atCapacity, resolveBasePort, clearMonitorClient, } from "./broker-state.mjs";
+import { acquirePortAndLaunch, deleteInstanceRecord, maintainWarmFloor, probeReady, runBrokerPass, withCrashSupervision, } from "./broker-launch.mjs";
+// Plan 02-07: resolvedBackend() is now the ONE reader of VICE_BACKEND in
+// this tree -- ViceBackend's own definition moved to backend-detect.mts too,
+// so broker-launch.mjs's own (type-only) re-import of it and this file's
+// VALUE import both name the same one home. A real value import is safe
+// here (unlike inside broker-launch.mts) because vice-broker.mts is ALWAYS
+// run from its own compiled resources/ form -- both modules are compiled
+// together in the same build.ts pass, so "./backend-detect.mjs" always
+// exists as a real sibling file by the time this import resolves.
+import { resolvedBackend } from "./backend-detect.mjs";
 import { verifiedKill, registerShutdownHandlers, startupBanner, reapOrphanedInstances } from "./broker-kill.mjs";
 import { writeEpochRecord, epochPathFor, nextEpochFor, instanceLogDirFor } from "./broker-epoch.mjs";
 import { startControlListener, newControlToken, drainPendingAcquires, resolveControlPort, } from "./broker-control.mjs";
@@ -226,15 +235,45 @@ function writeEpochForLaunch(record, logRelPath) {
  * epoch record naming the wrong one. Leaving it unset means a respawn's
  * output lands in the supervision module's own log file under the same
  * per-instance logs directory D-23 requires, and the epoch record names
- * the file that actually received the output. */
-function superviseDepsFor(stateDir, state) {
+ * the file that actually received the output.
+ *
+ * CR-01 (03-REVIEW.md): `backend` is a REQUIRED positional parameter, not an
+ * optional field a call site may quietly omit. Before this, both real call
+ * sites built their deps here WITHOUT it, so `spawnAndRecordInstance()`'s own
+ * `deps.backend ?? "fork"` default silently took over the moment crash
+ * supervision replaced an instance -- a stock instance's crash-respawn or
+ * `vice_recycle` relaunched it with the FORK's `-mcpserver` argv, which stock
+ * upstream VICE does not understand at all, leaving a pool member that can
+ * never be reached over the binary monitor again while still counting toward
+ * countReady()/countTotal(). Making it positional and required is what makes
+ * that omission a compile error rather than a silent backend swap: the FIRST
+ * launch and every REPLACEMENT of it now build their argv from the SAME
+ * resolved verdict. `binmonHost` is threaded for the same reason, one step
+ * ahead of need -- no broker call site configures a stock bind override today
+ * (acquirePortAndLaunch()'s own `binmonHost` is likewise unset), so it is
+ * always `undefined` in production right now; the parameter exists so that
+ * adding one later cannot reintroduce exactly this divergence between a
+ * launch's argv and its respawn's argv. */
+function superviseDepsFor(stateDir, state, backend, binmonHost) {
     return {
         state,
         stateDir,
         epoch: { epochPathFor, instanceLogDirFor, nextEpochFor, writeEpochRecord },
         log: (line) => process.stderr.write(`${line}\n`),
+        backend,
+        binmonHost,
     };
 }
+/** Exported ONLY so a test can install withCrashSupervision() through the
+ * REAL deps object this module actually uses in production, rather than a
+ * hand-built SuperviseChildDeps that can (and did) diverge from it -- the
+ * exact blind spot CR-01 (03-REVIEW.md) lived in: broker-launch.test.ts's own
+ * respawn/recycle tests each construct their deps inline and therefore pass
+ * `backend: "stock"` directly, so the production builder's missing field was
+ * invisible to the whole suite. Same discipline as broker-kill.mts's
+ * `_HANDLED_SIGNALS`: an underscore-prefixed alias, never called by any
+ * production code path in this module. */
+export const _superviseDepsFor = superviseDepsFor;
 /** Sets the deliberate-death marker and its respawn-after-kill answer
  * TOGETHER -- the single place in this module that ever writes either
  * field, so a call site can never set one and forget the other, which is
@@ -326,7 +365,11 @@ async function selectWarmInstance(state, deps) {
         // WR-02 only changes what happens to the kill's own PROMISE next, never
         // this ordering.
         markDeliberateDeath(record, false);
-        state.instances.delete(record.port);
+        // CR-02 (03-REVIEW.md): dropping a record is also where its second
+        // (`-remotemonitor`) port stops being spoken for -- deleteInstanceRecord()
+        // is the ONE place both mutations happen together, so a drop can never
+        // leak a port out of the fixed allocation band.
+        deleteInstanceRecord(state, record.port);
         // Distinct wording from shutdown()'s own "shutdown complete" line
         // (broker-kill.mts) and from handleRecycleForRealBroker's own log-free
         // path -- D-07's standing constraint that a lifecycle decision must be
@@ -383,7 +426,11 @@ async function selectWarmInstance(state, deps) {
  * control.mts's own attemptAcquire()/enqueueAcquire() queue the request and
  * retry it later rather than refusing it. */
 export async function handleAcquire(requestId, stateDir, state, deps = {}) {
-    const probe = deps.probe ?? ((port) => probeReady(port));
+    // WR-01: the readiness probe is backend-aware, from the SAME threaded-down
+    // verdict handleAcquire already uses for buildViceArgs() -- on stock the port
+    // speaks the binary monitor, so an HTTP POST there can never succeed.
+    const backend = deps.backend ?? "fork";
+    const probe = deps.probe ?? ((port) => probeReady(port, { backend }));
     // Textually a verifiedKill( call site, not merely a reference -- reused
     // UNCHANGED from broker-kill.mts (Phase 01.6.2 criterion 6), never
     // re-derived, and never replaced by a bare process.kill().
@@ -412,12 +459,18 @@ export async function handleAcquire(requestId, stateDir, state, deps = {}) {
             state,
             stateDir,
             allocatePort: nextFreePort,
+            // CR-01 (03-REVIEW.md): the SAME local `backend` const resolved at the
+            // top of this function feeds BOTH the initial argv (here) and the
+            // supervision deps below, so a crash-respawn of this instance can never
+            // build a different backend's argv than the launch it replaces.
+            backend,
+            allocateRemoteMonitorPort: deps.allocateRemoteMonitorPort,
             spawnFactory: deps.buildColdSpawnFactory ??
                 ((port) => {
                     const supervisorDir = join(stateDir, String(port));
                     const { spawn, logRelPath } = makeLoggingSpawn(join(supervisorDir, "logs"));
                     lastLogRelPath = logRelPath;
-                    return withCrashSupervision("acquire", port, spawn, superviseDepsFor(stateDir, state));
+                    return withCrashSupervision("acquire", port, spawn, superviseDepsFor(stateDir, state, backend));
                 }),
         });
         if (!result.ok) {
@@ -431,7 +484,10 @@ export async function handleAcquire(requestId, stateDir, state, deps = {}) {
             // toward countTotal()/atCapacity() until crash supervision's own
             // delayed respawn/give-up machinery eventually noticed and freed it,
             // even though the caller was already told "internal" right now.
-            state.instances.delete(result.record.port);
+            // CR-02: deleteInstanceRecord(), not a bare map delete -- a stock launch
+            // that failed this way already had its second port allocated and
+            // blocked by acquirePortAndLaunch().
+            deleteInstanceRecord(state, result.record.port);
             return { ok: false, reason: "internal" };
         }
         record = result.record;
@@ -465,8 +521,66 @@ function handleStatus(state) {
         state: r.state,
         reason: r.reason,
         epoch: typeof r.epoch === "number" ? r.epoch : null,
+        hasMonitorClient: r.monitorClient !== undefined,
     }));
 }
+/** Resolves a monitor_claim/monitor_release target the SAME way
+ * handleRelease() and handleRecycleForRealBroker() already resolve theirs:
+ * `targetId` is a grant id, looked up in state.grants for its port, then
+ * the instance at that port. Returns `null` for an unknown target_id/port
+ * so callers answer `bad_request`, never `internal` (plan 05's own
+ * acceptance criterion). */
+function resolveInstanceForMonitorTarget(targetId, state) {
+    const grant = state.grants.get(targetId);
+    if (!grant)
+        return null;
+    return state.instances.get(grant.port) ?? null;
+}
+/** Answers `monitor_claim` (plan 05, BROK-02/PROTO-08, D-13): exclusive
+ * monitor-socket ownership enforced HERE, broker-side, so a conflicting
+ * claim is refused by name before any second `connect()` is ever attempted
+ * -- the one state stock VICE cannot report and no client-side heuristic
+ * can diagnose. `targetId` doubles as both "which instance" (resolved via
+ * the SAME grant lookup handleRelease()/handleRecycleForRealBroker() already
+ * use) and "the requesting grant's own identity" -- the claim IS the grant,
+ * so there is no separate identity to carry. A repeated claim from the SAME
+ * grant is idempotent (`ok: true`, no second holder created); a claim from
+ * a DIFFERENT grant while the instance already has a holder is refused,
+ * naming the current holder (T-02-18) -- never the emulator's own fault. */
+export function handleMonitorClaim(requestId, targetId, state) {
+    void requestId; // correlation only -- the claim's own identity is targetId itself
+    const instance = resolveInstanceForMonitorTarget(targetId, state);
+    if (!instance)
+        return { ok: false, code: "bad_request" };
+    const existing = instance.monitorClient;
+    if (!existing) {
+        instance.monitorClient = { grantId: targetId, claimedAt: Date.now(), pid: instance.pid };
+        return { ok: true };
+    }
+    if (existing.grantId === targetId) {
+        return { ok: true }; // idempotent repeat from the SAME grant -- no second holder
+    }
+    return { ok: false, code: "monitor_owned", holder: { grantId: existing.grantId, claimedAt: existing.claimedAt, pid: existing.pid } };
+}
+/** Answers `monitor_release` (plan 05, T-02-01): clears `monitorClient` ONLY
+ * when `targetId` names the CURRENT holder -- a non-holder is refused, not
+ * silently accepted (spoofing a release is exactly T-02-01's own
+ * disposition). An instance with no current holder at all tolerates the
+ * release as a success, matching the container-side client's own documented
+ * tolerance for releasing a socket the broker already cleared. */
+export function handleMonitorRelease(requestId, targetId, state) {
+    void requestId; // correlation only, matching handleMonitorClaim()'s own posture
+    const instance = resolveInstanceForMonitorTarget(targetId, state);
+    if (!instance)
+        return { ok: false, code: "bad_request" };
+    if (!instance.monitorClient)
+        return { ok: true }; // already cleared -- tolerated, not an error
+    if (instance.monitorClient.grantId !== targetId) {
+        return { ok: false, code: "denied" };
+    }
+    clearMonitorClient(instance);
+    return { ok: true };
+}
 /** Resolves a recycle target's emulator child pid from THIS broker's own
  * in-memory instance record -- record.pid is, by construction, exactly the
  * same value broker-epoch.mts's writer puts in epoch.json's own `pid` field
@@ -530,6 +644,13 @@ async function handleRecycleForRealBroker(targetId, state) {
     }
     const epochBefore = typeof instance.epoch === "number" ? instance.epoch : null;
     markDeliberateDeath(instance, true);
+    // Plan 05: a recycle clears monitor-client ownership as a side effect --
+    // the respawned record the exit handler creates is a BRAND NEW
+    // InstanceRecord object (broker-launch.mts's spawnAndRecordInstance())
+    // that never carries this field forward regardless, but clearing it here
+    // too keeps the CURRENT (pre-kill) record's own state honest for the
+    // window between this call and that respawn.
+    clearMonitorClient(instance);
     const killStage = await verifiedKill({ pid: instance.pid, expectedIdentity: instance.expectedIdentity });
     const outcome = killStage === "identity_refused" ? "identity_refused" : "ok";
     const reason = killStage === "identity_refused" ? "process identity did not match the recorded emulator binary -- the target was NOT signalled and is still running" : "";
@@ -554,11 +675,12 @@ async function handleRecycleForRealBroker(targetId, state) {
  * because of invariants -- at most one launch per call, never invoked
  * concurrently with itself -- enforced elsewhere and never checked at the
  * point the variable used to be declared). */
-function maintainWarmFloorForRealBroker(stateDir, state) {
+function maintainWarmFloorForRealBroker(stateDir, state, backend) {
     let lastWarmLaunchLogRelPath = "";
     return maintainWarmFloor({
         state,
         stateDir,
+        backend,
         spawnFactory: (port) => {
             const supervisorDir = join(stateDir, String(port));
             const { spawn, logRelPath } = makeLoggingSpawn(join(supervisorDir, "logs"));
@@ -574,10 +696,21 @@ function maintainWarmFloorForRealBroker(stateDir, state) {
                 lastWarmLaunchLogRelPath = logRelPath;
                 return child;
             };
-            return withCrashSupervision("spare", port, stashingSpawn, superviseDepsFor(stateDir, state));
+            // CR-01 (03-REVIEW.md): the SAME resolved `backend` this function
+            // already receives for the launch argv is threaded into the supervision
+            // deps, so a warm instance's own crash-respawn stays on its backend.
+            return withCrashSupervision("spare", port, stashingSpawn, superviseDepsFor(stateDir, state, backend));
         },
-        probe: (port) => probeReady(port),
+        // WR-01: same backend-aware probe route as handleAcquire's, from the SAME
+        // resolved verdict this function already receives for the launch argv.
+        probe: (port) => probeReady(port, { backend }),
         allocatePort: nextFreePort,
+        // Plan 03-04 (DIRECT-06, D-13): same wiring as handleAcquire()'s own
+        // cold-launch arm -- acquirePortAndLaunch() (reached via
+        // maintainWarmFloor() below) gates the second allocation on
+        // `backend === "stock"` itself, so this function need not check the
+        // backend before passing it.
+        allocateRemoteMonitorPort: (s, exclude) => nextFreePort(s, { exclude }),
         countReady,
         countTotal,
         countLaunching,
@@ -631,8 +764,17 @@ export function handleRelease(requestId, state) {
     const instance = state.instances.get(grant.port);
     if (instance && instance.pid === grant.pid) {
         markDeliberateDeath(instance, false);
+        // Plan 05: releasing clears monitor-client ownership as a side effect
+        // -- redundant with the instance-map deletion two lines below (the
+        // WHOLE record, monitorClient included, is going away), but explicit
+        // for the same reason GrantRecord's own clearing is explicit here: the
+        // instance-map deletion is a Task-2-era invariant this task must not
+        // depend on silently continuing to hold.
+        clearMonitorClient(instance);
         state.grants.delete(requestId);
-        state.instances.delete(grant.port);
+        // CR-02: kill-never-recycle means this instance is gone for good, so its
+        // second (`-remotemonitor`) port must go back to the allocator with it.
+        deleteInstanceRecord(state, grant.port);
         verifiedKill({ pid: instance.pid, expectedIdentity: instance.expectedIdentity }).catch(() => {
             // best-effort; nothing further to report on this path this task
         });
@@ -692,6 +834,23 @@ async function run(args) {
         nextEpochFor,
         writeEpochRecord,
     });
+    // Plan 02-07 (D-01, D-03): resolved ONCE here, after the unconditional
+    // startup reap and BEFORE the control listener binds -- never re-read per
+    // launch, and never called from inside broker-launch.mts's `inFlight`
+    // single-owner guard (this call sits entirely outside it; no launch is
+    // even possible yet at this point in run()). `supervisorDir: args.stateDir`
+    // is passed explicitly -- args.stateDir IS `.vice-supervisor` under this
+    // broker's own repo root (see parseArgs() above), so this is the SAME
+    // directory repo-root.ts's supervisorDir() would resolve to, without this
+    // host-bound module ever importing that container-side resolver directly
+    // (backend-detect.mts's own header comment explains why it cannot). An
+    // `indeterminate` outcome does not prevent the broker from starting: it
+    // logs its own note (backend-detect.mts) and this line proceeds with the
+    // "fork" answer resolvedBackend() already returns for that case -- the
+    // pre-Phase-2 behaviour every existing install already has.
+    const backendResult = resolvedBackend({ supervisorDir: args.stateDir });
+    const backend = backendResult.backend;
+    process.stderr.write(`vice-broker: backend "${backend}" (source: ${backendResult.source}, binary: ${backendResult.binPath})\n`);
     // D-18: the singleton guarantee holds only while the control port keeps its default -- two brokers deliberately configured onto different ports are two brokers, and no code prevents that.
     let listener;
     try {
@@ -699,10 +858,18 @@ async function run(args) {
             host: controlHost,
             port: controlPort,
             token,
-            onAcquire: (requestId) => handleAcquire(requestId, args.stateDir, state),
+            onAcquire: (requestId) => handleAcquire(requestId, args.stateDir, state, {
+                backend,
+                // Plan 03-04 (DIRECT-06, D-13): threaded down to
+                // acquirePortAndLaunch()'s own gate (backend === "stock"); this
+                // callback does NOT re-read VICE_BACKEND itself.
+                allocateRemoteMonitorPort: (s, exclude) => nextFreePort(s, { exclude }),
+            }),
             onRelease: (requestId) => handleRelease(requestId, state),
             onRecycle: (targetId) => handleRecycleForRealBroker(targetId, state),
             onStatus: () => handleStatus(state),
+            onMonitorClaim: (requestId, targetId) => handleMonitorClaim(requestId, targetId, state),
+            onMonitorRelease: (requestId, targetId) => handleMonitorRelease(requestId, targetId, state),
             onHostState: () => ({
                 pid: process.pid,
                 startedAt,
@@ -711,6 +878,10 @@ async function run(args) {
                 warmFloor: resolveWarmFloorForRecord(),
                 maxInstances: resolveCeilingForRecord(),
                 basePort: resolveBasePort(),
+                // WR-04: the verdict THIS process resolved once, at startup, above --
+                // the same one every launch argv is built from. Never a second
+                // resolvedBackend() call (backend-detect.mts's own prohibition).
+                backend,
             }),
         });
     }
@@ -811,7 +982,7 @@ async function run(args) {
         passInFlight = true;
         runBrokerPass({
             serveAcquires: () => drainPendingAcquires(listener.pendingAcquires),
-            maintainWarmFloor: () => maintainWarmFloorForRealBroker(args.stateDir, state),
+            maintainWarmFloor: () => maintainWarmFloorForRealBroker(args.stateDir, state, backend),
         })
             .catch((e) => {
             process.stderr.write(`vice-broker: evaluation pass failed: ${e.message}\n`);

package/stock-address.ts

@@ -0,0 +1,219 @@
+#!/usr/bin/env node
+// stock-address.ts
+//
+// THE ONE address parser for the stock backend (D-04). Every stock handler
+// that accepts an address or a byte count parses it through parseAddress()/
+// parseByteCount() here -- never a second, re-derived regex or range check
+// in a family module.
+//
+// WHY THIS FILE EXISTS: re-deriving an address parser per tool family is
+// this codebase's own named anti-pattern ("re-deriving a cross-cutting seam
+// locally") -- the memory and checkpoint families (Phase 3) both need
+// identical decimal/$hex/0x parsing and identical 0..0xffff range
+// enforcement, and D-04 requires a single pluggable symbol-resolution hook
+// so Phase 5's symbol store (DERIV-04) can fill it later without every call
+// site changing.
+//
+// WHAT NOT TO DO:
+//   - Never re-derive an address regex in a family module -- import
+//     parseAddress()/parseByteCount() from here instead.
+//   - Never treat a bare decimal string as hex here. This is the MCP
+//     argument surface an agent (or a caller) types a value into, not
+//     VICE's own condition lexer -- CLAUDE.md's "bare integer literals are
+//     hex by default" rule belongs to the checkpoint-condition emitter, not
+//     this parser. Do not conflate the two.
+//   - Never implement symbol resolution in Phase 3. setSymbolResolver() is
+//     a deliberately empty extension point until Phase 5's DERIV-04 symbol
+//     store installs a real one; the default here stays `null`.
+//   - Never add a second resolver holder. `nameFor` (address -> name,
+//     DISASM-06's first consumer, Phase 4) and `resolve` (name -> address,
+//     Phase 3) live on the SAME `SymbolResolver` object, read from the SAME
+//     module-level `symbolResolver` holder above. Phase 5's DERIV-04 store
+//     installs one object implementing both; a second holder or a
+//     re-derived address->name map in a family module would force it to
+//     install itself twice.
+import { ViceError, type ViceErrorOptions } from "./vice.ts";
+
+export interface SymbolResolver {
+  resolve(name: string): number | undefined;
+  /** The inverse direction (DISASM-06, Phase 4's first consumer of it) --
+   * optional so the Phase 3 default (`null`, no resolver installed at all)
+   * and every existing test fake stay valid without implementing it. */
+  nameFor?(address: number): string | undefined;
+}
+
+// The ONE module-level holder for the installed resolver. `null` in Phase 3
+// -- no symbol resolution happens until a later phase installs one.
+let symbolResolver: SymbolResolver | null = null;
+
+/** The deliberately-empty extension point Phase 5's DERIV-04 symbol store
+ * fills. Passing `null` (the Phase 3 default) restores the "no symbol table
+ * loaded" refusal. */
+export function setSymbolResolver(resolver: SymbolResolver | null): void {
+  symbolResolver = resolver;
+}
+
+/** DISASM-06's reverse lookup: address -> name, read from the SAME holder
+ * `parseAddress()` reads. Returns `undefined` -- never throws -- when no
+ * resolver is installed, or when the installed resolver has no `nameFor`
+ * (e.g. a Phase 3-era fake that only implements `resolve`). This is a
+ * client-side convenience read, not an MCP argument parse, so there is no
+ * "no symbol table is loaded" refusal here -- that wording belongs to
+ * `parseAddress()`'s own symbolic-name path; a caller wanting an explanatory
+ * note for its own answer uses `hasSymbolStore()` to decide that itself. */
+export function symbolNameFor(address: number): string | undefined {
+  if (!symbolResolver || typeof symbolResolver.nameFor !== "function") {
+    return undefined;
+  }
+  return symbolResolver.nameFor(address);
+}
+
+/** True iff a resolver is installed AND it implements the reverse (`nameFor`)
+ * direction -- what D-14 reads to decide whether `show_symbols` is a
+ * no-op that SAYS SO on the answer, rather than the handler guessing from an
+ * empty/undefined result (which could equally mean "store installed, but no
+ * name for this particular address"). */
+export function hasSymbolStore(): boolean {
+  return symbolResolver !== null && typeof symbolResolver.nameFor === "function";
+}
+
+/** The one address/byte-count error type this module ever throws -- never a
+ * bare Error, matching vice.ts's established ViceError hierarchy. */
+export class StockAddressError extends ViceError {
+  constructor(message: string, options: ViceErrorOptions = {}) {
+    super(message, options);
+    this.name = "StockAddressError";
+  }
+}
+
+/** A bare word that COULD be a symbol name -- checked only after every
+ * numeric form below has already failed to match, so a malformed numeric
+ * string (e.g. "0xzz") is refused as malformed, never misread as a
+ * candidate symbol. */
+const SYMBOL_NAME_RE = /^[A-Za-z_][A-Za-z0-9_.]*$/;
+
+function inAddressRange(value: number): boolean {
+  return Number.isInteger(value) && value >= 0 && value <= 0xffff;
+}
+
+/**
+ * Parses `input` into a 0..0xffff address (D-04). Accepted forms: a JS
+ * `number` in range; a `"$hex"` string (leading `$`, hex digits,
+ * case-insensitive); a `"0x"`/`"0X"` string; or a bare decimal string
+ * (`"4096"`) -- decimal here, deliberately, since this is the MCP argument
+ * surface, not VICE's own condition lexer where bare literals are hex.
+ * Surrounding whitespace is trimmed. A symbolic name (matching
+ * `/^[A-Za-z_][A-Za-z0-9_.]*$/`) refuses with "no symbol table is loaded"
+ * when no resolver is installed, or "not a known symbol" when a resolver IS
+ * installed but returns `undefined` -- never a parse/syntax error either
+ * way (D-04's explicit requirement).
+ */
+export function parseAddress(input: unknown, opts: { what?: string } = {}): number {
+  const what = opts.what ?? "address";
+
+  if (typeof input === "number") {
+    if (!inAddressRange(input)) {
+      throw new StockAddressError(`${what}: ${input} is out of range -- expected an integer 0..65535 ($0000-$ffff)`);
+    }
+    return input;
+  }
+
+  if (typeof input !== "string") {
+    throw new StockAddressError(`${what}: expected a number, a decimal string, a "$hex" string, or a "0x" string, got ${typeof input}`);
+  }
+
+  const trimmed = input.trim();
+
+  if (trimmed === "") {
+    throw new StockAddressError(`${what}: empty string is not a valid address`);
+  }
+
+  if (trimmed.startsWith("$")) {
+    const hexPart = trimmed.slice(1);
+    if (hexPart === "" || !/^[0-9a-fA-F]+$/.test(hexPart)) {
+      throw new StockAddressError(`${what}: "${trimmed}" is not a valid "$hex" address -- expected "$" followed by hex digits, e.g. "$D019"`);
+    }
+    const value = parseInt(hexPart, 16);
+    if (!inAddressRange(value)) {
+      throw new StockAddressError(`${what}: "${trimmed}" (0x${value.toString(16)}) is out of range -- expected 0..65535 ($0000-$ffff)`);
+    }
+    return value;
+  }
+
+  if (/^0[xX]/.test(trimmed)) {
+    const hexPart = trimmed.slice(2);
+    if (hexPart === "" || !/^[0-9a-fA-F]+$/.test(hexPart)) {
+      throw new StockAddressError(`${what}: "${trimmed}" is not a valid "0x" address -- expected "0x" followed by hex digits, e.g. "0xD019"`);
+    }
+    const value = parseInt(hexPart, 16);
+    if (!inAddressRange(value)) {
+      throw new StockAddressError(`${what}: "${trimmed}" (0x${value.toString(16)}) is out of range -- expected 0..65535 ($0000-$ffff)`);
+    }
+    return value;
+  }
+
+  if (/^[0-9]+$/.test(trimmed)) {
+    const value = parseInt(trimmed, 10);
+    if (!inAddressRange(value)) {
+      throw new StockAddressError(`${what}: "${trimmed}" is out of range -- expected a decimal integer 0..65535`);
+    }
+    return value;
+  }
+
+  if (SYMBOL_NAME_RE.test(trimmed)) {
+    if (!symbolResolver) {
+      throw new StockAddressError(
+        `${what}: "${trimmed}" looks like a symbol name, but no symbol table is loaded -- use a numeric address ` +
+          `(decimal, "$hex", or "0x...") instead`,
+      );
+    }
+    const resolved = symbolResolver.resolve(trimmed);
+    if (resolved === undefined) {
+      throw new StockAddressError(`${what}: "${trimmed}" is not a known symbol`);
+    }
+    if (!inAddressRange(resolved)) {
+      throw new StockAddressError(`${what}: symbol "${trimmed}" resolved to ${resolved}, which is out of range 0..65535`);
+    }
+    return resolved;
+  }
+
+  throw new StockAddressError(`${what}: "${trimmed}" is not a valid address -- expected a decimal number, "$hex", "0x...", or a known symbol name`);
+}
+
+/**
+ * Parses a byte count through the same numeric forms as parseAddress() --
+ * decimal, "$hex", "0x..." -- never through the symbol path (a byte count
+ * is never symbolic). Refuses `0`, negatives, non-integers, and anything
+ * above `max` (default `0xffff`), so the `size`-style range check is not
+ * re-derived per family either.
+ */
+export function parseByteCount(input: unknown, opts: { max?: number; what?: string } = {}): number {
+  const max = opts.max ?? 0xffff;
+  const what = opts.what ?? "byte count";
+
+  let value: number;
+  if (typeof input === "number") {
+    if (!Number.isInteger(input)) {
+      throw new StockAddressError(`${what}: ${input} is not an integer`);
+    }
+    value = input;
+  } else if (typeof input === "string") {
+    const trimmed = input.trim();
+    if (/^\$[0-9a-fA-F]+$/.test(trimmed)) {
+      value = parseInt(trimmed.slice(1), 16);
+    } else if (/^0[xX][0-9a-fA-F]+$/.test(trimmed)) {
+      value = parseInt(trimmed.slice(2), 16);
+    } else if (/^[0-9]+$/.test(trimmed)) {
+      value = parseInt(trimmed, 10);
+    } else {
+      throw new StockAddressError(`${what}: "${trimmed}" is not a valid byte count -- expected a decimal number, "$hex", or "0x..."`);
+    }
+  } else {
+    throw new StockAddressError(`${what}: expected a number or a numeric string, got ${typeof input}`);
+  }
+
+  if (value <= 0 || value > max) {
+    throw new StockAddressError(`${what}: ${value} is out of range -- expected 1..${max}`);
+  }
+  return value;
+}