nervur 0.20.0 → 0.20.2

package/src/line/push.ts

@@ -0,0 +1,112 @@
+// SPDX-License-Identifier: Apache-2.0
+// A ring with no content, as Web Push sends it: RFC 8030 with no payload,
+// so nothing is encrypted and nothing is said, and RFC 8292's VAPID, so
+// the push service knows who rings. It runs on fetch and Web Crypto, in
+// every engine. The device a ring wakes asks its relay client to `ring`.
+//
+//   subject  { subject }   the contact a push service reaches, a mailto:
+//                          or https: URI, the owner's to set
+//   key                    the key a device subscribes with, as
+//                          PushManager takes it
+//   ring     { endpoint }  a ring to that endpoint: `rung`, `gone` where
+//                          the push service has let it go, or an error
+//
+// The signing key is drawn at the first `key` or `ring` and kept in the
+// faculty's cells, sealed with the rest of the harbor.
+import type { AskSpec, JsonObject } from '../being/index.ts';
+import { concat, utf8 } from '../crypto/index.ts';
+import { Push, type GroundFaculty } from '../harbor/index.ts';
+import { ownerAsk } from '../ward/index.ts';
+
+export const WEB_PUSH = 'org.nervur.web-push';
+// How long a push service holds a ring for a device, in seconds.
+export const PUSH_TTL = 60;
+// How long a VAPID token stands, in seconds, inside RFC 8292's day.
+export const VAPID_LIFE = 43_200;
+
+type Vapid = { d: string; x: string; y: string };
+const EC = { name: 'ECDSA', namedCurve: 'P-256' } as const;
+
+export const base64url = (bytes: Uint8Array): string => {
+  let s = '';
+  for (const b of bytes) s += String.fromCharCode(b);
+  return btoa(s).replace(/\+/g, '-').replace(/\//g, '_').replace(/=+$/, '');
+};
+const unbase64url = (text: string): Uint8Array => Uint8Array.from(atob(text.replace(/-/g, '+').replace(/_/g, '/')), (c) => c.charCodeAt(0));
+const local = (host: string): boolean => host === '127.0.0.1' || host === 'localhost' || host === '[::1]';
+
+// A push endpoint: an https URL, or plain http to this machine alone.
+export const pushEndpoint = (value: unknown): URL | null => {
+  if (typeof value !== 'string') return null;
+  try {
+    const url = new URL(value);
+    return url.protocol === 'https:' || (url.protocol === 'http:' && local(url.hostname)) ? url : null;
+  } catch {
+    return null;
+  }
+};
+const isSubject = (value: unknown): value is string => typeof value === 'string' && /^(mailto:.+|https:\/\/.+)$/.test(value);
+
+export const webPush: GroundFaculty = () =>
+  class WebPush extends Push {
+    static override readonly kind: string = WEB_PUSH;
+    static override asks: Record<string, AskSpec> = {
+      subject: ownerAsk('the contact a push service reaches, a mailto: or https: URI', { required: ['subject'] }),
+      key: { description: 'the key a device subscribes to pushes with', input: { type: 'object' } },
+      ring: { description: 'a ring with no content to a push endpoint', input: { type: 'object', required: ['endpoint'] } },
+    };
+
+    #drawing: Promise<Vapid> | undefined;
+
+    subject(args: JsonObject): JsonObject {
+      if (!isSubject(args.subject)) return { error: 'subject is a mailto: or https: URI' };
+      this.cells.subject = args.subject;
+      return { subject: args.subject };
+    }
+
+    async key(): Promise<JsonObject> {
+      return { key: WebPush.#public(await this.#vapid()) };
+    }
+
+    async ring(args: JsonObject): Promise<JsonObject> {
+      const endpoint = pushEndpoint(args.endpoint);
+      if (endpoint === null) return { error: 'endpoint is an https URL' };
+      const sub = this.cells.subject;
+      if (!isSubject(sub)) return { error: 'no subject is set' };
+      const vapid = await this.#vapid();
+      const signing = await crypto.subtle.importKey('jwk', { kty: 'EC', crv: 'P-256', ...vapid }, EC, false, ['sign']);
+      const part = (value: JsonObject) => base64url(utf8(JSON.stringify(value)));
+      const unsigned = `${part({ typ: 'JWT', alg: 'ES256' })}.${part({ aud: endpoint.origin, exp: Math.floor(Date.now() / 1000) + VAPID_LIFE, sub })}`;
+      const signature = new Uint8Array(await crypto.subtle.sign({ name: 'ECDSA', hash: 'SHA-256' }, signing, new Uint8Array(utf8(unsigned))));
+      let status: number;
+      try {
+        const response = await fetch(endpoint, {
+          method: 'POST',
+          headers: { TTL: String(PUSH_TTL), Urgency: 'high', 'Content-Length': '0', Authorization: `vapid t=${unsigned}.${base64url(signature)}, k=${WebPush.#public(vapid)}` },
+        });
+        status = response.status;
+        await response.body?.cancel();
+      } catch {
+        return { error: 'the push service was not reached' };
+      }
+      if (status === 404 || status === 410) return { gone: true };
+      return status >= 200 && status < 300 ? { rung: true } : { error: `the push service answered ${String(status)}` };
+    }
+
+    static #public({ x, y }: Vapid): string {
+      return base64url(concat(Uint8Array.of(4), unbase64url(x), unbase64url(y)));
+    }
+
+    #vapid(): Promise<Vapid> {
+      const kept = this.cells.vapid as Vapid | undefined;
+      if (kept) return Promise.resolve(kept);
+      this.#drawing ??= (async () => {
+        const pair = await crypto.subtle.generateKey(EC, true, ['sign']);
+        const { d, x, y } = await crypto.subtle.exportKey('jwk', pair.privateKey);
+        const vapid = { d: d!, x: x!, y: y! };
+        this.cells.vapid = vapid;
+        return vapid;
+      })();
+      return this.#drawing;
+    }
+  };

package/src/line/web.ts

@@ -0,0 +1,227 @@
+// SPDX-License-Identifier: Apache-2.0
+// Quo over the web, `quo/CARRIER-WEB.md`, on what every engine has: fetch
+// and the WebSocket client.
+//
+//   WebDialer     bytes to a ward pk at an address: `http` and `https` as
+//                 one post each, `ws` and `wss` on one held line per
+//                 address, which many asks share
+//   webFaculty    the web carrier as a faculty of one harbor: it dials
+//                 every web address the harbor routes, and listens where
+//                 its cells say, through a listener the ground hands it
+//
+// A post that comes back with status 200 and a body is a reply, and every
+// other status is nothing. A post the network refused, or a held line
+// that did not open, was not dialed. A line that carried a box and closed
+// answers nothing.
+import type { AskSpec, JsonObject } from '../being/index.ts';
+import { concat, hex, isHex, unhex } from '../crypto/index.ts';
+import { CarrierFaculty, UNDIALED, type Dialed, type Ground, type GroundFaculty } from '../harbor/index.ts';
+import { webAddress, type WebAddress } from '../quo/index.ts';
+import { ownerAsk } from '../ward/index.ts';
+import { askBody, readBody } from './frame.ts';
+
+export const MIN_POST = 65;
+export const MAX_POST = 64 + 1_048_576;
+const MAX_ID = 0xffff_ffff;
+
+// Bytes on a buffer of their own, as a body and a message take them.
+const own = (bytes: Uint8Array): Uint8Array<ArrayBuffer> => new Uint8Array(bytes);
+
+// One held line to one address.
+class HeldLine {
+  readonly #socket: WebSocket;
+  readonly #waiting = new Map<number, (box: Uint8Array | null) => void>();
+  #next = 1;
+
+  private constructor(socket: WebSocket) {
+    this.#socket = socket;
+    socket.binaryType = 'arraybuffer';
+    socket.addEventListener('message', (e: MessageEvent) => {
+      const frame = typeof e.data === 'string' ? null : readBody(new Uint8Array(e.data as ArrayBuffer));
+      if (frame === null) return this.close();
+      if (frame.kind === 'ask') return;
+      const done = this.#waiting.get(frame.id);
+      this.#waiting.delete(frame.id);
+      done?.(frame.kind === 'reply' ? frame.box : null);
+    });
+    socket.addEventListener('close', () => {
+      for (const done of this.#waiting.values()) done(null);
+      this.#waiting.clear();
+    });
+  }
+
+  // A line that opened with the subprotocol `quo`, or null.
+  static open(href: string, onClose: () => void): Promise<HeldLine | null> {
+    return new Promise((resolve) => {
+      let socket: WebSocket;
+      try {
+        socket = new WebSocket(href, 'quo');
+      } catch {
+        resolve(null);
+        return;
+      }
+      const line = new HeldLine(socket);
+      socket.addEventListener('open', () => (socket.protocol === 'quo' ? resolve(line) : (socket.close(), resolve(null))));
+      socket.addEventListener('close', () => {
+        onClose();
+        resolve(null);
+      });
+      socket.addEventListener('error', () => resolve(null));
+    });
+  }
+
+  ask(pk: Uint8Array, box: Uint8Array): Promise<Uint8Array | null> {
+    if (this.#socket.readyState !== WebSocket.OPEN) return Promise.resolve(null);
+    const id = this.#next;
+    this.#next = this.#next === MAX_ID ? 1 : this.#next + 1;
+    return new Promise((resolve) => {
+      this.#waiting.set(id, resolve);
+      this.#socket.send(own(askBody(id, pk, box)));
+    });
+  }
+
+  close(): void {
+    this.#socket.close();
+  }
+}
+
+export class WebDialer {
+  readonly #lines = new Map<string, Promise<HeldLine | null>>();
+
+  dial(at: string, pk: string, bytes: Uint8Array): Promise<Dialed> {
+    const address = webAddress(at);
+    if (address === null || !isHex(pk, 64)) return Promise.resolve(UNDIALED);
+    return address.held ? this.#held(address, pk, bytes) : this.#post(address, pk, bytes);
+  }
+
+  async #post(address: WebAddress, pk: string, bytes: Uint8Array): Promise<Dialed> {
+    let response: Response;
+    try {
+      response = await fetch(address.href, { method: 'POST', body: own(concat(unhex(pk), bytes)) });
+    } catch {
+      return UNDIALED;
+    }
+    const body = new Uint8Array(await response.arrayBuffer().catch(() => new ArrayBuffer(0)));
+    return response.status === 200 && body.length > 0 ? body : null;
+  }
+
+  async #held(address: WebAddress, pk: string, bytes: Uint8Array): Promise<Dialed> {
+    let line = this.#lines.get(address.href);
+    if (!line) {
+      line = HeldLine.open(address.href, () => this.#lines.delete(address.href));
+      this.#lines.set(address.href, line);
+      void line.then((held) => held ?? this.#lines.delete(address.href));
+    }
+    const held = await line;
+    return held ? held.ask(unhex(pk), bytes) : UNDIALED;
+  }
+
+  async close(): Promise<void> {
+    const lines = [...this.#lines.values()];
+    this.#lines.clear();
+    for (const line of await Promise.all(lines)) line?.close();
+  }
+}
+
+// Where the web carrier listens, as its cells keep it: a host, the port it
+// bound, the path it answers on, and the origins whose pages it answers.
+export type WebListen = { host: string; port: number; path: string; origins: string[] };
+
+// A listener a ground runs for the web carrier: it hands every ask it
+// hears to the ground, and says the addresses it answers at, a post's and
+// a held line's.
+export interface WebListener {
+  readonly at: string[];
+  readonly port: number;
+  close(): Promise<void>;
+}
+export type WebServe = (ground: Ground, listen: WebListen) => Promise<WebListener>;
+
+export const WEB = 'org.nervur.web';
+export const WEB_OPENING = { key: 'web', kind: WEB } as const;
+
+const listenOf = (value: unknown): WebListen | null => {
+  if (typeof value !== 'object' || value === null) return null;
+  const { host, port, path, origins } = value as Record<string, unknown>;
+  const fine =
+    typeof host === 'string' &&
+    Number.isInteger(port) &&
+    (port as number) >= 0 &&
+    (port as number) <= 65_535 &&
+    typeof path === 'string' &&
+    path.startsWith('/') &&
+    Array.isArray(origins) &&
+    origins.every((o) => typeof o === 'string');
+  return fine ? { host, port: port as number, path, origins: origins as string[] } : null;
+};
+
+// Quo over the web as a carrier faculty of one harbor, listening through
+// `serve` where the ground has one:
+//
+//   listen  { host?, port?, path?, origins? }
+//                  listen there from now on, 127.0.0.1, a free port, `/`
+//                  and every origin unless named, and on every wake at the
+//                  port it bound
+//   deaf           listen nowhere from now on
+export const webFaculty =
+  (serve?: WebServe): GroundFaculty =>
+  (ground: Ground) =>
+    class WebFaculty extends CarrierFaculty {
+      static override readonly kind: string = WEB;
+      static override asks: Record<string, AskSpec> = {
+        listen: ownerAsk('listen for Quo over the web, and on every wake'),
+        deaf: ownerAsk('listen nowhere'),
+      };
+
+      readonly #dialer = new WebDialer();
+      #listener: WebListener | undefined;
+
+      accepts(address: string): boolean {
+        return webAddress(address) !== null;
+      }
+
+      dial(address: string, pk: string, bytes: Uint8Array): Promise<Dialed> {
+        return this.#dialer.dial(address, pk, bytes);
+      }
+
+      override listening(): string[] {
+        return this.#listener ? [...this.#listener.at] : [];
+      }
+
+      override async awake(): Promise<void> {
+        const at = listenOf(this.cells.listen);
+        if (at && serve && !this.#listener) this.#listener = await serve(ground, at);
+      }
+
+      override async sleep(): Promise<void> {
+        await this.#dialer.close();
+        await this.#listener?.close();
+        this.#listener = undefined;
+      }
+
+      async listen(args: JsonObject): Promise<JsonObject> {
+        if (!serve) return { error: 'this ground listens nowhere on the web' };
+        const at = listenOf({ host: args.host ?? '127.0.0.1', port: args.port ?? 0, path: args.path ?? '/', origins: args.origins ?? ['*'] });
+        if (at === null) return { error: 'host is text, port a port, path a path and origins a list' };
+        await this.#listener?.close();
+        this.#listener = undefined;
+        try {
+          this.#listener = await serve(ground, at);
+        } catch (e) {
+          return { error: (e as Error).message };
+        }
+        this.cells.listen = { ...at, port: this.#listener.port };
+        return { at: [...this.#listener.at] };
+      }
+
+      async deaf(): Promise<JsonObject> {
+        await this.#listener?.close();
+        this.#listener = undefined;
+        delete this.cells.listen;
+        return { deaf: true };
+      }
+    };
+
+// The ward pk and box a post carries, or null for a body that is no ask.
+export const readPost = (body: Uint8Array): { pk: string; box: Uint8Array } | null =>
+  body.length < MIN_POST || body.length > MAX_POST ? null : { pk: hex(body.subarray(0, 64)), box: body.slice(64) };

package/src/node/index.ts

@@ -0,0 +1,170 @@
+// SPDX-License-Identifier: Apache-2.0
+// `nervur/node`: the Node ground. A harbor keeps its seed and sealed
+// memory in a folder, finds its code among the modules it is handed and
+// then in files, speaks TCP from genesis and the web and Web Push where
+// the root opens them, and serves the root line on a local socket, so the
+// `nervur` command reaches it while it stands.
+//
+//   <dir>/seed        the harbor's seed
+//   <dir>/<place>/    its sealed memory
+//   <dir>/root.sock   the root line while the harbor is served, open to
+//                     this user alone, or in the temporary folder for a
+//                     folder too deep for a socket path
+//
+// One run holds a folder: a terrain refuses a folder another run serves.
+import { createHash } from 'node:crypto';
+import { chmod, rm } from 'node:fs/promises';
+import { connect, createServer, type Server } from 'node:net';
+import { homedir, tmpdir } from 'node:os';
+import { join, resolve } from 'node:path';
+import { pathToFileURL } from 'node:url';
+import type { JsonObject } from '../being/index.ts';
+import { Loader, type Loaded, type Module } from '../contract/index.ts';
+import { FolderCustody, FolderMemory } from '../folder/index.ts';
+import { rootLine, type GroundProbe, type Harbor, type RootRequest } from '../harbor/index.ts';
+import { webGround } from '../http/index.ts';
+import { webPush } from '../line/index.ts';
+import { CryptoEntropy, HeldLoader, PointerTerrain } from '../pointer/index.ts';
+import { TCP_OPENING, tcpFaculty } from '../tcp/index.ts';
+
+export const NODE = 'node';
+
+// Where a harbor of this user lives unless named: $NERVUR_DIR, then
+// ~/.nervur.
+export const harborDir = (env: Record<string, string | undefined> = process.env): string => env.NERVUR_DIR ?? join(homedir(), '.nervur');
+
+// A socket path has a hundred bytes or so on every system, so a folder too
+// deep for one puts its socket in this user's temporary folder, under a
+// name drawn from the folder's own path.
+const SOCKET_PATH = 100;
+export const socketOf = (dir: string): string => {
+  const beside = join(resolve(dir), 'root.sock');
+  if (Buffer.byteLength(beside) <= SOCKET_PATH) return beside;
+  return join(tmpdir(), `nervur-${createHash('sha256').update(resolve(dir)).digest('hex').slice(0, 32)}.sock`);
+};
+
+// Code from a file: a module that exports `module`, `version` and
+// `classes`, found again by its absolute path. A file that cannot be
+// imported, or exports no module, is none.
+export class ImportLoader extends Loader {
+  async load(from: string): Promise<Loaded | null> {
+    const path = resolve(from);
+    let exported: { module?: unknown; version?: unknown; classes?: unknown };
+    try {
+      exported = (await import(pathToFileURL(path).href)) as typeof exported;
+    } catch {
+      return null;
+    }
+    const { module, version, classes } = exported;
+    if (typeof module !== 'string' || typeof version !== 'string' || !Array.isArray(classes)) return null;
+    return { module, version, classes, from: path };
+  }
+}
+
+// The modules a harbor is handed, by name, and then files.
+export class NodeLoader extends ImportLoader {
+  readonly #held: HeldLoader;
+  constructor(modules: readonly Module[] = []) {
+    super();
+    this.#held = new HeldLoader(modules);
+  }
+  override async load(from: string): Promise<Loaded | null> {
+    return (await this.#held.load(from)) ?? super.load(from);
+  }
+}
+
+// One root request over a served harbor's socket, or undefined where none
+// is served.
+export const askServed = (dir: string, request: RootRequest): Promise<JsonObject | undefined> =>
+  new Promise((done, fail) => {
+    const socket = connect(socketOf(dir));
+    let text = '';
+    socket.once('connect', () => socket.write(`${JSON.stringify(request)}\n`));
+    socket.on('data', (chunk: Buffer) => {
+      text += chunk.toString('utf8');
+      const end = text.indexOf('\n');
+      if (end < 0) return;
+      socket.end();
+      done(JSON.parse(text.slice(0, end)) as JsonObject);
+    });
+    socket.once('error', (e: NodeJS.ErrnoException) => (e.code === 'ENOENT' || e.code === 'ECONNREFUSED' ? done(undefined) : fail(e)));
+  });
+
+export type NodeParts = {
+  readonly dir: string;
+  readonly modules?: readonly Module[];
+  // Whether its carriers wake, and whether it serves the root line.
+  readonly wakes?: boolean;
+  readonly serves?: boolean;
+};
+
+export class NodeTerrain extends PointerTerrain {
+  readonly dir: string;
+  readonly serves: boolean;
+  #server: Server | undefined;
+
+  constructor(parts: NodeParts) {
+    const entropy = new CryptoEntropy();
+    super({
+      entropy,
+      loader: new NodeLoader(parts.modules),
+      custody: new FolderCustody(parts.dir, entropy),
+      memory: new FolderMemory(parts.dir),
+      faculties: [tcpFaculty, webGround, webPush],
+      opens: [TCP_OPENING],
+      wakes: parts.wakes ?? true,
+    });
+    this.dir = parts.dir;
+    this.serves = parts.serves ?? true;
+  }
+
+  override async claim(): Promise<void> {
+    if ((await askServed(this.dir, {})) !== undefined) throw new Error(`a harbor is already served from ${this.dir}`);
+  }
+
+  // The root line on the socket. A socket file nobody answers on is a
+  // stale one, and is replaced.
+  override async stand(harbor: Harbor): Promise<void> {
+    if (!this.serves) return;
+    const root = socketOf(this.dir);
+    await rm(root, { force: true });
+    const server = createServer((socket) => {
+      let text = '';
+      socket.on('data', (chunk: Buffer) => {
+        text += chunk.toString('utf8');
+        for (let end = text.indexOf('\n'); end >= 0; end = text.indexOf('\n')) {
+          const line = text.slice(0, end);
+          text = text.slice(end + 1);
+          let value: unknown;
+          try {
+            value = JSON.parse(line);
+          } catch {
+            value = undefined;
+          }
+          void rootLine(harbor, value)
+            .catch(() => ({ error: 'the harbor threw' }))
+            .then((answer) => socket.write(`${JSON.stringify(answer)}\n`));
+        }
+      });
+      socket.on('error', () => socket.destroy());
+    });
+    await new Promise<void>((done) => server.listen(root, done));
+    await chmod(root, 0o600);
+    this.#server = server;
+  }
+
+  override async release(): Promise<void> {
+    const server = this.#server;
+    if (!server) return;
+    this.#server = undefined;
+    await new Promise((done) => server.close(done));
+    await rm(socketOf(this.dir), { force: true });
+  }
+}
+
+// Node, and the engines that answer as Node does.
+export const nodeGround: GroundProbe = {
+  name: NODE,
+  fits: () => typeof process !== 'undefined' && typeof process.versions?.node === 'string',
+  terrain: ({ modules, where }) => new NodeTerrain({ dir: where ?? harborDir(), ...(modules ? { modules } : {}) }),
+};

package/src/node.ts

@@ -0,0 +1,9 @@
+// SPDX-License-Identifier: Apache-2.0
+// `nervur` as Node reads it: the main entry, with the Node ground added, so
+// `Harbor.open()` keeps a harbor in a folder and serves its root line.
+import { addGround } from './harbor/index.ts';
+import { nodeGround } from './node/index.ts';
+
+export * from './index.ts';
+
+addGround(nodeGround);

package/src/pointer/bodies.ts

@@ -1,7 +1,7 @@
 // SPDX-License-Identifier: Apache-2.0
 // The pointer terrain's bodies: each contract fulfilled in one process,
 // with nothing beyond JavaScript.
-import { Clock, Custody, Entropy, Memory, type Rows } from '../contract/index.ts';
+import { Clock, Custody, Entropy, Loader, Memory, type Loaded, type Module } from '../contract/index.ts';
 
 export class CryptoEntropy extends Entropy {
   draw(length: number): Uint8Array {
@@ -20,28 +20,57 @@ export class SystemClock extends Clock {
   }
 }
 
-// Seeds drawn once per name and held by this object.
+// The harbor's seed, drawn once and held by this object.
 export class HeldCustody extends Custody {
-  readonly #entropy: Entropy;
-  readonly #seeds = new Map<string, Uint8Array>();
+  readonly #seed: Uint8Array;
   constructor(entropy: Entropy) {
     super();
-    this.#entropy = entropy;
+    this.#seed = entropy.draw(32);
   }
-  seed(name: string): Promise<Uint8Array> {
-    let seed = this.#seeds.get(name);
-    if (!seed) this.#seeds.set(name, (seed = this.#entropy.draw(32)));
-    return Promise.resolve(seed);
+  seed(): Promise<Uint8Array> {
+    return Promise.resolve(this.#seed.slice());
   }
 }
 
-// Rows that live as long as this object: opening a name again gives the
-// same rows, which is what a restart in one process finds.
+// Modules handed to this object, found by the name each declares.
+export class HeldLoader extends Loader {
+  readonly #modules = new Map<string, Module>();
+  constructor(modules: readonly Module[] = []) {
+    super();
+    for (const m of modules) this.#modules.set(m.module, m);
+  }
+  load(from: string): Promise<Loaded | null> {
+    const m = this.#modules.get(from);
+    return Promise.resolve(m ? { module: m.module, version: m.version, classes: m.classes, from } : null);
+  }
+}
+
+// Entries that live as long as this object, copied in and out, which is
+// what a restart in one process finds.
 export class VolatileMemory extends Memory {
-  readonly #wards = new Map<string, Rows>();
-  open(name: string): Promise<Rows> {
-    let rows = this.#wards.get(name);
-    if (!rows) this.#wards.set(name, (rows = { rows: {}, told: () => {}, kept: () => Promise.resolve(true) }));
-    return Promise.resolve(rows);
+  readonly #places = new Map<string, Map<string, Uint8Array>>();
+  read(place: string): Promise<Map<string, Uint8Array>> {
+    const entries = this.#places.get(place) ?? new Map<string, Uint8Array>();
+    return Promise.resolve(new Map([...entries].map(([name, bytes]) => [name, bytes.slice()])));
+  }
+  // One object holds it, so a keep is whole by the run of one turn.
+  write(place: string, entries: ReadonlyMap<string, Uint8Array | null>): Promise<void> {
+    let kept = this.#places.get(place);
+    if (!kept) this.#places.set(place, (kept = new Map()));
+    for (const [name, bytes] of entries) {
+      if (bytes === null) kept.delete(name);
+      else kept.set(name, bytes.slice());
+    }
+    if (kept.size === 0) this.#places.delete(place);
+    return Promise.resolve();
+  }
+
+  places(): Promise<string[]> {
+    return Promise.resolve([...this.#places.keys()]);
+  }
+
+  forget(place: string): Promise<void> {
+    this.#places.delete(place);
+    return Promise.resolve();
   }
 }

package/src/pointer/index.ts

@@ -1,4 +1,4 @@
 // SPDX-License-Identifier: Apache-2.0
 // The pointer dock: a whole world with `nervur` alone.
-export { CryptoEntropy, HeldCustody, SystemClock, VolatileMemory } from './bodies.ts';
+export { CryptoEntropy, HeldCustody, HeldLoader, SystemClock, VolatileMemory } from './bodies.ts';
 export { NoCarrier, PointerCarrier, PointerTerrain, World, type PointerParts } from './world.ts';