@coda-console/kernel 0.0.0-stage → 0.1.0

package/src/kernel.mjs

@@ -0,0 +1,1038 @@
+import { createHash } from 'node:crypto';
+import { META, MIGRATIONS, SQL } from './schema.mjs';
+import { Transactions } from './transaction.mjs';
+
+/**
+ * Thrown by `accept` to refuse a call: the run ends `failed` with `effects: 'none'`, and a repeat gets the same. Thrown
+ * by `answer` to refuse an answer: the run stays as it was, and the receipt says why.
+ */
+export class Rejected extends Error {
+  /**
+   * @param {string} code
+   * @param {string} [message]
+   */
+  constructor(code, message = code) {
+    super(message);
+    this.name = 'Rejected';
+    this.code = code;
+  }
+}
+
+/** Thrown by `accept` to not take a call now: nothing is kept, and the caller sends it again on a later pump(). */
+export class Busy extends Error {
+  constructor(message = 'busy') {
+    super(message);
+    this.name = 'Busy';
+  }
+}
+
+const ENDED = new Set(['completed', 'failed', 'canceled']);
+const EFFECTS = new Set(['none', 'unknown', 'some']);
+const WORKING = new Set(['working', 'input-required']);
+// Receipts after which a letter stays in the outbox, untouched, until the next pump() (C10).
+const HOLD = new Set(['busy', 'not_ready']);
+// Letters the send loop hands over before it yields to the event loop once.
+const BATCH = 8;
+// The fields each kind of letter has (6); a name in `must` outside these makes the letter unsupported.
+const fields = names => new Set(`v kind from to must ${names}`.split(' '));
+const FIELDS = {
+  call: fields('id op input digest awaited parent confirmed'),
+  status: fields('call rev status asked asking progress'),
+  result: fields('call outcome result error progress'),
+  cancel: fields('call reason'),
+  answer: fields('id call asked answer'),
+};
+
+/**
+ * @typedef {{ from: string, id: string }} Ref
+ * @typedef {{ outcome: 'completed', result?: unknown } | { outcome: 'failed', error?: unknown } | { outcome: 'canceled' }} Outcome
+ * @typedef {{ from: string, id: string, to: string, op: string, input: unknown, awaited: boolean, parent: unknown }} Incoming
+ * @typedef {{ from: string, id: string, asked: number, answer: unknown }} Answer
+ * @typedef {{ accept: (call: Incoming) => Outcome | undefined, cancel?: (run: object, reason: unknown) => void,
+ *   answer?: (run: object, answer: Answer) => void }} Handlers
+ * @typedef {{ status?: (call: object) => void, result?: (call: object) => void, late?: (call: object) => void }} ResultHandlers
+ * @typedef {{ ok: true, view?: object, applied?: boolean } | { ok: false, code: string, error?: { code: string, message: string } }} Receipt
+ */
+
+/**
+ * @param {{
+ *   db: import('node:sqlite').DatabaseSync,
+ *   now: () => number,
+ *   send: (to: string, envelope: object) => Promise<Receipt>,
+ *   onError?: (error: unknown) => void,
+ *   wake?: (due: number | null) => void,
+ *   schedule?: (fn: () => void) => void,
+ * }} options
+ */
+export function createKernel(options) {
+  return new Kernel(options);
+}
+
+class Kernel {
+  #db;
+  #now;
+  #send;
+  #onError;
+  #wake;
+  #schedule;
+  #tx;
+  /** @type {Map<string, import('node:sqlite').StatementSync>} */
+  #statements = new Map();
+  /** @type {Map<string, Map<string, Handlers>>} */
+  #handlers = new Map();
+  /** @type {Map<string, ResultHandlers>} */
+  #results = new Map();
+  #started = false;
+  #closed = false;
+  // The send loop's memory (R1): all of it may be lost, the outbox says what is still owed.
+  #running = false;
+  #again = false;
+  /** @type {Set<number>} letters, by `seq`, handed to send() and not answered yet */
+  #flying = new Set();
+  /** letters and inquiries handed to send() and not answered yet */
+  #out = 0;
+  /** @type {Set<number>} letters that wait for the next pump() */
+  #held = new Set();
+  /** @type {Map<string, Ref>} inquiries that got no receipt and go again on the next pump() (C5) */
+  #rereads = new Map();
+  /** @type {Array<() => void>} */
+  #idle = [];
+  /** @type {number | null} the earliest due time the host was last told of; null: it holds no timer (7, R1) */
+  #told = null;
+  /** @type {Array<{ ref: Ref, what: string, resolve: (call: object) => void, reject: (error: Error) => void }>} when()'s (R1) */
+  #waiters = [];
+
+  constructor({ db, now, send, onError = error => console.error(error), wake, schedule = setImmediate }) {
+    this.#db = db;
+    this.#now = now;
+    this.#send = send;
+    this.#onError = onError;
+    this.#wake = wake;
+    this.#schedule = schedule;
+    this.#tx = new Transactions(db, error => this.#onError(error), () => this.#committed());
+  }
+
+  /**
+   * @template T
+   * @param {() => T} fn
+   * @returns {T}
+   */
+  transaction(fn) {
+    if (this.#closed) throw new Error('the kernel is closed');
+    return this.#tx.run(fn);
+  }
+
+  /** @param {() => void} fn */
+  afterCommit(fn) {
+    this.#tx.after(fn);
+  }
+
+  migrate() {
+    this.#inside();
+    this.#db.exec(META);
+    const version = this.#q(SQL.version).get()?.value ?? 0;
+    // A database newer than this code was written by a later kernel: running on it, or writing the older version back,
+    // would break the later one.
+    if (version > MIGRATIONS.length) throw new Error(`the database is at schema version ${version}, newer than this kernel's ${MIGRATIONS.length}`);
+    if (version === MIGRATIONS.length) return;
+    for (const step of MIGRATIONS.slice(version)) this.#db.exec(step);
+    this.#q(SQL.setVersion).run(MIGRATIONS.length);
+  }
+
+  /**
+   * @param {string} address
+   * @param {string} op
+   * @param {Handlers} handlers
+   */
+  handle(address, op, handlers) {
+    if (!this.#handlers.has(address)) this.#handlers.set(address, new Map());
+    this.#handlers.get(address).set(op, handlers);
+  }
+
+  /**
+   * @param {string} address
+   * @param {ResultHandlers} handlers
+   */
+  results(address, handlers) {
+    this.#results.set(address, handlers);
+  }
+
+  /**
+   * @param {{ from: string, id: string, to: string, op: string, input?: unknown, lane?: string, by?: Ref,
+   *   awaited?: boolean, parent?: unknown, memo?: unknown }} call
+   */
+  call({ from, id, to, op, input = null, lane = null, by, awaited = false, parent = null, memo }) {
+    this.#inside();
+    const digest = digestOf([to, op, input, parent]);
+    const found = this.#found(from, id, digest);
+    if (found) return found;
+    awaited = this.#awaits(from, by, awaited);
+    this.#start({ from, id, to, op, digest, input, parent, lane, by, awaited, memo });
+    return defined({ from, id, to, op, state: 'sending', memo, by: by && { from: by.from, id: by.id }, awaited });
+  }
+
+  /**
+   * A call to make once `delayMs` has passed (7). Until then it is a timer, which shares its id with the calls.
+   * @param {{ from: string, id: string, delayMs: number, to: string, op: string, input?: unknown, lane?: string, by?: Ref,
+   *   awaited?: boolean, parent?: unknown, memo?: unknown }} timer
+   */
+  after({ from, id, delayMs, to, op, input = null, lane = null, by, awaited = false, parent = null, memo }) {
+    this.#inside();
+    if (!Number.isFinite(delayMs) || delayMs < 0) throw new Error(`delayMs must be a finite number not below 0, not ${delayMs}`);
+    const digest = digestOf([to, op, input, parent]);
+    const found = this.#found(from, id, digest);
+    if (found) return found;
+    awaited = this.#awaits(from, by, awaited);
+    this.#q(SQL.addTimer).run(from, id, to, op, digest, json(input), json(parent), lane, by?.from ?? null, by?.id ?? null, awaited ? 1 : 0,
+      json(memo), this.#now() + delayMs);
+    return timerView(this.#q(SQL.timer).get(from, id));
+  }
+
+  /**
+   * Takes back a timer not yet due (7). A timer that has become a call is left alone.
+   * @param {Ref} timer
+   */
+  unschedule(timer) {
+    this.#inside();
+    if (!this.#unschedule(timer)) this.#made(timer);
+  }
+
+  /** Turns every timer that has come due into a call, in one transaction that calls no handler (7). */
+  tick() {
+    this.#outside();
+    const due = this.#q(SQL.dueTimers).all(this.#now());
+    if (due.length > 0) {
+      this.transaction(() => {
+        for (const row of due) {
+          this.#q(SQL.dropTimer).run(row.from_addr, row.id);
+          this.#start({ from: row.from_addr, id: row.id, to: row.to_addr, op: row.op, digest: row.digest, input: parse(row.input), parent: parse(row.parent),
+            lane: row.lane, by: byOf(row), awaited: row.awaited === 1, memo: parse(row.memo) });
+        }
+      });
+    }
+    // The host's timer has just gone off, and its clock may run a little early: while timers are left, it hears again.
+    if (!this.#started || !this.#wake) return;
+    const next = this.#q(SQL.firstDue).get().due;
+    if (next !== null) this.#tell(next);
+  }
+
+  /**
+   * A run reports how it is going (C6).
+   * @param {Ref} run
+   * @param {{ status?: 'working' | 'input-required', asking?: unknown, progress?: unknown }} change
+   *   what is not given stays as it was; `asking` only means something while the run is `input-required`
+   */
+  update(run, { status, asking, progress }) {
+    this.#inside();
+    const row = this.#open(run);
+    const next = status ?? row.status;
+    if (!WORKING.has(next)) throw new Error(`a run cannot be updated to ${next}`);
+    const question = next === 'input-required' ? (asking === undefined ? row.asking : json(asking)) : null;
+    const asks = next === 'input-required' && (row.status !== 'input-required' || question !== row.asking);
+    const now = this.#q(SQL.updateRun).get(next, row.asked + (asks ? 1 : 0), question, progress === undefined ? row.progress : json(progress),
+      row.from_addr, row.id);
+    if (now.root === 1) return;
+    // The newest status replaces one not yet confirmed, in its place (R3).
+    const old = this.#q(SQL.dropStatusLetter).get(now.from_addr, now.id);
+    this.#owe(now.from_addr, null, 'status', { from: now.from_addr, id: now.id },
+      { v: 1, kind: 'status', from: now.to_addr, to: now.from_addr, call: { from: now.from_addr, id: now.id }, rev: now.rev,
+        status: now.status, asked: now.asked, asking: parse(now.asking), progress: parse(now.progress) }, old?.pos);
+  }
+
+  /**
+   * @param {Ref} run
+   * @param {Outcome} outcome
+   * @param {{ progress?: unknown }} [options] without it, the run's last progress stays
+   */
+  settle(run, outcome, { progress } = {}) {
+    this.#inside();
+    if (!ENDED.has(outcome.outcome)) throw new Error(`${outcome.outcome} is not an outcome`);
+    if (outcome.outcome === 'failed') outcome = { ...outcome, error: written(outcome.error) };
+    const row = this.#open(run);
+    if (this.#q(SQL.awaiting).get(row.from_addr, row.id) || this.#q(SQL.awaitedTimer).get(row.from_addr, row.id))
+      throw new Error(`run ${run.from}/${run.id} still awaits a call it made`);
+    this.#end(row.from_addr, row.id, outcome, progress);
+  }
+
+  /**
+   * Starts a run that nobody called (2). Its status and outcome go to no one.
+   * @param {{ address: string, op: string, id: string, parent?: unknown }} run
+   */
+  root({ address, op, id, parent = null }) {
+    this.#inside();
+    this.#q(SQL.addRun).run(address, id, address, op, null, json(parent), 0, 1);
+    return runView(this.#q(SQL.run).get(address, id));
+  }
+
+  /**
+   * A handler stops a run of its own, a root run say: as if its caller had canceled it, without calling `cancel` (C7).
+   * @param {Ref} run
+   */
+  stop(run) {
+    this.#inside();
+    const row = this.#q(SQL.run).get(run.from, run.id);
+    if (!row) throw new Error(`there is no run ${run.from}/${run.id}`);
+    this.#halt(row);
+  }
+
+  /**
+   * The runs a handler took and that have not ended, root runs included: what a host scans again on start (T4).
+   * @param {{ address: string, status?: string }} filter
+   */
+  runs({ address, status = null }) {
+    return this.#q(SQL.runs).all(address, status).map(runView);
+  }
+
+  /**
+   * The calls an address made that have not ended (T4).
+   * @param {{ address: string, state?: string }} filter
+   */
+  calls({ address, state = null }) {
+    return this.#q(SQL.calls).all(address, state).map(callView);
+  }
+
+  /**
+   * What an address has not finished (8): its calls and runs, its timers not yet due, and the letters it owes, in the
+   * order they go.
+   * @param {{ address: string }} filter
+   */
+  pending({ address }) {
+    return {
+      calls: this.calls({ address }),
+      runs: this.runs({ address }),
+      timers: this.#q(SQL.timers).all(address).map(timerView),
+      letters: this.#q(SQL.letters).all(address).map(row => ({ kind: row.kind, to: row.to_addr, call: { from: row.call_from, id: row.call_id } })),
+    };
+  }
+
+  /**
+   * Waits until a call has left `sending`, or has ended (8); a timer is waited for until it is a call. Only memory
+   * holds the wait: after close() or a crash it never ends (R1).
+   * @param {Ref} ref
+   * @param {'accepted' | 'ended'} what
+   * @returns {Promise<object>} the call, as call() returns it
+   */
+  when(ref, what) {
+    this.#outside();
+    return new Promise((resolve, reject) => {
+      const waiter = { ref: { from: ref.from, id: ref.id }, what, resolve, reject };
+      if (!this.#met(waiter)) this.#waiters.push(waiter);
+    });
+  }
+
+  /**
+   * The caller no longer waits for this call (C9). The callee is not told; its outcome still comes to `result`.
+   * @param {Ref} call
+   */
+  detach(call) {
+    this.#inside();
+    if (this.#q(SQL.detachTimer).run(call.from, call.id).changes > 0) return;
+    // An ended call no longer changes (C3).
+    if (!ENDED.has(this.#made(call).state)) this.#q(SQL.detach).run(call.from, call.id);
+  }
+
+  /**
+   * The caller asks the callee to cancel the call's run (C7). How and when the run ends is the callee's; its outcome
+   * still comes. A call that has ended is not canceled.
+   * @param {Ref} call
+   * @param {unknown} [reason] goes to the callee's `cancel` as it is
+   */
+  cancel(call, reason) {
+    this.#inside();
+    if (this.#unschedule(call)) return;
+    const row = this.#made(call);
+    if (!ENDED.has(row.state)) this.#recall(row, reason);
+  }
+
+  /**
+   * The caller gives up on a call: it ends failed here, without a call to `result`, and the callee is asked to cancel
+   * (C12). The callee's own outcome, when it comes, goes to `late`.
+   * @param {Ref} call
+   */
+  abandon(call) {
+    this.#inside();
+    if (this.#unschedule(call)) return;
+    const row = this.#made(call);
+    if (ENDED.has(row.state)) return;
+    this.#recall(row);
+    this.#q(SQL.abandonCall).run(json({ code: 'abandoned', message: 'the caller abandoned this call', effects: 'unknown' }), row.from_addr, row.id);
+  }
+
+  /**
+   * Sends an open call again with `confirmed`, to learn how its run is now (C5). What it learns goes to the result
+   * handlers; a call that is not open is left alone.
+   * @param {Ref} call
+   */
+  inquire(call) {
+    this.#outside();
+    // A timer not yet due has no run to ask about.
+    if (this.#q(SQL.timer).get(call.from, call.id)) return;
+    const row = this.#made(call);
+    if (row.state === 'open') this.#ask(row);
+  }
+
+  /**
+   * Answers a run waiting for input (C8). Nothing of it is kept here: it goes once, and the answerer decides whether to
+   * send it again under the same id.
+   * @param {{ from: string, id: string, to: string, call: Ref, asked: number, answer?: unknown }} answer
+   * @returns {Promise<Receipt>} rejected when send() is
+   */
+  answer({ from, id, to, call, asked, answer }) {
+    this.#outside();
+    const envelope = { v: 1, kind: 'answer', from, to, id, call: { from: call.from, id: call.id }, asked, answer };
+    return new Promise(resolve => resolve(this.#local(to) ? this.receive(envelope) : this.#send(to, envelope)));
+  }
+
+  /**
+   * @param {object} envelope
+   * @returns {Receipt}
+   */
+  receive(envelope) {
+    this.#outside();
+    if (!this.#started) return { ok: false, code: 'not_ready' };
+    const known = envelope.v === 1 ? FIELDS[envelope.kind] : undefined;
+    if (!known || envelope.must?.some(name => !known.has(name))) return { ok: false, code: 'unsupported' };
+    return this.transaction(() => this.#take(envelope));
+  }
+
+  pump() {
+    this.#outside();
+    this.#held.clear();
+    // One transaction per owed result: one transaction calls the functions of one address only.
+    for (const { from_addr, id } of this.#q(SQL.owedCalls).all()) this.transaction(() => this.#notify(from_addr, id));
+    const rereads = [...this.#rereads.values()];
+    this.#rereads.clear();
+    for (const call of rereads) this.inquire(call);
+    this.#kick();
+  }
+
+  recover() {
+    this.#outside();
+    this.#started = true;
+    this.pump();
+    for (const row of this.#q(SQL.openCalls).all()) this.#ask(row);
+    this.tick();
+  }
+
+  /** @returns {Promise<void>} */
+  idle() {
+    if (!this.#running && this.#out === 0) return Promise.resolve();
+    return new Promise(resolve => this.#idle.push(resolve));
+  }
+
+  close() {
+    this.#closed = true;
+  }
+
+  #inside() {
+    if (!this.#tx.open) throw new Error('this must be called inside kernel.transaction()');
+  }
+
+  #outside() {
+    if (this.#closed) throw new Error('the kernel is closed');
+    if (this.#tx.open) throw new Error('this opens its own transaction and must not be called inside one');
+  }
+
+  /**
+   * What a request id already names, a call or a timer, if anything: ids are shared between the two (C1, 7). Throws
+   * when it was made with other content.
+   * @param {string} from
+   * @param {string} id
+   * @param {string} digest
+   */
+  #found(from, id, digest) {
+    const call = this.#q(SQL.call).get(from, id);
+    const found = call ?? this.#q(SQL.timer).get(from, id);
+    if (!found) return undefined;
+    if (found.digest !== digest) throw new Error(`call ${from}/${id} already exists with other content`);
+    return call ? callView(call) : timerView(found);
+  }
+
+  /**
+   * Whether a call or a timer that run `by` makes is awaited (C9). `by` must be a run of `from`.
+   * @param {string} from
+   * @param {Ref | undefined} by
+   * @param {boolean} awaited
+   */
+  #awaits(from, by, awaited) {
+    if (!by) return awaited;
+    const run = this.#q(SQL.run).get(by.from, by.id);
+    if (run?.to_addr !== from) throw new Error(`there is no run ${by.from}/${by.id} at ${from}`);
+    // A run asked to cancel no longer waits for what it starts (C9).
+    if (run.cancel_asked === 1) return false;
+    // An ended run awaiting a call would break C9.
+    if (awaited && ENDED.has(run.status)) throw new Error(`run ${by.from}/${by.id} has already ended and cannot await a call`);
+    return awaited;
+  }
+
+  // Writes a call and owes its letter (5.1): for call(), and for a timer that has come due.
+  #start({ from, id, to, op, digest, input, parent, lane, by, awaited, memo }) {
+    this.#q(SQL.addCall).run(from, id, to, op, digest, json(input), json(parent), lane, by?.from ?? null, by?.id ?? null, awaited ? 1 : 0, json(memo));
+    this.#owe(to, lane, 'call', { from, id }, { v: 1, kind: 'call', from, to, id, op, input, digest, awaited, parent });
+  }
+
+  /**
+   * Takes back a timer not yet due, without a trace (7); false when there is none.
+   * @param {Ref} timer
+   */
+  #unschedule(timer) {
+    return this.#q(SQL.dropTimer).run(timer.from, timer.id).changes > 0;
+  }
+
+  /**
+   * A call this instance made.
+   * @param {Ref} call
+   */
+  #made(call) {
+    const row = this.#q(SQL.call).get(call.from, call.id);
+    if (!row) throw new Error(`there is no call ${call.from}/${call.id}`);
+    return row;
+  }
+
+  /**
+   * A run that may still change (C3).
+   * @param {Ref} run
+   */
+  #open(run) {
+    const row = this.#q(SQL.run).get(run.from, run.id);
+    if (!row) throw new Error(`there is no run ${run.from}/${run.id}`);
+    if (ENDED.has(row.status)) throw new Error(`run ${run.from}/${run.id} has already ended`);
+    return row;
+  }
+
+  /** @param {string} sql */
+  #q(sql) {
+    let statement = this.#statements.get(sql);
+    if (!statement) this.#statements.set(sql, statement = this.#db.prepare(sql));
+    return statement;
+  }
+
+  /** @param {string} address */
+  #local(address) {
+    return this.#handlers.has(address) || this.#results.has(address);
+  }
+
+  /**
+   * @param {string} to
+   * @param {string | null} lane
+   * @param {'call' | 'status' | 'result' | 'cancel'} kind
+   * @param {Ref} call
+   * @param {object} envelope
+   * @param {number} [pos] the place of the letter this one replaces; a new letter goes last
+   */
+  #owe(to, lane, kind, call, envelope, pos = null) {
+    this.#q(SQL.owe).run(pos, envelope.from, to, lane, kind, call.from, call.id, JSON.stringify(envelope));
+  }
+
+  /** @param {object} envelope of a kind in FIELDS */
+  #take(envelope) {
+    switch (envelope.kind) {
+      case 'call':
+        return this.#accept(envelope);
+      case 'cancel':
+        return this.#revoke(envelope);
+      case 'status':
+        return this.#hear(envelope.call, envelope.from, envelope);
+      case 'result':
+        return this.#conclude(envelope.call, envelope.from, envelope);
+      case 'answer':
+        return this.#reply(envelope);
+    }
+  }
+
+  // The callee's side of a call letter (5.2, C1).
+  #accept({ from, id, to, op, input, digest, awaited, parent, confirmed }) {
+    const found = this.#q(SQL.run).get(from, id);
+    // A record that a cancel left alone has no digest to compare (C1, C7).
+    if (found) return found.digest === digest || found.op === null ? { ok: true, view: view(found) } : { ok: false, code: 'conflict' };
+    // A confirmed call was taken once; with no record of it here, it is not run now (C5).
+    if (confirmed) return { ok: false, code: 'unknown_call' };
+    this.#q(SQL.addRun).run(from, id, to, op, digest, json(parent), awaited ? 1 : 0, 0);
+    const handlers = this.#handlers.get(to)?.get(op);
+    if (!handlers) this.#end(from, id, failure('no_handler', `nothing handles ${op} at ${to}`));
+    else {
+      try {
+        this.transaction(() => {
+          const outcome = handlers.accept({ from, id, to, op, input, awaited, parent });
+          if (outcome) this.settle({ from, id }, outcome);
+        });
+      } catch (error) {
+        if (error instanceof Busy) {
+          this.#q(SQL.dropRun).run(from, id);
+          return { ok: false, code: 'busy' };
+        }
+        if (error instanceof Rejected) this.#end(from, id, failure(error.code, error.message));
+        else {
+          this.#tx.after(() => this.#onError(error));
+          this.#end(from, id, failure('handler_error', error?.message));
+        }
+      }
+    }
+    return { ok: true, view: view(this.#q(SQL.run).get(from, id)) };
+  }
+
+  // Writes a run's outcome and owes its caller a letter carrying it in place of any status not yet confirmed (C3, C4, C6).
+  #end(from, id, { outcome, result, error }, progress) {
+    const row = this.#q(SQL.endRun).get(outcome, json(result), json(error), json(progress), from, id);
+    if (row.root === 1) return;
+    this.#q(SQL.dropStatusLetter).get(from, id);
+    this.#owe(from, null, 'result', { from, id },
+      { v: 1, kind: 'result', from: row.to_addr, to: from, call: { from, id }, outcome, result, error, progress: parse(row.progress) });
+  }
+
+  // The callee's side of a cancel letter (C7).
+  #revoke({ from, to, call, reason }) {
+    if (from !== call.from) {
+      this.#tx.after(() => this.#onError(new Error(`${from} sent a cancel for call ${call.from}/${call.id}, which ${call.from} made`)));
+      return { ok: true };
+    }
+    const row = this.#q(SQL.run).get(call.from, call.id);
+    if (!row) {
+      // The cancel came before its call: this record, without op, parent or digest, answers the call when it comes.
+      this.#q(SQL.addRun).run(call.from, call.id, to, null, null, null, 0, 0);
+      this.#end(call.from, call.id, { outcome: 'canceled' });
+    } else if (this.#halt(row, reason)) {
+      // T6: a cancel function that throws loses its own changes only, and is not called again.
+      try {
+        this.transaction(() => this.#handlers.get(row.to_addr)?.get(row.op)?.cancel?.(runView(this.#q(SQL.run).get(call.from, call.id)), reason));
+      } catch (error) {
+        this.#tx.after(() => this.#onError(error));
+      }
+    }
+    return { ok: true, view: view(this.#q(SQL.run).get(call.from, call.id)) };
+  }
+
+  // The callee's side of an answer (C8): taken at most once per question, and per number.
+  #reply({ from, to, id, call, asked, answer }) {
+    const row = this.#q(SQL.run).get(call.from, call.id);
+    if (row?.to_addr !== to) return { ok: false, code: 'unknown_call' };
+    if (this.#q(SQL.answer).get(from, id)) return { ok: true, applied: true, view: view(row) };
+    if (row.status !== 'input-required' || asked !== row.asked) return { ok: true, applied: false, view: view(row) };
+    const handlers = this.#handlers.get(row.to_addr)?.get(row.op);
+    if (!handlers?.answer) return { ok: false, code: 'rejected', error: { code: 'no_handler', message: `nothing answers ${row.op} at ${row.to_addr}` } };
+    try {
+      // The run is working again before its handler sees the answer; whatever the handler throws, the question stands.
+      this.transaction(() => {
+        this.update(call, { status: 'working' });
+        this.#q(SQL.addAnswer).run(from, id, call.from, call.id, asked);
+        handlers.answer(runView(this.#q(SQL.run).get(call.from, call.id)), { from, id, asked, answer });
+      });
+    } catch (error) {
+      if (error instanceof Rejected) return { ok: false, code: 'rejected', error: { code: error.code, message: error.message } };
+      this.#tx.after(() => this.#onError(error));
+      return { ok: false, code: 'handler_error' };
+    }
+    return { ok: true, applied: true, view: view(this.#q(SQL.run).get(call.from, call.id)) };
+  }
+
+  /**
+   * Marks a run asked to cancel, drops its timers and cancels the calls it awaits (C7, 7). False when the run has ended
+   * or was asked before.
+   * @param {object} row
+   * @param {unknown} [reason]
+   */
+  #halt(row, reason) {
+    if (ENDED.has(row.status) || row.cancel_asked === 1) return false;
+    this.#q(SQL.haltRun).run(row.from_addr, row.id);
+    this.#q(SQL.dropRunTimers).run(row.from_addr, row.id);
+    for (const call of this.#q(SQL.awaiting).all(row.from_addr, row.id)) this.#recall(call, reason);
+    return true;
+  }
+
+  /**
+   * Owes the callee a cancel (C7): in the place of a call letter not yet confirmed, holding its lane, or else outside
+   * any lane. A cancel already owed is the one that goes.
+   * @param {object} row the call, not ended
+   * @param {unknown} [reason]
+   */
+  #recall(row, reason) {
+    if (this.#q(SQL.cancelLetter).get(row.from_addr, row.id)) return;
+    const call = { from: row.from_addr, id: row.id };
+    const letter = this.#q(SQL.dropCallLetter).get(row.from_addr, row.id);
+    this.#owe(row.to_addr, letter ? row.lane : null, 'cancel', call, { v: 1, kind: 'cancel', from: row.from_addr, to: row.to_addr, call, reason },
+      letter?.pos);
+  }
+
+  /**
+   * The caller hears a status of the run its call started (C6).
+   * @param {Ref} call
+   * @param {string} sender
+   * @param {{ rev: number, status: string, asked: number, asking?: unknown, progress?: unknown }} status
+   */
+  #hear(call, sender, { rev, status, asked, asking, progress }) {
+    const row = this.#known(call, sender, 'a status');
+    if (!row || ENDED.has(row.state) || rev <= row.rev) return { ok: true };
+    if (row.state === 'sending') this.#q(SQL.dropCallLetter).run(call.from, call.id);
+    const known = WORKING.has(status) ? status : 'working';
+    const now = this.#q(SQL.hearCall).get(known, rev, asked, known === 'input-required' ? json(asking) : null, json(progress), call.from, call.id);
+    // T6: a status handler that throws loses its own changes only, and is not called again.
+    try {
+      this.transaction(() => this.#results.get(call.from)?.status?.(callView(now)));
+    } catch (error) {
+      this.#tx.after(() => this.#onError(error));
+    }
+    return { ok: true };
+  }
+
+  /**
+   * The caller's row of a call that a status or an outcome is about, if it came from the call's callee (C4).
+   * @param {Ref} call
+   * @param {string} sender
+   * @param {string} what
+   */
+  #known(call, sender, what) {
+    const row = this.#q(SQL.call).get(call.from, call.id);
+    if (!row) {
+      this.#tx.after(() => this.#onError(new Error(`${what} arrived for unknown call ${call.from}/${call.id}`)));
+      return undefined;
+    }
+    if (sender !== row.to_addr) {
+      this.#tx.after(() => this.#onError(new Error(`${sender} sent ${what} for call ${call.from}/${call.id}, which went to ${row.to_addr}`)));
+      return undefined;
+    }
+    return row;
+  }
+
+  /**
+   * The caller learns an outcome, from a result letter or from a receipt that carries one (C4).
+   * @param {Ref} call
+   * @param {string} sender the address the outcome came from
+   * @param {{ outcome: string, result?: unknown, error?: unknown, progress?: unknown }} ending
+   * @param {boolean} [local] the caller's kernel wrote this outcome itself
+   */
+  #conclude(call, sender, ending, local = false) {
+    const row = this.#known(call, sender, 'an outcome');
+    // After an abandon, the callee's own outcome is still taken once, as the late one (C12).
+    const late = row?.abandoned === 1 && row.late === null && !local;
+    if (!row || (ENDED.has(row.state) && !late)) return { ok: true };
+    let { outcome, result, error, progress } = ending;
+    if (!ENDED.has(outcome)) {
+      error = { code: 'unknown_outcome', effects: 'unknown', original: { outcome, result, error } };
+      outcome = 'failed';
+      result = undefined;
+      local = true;
+    } else if (outcome === 'failed' && !local) error = heard(error);
+    if (late) this.#q(SQL.lateCall).run(JSON.stringify({ outcome, result, error, progress }), call.from, call.id);
+    else {
+      // Hearing the outcome means the callee took the call: its letter goes, and its lane moves on. A cancel not yet
+      // confirmed goes too; an abandoned call keeps its cancel until confirmed.
+      if (row.state === 'sending') this.#q(SQL.dropCallLetter).run(call.from, call.id);
+      this.#q(SQL.dropCancelLetter).run(call.from, call.id);
+      this.#q(SQL.endCall).run(outcome, json(result), json(error), json(progress), local ? 1 : 0, call.from, call.id);
+    }
+    this.#notify(call.from, call.id);
+    return { ok: true };
+  }
+
+  // Hands an ended call to its result handler, or an abandoned one's late outcome to `late`. Until that commits, the call
+  // stays owed and pump() tries again (C4, C12, T6).
+  #notify(from, id) {
+    try {
+      this.transaction(() => {
+        const row = this.#q(SQL.call).get(from, id);
+        this.#results.get(from)?.[row.late === null ? 'result' : 'late']?.(callView(row));
+        this.#q(SQL.paidCall).run(from, id);
+      });
+    } catch (error) {
+      this.#tx.after(() => this.#onError(error));
+    }
+  }
+
+  /**
+   * What a receipt means for the letter it answers, in the sender's transaction.
+   * @param {object} row
+   * @param {Receipt} receipt
+   * @param {boolean} [direct] the letter was delivered locally, in this same transaction
+   */
+  #heard(row, receipt, direct = false) {
+    this.#q(SQL.dropLetter).run(row.seq);
+    const call = { from: row.call_from, id: row.call_id };
+    if (!receipt.ok) {
+      if (row.kind === 'call') this.#conclude(call, row.to_addr, failure(receipt.code, `${row.to_addr} answered ${receipt.code}`), true);
+      // A cancel in the place of a call letter not yet confirmed: that letter may have arrived all the same (C7).
+      else if (row.kind === 'cancel' && this.#q(SQL.call).get(call.from, call.id).state === 'sending')
+        this.#conclude(call, row.to_addr, failure(receipt.code, `${row.to_addr} answered ${receipt.code} to a cancel`, 'unknown'), true);
+      else this.#tx.after(() => this.#onError(new Error(`${row.to_addr} refused a ${row.kind} letter: ${receipt.code}`)));
+      return;
+    }
+    if (row.kind !== 'call' && row.kind !== 'cancel') return;
+    // A local callee has just run its own functions in this transaction; its outcome and its status come in their own
+    // letters (4, C6).
+    if (!direct && receipt.view.outcome) this.#conclude(call, row.to_addr, receipt.view);
+    else {
+      this.#q(SQL.openCall).run(call.from, call.id);
+      if (!direct) this.#hear(call, row.to_addr, receipt.view);
+    }
+  }
+
+  /**
+   * Sends an open call again with `confirmed` (C5). It is not kept in the outbox: without a receipt it waits in memory
+   * for the next pump(). One to a local address is taken at once; there the callee runs no function of its own.
+   * @param {object} row
+   */
+  #ask(row) {
+    const call = { from: row.from_addr, id: row.id };
+    const envelope = { v: 1, kind: 'call', from: row.from_addr, to: row.to_addr, id: row.id, op: row.op, input: parse(row.input),
+      digest: row.digest, awaited: row.awaited === 1, parent: parse(row.parent), confirmed: true };
+    if (this.#local(row.to_addr)) {
+      this.transaction(() => this.#reread(call, row.to_addr, this.#take(envelope)));
+      return;
+    }
+    this.#hand(row.to_addr, envelope, receipt => {
+      if (receipt === undefined || HOLD.has(receipt.code)) this.#rereads.set(JSON.stringify([call.from, call.id]), call);
+      else {
+        try {
+          this.transaction(() => this.#reread(call, row.to_addr, receipt));
+        } catch (error) {
+          this.#rereads.set(JSON.stringify([call.from, call.id]), call);
+          this.#onError(error);
+        }
+      }
+    });
+  }
+
+  /**
+   * What the receipt of an inquiry means for the call (C5): an outcome, a newer status, or that the callee has no record.
+   * @param {Ref} call
+   * @param {string} to
+   * @param {Receipt} receipt
+   */
+  #reread(call, to, receipt) {
+    if (!receipt.ok) {
+      if (receipt.code === 'unknown_call') {
+        this.#conclude(call, to, { outcome: 'failed', error: { code: 'lost', message: `${to} has no record of this call`, effects: 'unknown' } }, true);
+      } else this.#tx.after(() => this.#onError(new Error(`${to} answered ${receipt.code} to an inquiry about ${call.from}/${call.id}`)));
+    } else if (receipt.view.outcome) this.#conclude(call, to, receipt.view);
+    else this.#hear(call, to, receipt.view);
+  }
+
+  // After every outermost commit: the send loop goes on, the waiters of when() look again, and the host hears of a new
+  // earliest timer (T3, 8, 7).
+  #committed() {
+    this.#kick();
+    this.#waiters = this.#waiters.filter(waiter => !this.#met(waiter));
+    if (!this.#started || !this.#wake) return;
+    const due = this.#q(SQL.firstDue).get().due;
+    if (due !== this.#told) this.#tell(due);
+  }
+
+  /**
+   * Ends a wait of when() if it can: true when it is done with.
+   * @param {{ ref: Ref, what: string, resolve: (call: object) => void, reject: (error: Error) => void }} waiter
+   */
+  #met({ ref, what, resolve, reject }) {
+    const row = this.#q(SQL.call).get(ref.from, ref.id);
+    if (row) {
+      if (what === 'accepted' ? row.state === 'sending' : !ENDED.has(row.state)) return false;
+      resolve(callView(row));
+      return true;
+    }
+    // A timer is still to become the call; one taken back never will.
+    if (this.#q(SQL.timer).get(ref.from, ref.id)) return false;
+    reject(new Error(`there is no call ${ref.from}/${ref.id}`));
+    return true;
+  }
+
+  /** @param {number | null} due */
+  #tell(due) {
+    this.#told = due;
+    try {
+      this.#wake(due);
+    } catch (error) {
+      this.#onError(error);
+    }
+  }
+
+  #kick() {
+    if (!this.#started || this.#closed) return;
+    if (this.#running) {
+      this.#again = true;
+      return;
+    }
+    this.#running = true;
+    queueMicrotask(() => this.#pass().catch(error => this.#onError(error)));
+  }
+
+  // One walk over the outbox in order; walks again when something committed meanwhile.
+  async #pass() {
+    let after = 0;
+    let handed = 0;
+    try {
+      for (;;) {
+        if (this.#closed) return;
+        const row = this.#q(SQL.next).get(after);
+        if (!row) {
+          if (!this.#again) break;
+          this.#again = false;
+          after = 0;
+          continue;
+        }
+        after = row.pos;
+        if (this.#flying.has(row.seq) || this.#held.has(row.seq)) continue;
+        if (this.#local(row.to_addr)) this.#deliver(row);
+        else this.#post(row);
+        if (++handed % BATCH === 0) await new Promise(resolve => this.#schedule(resolve));
+      }
+    } finally {
+      // Whatever ended this walk, the next commit or pump() starts another.
+      this.#running = false;
+      this.#settled();
+    }
+  }
+
+  // A letter to a local address: take it, drop it from the outbox and apply the receipt, in one transaction.
+  #deliver(row) {
+    try {
+      const receipt = this.transaction(() => {
+        const receipt = this.#take(JSON.parse(row.envelope));
+        if (!HOLD.has(receipt.code)) this.#heard(row, receipt, true);
+        return receipt;
+      });
+      if (HOLD.has(receipt.code)) this.#held.add(row.seq);
+    } catch (error) {
+      this.#held.add(row.seq);
+      this.#onError(error);
+    }
+  }
+
+  #post(row) {
+    this.#flying.add(row.seq);
+    this.#hand(row.to_addr, JSON.parse(row.envelope), receipt => {
+      this.#flying.delete(row.seq);
+      this.#answered(row, receipt);
+    });
+  }
+
+  /**
+   * @param {string} to
+   * @param {object} envelope
+   * @param {(receipt: Receipt | undefined) => void} answered gets undefined when send() rejected
+   */
+  #hand(to, envelope, answered) {
+    this.#out += 1;
+    // A send() that throws instead of returning a promise counts as rejected.
+    new Promise(resolve => resolve(this.#send(to, envelope))).then(receipt => receipt, () => undefined).then(receipt => {
+      // A closed kernel no longer writes: a receipt that comes back now is void (R4).
+      if (this.#closed) return;
+      this.#out -= 1;
+      answered(receipt);
+      this.#settled();
+    });
+  }
+
+  /**
+   * @param {object} row
+   * @param {Receipt | undefined} receipt undefined when send() rejected
+   */
+  #answered(row, receipt) {
+    if (receipt === undefined || HOLD.has(receipt.code)) {
+      this.#held.add(row.seq);
+      return;
+    }
+    try {
+      this.transaction(() => this.#heard(row, receipt));
+    } catch (error) {
+      this.#held.add(row.seq);
+      this.#onError(error);
+    }
+  }
+
+  #settled() {
+    if (this.#running || this.#out > 0) return;
+    for (const resolve of this.#idle.splice(0)) resolve();
+  }
+}
+
+function failure(code, message, effects = 'none') {
+  return { outcome: 'failed', error: { code, message, effects } };
+}
+
+/**
+ * A failure as its callee writes it (C11): `unknown` unless it says otherwise. An error that is no object, or effects
+ * of no known kind, is the handler's mistake.
+ * @param {unknown} [error]
+ */
+function written(error) {
+  if (error == null) return { effects: 'unknown' };
+  if (!isObject(error)) throw new Error(`the error of a failure must be an object, not ${JSON.stringify(error)}`);
+  const effects = error.effects ?? 'unknown';
+  if (!EFFECTS.has(effects)) throw new Error(`effects must be none, unknown or some, not ${JSON.stringify(effects)}`);
+  return { ...error, effects };
+}
+
+/**
+ * A failure as its caller hears it (6, C11): what this kernel does not know reads as `unknown`, and the rest is kept.
+ * @param {unknown} error
+ */
+function heard(error) {
+  if (error == null) return { effects: 'unknown' };
+  if (!isObject(error)) return { effects: 'unknown', original: error };
+  return EFFECTS.has(error.effects) ? error : { ...error, effects: 'unknown' };
+}
+
+const isObject = value => typeof value === 'object' && value !== null && !Array.isArray(value);
+
+/** @param {unknown} value */
+function json(value) {
+  return value === undefined ? null : JSON.stringify(value);
+}
+
+/** @param {string | null} text */
+function parse(text) {
+  return text === null ? undefined : JSON.parse(text);
+}
+
+/** @param {object} object */
+function defined(object) {
+  return Object.fromEntries(Object.entries(object).filter(([, value]) => value !== undefined));
+}
+
+// The outcome fields of an ended row.
+function outcomeOf(name, row) {
+  return { outcome: name, result: parse(row.result), error: parse(row.error), progress: parse(row.progress) };
+}
+
+// A run as its caller sees it in a receipt (6).
+function view(row) {
+  return defined({ status: row.status, rev: row.rev, asked: row.asked, asking: parse(row.asking), progress: parse(row.progress),
+    ...(ENDED.has(row.status) && outcomeOf(row.status, row)) });
+}
+
+// A run as its handler's host sees it in runs().
+function runView(row) {
+  return defined({ from: row.from_addr, id: row.id, to: row.to_addr, op: row.op, parent: parse(row.parent), awaited: row.awaited === 1,
+    cancelAsked: row.cancel_asked === 1, status: row.status, rev: row.rev, asked: row.asked, asking: parse(row.asking), progress: parse(row.progress),
+    ...(row.root === 1 && { root: true }) });
+}
+
+// The run that made a call or a timer (C9).
+function byOf(row) {
+  return row.by_from === null ? undefined : { from: row.by_from, id: row.by_id };
+}
+
+// A timer as its host sees it, until it comes due and is a call (7).
+function timerView(row) {
+  return defined({ from: row.from_addr, id: row.id, to: row.to_addr, op: row.op, state: 'scheduled', dueAt: row.due, memo: parse(row.memo),
+    by: byOf(row), awaited: row.awaited === 1 });
+}
+
+// A call as the caller's host sees it: with the last status it heard while open, with its outcome once ended.
+function callView(row) {
+  return defined({ from: row.from_addr, id: row.id, to: row.to_addr, op: row.op, state: row.state, memo: parse(row.memo), by: byOf(row),
+    awaited: row.awaited === 1,
+    ...(row.state === 'open' && { status: row.status, rev: row.rev, asked: row.asked, asking: parse(row.asking), progress: parse(row.progress) }),
+    ...(ENDED.has(row.state) && outcomeOf(row.state, row)), ...(row.local === 1 && { local: true }),
+    ...(row.late !== null && { late: parse(row.late) }) });
+}
+
+// The digest of what makes two calls under one id the same call (C1). Key order is not content.
+function digestOf(value) {
+  return createHash('sha256').update(canonical(value)).digest('hex');
+}
+
+function canonical(value) {
+  if (Array.isArray(value)) return `[${value.map(canonical).join(',')}]`;
+  if (value === null || typeof value !== 'object') return JSON.stringify(value);
+  const keys = Object.keys(value).filter(key => value[key] !== undefined).sort();
+  return `{${keys.map(key => `${JSON.stringify(key)}:${canonical(value[key])}`).join(',')}}`;
+}