@coda-console/kernel 0.2.0 → 0.3.0

package/sim/world.mjs

@@ -63,6 +63,23 @@ const lateEnding = row => {
 };
 const statusOf = row => JSON.stringify([row.status, row.rev, row.asked, row.asking, row.progress]);
 
+/**
+ * Whether the kernel that sent the letter can read `receipt`, as far as it reads one: a refusal's code, which it
+ * compares; and for a call or cancel taken, the view's outcome, and without one the status's rev and asked, integers it
+ * compares and writes into its table. It reads nothing else of a view. An answer's receipt goes to its host, and the
+ * world reads its applied (C8), so that is a boolean.
+ */
+function fits(envelope, receipt) {
+  if (receipt?.ok === false) return typeof receipt.code === 'string';
+  if (receipt?.ok !== true) return false;
+  if (envelope.kind === 'answer') return typeof receipt.applied === 'boolean';
+  if (envelope.kind !== 'call' && envelope.kind !== 'cancel') return true;
+  // A cancel from someone but the caller is taken without a view (the kernel's #revoke).
+  if (envelope.kind === 'cancel' && envelope.from !== envelope.call.from) return true;
+  const { view } = receipt;
+  return typeof view === 'object' && view !== null && (Boolean(view.outcome) || Number.isInteger(view.rev) && Number.isInteger(view.asked));
+}
+
 // The connection one generation of an instance gets, over the database it runs on: it counts commits and fails them
 // on purpose, and once that generation dies every call through it, or through a statement it prepared, throws Crash.
 // Everything else passes through. The kernel's copy also records what it prepares.
@@ -81,6 +98,7 @@ function connection(node, generation, record) {
         if (sql === 'BEGIN IMMEDIATE') {
           node.called = new Set();
           node.intents = new Set();
+          node.forgetting = [];
         }
         if (sql === 'COMMIT') node.commit();
         else raw.exec(sql);
@@ -131,14 +149,17 @@ function post(node, generation, to, envelope) {
 /**
  * Where a host stands between the world and its kernel, for one generation; each one left out is the world's own way.
  * - receive: the world hands the host a letter for this instance; `from` is the instance that put it into the network,
- *   which the world vouches for (P3). Returns the receipt.
+ *   which the world vouches for (P3). Returns the receipt, as its sending kernel reads one (P-receipt).
  * - send: this generation's kernel hands over a letter; the host puts it into the network with the `post` that
  *   `node.ports()` returned, or not.
  * - recover: the world recovers this generation; the host calls `kernel.recover()`.
+ * - wake: this generation's kernel tells of its earliest due time, after the world has kept it in `node.woke` (7). The
+ *   host sets its own timer and calls `kernel.tick()` when it goes off; the world no longer ticks this instance.
  * @typedef {{
  *   receive?: (envelope: object, from: SimNode) => object,
  *   send?: (to: string, envelope: object) => Promise<object>,
  *   recover?: () => void,
+ *   wake?: (due: number | null) => void,
  * }} Ports
  */
 
@@ -165,6 +186,10 @@ export class SimNode {
    * One asked in a savepoint that rolled back, inside a transaction that committed, still counts.
    */
   intents = new Set();
+  /** @type {Array<{ name: string, table: string, row: object }>} the rows forget() took in the open transaction (9) */
+  forgetting = [];
+  /** the last commit took rows: observe() looks again at every run (9) */
+  forgot = false;
   /** whatever the host's setup leaves here for its tests to reach; the world does not look at it */
   host = undefined;
   /** @type {(() => void) | undefined} what this generation's host does once its recover() has succeeded */
@@ -227,6 +252,7 @@ export class SimNode {
       onError: error => this.report(error),
       wake: at => {
         this.woke = at;
+        generation.ports.wake?.(at);
       },
       schedule: fn => this.world.tasks.push(fn),
     });
@@ -239,6 +265,9 @@ export class SimNode {
         return fn(ref, ...rest);
       };
     }
+    // What forget() takes is checked as it takes it, and kept once it commits (9).
+    const forgetting = kernel.forget.bind(kernel);
+    kernel.forget = options => this.forgets(() => forgetting(options), options.before);
     // Counted for P-rec.
     const recovering = kernel.recover.bind(kernel);
     kernel.recover = () => {
@@ -253,9 +282,15 @@ export class SimNode {
       if (this.delivering) this.taken += 1;
       return kernel.receive(envelope);
     };
+    // A tick of a host given wake is its own, on its own clock; the kernel's recover() ticking itself is not one.
+    const tick = () => {
+      if (generation.ports.wake) this.world.count('ports: a tick through the host');
+      return kernel.tick();
+    };
     this.kernel = new Proxy(kernel, {
       get(target, name) {
         if (name === 'receive') return receive;
+        if (name === 'tick') return tick;
         const value = Reflect.get(target, name);
         return typeof value === 'function' ? value.bind(target) : value;
       },
@@ -319,6 +354,50 @@ export class SimNode {
     };
   }
 
+  /**
+   * forget() runs in `fn`, in the host's transaction. Every row it takes must have ended and been quiet since before
+   * `before`, with no letter about it in the outbox, and a call with its handler committed; an answer's number goes with
+   * its run, and only then. What it leaves must not be such a row. The rows taken wait for the commit, which keeps those
+   * still gone. A run it leaves that the world saw end before `before`, only as it is not quiet yet, is noted (9).
+   * @param {() => { calls: number, runs: number, answers: number }} fn
+   * @param {number} before
+   */
+  forgets(fn, before) {
+    const tables = ['kernel_calls', 'kernel_runs', 'kernel_answers'];
+    const read = () => tables.map(table => new Map(this.q(`SELECT * FROM ${table}`).all().map(row => [key(row.from_addr, row.id), row])));
+    const owed = () => new Set(this.q('SELECT call_from, call_id FROM kernel_outbox').all().map(row => key(row.call_from, row.call_id)));
+    // A row without a quiet time is never quiet: one not ended, or a run imported once ended (5.5).
+    const quiet = row => row.quiet_at !== null && row.quiet_at < before;
+    const may = (table, name, row) => table === 'kernel_calls' ? ENDED.has(row.state) && quiet(row) && row.owed === 0 && !letters.has(name)
+      : ENDED.has(row.status) && quiet(row) && !letters.has(name);
+    const untouched = () => JSON.stringify(['kernel_outbox', 'kernel_timers'].map(table => this.q(`SELECT * FROM ${table} ORDER BY rowid`).all()));
+    const letters = owed();
+    const kept = untouched();
+    const was = read();
+    const counts = fn();
+    const now = read();
+    if (untouched() !== kept) this.world.violations.push(`9: forget() on ${this.name} changed its outbox or its timers`);
+    const runs = new Set();
+    for (const [index, table] of tables.entries()) {
+      const taken = [...was[index]].filter(([name]) => !now[index].has(name));
+      const told = counts[['calls', 'runs', 'answers'][index]];
+      if (told !== taken.length) this.world.violations.push(`9: forget() on ${this.name} said it took ${told} of ${table}, not ${taken.length}`);
+      for (const [name, row] of taken) {
+        if (table === 'kernel_runs') runs.add(name);
+        const fits = table === 'kernel_answers' ? runs.has(key(row.run_from, row.run_id)) : may(table, name, row);
+        if (!fits) this.world.violations.push(`9: forget() on ${this.name} took ${table} ${name}, which it may not: ${JSON.stringify(row)}`);
+        this.forgetting.push({ name, table, row });
+      }
+      for (const [name, row] of now[index]) {
+        const left = table === 'kernel_answers' ? runs.has(key(row.run_from, row.run_id)) : may(table, name, row);
+        if (left) this.world.violations.push(`9: forget() on ${this.name} left ${table} ${name}, which it should take: ${JSON.stringify(row)}`);
+        if (table === 'kernel_runs' && ENDED.has(row.status) && !letters.has(name) && this.world.endSeen.get(`${this.name} run ${name}`) < before)
+          this.world.spared.add(`${this.name} run ${name}`);
+      }
+    }
+    return counts;
+  }
+
   recover() {
     const { generation } = this;
     try {
@@ -387,6 +466,15 @@ export class SimNode {
     this.raw.exec('COMMIT');
     world.commits += 1;
     for (const intent of this.intents) world.intents.add(intent);
+    // A savepoint rolled back may have put back what forget() took in it.
+    for (const { name, table, row } of this.forgetting) {
+      if (this.q(`SELECT 1 FROM ${table} WHERE from_addr = ? AND id = ?`).get(row.from_addr, row.id)) continue;
+      const what = { kernel_calls: 'call', kernel_runs: 'run', kernel_answers: 'answer number' }[table];
+      // The first row taken under a name is the one the checks judge by: a later one is the record a late cancel left (9).
+      if (!world.forgotten.has(`${this.name} ${what} ${name}`)) world.forgotten.set(`${this.name} ${what} ${name}`, row);
+      world.count(`forget: ${what} taken${world.calm ? ' at rest' : ''}`);
+      this.forgot = true;
+    }
     world.observe(this);
     if (world.commits === world.crashAt) {
       world.crashed += 1;
@@ -405,8 +493,10 @@ export class SimNode {
     if (this.called.size > 1) this.world.violations.push(`S9: one transaction of ${this.name} called handlers of ${[...this.called].join(', ')}`);
   }
 
+  // A first generation's migration committed. The world's own tables tell, as they commit with the kernel's: a database
+  // the host opened may come with the kernel's tables already made, and without the world's.
   migrated() {
-    return this.q("SELECT 1 FROM sqlite_master WHERE name = 'kernel_runs'").get() !== undefined;
+    return this.q("SELECT 1 FROM sqlite_master WHERE name = 'sim_accepted'").get() !== undefined;
   }
 
   // The checks' own statements, kept per database; they bypass the generation's connection.
@@ -452,6 +542,15 @@ export class World {
   intents = new Set();
   /** @type {Map<string, number>} how often each of the rarer paths was taken */
   tally = new Map();
+  /**
+   * @type {Map<string, object>} the rows forget() took, as they were then, by `<node> call|run|answer number <key>`: the
+   * checks that read a row it may take read this one once it is gone (9)
+   */
+  forgotten = new Map();
+  /** @type {Map<string, number>} when check() first saw each ended row, by `<node> call|run <key>`: no earlier than it ended */
+  endSeen = new Map();
+  /** @type {Set<string>} runs, by `<node> run <key>`, that forget() left though they had ended before its `before` (9) */
+  spared = new Set();
   violations = [];
   /** @type {Array<() => void>} the hosts' own checks after every step, run by check() */
   steps = [];
@@ -502,9 +601,13 @@ export class World {
   // After every commit: which runs it recorded, and which lane letters it owed, for S5; which runs it asked to cancel,
   // with the calls they awaited then, for L3; and where each timer that left its table went (7).
   observe(node) {
+    // Once rows were taken, a new run may get the rowid of one taken (9): every run is looked at once more. A call's
+    // first record is the one that counts.
+    if (node.forgot) node.seen.run = 0;
+    node.forgot = false;
     for (const row of node.q('SELECT rowid, from_addr, id FROM kernel_runs WHERE rowid > ?').all(node.seen.run)) {
       node.seen.run = row.rowid;
-      this.order.set(key(row.from_addr, row.id), this.commits);
+      if (!this.order.has(key(row.from_addr, row.id))) this.order.set(key(row.from_addr, row.id), this.commits);
     }
     for (const row of node.q('SELECT seq, lane, kind, call_from, call_id FROM kernel_outbox WHERE seq > ?').all(node.seen.seq)) {
       node.seen.seq = row.seq;
@@ -598,8 +701,14 @@ export class World {
     if (moment === 'letter') {
       if (envelope.kind === 'answer') this.noticeAnswer(envelope);
       if (envelope.kind === 'cancel' && !row(envelope.to, 'kernel_runs')) this.count('cancel before its call');
+      if (envelope.kind === 'call' && row(envelope.to, 'kernel_runs') && this.spared.has(`${this.owners.get(envelope.to).name} run ${key(call.from, call.id)}`))
+        this.count(`forget: a call letter${envelope.confirmed ? ' (confirmed)' : ''} for a run kept, ended before the retention but not quiet`);
+      if ((envelope.kind === 'call' || envelope.kind === 'cancel') && !row(envelope.to, 'kernel_runs') && this.owners.get(envelope.to)?.migrated()
+        && this.forgotten.has(`${this.owners.get(envelope.to).name} run ${key(call.from, call.id)}`)) this.count(`forget: a ${envelope.kind} letter${envelope.confirmed ? ' (confirmed)' : ''} for a run taken`);
       if (envelope.kind === 'status' && ENDED.has(row(envelope.to, 'kernel_calls')?.state)) this.count('status after the outcome');
       if (envelope.kind === 'result' && row(envelope.to, 'kernel_calls')?.abandoned === 1) this.count('outcome letter after an abandon');
+      if ((envelope.kind === 'status' || envelope.kind === 'result') && this.owners.get(envelope.to)?.migrated() && !row(envelope.to, 'kernel_calls')
+        && this.forgotten.has(`${this.owners.get(envelope.to).name} call ${key(call.from, call.id)}`)) this.count(`forget: a ${envelope.kind} letter for a call taken`);
       return;
     }
     if (!receipt?.ok || (envelope.kind !== 'call' && envelope.kind !== 'cancel')) {
@@ -618,6 +727,8 @@ export class World {
     const node = this.owners.get(envelope.to);
     if (!node?.up || !node.migrated()) return;
     if (node.q('SELECT 1 FROM kernel_answers WHERE from_addr = ? AND id = ?').get(envelope.from, envelope.id)) this.count('answer: its number was taken before');
+    else if (this.forgotten.has(`${node.name} run ${key(envelope.call.from, envelope.call.id)}`)
+      && !node.q('SELECT 1 FROM kernel_runs WHERE from_addr = ? AND id = ?').get(envelope.call.from, envelope.call.id)) this.count('forget: an answer to a run taken');
     else if (node.q('SELECT 1 FROM kernel_runs WHERE from_addr = ? AND id = ? AND to_addr = ? AND status = ? AND asked = ?')
       .get(envelope.call.from, envelope.call.id, envelope.to, 'input-required', envelope.asked)) this.count('answer: to its question');
   }
@@ -670,7 +781,14 @@ export class World {
     try {
       if (!ports.receive) return JSON.parse(JSON.stringify(node.kernel.receive(envelope)));
       this.count('ports: a letter in through the host');
-      return JSON.parse(JSON.stringify(ports.receive(envelope, from)));
+      // What goes over the wire is what the sending kernel gets, and what is checked; nothing at all comes as null.
+      const receipt = JSON.parse(JSON.stringify(ports.receive(envelope, from)) ?? 'null');
+      // The sending kernel could not read it: the world tells of it, and the receipt is lost on its way.
+      if (!fits(envelope, receipt)) {
+        this.violations.push(`P-receipt: the host of ${node.name} answered a ${envelope.kind} letter with no receipt of the kernel's: ${JSON.stringify(receipt)}`);
+        return undefined;
+      }
+      return receipt;
     } catch (error) {
       if (!lost(error)) throw error;
       return undefined;
@@ -702,10 +820,12 @@ export class World {
     }
   }
 
-  /** The host of `node` ticks, as its timer would make it (7). */
+  /** The host of `node` ticks, as its timer would make it (7); not one given wake, which ticks on its own clock. */
   tick(node) {
     if (!node.up && this.restart) node.boot();
     if (!node.up) return;
+    // Such a tick would be counted as the host's own (see wrap()), and the tally would say what no host did.
+    if (node.generation.ports.wake) throw new Error(`the host of ${node.name} was given wake: its clock is the host's, and the world does not tick it`);
     try {
       node.kernel.tick();
     } catch (error) {
@@ -743,13 +863,16 @@ export class World {
    * advance. Otherwise it looks at none of the kernel's tables; what they hold at rest is for checkQuiet() to judge.
    * @param {() => boolean} [advance] the hosts move on what they hold by a step; true while there was something to move
    * @param {{ resend?: () => void }} [options] resend: how the hosts have every instance send what it keeps again, once a
-   *   round; without it the world pumps every instance itself, which would make up for a host that never does
+   *   round, and tick an instance whose host was given wake; without it the world pumps every instance itself, which
+   *   would make up for a host that never does
    */
   async quiesce(advance = () => false, { resend } = {}) {
     this.calm = true;
     // Letters already in flight may still come back refused by faults chosen earlier; the pumps that count come after.
     await this.drain();
     await this.rest(() => false, resend);
+    // A host's fault met on the way is told of first, not as the kernel's invariant it leaves broken.
+    assert.deepEqual(this.violations, []);
     this.checkStatus();
     this.checkHalted();
     await this.rest(advance, resend);
@@ -766,16 +889,43 @@ export class World {
       const advanced = advance();
       if (resend) resend();
       else for (const node of this.nodes) this.pump(node);
-      // The clock passes every timer, and every instance ticks.
+      // The clock passes every timer, and every instance ticks, but one whose host was given wake: its own timer, on its
+      // own clock, ticks it once its host moves that clock on, which resend() does.
       this.time = Math.max(this.time, ...this.nodes.filter(node => node.migrated()).map(node => node.q('SELECT max(due) AS due FROM kernel_timers').get().due ?? 0));
-      for (const node of this.nodes) this.tick(node);
+      for (const node of this.nodes) if (!node.generation.ports.wake) this.tick(node);
       await this.drain();
       await Promise.all(this.nodes.filter(node => node.up).map(node => node.kernel.idle()));
       if (this.crashed === crashed && !advanced && this.net.length === 0 && this.tasks.length === 0
         && this.nodes.every(node => node.ready && node.count('SELECT count(*) AS n FROM kernel_timers') === 0)) return;
     }
     throw new Error(`the world did not come to rest: ${this.nodes.map(node => `${node.name} has ${node.count('SELECT count(*) AS n FROM kernel_outbox')} `
-      + `letters in its outbox and ${node.count(`SELECT count(*) AS n FROM kernel_calls WHERE state IN ${UNENDED}`)} calls not ended`).join(', ')}`);
+      + `letters in its outbox, ${node.count(`SELECT count(*) AS n FROM kernel_calls WHERE state IN ${UNENDED}`)} calls not ended `
+      + `and ${node.count('SELECT count(*) AS n FROM kernel_timers')} timers`).join(', ')}`);
+  }
+
+  /**
+   * A call of `node` as the checks read it: as it is, or as forget() took it (9).
+   * @param {SimNode} node
+   * @param {string} from
+   * @param {string} id
+   */
+  call(node, from, id) {
+    return node.q('SELECT * FROM kernel_calls WHERE from_addr = ? AND id = ?').get(from, id) ?? this.forgotten.get(`${node.name} call ${key(from, id)}`);
+  }
+
+  /**
+   * The run of a call to `to`, as it is or as forget() took it (9).
+   * @param {string} from
+   * @param {string} id
+   * @param {string} to
+   */
+  run(from, id, to) {
+    const node = this.owners.get(to);
+    const row = node.q('SELECT * FROM kernel_runs WHERE from_addr = ? AND id = ?').get(from, id);
+    const gone = this.forgotten.get(`${node.name} run ${key(from, id)}`);
+    // The cancel of an abandoned call that its caller got through only after the retention finds the run forgotten,
+    // and leaves a record of its own (C7); the run's outcome is the one forget() took (9).
+    return row && !(row.op === null && gone) ? row : gone;
   }
 
   /** At rest, before the held runs finish: a call that has not ended knows the status its run has now (C6). */
@@ -796,7 +946,7 @@ export class World {
   checkHalted() {
     for (const [name, { node, calls }] of this.halted)
       for (const call of calls) {
-        if (ENDED.has(node.q('SELECT state FROM kernel_calls WHERE from_addr = ? AND id = ?').get(call.from_addr, call.id).state)) continue;
+        if (ENDED.has(this.call(node, call.from_addr, call.id).state)) continue;
         const run = this.owners.get(call.to_addr).q('SELECT cancel_asked FROM kernel_runs WHERE from_addr = ? AND id = ?').get(call.from_addr, call.id);
         assert.equal(run?.cancel_asked, 1, `L3: run ${name} was asked to cancel, but the callee of ${key(call.from_addr, call.id)}, which it awaited, was not`);
       }
@@ -819,10 +969,20 @@ export class World {
       for (const row of node.q('SELECT * FROM kernel_calls').all())
         if (ENDED.has(row.state)) now.set(`${node.name} call ${key(row.from_addr, row.id)}`, ending(row, 'state'));
       for (const row of node.q('SELECT * FROM kernel_runs').all())
-        if (ENDED.has(row.status)) now.set(`${node.name} run ${key(row.from_addr, row.id)}`, ending(row, 'status'));
-      for (const [name, text] of this.ended)
-        if (name.startsWith(`${node.name} `)) assert.equal(now.get(name), text, `S1: the outcome of ${name} changed`);
-      for (const [name, text] of now) this.ended.set(name, text);
+        if (ENDED.has(row.status)) {
+          const name = `${node.name} run ${key(row.from_addr, row.id)}`;
+          // A record a late cancel left: the run's outcome is the one forget() took (see run()).
+          now.set(name, ending((row.op === null && this.forgotten.get(name)) || row, 'status'));
+        }
+      for (const [name, text] of this.ended) {
+        if (!name.startsWith(`${node.name} `)) continue;
+        const gone = this.forgotten.get(name);
+        assert.equal(now.get(name) ?? (gone && ending(gone, name.startsWith(`${node.name} call `) ? 'state' : 'status')), text, `S1: the outcome of ${name} changed`);
+      }
+      for (const [name, text] of now) {
+        if (!this.ended.has(name)) this.endSeen.set(name, this.time);
+        this.ended.set(name, text);
+      }
 
       for (const [table, what] of [['sim_accepted', 'S2: accept'], ['sim_results', 'S3: result'], ['sim_lates', 'S3: late'],
         ['sim_cancels', 'the cancel function']]) {
@@ -839,7 +999,7 @@ export class World {
       // An outcome from the callee, or an abandoned call's late one, is the outcome of its run.
       for (const call of node.q('SELECT * FROM kernel_calls').all()) {
         if (!ENDED.has(call.state) || (call.local === 1 && call.late === null)) continue;
-        const run = this.owners.get(call.to_addr).q('SELECT * FROM kernel_runs WHERE from_addr = ? AND id = ?').get(call.from_addr, call.id);
+        const run = this.run(call.from_addr, call.id, call.to_addr);
         assert.ok(run, `S4: call ${key(call.from_addr, call.id)} ended but its callee has no run`);
         assert.equal(call.late === null ? ending(call, 'state') : lateEnding(call), ending(run, 'status'), `S4: call ${key(call.from_addr, call.id)} ended unlike its run`);
       }
@@ -902,16 +1062,31 @@ export class World {
       assert.equal(node.count('SELECT count(*) AS n FROM kernel_calls WHERE owed = 1'), 0, `results of ${node.name} are still owed at rest`);
       for (const call of node.q('SELECT * FROM kernel_calls').all())
         assert.ok(ENDED.has(call.state), `call ${key(call.from_addr, call.id)} is still ${call.state} at rest`);
-      for (const run of node.q('SELECT * FROM kernel_runs').all()) {
-        const name = key(run.from_addr, run.id);
-        assert.ok(ENDED.has(run.status), `run ${name} is still ${run.status} at rest`);
-        if (run.root === 1) continue;
+      // The runs it has, and those forget() took, which L2 holds for all the same (9).
+      const runs = new Map(node.q('SELECT * FROM kernel_runs').all().map(row => [key(row.from_addr, row.id), row]));
+      for (const [name, row] of this.forgotten)
+        if (name.startsWith(`${node.name} run `) && !runs.has(key(row.from_addr, row.id))) runs.set(key(row.from_addr, row.id), row);
+      for (const [name, row] of runs) {
+        assert.ok(ENDED.has(row.status), `run ${name} is still ${row.status} at rest`);
+        if (row.root === 1) continue;
+        const run = this.run(row.from_addr, row.id, row.to_addr);
         const caller = this.owners.get(run.from_addr);
-        const call = caller.q('SELECT * FROM kernel_calls WHERE from_addr = ? AND id = ?').get(run.from_addr, run.id);
+        const call = this.call(caller, run.from_addr, run.id);
         // An abandoned call has its own outcome; the run's comes as the late one, to `late` instead of `result`.
         const abandoned = call?.abandoned === 1;
-        assert.equal(call && (abandoned ? call.late && lateEnding(call) : ending(call, 'state')), ending(run, 'status'),
-          `L2: the caller of ${name} does not have its ${abandoned ? 'late ' : ''}outcome`);
+        // forget() took an abandoned call before the run's own outcome came: a late outcome is no longer taken (9).
+        if (abandoned && call.late === null && this.forgotten.has(`${caller.name} call ${name}`)) {
+          for (const table of ['sim_results', 'sim_lates'])
+            assert.equal(caller.count(`SELECT count(*) AS n FROM ${table} WHERE from_addr = ? AND id = ?`, run.from_addr, run.id), 0,
+              `L2: ${name} was forgotten before its late outcome came, but a handler took one`);
+          this.count('forget: an abandoned call taken before its late outcome');
+          continue;
+        }
+        // An outcome the caller's kernel wrote itself is not compared: the callee's, coming after, does not change it (C4).
+        // Say a call imported open whose callee had no record: lost, and the cancel sent after it left a canceled record.
+        if (!(call?.local === 1 && !abandoned))
+          assert.equal(call && (abandoned ? call.late && lateEnding(call) : ending(call, 'state')), ending(run, 'status'),
+            `L2: the caller of ${name} does not have its ${abandoned ? 'late ' : ''}outcome`);
         for (const [table, what] of [['sim_results', 'result'], ['sim_lates', 'late']])
           assert.equal(caller.count(`SELECT count(*) AS n FROM ${table} WHERE from_addr = ? AND id = ?`, run.from_addr, run.id),
             (what === 'late') === abandoned ? 1 : 0, `L2: ${what} of ${name} was not committed exactly as often as it should`);

package/src/kernel.mjs

@@ -135,7 +135,7 @@ class Kernel {
     // 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);
+    for (const step of MIGRATIONS.slice(version)) this.#db.exec(typeof step === 'string' ? step : step(this.#now()));
     this.#q(SQL.setVersion).run(MIGRATIONS.length);
   }
 
@@ -171,6 +171,47 @@ class Kernel {
     return defined({ from, id, to, op, state: 'sending', memo, by: by && { from: by.from, id: by.id }, awaited });
   }
 
+  /**
+   * Imports a call its callee had already taken before this kernel kept it (导入): it is open, at version 0, and owes no
+   * letter. A call letter would have a callee without the record run it again; recover() inquires instead (C5).
+   * @param {{ from: string, id: string, to: string, op: string, input?: unknown, lane?: string, by?: Ref,
+   *   awaited?: boolean, parent?: unknown, memo?: unknown }} call
+   */
+  adoptCall({ from, id, to, op, input = null, lane = null, by, awaited = false, parent = null, memo }) {
+    this.#adopting();
+    const digest = digestOf([to, op, input, parent]);
+    const found = this.#found(from, id, digest);
+    if (found) return found;
+    awaited = this.#awaits(from, by, awaited);
+    return callView(this.#q(SQL.adoptCall).get(from, id, to, op, digest, json(input), json(parent), lane, by?.from ?? null, by?.id ?? null,
+      awaited ? 1 : 0, json(memo)));
+  }
+
+  /**
+   * Imports a run taken before this kernel kept it (导入): no handler is called and no letter owed. Without an outcome
+   * it is working, or waiting for input on its first question; with one, it has ended.
+   * @param {{ from: string, id: string, to: string, op: string, input?: unknown, parent?: unknown, awaited?: boolean,
+   *   status?: 'working' | 'input-required', asking?: unknown, progress?: unknown, outcome?: Outcome }} run
+   */
+  adoptRun({ from, id, to, op, input = null, parent = null, awaited = false, status = 'working', asking, progress, outcome }) {
+    this.#adopting();
+    // A run without op is the record a cancel leaves, whose digest is never compared (C1).
+    if (op == null) throw new Error(`an imported run needs its op: ${from}/${id}`);
+    const digest = digestOf([to, op, input, parent]);
+    const found = this.#q(SQL.run).get(from, id);
+    if (found) {
+      if (found.digest !== digest) throw new Error(`run ${from}/${id} already exists with other content`);
+      return adoptedView(found);
+    }
+    if (outcome) {
+      if (!ENDED.has(outcome.outcome)) throw new Error(`${outcome.outcome} is not an outcome`);
+      status = outcome.outcome;
+    } else if (!WORKING.has(status)) throw new Error(`a run cannot be imported as ${status}`);
+    const asks = status === 'input-required';
+    return adoptedView(this.#q(SQL.adoptRun).get(from, id, to, op, digest, json(parent), awaited ? 1 : 0, status, asks ? 1 : 0,
+      asks ? json(asking) : null, json(outcome?.result), outcome?.outcome === 'failed' ? json(written(outcome.error)) : null, json(progress)));
+  }
+
   /**
    * 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,
@@ -355,7 +396,25 @@ class Kernel {
     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);
+    this.#q(SQL.abandonCall).run(json({ code: 'abandoned', message: 'the caller abandoned this call', effects: 'unknown' }), this.#now(),
+      row.from_addr, row.id);
+  }
+
+  /**
+   * Deletes what has been quiet since before `before` and is no longer needed to tell a repeat (9): ended calls whose
+   * handler has committed, and ended runs, about which no letter is owed and none has left the outbox since, with the
+   * numbers of the answers a deleted run took. A repeat comes no later than the host's retention after the last letter
+   * about it, which `before` stands for; after it, its id is unknown here.
+   * @param {{ before: number }} options
+   * @returns {{ calls: number, runs: number, answers: number }} how many rows of each were deleted
+   */
+  forget({ before }) {
+    this.#inside();
+    const calls = this.#q(SQL.forgetCalls).run(before).changes;
+    const runs = this.#q(SQL.forgetRuns).all(before);
+    let answers = 0;
+    for (const run of runs) answers += this.#q(SQL.forgetAnswers).run(run.from_addr, run.id).changes;
+    return { calls, runs: runs.length, answers };
   }
 
   /**
@@ -402,7 +461,12 @@ class Kernel {
     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);
+    // Read the row itself, not through inquire(): forget() may have deleted a call kept here since, and that is no
+    // reason to throw and lose the other rereads (9, C5).
+    for (const call of rereads) {
+      const row = this.#q(SQL.call).get(call.from, call.id);
+      if (row?.state === 'open') this.#ask(row);
+    }
     this.#kick();
   }
 
@@ -428,6 +492,13 @@ class Kernel {
     if (!this.#tx.open) throw new Error('this must be called inside kernel.transaction()');
   }
 
+  // Imports come before recover(): its first rereads and letters are what moves them on, and no letter or memory of
+  // this instance has met them yet (R1, R2).
+  #adopting() {
+    this.#inside();
+    if (this.#started) throw new Error('imports must come before recover()');
+  }
+
   #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');
@@ -573,7 +644,7 @@ class Kernel {
 
   // 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);
+    const row = this.#q(SQL.endRun).get(outcome, json(result), json(error), json(progress), this.#now(), from, id);
     if (row.root === 1) return;
     this.#q(SQL.dropStatusLetter).get(from, id);
     this.#owe(from, null, 'result', { from, id },
@@ -658,13 +729,24 @@ class Kernel {
    * @param {Ref} call
    * @param {string} sender
    * @param {{ rev: number, status: string, asked: number, asking?: unknown, progress?: unknown }} status
+   * @param {boolean} [muted] the callee's cancel function may have run in this same transaction (S9)
+   * @param {boolean} [receipt] this is the receipt of the letter just dropped from the outbox, not a status letter
    */
-  #hear(call, sender, { rev, status, asked, asking, progress }) {
+  #hear(call, sender, { rev, status, asked, asking, progress }, muted = false, receipt = false) {
     const row = this.#known(call, sender, 'a status');
-    if (!row || ENDED.has(row.state) || rev <= row.rev) return { ok: true };
+    // A receipt for a sending call comes as its letter is dropped: whatever version it says, the callee took the call,
+    // and the call leaves sending (S10). A status letter at a version not above the row's is an old one, and changes
+    // nothing (C6).
+    if (!row || ENDED.has(row.state) || (!(receipt && row.state === 'sending') && 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);
+    // The callee's cancel function may have just run in this transaction: the caller's are not called (S9).
+    if (muted) return { ok: true };
+    // The receipt that takes a call is no status of its own (C6): at version 1, or below it from a callee that breaks
+    // C6, it is the run as it was taken. An imported run may have been taken waiting for input (5.5), and no letter of
+    // its own will ask: the caller hears the question here.
+    if (row.state === 'sending' && rev <= 1 && known === 'working') return { ok: true };
     // 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)));
@@ -718,7 +800,7 @@ class Kernel {
       // 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.#q(SQL.endCall).run(outcome, json(result), json(error), json(progress), local ? 1 : 0, this.#now(), call.from, call.id);
     }
     this.#notify(call.from, call.id);
     return { ok: true };
@@ -743,9 +825,14 @@ class Kernel {
    * @param {object} row
    * @param {Receipt} receipt
    * @param {boolean} [direct] the letter was delivered locally, in this same transaction
+   * @param {boolean} [muted] the callee may have run a function of its own in this same transaction (S9)
    */
-  #heard(row, receipt, direct = false) {
+  #heard(row, receipt, direct = false, muted = false) {
     this.#q(SQL.dropLetter).run(row.seq);
+    // A copy of the letter may still be on its way, and the other side may still send what it answers, until it heard
+    // this one: an ended row is kept for a repeat from now on (9). A call or cancel is about the caller's call, a status
+    // or an outcome about the callee's run.
+    this.#q(row.kind === 'call' || row.kind === 'cancel' ? SQL.quietCall : SQL.quietRun).run(this.#now(), row.call_from, row.call_id);
     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);
@@ -759,10 +846,8 @@ class Kernel {
     // 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);
-    }
+    else if (direct) this.#q(SQL.openCall).run(call.from, call.id);
+    else this.#hear(call, row.to_addr, receipt.view, muted, true);
   }
 
   /**
@@ -884,8 +969,19 @@ class Kernel {
   #deliver(row) {
     try {
       const receipt = this.transaction(() => {
+        // A callee that took this call before, an imported run say, runs nothing of its own now and owes nothing more:
+        // its receipt is all the caller hears, as from a callee elsewhere (5.5, S9). So too a cancel that finds the run
+        // ended, and one in the place of the call letter that leaves such a run as it was before the cancel, at the same
+        // version: no letter of its own will tell either. The run may have changed since it was imported, its status
+        // letter dropped by a caller that had no call yet. A cancel function that changed the run owes its own letters
+        // (C6, C7).
+        const run = row.kind === 'call' || row.kind === 'cancel' ? this.#q(SQL.run).get(row.call_from, row.call_id) : undefined;
         const receipt = this.#take(JSON.parse(row.envelope));
-        if (!HOLD.has(receipt.code)) this.#heard(row, receipt, true);
+        const taken = row.kind === 'call' ? run !== undefined
+          : ENDED.has(run?.status) || (run !== undefined && !receipt.view.outcome && receipt.view.rev === run.rev
+            && this.#q(SQL.call).get(row.call_from, row.call_id).state === 'sending');
+        // A cancel delivered here may have just run the callee's cancel function: its receipt calls no status (S9).
+        if (!HOLD.has(receipt.code)) this.#heard(row, receipt, !taken, row.kind === 'cancel');
         return receipt;
       });
       if (HOLD.has(receipt.code)) this.#held.add(row.seq);
@@ -1005,6 +1101,11 @@ function runView(row) {
     ...(row.root === 1 && { root: true }) });
 }
 
+// An imported run as adoptRun() returns it: as runs() lists it, with its outcome once ended.
+function adoptedView(row) {
+  return defined({ ...runView(row), ...(ENDED.has(row.status) && outcomeOf(row.status, row)) });
+}
+
 // 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 };