@henols/vice-mcp 0.2.2 → 0.2.3

package/channel-lock.ts

@@ -0,0 +1,349 @@
+#!/usr/bin/env node
+// channel-lock.ts
+//
+// THE ONE PLACE the cross-channel mutex, its FIFO queue, its holder record
+// and its refusal text live. Phase 39's `go` verdict (rule R15) selected an
+// in-process async mutex with no narrowing as the shape that serializes
+// every halt-taking operation on either monitor channel -- this is that
+// primitive, built fresh: there is no async mutex anywhere in this tree, and
+// the only prior single-flight queue died with the retired analyser and was
+// explicitly not extracted. None of the four pieces this module owns -- the
+// mutex, its FIFO queue, its holder record, its refusal text -- may be
+// re-derived in stock-dispatch.ts, text-protocol.ts or stock-diagnose.ts.
+//
+// WHY HAND-BUILT RATHER THAN TAKEN FROM A LIBRARY: a generic mutex (e.g.
+// `async-mutex`) grants and releases but exposes no holder record -- it
+// cannot answer "who holds this, since when, doing what". This module's
+// `ChannelLockHolder` is exactly that record, and it is what makes
+// contention readable to `vice_diagnose` (plan 41-04) rather than a bare
+// "something is locked". `async-mutex` was considered and rejected by this
+// phase's own locked decision; it is never installed, and there is no
+// install task in this plan for a package-legitimacy audit to cover.
+//
+// WHY `MonitorChannel` IS DECLARED HERE A SECOND TIME rather than imported
+// from broker-state.mts (which already has an `InstanceRecord.monitorClient`
+// concept): broker-state.mts is host-bound and compiled into
+// `resources/*.mjs`, so a container-side `.ts` module -- this one -- cannot
+// import it at runtime. The shared thing between the two declarations is the
+// two-value contract ("binary" | "text"), not the declaration itself --
+// exactly as textmon-fixtures.ts reimplements the provenance contract rather
+// than importing it from binmon-fixtures.ts.
+//
+// WHAT NOT TO DO:
+//   - Never acquire this lock per wire command in a way that lets a foreign
+//     command land between a resume and its checkpoint observation -- the
+//     lock is acquired per LOGICAL OPERATION (see stock-dispatch.ts's
+//     withChannelLockHeld() and text-protocol.ts's withTextChannelLock()),
+//     spanning resume -> wait -> observe. A design that preserves the resume
+//     count while destroying what the count protects is a regression, not a
+//     variant.
+//   - Never import stock-run-until.ts from this module. The derivation
+//     comment on CHANNEL_LOCK_ACQUIRE_TIMEOUT_MS below states the
+//     relationship to RUN_UNTIL_MAX_TIMEOUT_MS in prose; importing it here
+//     would invert the dependency, with the primitive importing a consumer.
+//     channel-lock.test.ts cross-imports both files to assert the
+//     inequality instead.
+//   - Never resolve a waiter's timeout through a second admission path.
+//     Both the grant-on-free branch and the enqueue branch below run
+//     through one internal function (admit()) so there is exactly one place
+//     a caller is ever granted the lock.
+//   - Never hand the lock to the next waiter through a `setTimeout` on
+//     release -- that would let timer scheduling perturb arrival order.
+//     release() hands off synchronously, in the same tick.
+
+// ---------------------------------------------------------------------------
+// MonitorChannel -- the two-value contract, declared here (see header).
+// ---------------------------------------------------------------------------
+
+/** Exactly two channels exist and a third is not anticipated -- stock VICE
+ * exposes precisely the binary monitor and the `-remotemonitor` text
+ * channel, and this project has no plan to add a third. Frozen so a
+ * consumer cannot accidentally push a third value onto it at runtime. */
+export const MONITOR_CHANNELS = Object.freeze(["binary", "text"] as const);
+
+export type MonitorChannel = (typeof MONITOR_CHANNELS)[number];
+
+// ---------------------------------------------------------------------------
+// The holder record and the lock handle.
+// ---------------------------------------------------------------------------
+
+/** A read-only snapshot of who currently holds halt authority. `grantId` is
+ * `null` when the caller did not supply one (not every acquirer has a
+ * broker-issued grant id to report) -- `channelLockRefusalMessage()` renders
+ * that case as the literal `unknown`, never a fabricated id. */
+export interface ChannelLockHolder {
+  channel: MonitorChannel;
+  operation: string;
+  grantId: string | null;
+  heldSince: number;
+}
+
+/** Returned by a successful acquire. `release()` is idempotent: a second
+ * call is a no-op, and a stale handle's release() (called after the lock has
+ * already been re-acquired by someone else) never releases the NEW holder's
+ * lock -- both are identity-checked against a private id captured at grant
+ * time, never against the holder record's own field values. */
+export interface ChannelLockHandle {
+  readonly holder: ChannelLockHolder;
+  release(): void;
+}
+
+// ---------------------------------------------------------------------------
+// CHANNEL_LOCK_ACQUIRE_TIMEOUT_MS -- the bounded-wait default (D-06).
+// ---------------------------------------------------------------------------
+
+/**
+ * Default bound (milliseconds) on how long acquireChannelLock() will queue
+ * behind a holder before rejecting. Overridable via
+ * VICE_CHANNEL_LOCK_TIMEOUT_MS for a test or a deliberately narrowed
+ * deployment.
+ *
+ * DERIVATION (stated in prose, never imported -- see header): the longest
+ * legitimate hold on this lock is a stock wait path bounded by
+ * stock-run-until.ts's `RUN_UNTIL_MAX_TIMEOUT_MS` (600000ms). This default
+ * is that bound plus a 30000ms margin -- 630000ms -- so the queued-wait
+ * bound always EXCEEDS the longest legitimate hold and never fires on
+ * healthy operation. A bound below the longest legitimate hold would fire
+ * while the machine is doing exactly what it was asked to do, which is
+ * precisely the self-inflicted-DoS failure this constant exists to prevent
+ * (T-41-06). A waiting caller's own MCP client timeout (150000ms,
+ * `.mcp.json`) will surface first for THAT caller regardless -- that is a
+ * timeout on their call, not a wedge diagnosis of the instance.
+ */
+export const CHANNEL_LOCK_ACQUIRE_TIMEOUT_MS: number = (() => {
+  const raw = process.env.VICE_CHANNEL_LOCK_TIMEOUT_MS;
+  if (raw === undefined || raw === "") return 630000;
+  const n = Number(raw);
+  return Number.isFinite(n) && n > 0 ? n : 630000;
+})();
+
+// ---------------------------------------------------------------------------
+// The refusal wording -- the ONE place it is composed.
+// ---------------------------------------------------------------------------
+
+/**
+ * The ONE refusal wording produced when a caller cannot be granted the lock
+ * (either an immediate `tryAcquireChannelLock()` miss reported by a caller,
+ * or a `ChannelLockTimeoutError`'s own message). Names the other channel,
+ * the operation it is running, the hold duration in whole milliseconds, and
+ * the holder's grant id (or the literal `unknown` when there is none --
+ * never a fabricated id, matching claimMonitor()'s own posture for a
+ * malformed holder payload).
+ *
+ * This reads as a legitimate ownership statement -- the same register
+ * broker-control.mts's MONITOR_OWNERSHIP_DENIAL/`monitor_owned` refusal
+ * already establishes for the broker's own monitor-claim conflict -- and
+ * must NEVER contain the words wedge, wedged, hang, hung, frozen, stuck or
+ * unresponsive, nor otherwise suggest the emulator itself has stopped
+ * answering. A hold the OTHER channel cannot see would otherwise read as
+ * exactly the `wedged` triage signature, whose recommended remedy is
+ * destructive (T-41-06's threat-register entry).
+ */
+export function channelLockRefusalMessage(holder: ChannelLockHolder, nowMs: number): string {
+  const heldMs = Math.max(0, nowMs - holder.heldSince);
+  const grantId = holder.grantId ?? "unknown";
+  return (
+    `channel-lock: the ${holder.channel} channel currently holds halt authority ` +
+    `(operation "${holder.operation}", grant ${grantId}, held for ${heldMs}ms) -- ` +
+    `this call must wait for that channel to release before it can proceed`
+  );
+}
+
+/**
+ * Thrown by acquireChannelLock() when a queued waiter's bound
+ * (CHANNEL_LOCK_ACQUIRE_TIMEOUT_MS by default, or an explicit override)
+ * expires before the lock reaches it. Carries the holder record that was
+ * blocking it and the measured hold/wait durations as public fields, with
+ * `message` produced by channelLockRefusalMessage() -- callers must never
+ * re-word this message, only pass it through verbatim.
+ */
+export class ChannelLockTimeoutError extends Error {
+  readonly holder: ChannelLockHolder;
+  readonly heldMs: number;
+  readonly waitedMs: number;
+
+  constructor(holder: ChannelLockHolder, waitedMs: number, nowMs: number = Date.now()) {
+    super(channelLockRefusalMessage(holder, nowMs));
+    this.name = "ChannelLockTimeoutError";
+    this.holder = holder;
+    this.heldMs = Math.max(0, nowMs - holder.heldSince);
+    this.waitedMs = waitedMs;
+  }
+}
+
+// ---------------------------------------------------------------------------
+// The mutex itself: one holder, one FIFO queue, one admission path.
+// ---------------------------------------------------------------------------
+
+interface QueueEntry {
+  readonly id: symbol;
+  readonly channel: MonitorChannel;
+  readonly operation: string;
+  readonly grantId: string | null;
+  readonly arrivedAt: number;
+  timer: NodeJS.Timeout | null;
+  readonly resolve: (handle: ChannelLockHandle) => void;
+  readonly reject: (err: unknown) => void;
+}
+
+let currentHolder: ChannelLockHolder | null = null;
+/** Identity of the handle that currently owns `currentHolder` -- distinct
+ * from the holder record's own field values, so a stale handle (one whose
+ * release() runs after the lock has already passed to someone else) can
+ * never be mistaken for the live one even if the new holder happens to
+ * share the same channel/operation/grantId. */
+let currentHolderHandleId: symbol | null = null;
+
+/** Plain array, used strictly FIFO: push() to enqueue, shift() to wake --
+ * per this module's own implementation requirement, never a priority queue,
+ * never a LIFO stack. */
+let queue: QueueEntry[] = [];
+
+function removeFromQueueById(id: symbol): QueueEntry | null {
+  const idx = queue.findIndex((e) => e.id === id);
+  if (idx === -1) return null;
+  const [entry] = queue.splice(idx, 1);
+  return entry;
+}
+
+/** The ONE place a caller is granted the lock, whether immediately (queue
+ * was empty) or via wakeNext() below (queue had waiters). Builds a fresh
+ * holder record and a fresh handle identity every time -- there is no
+ * second admission path. */
+function grantLock(channel: MonitorChannel, operation: string, grantId: string | null): ChannelLockHandle {
+  const id = Symbol("channel-lock-handle");
+  const holder: ChannelLockHolder = { channel, operation, grantId, heldSince: Date.now() };
+  currentHolder = holder;
+  currentHolderHandleId = id;
+  let released = false;
+  return {
+    holder,
+    release: () => {
+      if (released) return;
+      released = true;
+      // Identity check: a stale handle whose lock has already been handed
+      // to a new holder (this handle's `id` no longer matches
+      // currentHolderHandleId) must not clear the NEW holder's state.
+      if (currentHolderHandleId !== id) return;
+      currentHolder = null;
+      currentHolderHandleId = null;
+      wakeNext();
+    },
+  };
+}
+
+/** Hands the lock to the next queued waiter, synchronously -- never through
+ * a setTimeout, so release-to-grant handoff cannot be reordered by timer
+ * scheduling. No-op when the queue is empty. */
+function wakeNext(): void {
+  const next = queue.shift();
+  if (!next) return;
+  if (next.timer) {
+    clearTimeout(next.timer);
+    next.timer = null;
+  }
+  const handle = grantLock(next.channel, next.operation, next.grantId);
+  next.resolve(handle);
+}
+
+/** The ONE internal admission function both acquireChannelLock() and its
+ * queueing path run through -- grants immediately when free, otherwise
+ * enqueues and resolves later via wakeNext(). */
+function admit(channel: MonitorChannel, operation: string, grantId: string | null, timeoutMs: number): Promise<ChannelLockHandle> {
+  if (currentHolder === null) {
+    return Promise.resolve(grantLock(channel, operation, grantId));
+  }
+  return new Promise<ChannelLockHandle>((resolve, reject) => {
+    const id = Symbol("channel-lock-waiter");
+    const arrivedAt = Date.now();
+    const entry: QueueEntry = { id, channel, operation, grantId, arrivedAt, timer: null, resolve, reject };
+    entry.timer = setTimeout(() => {
+      const removed = removeFromQueueById(id);
+      if (!removed) {
+        // Already granted or already drained by resetChannelLockForTests()
+        // between the timer firing and this callback running -- nothing
+        // left to reject. Unreachable in the single-threaded JS event loop
+        // under normal operation, but defensive rather than assumed.
+        return;
+      }
+      // Invariant: a queued entry can only exist while the lock is held --
+      // every release() immediately drains the queue via wakeNext() when
+      // non-empty, and admit() only enqueues when currentHolder !== null.
+      // So currentHolder is guaranteed non-null here.
+      const holder = currentHolder;
+      if (holder === null) {
+        reject(
+          new Error(
+            "channel-lock: internal invariant violation -- a queued waiter's timeout fired while no holder was recorded",
+          ),
+        );
+        return;
+      }
+      reject(new ChannelLockTimeoutError(holder, Date.now() - arrivedAt));
+    }, timeoutMs);
+    if (typeof entry.timer.unref === "function") entry.timer.unref();
+    queue.push(entry);
+  });
+}
+
+export interface AcquireChannelLockOptions {
+  channel: MonitorChannel;
+  operation: string;
+  grantId?: string | null;
+  timeoutMs?: number;
+}
+
+/**
+ * Grants the lock immediately when free; otherwise appends to the FIFO
+ * queue and resolves when the lock reaches this caller. On expiry of
+ * `timeoutMs` (default CHANNEL_LOCK_ACQUIRE_TIMEOUT_MS) removes its own
+ * entry from the queue (by identity, so a later release() can never wake an
+ * already-rejected waiter) and rejects with ChannelLockTimeoutError carrying
+ * the holder record and the measured hold/wait durations.
+ */
+export function acquireChannelLock(opts: AcquireChannelLockOptions): Promise<ChannelLockHandle> {
+  return admit(opts.channel, opts.operation, opts.grantId ?? null, opts.timeoutMs ?? CHANNEL_LOCK_ACQUIRE_TIMEOUT_MS);
+}
+
+export interface TryAcquireChannelLockOptions {
+  channel: MonitorChannel;
+  operation: string;
+  grantId?: string | null;
+}
+
+/**
+ * Fully synchronous, no `await` anywhere: grants and returns a handle when
+ * free, returns `null` immediately when held -- never queues. This is the
+ * entry point a diagnostic uses so that diagnosing contention never queues
+ * behind the holder it is diagnosing (consumed by vice_diagnose, plan
+ * 41-04).
+ */
+export function tryAcquireChannelLock(opts: TryAcquireChannelLockOptions): ChannelLockHandle | null {
+  if (currentHolder !== null) return null;
+  return grantLock(opts.channel, opts.operation, opts.grantId ?? null);
+}
+
+/** A read-only COPY of the holder record -- never the live object, so a
+ * caller cannot mutate module state by holding onto what this returns.
+ * `null` when nothing holds the lock. */
+export function currentChannelLockHolder(): ChannelLockHolder | null {
+  if (currentHolder === null) return null;
+  return { ...currentHolder };
+}
+
+/**
+ * Clears the holder and drains the queue by rejecting every waiter --
+ * exists only so a test file can start from a known state, in the register
+ * stock-dispatch.ts's own clearHeldStockSession() already establishes.
+ * Never called from production code.
+ */
+export function resetChannelLockForTests(): void {
+  currentHolder = null;
+  currentHolderHandleId = null;
+  const pending = queue;
+  queue = [];
+  for (const entry of pending) {
+    if (entry.timer) clearTimeout(entry.timer);
+    entry.reject(new Error("channel-lock: resetChannelLockForTests() drained this waiter"));
+  }
+}

package/evid-ingest.ts

@@ -0,0 +1,217 @@
+#!/usr/bin/env node
+// evid-ingest.ts
+//
+// Plan 43-05 (EVID-01, EVID-04): THE ONE PLACE a parsed `memmapshow` access
+// map (`textmon-memmap.ts`'s `AccessMap`) becomes durable-store-shaped
+// observation rows. `anno-tools.ts`'s `anno_evid_ingest` dispatch arm calls
+// this module's pure functions and then, and only then, writes what they
+// return through `anno-store.ts`'s `insertExecObservations`.
+//
+// THE ONE POSITIVE FACT THIS LAYER IS LICENSED TO ASSERT (quoted from this
+// plan's own objective, verbatim, so a later reader never has to re-derive
+// it): "A row is written if and only if an address's `ram.execute`,
+// `rom.execute` or `io.execute` flag is true in the parsed reply. Nothing
+// else produces a row." An address `memmapshow` mentioned with read or
+// write access but no execute produces no row, and an address absent from
+// the sparse `entries` array produces no row either -- those are two
+// DIFFERENT facts about the world, and neither is recoverable from the
+// store's row set alone, only from the reply itself. That is correct and is
+// the point: the store holds observed execution, and the absence of a row
+// is not a fact the store asserts about the address. It is the absence of
+// an assertion.
+//
+// Read-and-write-only observations are deliberately NOT stored here. The
+// schema can gain a separate table for them later without a migration,
+// because it would be a wholly new table -- the store's existing additive
+// discipline.
+//
+// WHY THE VERB TAKES AN ARGV ARRAY AND NEVER A DIGEST: a caller-supplied
+// pre-computed digest would let a caller invent a run identity, a second
+// notion of sameness sitting beside EVID-01's own. `runIdentityFrom()`
+// below computes `argvDigest` itself, from the exact `argv` the caller
+// supplies, through the ONE shipped digest function
+// (`capture-predicate.ts`'s `argvDigest()`) and nothing else -- there is no
+// code path here that accepts a digest as input.
+//
+// ---------------------------------------------------------------------------
+// WHAT NOT TO DO -- each of these is a specific, named trap
+// ---------------------------------------------------------------------------
+//   1. NEVER write a row from an address's ABSENCE. `execObservationsFrom()`
+//      only ever iterates `map.entries` -- the sparse array VICE actually
+//      sent -- and never pads it back out to the full address space. An
+//      address absent from `entries` produces nothing, silently, by
+//      construction: there is no branch here that could emit a row for it.
+//   2. NEVER merge two banks' execute bits into one row. `ram.execute`,
+//      `rom.execute` and `io.execute` are three independent facts
+//      (`textmon-memmap.ts`'s own header states this for `AccessFlags`);
+//      this module emits at most one observation per (address, bank) pair,
+//      never a combined "any bank executed" row.
+//   3. NEVER accept a pre-computed argv digest. `runIdentityFrom()`'s ONLY
+//      input for identity is `argv` itself; there is no `argvDigest`
+//      parameter anywhere in this module's exported surface.
+//   4. NEVER open a store here. This module imports nothing from
+//      `anno-store.ts` and touches no filesystem, transport or
+//      child-process -- the write happens in `anno-tools.ts`'s dispatch
+//      arm, which is what keeps this module out of `anno-seam.test.ts`'s
+//      single-consumer set (`anno-store.ts` remains the one module naming
+//      `node:sqlite`).
+//   5. NEVER read `.read` or `.write` off an `AccessFlags` value anywhere in
+//      this file. Only `.execute` is ever inspected -- read-and-write-only
+//      access is deliberately not this layer's concern (see the header
+//      above).
+import type { AccessMap, AccessMapParseResult } from "./textmon-memmap.ts";
+import { argvDigest } from "./capture-predicate.ts";
+import { EVID_SOURCE_BANKS, type EvidSourceBank } from "./anno-types.ts";
+import { ViceError } from "./vice-errors.ts";
+
+/** One observed execute bit: this address, in this source bank, was seen
+ * executing. There is no third field -- an `ExecObservation` carries no
+ * opinion about whether the address is "code" or "data"; it is a single,
+ * narrow fact about what the emulator actually did. */
+export interface ExecObservation {
+  readonly address: number;
+  readonly sourceBank: EvidSourceBank;
+}
+
+/** Exactly 64 lowercase hex characters -- the shape a sha256 digest (an
+ * image hash, or `argvDigest()`'s own output) always takes. This module's
+ * OWN copy of the check, deliberately not imported from `anno-types.ts`
+ * (this file's import list is closed to exactly the five named imports
+ * above): the caller-supplied `imageSha256` never reaches a digest
+ * function here, so there is nothing to route through `argvDigest`'s own
+ * shape, and duplicating a four-line regex check is cheaper than widening
+ * this module's import surface for it. */
+const RUN_IDENTITY_DIGEST_RE = /^[0-9a-f]{64}$/;
+
+/** The exact launch identity a caller must supply. `runClass` exists ONLY
+ * on plan 43-01's `promote` branch decision and is never read by this
+ * module's `no-change` implementation -- carried in the type so a future
+ * `promote` branch has somewhere to put it without a second interface. */
+export interface IngestRunIdentity {
+  readonly imageSha256: string;
+  readonly argv: readonly string[];
+  readonly seed: string;
+}
+
+/** `runIdentityFrom()`'s answer: the bare `(imageSha256, argvDigest, seed)`
+ * triple the `no-change` run-identity decision selected (plan 43-01,
+ * `docs/phase43-instrumentation-perturbation-ab.md`) -- no `runClass`
+ * discriminator field exists on this type. */
+export interface RunIdentity {
+  readonly imageSha256: string;
+  readonly argvDigest: string;
+  readonly seed: string;
+}
+
+/** Validates `identity.imageSha256` and `identity.seed`, then computes
+ * `argvDigest` from `identity.argv` through the ONE shipped digest function
+ * -- and nothing else. Refuses BY NAME, throwing inside the `ViceError`
+ * family so the anno never-throw boundary (`anno-tools.ts`'s
+ * `runAnnoTool()`) can name the class in its `{isError:true}` answer:
+ *
+ *   - `imageSha256` that is not exactly 64 lowercase hex characters
+ *     (the program image is named by its bytes; a malformed digest here
+ *     would silently key a run under the wrong image identity forever).
+ *   - `seed` that is not a non-empty string.
+ *   - `argv` that is not an array, or an empty array -- both refusals are
+ *     `argvDigest()`'s OWN (this function never duplicates that check; it
+ *     lets `argvDigest()` throw and re-wraps the message as a `ViceError`
+ *     so the caller sees one error family regardless of which check fired).
+ *
+ * `argvDigest()` is the ONLY place `argv` becomes an identity: there is no
+ * second hashing site here, and no parameter anywhere on this module's
+ * surface through which a caller could hand in an already-computed digest.
+ */
+export function runIdentityFrom(identity: IngestRunIdentity): RunIdentity {
+  if (typeof identity?.imageSha256 !== "string" || !RUN_IDENTITY_DIGEST_RE.test(identity.imageSha256)) {
+    throw new ViceError(
+      `runIdentityFrom: imageSha256 ${JSON.stringify(identity?.imageSha256)} is not exactly 64 lowercase hex characters -- ` +
+        "expected the sha256 digest of the program image's own bytes.",
+      { code: "evid-ingest-bad-image-sha256" },
+    );
+  }
+  if (typeof identity.seed !== "string" || identity.seed.length === 0) {
+    throw new ViceError(`runIdentityFrom: seed ${JSON.stringify(identity.seed)} is not a non-empty string.`, {
+      code: "evid-ingest-bad-seed",
+    });
+  }
+
+  let digest: string;
+  try {
+    digest = argvDigest(identity.argv);
+  } catch (err) {
+    const reason = err instanceof Error ? err.message : String(err);
+    throw new ViceError(`runIdentityFrom: ${reason}`, { code: "evid-ingest-bad-argv" });
+  }
+
+  return { imageSha256: identity.imageSha256, argvDigest: digest, seed: identity.seed };
+}
+
+/**
+ * The pure transform (EVID-01, EVID-04): one observation per (address,
+ * bank) pair whose `execute` flag is `true` in `map.entries`, sorted
+ * ascending by address then by the bank's index in `EVID_SOURCE_BANKS`'s
+ * frozen order (`ram`, `rom`, `io`). One pass over `map.entries`; never
+ * reads `.read` or `.write`; never derives an observation from an address's
+ * absence, because the loop only ever visits addresses `map.entries`
+ * actually contains.
+ */
+export function execObservationsFrom(map: AccessMap): ExecObservation[] {
+  const observations: ExecObservation[] = [];
+  for (const entry of map.entries) {
+    for (const bank of EVID_SOURCE_BANKS) {
+      if (entry[bank].execute) {
+        observations.push({ address: entry.address, sourceBank: bank });
+      }
+    }
+  }
+  observations.sort((a, b) => {
+    if (a.address !== b.address) return a.address - b.address;
+    return EVID_SOURCE_BANKS.indexOf(a.sourceBank) - EVID_SOURCE_BANKS.indexOf(b.sourceBank);
+  });
+  return observations;
+}
+
+/** `ingestAccessMap()`'s success arm: the derived run identity plus the
+ * sorted observation list -- exactly what `anno-tools.ts`'s dispatch arm
+ * hands to `insertExecObservations()` in one call. */
+export interface IngestAccessMapOk {
+  readonly ok: true;
+  readonly runIdentity: RunIdentity;
+  readonly observations: readonly ExecObservation[];
+}
+
+/** `ingestAccessMap()`'s refusal arm: the parse refusal's own code, line
+ * number and offending line, carried through UNABSORBED -- a drifted or
+ * malformed `memmapshow` reply is never silently treated as a zero-entry
+ * capture. */
+export interface IngestAccessMapRefusal {
+  readonly ok: false;
+  readonly message: string;
+}
+
+export type IngestAccessMapResult = IngestAccessMapOk | IngestAccessMapRefusal;
+
+/**
+ * The one join of a parse result and a run identity into observations ready
+ * to write. THIS FUNCTION DOES NOT WRITE -- it is pure, and the store write
+ * happens in `anno-tools.ts`'s dispatch arm.
+ *
+ * On `parsed.ok === false`, returns the refusal form carrying the refusal's
+ * own code, line number and offending line, and touches nothing else --
+ * neither `runIdentityFrom()` nor `execObservationsFrom()` is ever called on
+ * a refused parse, because there is nothing in a refusal to derive either
+ * from.
+ */
+export function ingestAccessMap(parsed: AccessMapParseResult, identity: IngestRunIdentity): IngestAccessMapResult {
+  if (!parsed.ok) {
+    const { refusal } = parsed;
+    return {
+      ok: false,
+      message: `memmapshow reply refused [${refusal.code}] at line ${refusal.lineNumber}: ${refusal.message} (offending line: ${JSON.stringify(refusal.line)})`,
+    };
+  }
+  const runIdentity = runIdentityFrom(identity);
+  const observations = execObservationsFrom(parsed.value);
+  return { ok: true, runIdentity, observations };
+}