@nervur-org/dock 0.3.0

package/harbor/capacitor.ts

@@ -0,0 +1,223 @@
+// SPDX-License-Identifier: Apache-2.0
+// The phone: the sealed store over Capacitor's Filesystem and a secure
+// storage plugin, the browser harbor over that store, and the phone's
+// faculties as its plugins give them. The files sit in the folder iCloud
+// does not copy on iOS and in the app's own data folder on Android, whose
+// manifest says no backup; the key sits in the Keychain or the Keystore,
+// this device only. The custody rule is the sealed store's, `sealed.ts`,
+// and this file hands it the two seams and nothing more.
+//
+// The harbor on a phone is the browser harbor over that store: the app
+// process is its lease, and the App plugin's foreground is its wake.
+import { Capacitor } from '@capacitor/core';
+import { App } from '@capacitor/app';
+import { Filesystem, Directory, Encoding } from '@capacitor/filesystem';
+import { SecureStorage, KeychainAccess } from '@aparajita/capacitor-secure-storage';
+import { Geolocation } from '@capacitor/geolocation';
+import { LocalNotifications } from '@capacitor/local-notifications';
+import { PushNotifications } from '@capacitor/push-notifications';
+import type { BeingClass, JsonObject } from '@nervur-org/nervur';
+import { LOCATION, NOTIFICATIONS, Location, Notifications, type Token, type Where } from '../dock/index.ts';
+import { BrowserHarbor } from './browser.ts';
+import { Sealed, type Files, type Secrets } from './sealed.ts';
+
+// The phone's faculties, as its plugins give them: the two defaults extended,
+// and handed to the harbor as its dock. The platform's permission is the
+// faculty's: a prompt is slow work, since it waits on the human, so the first
+// ask puts the prompt up and answers at once that the human is being asked,
+// and a refusal is the error object every ask after answers with.
+// The secure storage item the banner key's secret half is copied into. The
+// account the keychain holds it under is this name behind the plugin's own
+// prefix, `capacitor-storage_banner`, and the extension reads it there.
+const BANNER = 'banner';
+const asked = (what: string) => new Error(`the human is being asked to allow ${what} on this device; ask again`);
+const refused = (what: string) => new Error(`${what} is not allowed on this device`);
+
+export class PhoneLocation extends Location {
+  override async where(): Promise<Where | JsonObject> {
+    const { location } = await Geolocation.checkPermissions();
+    if (location === 'prompt' || location === 'prompt-with-rationale') {
+      void Geolocation.requestPermissions().catch(() => {});
+      throw asked('location');
+    }
+    if (location !== 'granted') throw refused('location');
+    const p = await Geolocation.getCurrentPosition({ enableHighAccuracy: true, timeout: 20_000 });
+    return { lat: p.coords.latitude, lng: p.coords.longitude, accuracy: p.coords.accuracy, at: p.timestamp };
+  }
+}
+
+export class PhoneNotifications extends Notifications {
+  override async notify(args: JsonObject): Promise<JsonObject> {
+    const title = typeof args.title === 'string' ? args.title : '';
+    const body = typeof args.body === 'string' ? args.body : '';
+    const { display } = await LocalNotifications.checkPermissions();
+    if (display === 'prompt' || display === 'prompt-with-rationale') {
+      void LocalNotifications.requestPermissions().catch(() => {});
+      throw asked('notifications');
+    }
+    if (display !== 'granted') throw refused('notifications');
+    // `isExactNotification` defaults to true, and on Android 12 and up a
+    // notification that wants an exact alarm without the permission for one
+    // opens the Alarms and reminders settings screen and never answers, so
+    // the ask goes late. This one is shown now and waits for no clock, and
+    // the permission it would otherwise want is the kind a store asks an
+    // alarm app to justify.
+    await LocalNotifications.schedule({ notifications: [{ id: Date.now() % 2147483647, title, body, isExactNotification: false }] });
+    return { shown: true };
+  }
+
+  // Where a phone's notification process reads the banner key. The process
+  // that draws a banner here is not this one: an extension runs between the
+  // platform and the screen and cannot reach a ward at all, so the secret
+  // half goes into the keychain group the two share. The pair itself stays
+  // in the faculty's cells, which is the truth of it, and this is a copy of
+  // one half put somewhere a platform can find it.
+  //
+  // It goes through the same secure storage the store keeps its key in, and
+  // not through a plugin of the app's own. An item written there lands in
+  // the app's first keychain group, which is the group the extension is in,
+  // so the two meet with nothing written to make them meet. A plugin would
+  // have had to be registered before the page loads, which on this platform
+  // is a list a `cap sync` rewrites, so the app would have carried a hand
+  // edit that the next sync undoes.
+  //
+  // The platform's permission is asked for here, in the same act. A device
+  // that has just minted a banner key is a device about to be rung, and the
+  // ring that will carry that banner is an alert the platform draws, which
+  // it draws for nobody who has not allowed it. Registering for remote
+  // notifications asked for nothing, deliberately, so this is the one place
+  // on this terrain where the person is asked at all.
+  //
+  // A refusal leaves the key where it is and costs the device the line and
+  // not the wake: the seal is planted, the world is admitted, and what
+  // arrives is a push the human never sees until the app is opened. So the
+  // answer is not waited on and not read: the person may say yes later in
+  // Settings and everything already planted still works.
+  protected override async plant(pair: { secret: Uint8Array }): Promise<void> {
+    const hex = Array.from(pair.secret, (b) => b.toString(16).padStart(2, '0')).join('');
+    await SecureStorage.set(BANNER, hex, false, false, KeychainAccess.afterFirstUnlockThisDeviceOnly);
+    const { receive } = await PushNotifications.checkPermissions().catch(() => ({ receive: 'denied' as const }));
+    if (receive === 'prompt' || receive === 'prompt-with-rationale') await PushNotifications.requestPermissions().catch(() => ({ receive: 'denied' as const }));
+  }
+}
+
+// What a phone lends: the two faculties above under the names every box
+// lends them under, and nothing a phone has not. The harbor holds these
+// class bodies for its own ward, and boots one being of each in it.
+export const PHONE_FACULTIES: Record<string, BeingClass> = { Location: PhoneLocation, Notifications: PhoneNotifications };
+export const phoneLent: Record<string, string> = { [LOCATION]: 'Location', [NOTIFICATIONS]: 'Notifications' };
+
+// The phone's ear, as `human/app.ts` asks for one: the token this device is
+// reachable at while it sleeps, or null.
+//
+// It asks the human for nothing, and it does not have to. Registering for
+// remote notifications shows no prompt and wants no permission: what a
+// permission gates is showing a human a banner, and a doorbell shows
+// nobody anything. It carries no title, no body and no id, it wakes the
+// app and nothing more, and what the human eventually reads is composed
+// here afterwards out of objects that crossed sealed. So a device whose
+// human has allowed nothing is still reachable, and misses only the line
+// it would have read; the permission it wants for that line is the
+// Notifications faculty's ask and not this one's.
+//
+// The token arrives as an event and not as an answer, so the registration
+// is awaited once and kept: the platform hands the same token back on every
+// later call, and a new one whenever it decides to, which is why the shell
+// asks again on every foreground.
+//
+// `named` is what the build says of this shell, the way `sandbox` is: the
+// bell service holding this app's keys and the app id, so a world rings
+// this phone through the right service whoever shipped the app.
+export function phoneEar(sandbox = false, within = 10_000, named: { bell?: string; app?: string } = {}): () => Promise<Token | null> {
+  let token: string | null = null;
+  return async () => {
+    if (!token) {
+      token = await new Promise<string | null>((answer) => {
+        const done = setTimeout(() => answer(null), within);
+        void PushNotifications.addListener('registration', ({ value }) => {
+          clearTimeout(done);
+          answer(value);
+        });
+        void PushNotifications.addListener('registrationError', () => {
+          clearTimeout(done);
+          answer(null);
+        });
+        void PushNotifications.register().catch(() => {
+          clearTimeout(done);
+          answer(null);
+        });
+      });
+    }
+    if (!token) return null;
+    // Which of Apple's two push hosts minted it. Nothing in a device token
+    // says so, and a development token means nothing to the production
+    // host, so the build that knows what it is is the one that says.
+    const says = { ...(named.bell ? { bell: named.bell } : {}), ...(named.app ? { app: named.app } : {}) };
+    const apple: Token = { kind: 'apns', device: token, sandbox, ...says };
+    const google: Token = { kind: 'fcm', device: token, ...says };
+    return Capacitor.getPlatform() === 'ios' ? apple : google;
+  };
+}
+
+// The app's one harbor, booted, lending the phone's faculties to its wards,
+// told `wake` every time the app comes to the foreground, since a phone
+// asleep loses its sockets silently.
+export async function nativeHarbor(name = 'quo', classes: Record<string, BeingClass> = {}): Promise<BrowserHarbor> {
+  const h = new BrowserHarbor(await Native.open(name), { ...PHONE_FACULTIES, ...classes });
+  await h.stand(phoneLent);
+  await h.boot();
+  await App.addListener('appStateChange', ({ isActive }) => {
+    if (isActive) h.wake();
+  });
+  return h;
+}
+
+// Where the files live: the folder iCloud does not copy on iOS, the app's
+// own files on Android, whose manifest says no backup.
+export const directory = Capacitor.getPlatform() === 'ios' ? Directory.LibraryNoCloud : Directory.Data;
+
+// The two seams, as the plugins give them. Two things the plugins taught:
+// the secure store keeps JSON, so a value is read with the call that
+// parses; and mkdir refuses a folder that exists, recursive or not.
+export const phoneFiles: Files = {
+  exists: async (path) => {
+    try {
+      await Filesystem.stat({ path, directory });
+      return true;
+    } catch {
+      return false;
+    }
+  },
+  read: async (path) => (await Filesystem.readFile({ path, directory, encoding: Encoding.UTF8 })).data as string,
+  write: async (path, data) => {
+    await Filesystem.writeFile({ path, directory, data, encoding: Encoding.UTF8 });
+  },
+  remove: async (path) => {
+    await Filesystem.deleteFile({ path, directory });
+  },
+  mkdir: async (path) => {
+    await Filesystem.mkdir({ path, directory, recursive: true });
+  },
+  rmdir: async (path) => {
+    await Filesystem.rmdir({ path, directory, recursive: true });
+  },
+  list: async (path) => (await Filesystem.readdir({ path, directory })).files.map((f) => f.name),
+};
+export const phoneSecrets: Secrets = {
+  get: async (item) => {
+    const got = await SecureStorage.get(item, false, false);
+    return typeof got === 'string' ? got : undefined;
+  },
+  set: async (item, value) => {
+    await SecureStorage.set(item, value, false, false, KeychainAccess.afterFirstUnlockThisDeviceOnly);
+  },
+  remove: async (item) => {
+    await SecureStorage.remove(item);
+  },
+};
+
+// The phone's store: the sealed store over the two seams above.
+export const Native = {
+  open: (harbor: string): Promise<Sealed> => Sealed.open(harbor, phoneFiles, phoneSecrets),
+  wipe: (harbor: string): Promise<void> => Sealed.wipe(harbor, phoneFiles, phoneSecrets),
+};

package/harbor/disk.ts

@@ -0,0 +1,237 @@
+// SPDX-License-Identifier: Apache-2.0
+// The node daemon's harbor: the core over a folder on disk. The store is
+// `files.ts`, one folder per ward; the class bodies come from a module the
+// ward record names, loaded from the folder; the lease is a pid file. The
+// estate's own beings, the user being, the front desk and the avatar, are
+// held by every harbor here: they are what every side needs, and a folder's
+// class source adds to them.
+//
+//   <dir>/
+//     lease                 pid of the one process that holds this harbor
+//     classes/index.ts      the default class source, a module exporting classes
+//     tab/index.ts          the classes for the tab, served bundled by the web route: human/web.ts
+//     design/               the face this world wears: tokens.css, fonts.css, fonts/, served by the web route
+//     wards/<name>/         seed, rows/, ward.json, or one sealed
+//                           blob when the daemon holds QUO_SEED_KEY: see files.ts
+//     reach.json            the directory's hints
+import { mkdir, readFile, writeFile, unlink, stat } from 'node:fs/promises';
+import { existsSync } from 'node:fs';
+import { join, resolve, isAbsolute } from 'node:path';
+import { pathToFileURL } from 'node:url';
+import { register } from 'node:module';
+import process from 'node:process';
+import type { BeingClass } from '@nervur-org/nervur';
+import { User, Desk, Avatar, Presence, Clock, Courier } from '../beings/index.ts';
+import { setup } from '../beings/setup.ts';
+import { Harbor, DEFAULT_CODE, type Hosted, type Lend } from '@nervur-org/nervur/harbor';
+import { FACULTY_CLASSES, settled, stand } from '../dock/index.ts';
+import { Files } from './files.ts';
+
+export type { Hosted, Bound } from '@nervur-org/nervur/harbor';
+export type { WardRecord } from '@nervur-org/nervur/harbor';
+export const BUILT_IN: Record<string, BeingClass> = { User, Desk, Avatar, Presence, Clock, Courier, ...FACULTY_CLASSES };
+
+// The default ward, the one a caller means when naming none: the one marked,
+// or the one ward hosted when there is exactly one, which is every harbor an
+// adopter stands with one `quo init`. Several wards and none marked is
+// refused by name, since agents and a door would otherwise hang off a
+// guess. The dock ward is furniture, never a candidate.
+export function defaultWard(marked: string[], hosted: string[]): string {
+  if (marked.length > 1) throw new Error(`this device marks ${marked.join(', ')} as default, and one at most may be`);
+  const one = marked[0];
+  if (one !== undefined) {
+    if (!hosted.includes(one)) throw new Error(`this device says its default ward is ${one}, and hosts no such ward`);
+    return one;
+  }
+  const [first, ...more] = hosted.filter((n) => n !== 'dock');
+  if (first !== undefined && more.length === 0) return first;
+  const names = first === undefined ? [] : [first, ...more];
+  throw new Error(names.length === 0 ? 'this device hosts no ward: run `quo init`' : `this device hosts ${names.join(', ')} and says which is the default: quo default <name>`);
+}
+
+// Folders held by a harbor in this process. The lease file names a pid, and
+// a second harbor in the same pid would pass that check while still being a
+// second ward with one pk.
+const HELD = new Set<string>();
+
+// A class file in the harbor folder resolves its packages from where the
+// dock is installed, `resolve.ts`: the folder has no node_modules and is not
+// meant to. Registered once per process, before the first class loads.
+let hooked = false;
+function hook(): void {
+  if (hooked) return;
+  hooked = true;
+  const self = import.meta.url as string | undefined;
+  // bundled into one script, as the desk's sidecar is, the dock has no URL and no folder of
+  // packages beside it to resolve to: a class file there imports nothing bare
+  if (!self) return;
+  register(new URL(self.endsWith('.ts') ? './resolve.ts' : './resolve.js', self), { parentURL: self, data: { parent: self } });
+}
+
+// The class source is a module. Every export that is a class is a class the
+// harbor holds, under its export name. The harbor never sees a body: it
+// constructs when a ward names a class, and never chooses one.
+async function loadClasses(path: string): Promise<Record<string, BeingClass>> {
+  if (!existsSync(path)) return {};
+  hook();
+  // Keyed by the file's own time, so a source that changed on disk is read
+  // again and a harbor boots on what it pins, not on what it once loaded.
+  const { mtimeMs } = await stat(path);
+  const mod = (await import(`${pathToFileURL(path).href}?v=${mtimeMs}`)) as Record<string, unknown>;
+  const out: Record<string, BeingClass> = {};
+  for (const [name, v] of Object.entries(mod)) if (typeof v === 'function' && 'prototype' in v) out[name] = v as BeingClass;
+  return out;
+}
+
+export class DiskHarbor extends Harbor {
+  readonly dir: string;
+  // The default ward: the one a caller means when naming none. Not a kind of
+  // ward and nothing in Quo knows of it: a harbor is not a being and has no
+  // self to be, so it can only point at one of its wards. Its agents boot
+  // there, and its door answers for it when a caller names no ward. The one
+  // ward it hosts when there is one, the one marked otherwise, resolved by
+  // the daemon at boot; empty until then.
+  defaultWard = '';
+
+  // The mark is a file in the ward's own folder, `wards/<name>/default`, so
+  // it moves with the ward and nothing beside the wards says it. One at most:
+  // marking one takes the mark off every other.
+  static async setDefault(dir: string, name: string): Promise<void> {
+    const h = new DiskHarbor(dir);
+    const names = await h.store.list();
+    if (!names.includes(name)) throw new Error(`no ward ${name} in ${h.dir}`);
+    for (const n of names) await unlink(join(h.dir, 'wards', n, 'default')).catch(() => {});
+    await writeFile(join(h.dir, 'wards', name, 'default'), '');
+  }
+
+  // Whether a ward is shown at the web route: listed at its root and its
+  // public being's page painted for a stranger. Hidden, it is not listed
+  // and a stranger meets the plain door page, while a link still knocks
+  // with its invitation and the desk still answers a proof, so nothing of
+  // the way in changes. A mark in the ward's own folder, `wards/<name>/shown`,
+  // hidden until the root shows it.
+  static async setShown(dir: string, name: string, shown: boolean): Promise<void> {
+    const h = new DiskHarbor(dir);
+    if (!(await h.store.list()).includes(name)) throw new Error(`no ward ${name} in ${h.dir}`);
+    const p = join(h.dir, 'wards', name, 'shown');
+    if (shown) await writeFile(p, '');
+    else await unlink(p).catch(() => {});
+  }
+
+  static isShown(dir: string, name: string): boolean {
+    return existsSync(join(resolve(dir), 'wards', name, 'shown'));
+  }
+
+  static async marked(dir: string): Promise<string[]> {
+    const h = new DiskHarbor(dir);
+    return (await h.store.list()).filter((n) => existsSync(join(h.dir, 'wards', n, 'default')));
+  }
+
+  // The default ward read from the folder alone, for a command with no
+  // daemon in front of it and no `--ward` given.
+  static async defaultOf(dir: string): Promise<string> {
+    const h = new DiskHarbor(dir);
+    return defaultWard(await DiskHarbor.marked(dir), await h.store.list());
+  }
+  #held = false;
+
+  // `lend` is what this box lends the beings of every ward here: a name to
+  // an invitation on a being of its own ward, which `stand` puts up. A
+  // folder booted by a command lends nothing.
+  // `own` are this terrain's own class bodies, the faculty subclasses a box
+  // has: they stand in front of the built-ins, so a daemon that can ring
+  // hands its own `Push` and the dock ward boots that one.
+  constructor(dir: string, lend?: Lend, own: Record<string, BeingClass> = {}) {
+    const abs = resolve(dir);
+    // The key the environment gives, the edge's name for it: from the
+    // Keychain through the app that spawned this daemon, or nothing on a
+    // droplet, whose folder stays plain under its file modes.
+    super(new Files(abs, process.env.QUO_SEED_KEY), async (rec) => ({ ...BUILT_IN, ...own, ...(await loadClasses(isAbsolute(rec.code) ? rec.code : join(abs, rec.code))) }), lend);
+    this.dir = abs;
+  }
+
+  // What this box lends, by name. Set before `boot` and read there; a box
+  // that says nothing stands no ward of its own and lends nothing.
+  lent: Record<string, string> | undefined;
+
+  // Create a harbor folder with one ward, and the root's setup in it: the
+  // front desk, public, and one user being, with the desk holding a standing
+  // to her placed by the root's knock. Boots the ward once, with no lease, to
+  // do that and to learn its pk, and writes the record. Refuses a folder that
+  // has one.
+  static async init(dir: string, name = 'main', user = 'me', cls = 'User', mark = false, shown = false): Promise<{ dir: string; name: string; pk: string; user: string }> {
+    const h = new DiskHarbor(dir);
+    if ((await h.store.list()).includes(name)) throw new Error(`ward ${name} already exists in ${h.dir}`);
+    await mkdir(join(h.dir, 'classes'), { recursive: true });
+    const classes = join(h.dir, DEFAULT_CODE);
+    if (!existsSync(classes)) await writeFile(classes, '// The classes this harbor holds beside the built-in ones. Export each one by name.\nexport {};\n');
+    const hosted = await h.create(name, user);
+    await setup(hosted, user, cls);
+    if (mark) await DiskHarbor.setDefault(h.dir, name);
+    if (shown) await DiskHarbor.setShown(h.dir, name, true);
+    return { dir: h.dir, name, pk: hosted.pk, user };
+  }
+
+  // Take the lease and boot every ward in the folder. The lease is the
+  // harbor's vouch made a store property: two processes over one seed are two
+  // wards with one pk, so a held lease refuses the boot.
+  //
+  // The box's own ward goes up before every other, because a being born in
+  // any of them lends from her first line, and a ground that could not reach
+  // it yet would leave her holding nothing until her next birth.
+  override async boot(): Promise<void> {
+    await this.#lease();
+    if (this.lent) this.lend = await stand(this, this.lent);
+    await super.boot();
+    // Every being who takes what this box lends does it at her birth, and
+    // birth is synchronous while taking a standing is not. A box is up when
+    // they have landed, not before.
+    await settled();
+  }
+
+  // Every ward's writing finished, then the lease. A ward says it wrote and
+  // the harbor writes it after, so a close that only dropped the lease would
+  // let the process end with a write still on its way to the disk, and the
+  // next daemon would boot on a partition older than the last reply this one
+  // gave. The lease goes last: while a write is in flight this box is still
+  // the one holding these wards.
+  async close(): Promise<void> {
+    for (const w of this.wards.values()) await w.save().catch(() => {});
+    if (!this.#held) return;
+    await unlink(join(this.dir, 'lease')).catch(() => {});
+    HELD.delete(this.dir);
+    this.#held = false;
+  }
+
+  // Boot a ward whose folder was placed here by hand.
+  async adoptFolder(name: string): Promise<Hosted> {
+    const kept = await this.store.load(name);
+    if (!kept) throw new Error(`no ward ${name} in ${this.dir}`);
+    return this.host(name, kept);
+  }
+
+  async #lease(): Promise<void> {
+    if (HELD.has(this.dir)) throw new Error(`harbor ${this.dir} is held by pid ${process.pid}`);
+    const path = join(this.dir, 'lease');
+    if (existsSync(path)) {
+      const pid = Number(await readFile(path, 'utf8'));
+      let alive = pid !== process.pid; // our own pid with no entry in HELD is a lease we left behind
+      if (alive) {
+        try {
+          process.kill(pid, 0);
+        } catch (e) {
+          alive = (e as { code?: string }).code === 'EPERM'; // EPERM: somebody is home, and not us. anything else: a corpse
+        }
+      }
+      if (alive) throw new Error(`harbor ${this.dir} is held by pid ${pid}`);
+      await unlink(path).catch(() => {}); // the corpse, so the write below can be exclusive
+    }
+    try {
+      await writeFile(path, String(process.pid), { flag: 'wx', mode: 0o600 });
+    } catch {
+      throw new Error(`harbor ${this.dir} is held: another daemon took the lease first`);
+    }
+    HELD.add(this.dir);
+    this.#held = true;
+  }
+}

package/harbor/edge/alarm.ts

@@ -0,0 +1,48 @@
+// SPDX-License-Identifier: Apache-2.0
+// The box's timer on this terrain. One method of hers knows a platform, the
+// arming, and this replaces it: the object's own storage alarm in place of a
+// `setTimeout` that would die with the request. Everything else about her is
+// the same class, the same door and the same suite, because when a box wakes
+// is a terrain's answer and what it does when it wakes is not.
+//
+// One harbor is one Durable Object, and every ward of it lives in that
+// object, so the alarm wakes the whole harbor and a tick from her to a home's
+// Clock is in-process here as it is on a disk. Only the object may set its
+// own alarm, so the two calls are handed to her after the box ward stands,
+// the way the grants are handed their save: a faculty is built by her ward
+// with a stance and nothing else.
+import { Timer } from '../../dock/index.ts';
+import type { Storage } from './platform.d.ts';
+
+// Be woken at this moment, or at no moment at all. One alarm per object,
+// replaced by the next set and gone when it is deleted, which is exactly what
+// one armed moment is.
+export type Alarms = (at: number | null) => Promise<void>;
+
+export const alarmsIn =
+  (storage: Storage): Alarms =>
+  async (at) => {
+    if (at === null) await storage.deleteAlarm();
+    else await storage.setAlarm(at);
+  };
+
+export class Alarm extends Timer {
+  // Handed in after the box ward stands. A timer holding none arms nothing
+  // and wakes nobody, which is a harbor standing no box ward.
+  alarms: Alarms | undefined;
+  #setting: Promise<void> = Promise.resolve();
+
+  // The arming written, for the device's own code and a suite: on this
+  // terrain an arming is a write to storage, and a reader of the alarm waits
+  // for it. It crosses no door.
+  get setting(): Promise<void> {
+    return this.#setting;
+  }
+
+  protected override arm(when: number | null): void {
+    // A faculty arms inside whatever ask learned the moment, and a write is
+    // not something that ask can answer for, so this is left to finish on its
+    // own. An alarm the platform refused is armed again by the next round.
+    this.#setting = (this.alarms?.(when) ?? Promise.resolve()).catch(() => {});
+  }
+}