@nervur-org/dock 0.3.0

package/harbor/edge/given.ts

@@ -0,0 +1,106 @@
+// SPDX-License-Identifier: Apache-2.0
+// What a side mounted at the edge is given. `Given` is the one shape: the
+// code a page runs, the design a world wears, the public origins, the apps
+// table and the bell key. On the daemon the same list is what `cli/daemon.ts`
+// reads off a disk and out of `routes.json`; here it has two provenances,
+// and the split is what the value is, not an accident of this file.
+//
+// `Deployed` is the half the deploy carries: the tab's bundle, the service
+// worker's, and whatever being classes the deployment adds. They change only
+// when something is built, so they are text modules the `wrangler.toml`
+// names and the worker module holds them from its first line.
+//
+// `Settings` is the half that is worn and configured while the worker runs:
+// the origins the proxy serves, the apps whose links this world's hostname
+// opens, and the public half of the doorbell key. It is one row in the
+// object's own storage, put there by the root's door, because a root
+// reconfigures a box without redeploying it. The design a world wears is
+// rows beside it, one per file, reached through `Folder` like every other
+// terrain's.
+import type { BeingClass } from '@nervur-org/nervur';
+import { GRANTS } from '../../dock/grants.ts';
+import { TIMER } from '../../dock/index.ts';
+import type { Apps, Folder } from '../../human/web.ts';
+import type { Routes } from '../../mcp/route.ts';
+
+// What a worker lends the beings of the wards it holds, by name to the class
+// that stands for it. The box's state has one home on every terrain, the box
+// ward's partition, so the edge stands that ward like every other terrain;
+// what differs is this list, and a faculty the platform has no answer for is
+// not lent at all rather than lent and hollow.
+//
+// `grants` and `timer` are lent, and they are the whole of it. A bearer to an
+// identity in a world is a record in her cells and nothing else, so the
+// grants are the same code here as on a disk and the routes that honour a
+// bearer, `api.` and `mcp.`, work the moment she stands. The timer is the
+// same class too, with the one method that knows a terrain replaced: she arms
+// the object's own storage alarm, which is the clock here, so a home on this
+// terrain wakes for its schedules with nobody asking. `Alarm` in
+// `edge/alarm.ts` is that subclass.
+//
+// The three others every box ships are not lent here, each for its own
+// reason. `location` and `notifications` are a place and a screen, and a
+// worker is at neither: it runs wherever the platform put it and no human is
+// looking at it. `push` rings under this world's own web origin, and a worker
+// learns its origin from the request it is answering and not at boot, so a
+// ring signed at the moment the faculty stood would be signed for nowhere.
+//
+// There is no process on the other side of a worker either, so `local`,
+// `dialers` and `agents`, which the daemon adds, name nothing here: no
+// socket a process was seen on, no line this box holds open, and no command
+// to run an agent in.
+export const LENT: Record<string, string> = { [GRANTS]: 'Grants', [TIMER]: 'Alarm' };
+
+// The ceiling on one row in this object's storage, key and value together,
+// in bytes. The platform publishes it for a SQLite-backed Durable Object,
+// which is what `wrangler.toml` declares this class to be, and past it the
+// storage refuses the write. It is written here once, beside the rest of
+// what this terrain is, because a number a store carries in its own body is
+// a number nobody finds when the platform moves it.
+//
+// A being is one row, so this is the ceiling on one being's cells and her
+// bind table. The store measures the JSON it is about to write and refuses
+// over it rather than handing the platform a value it will refuse anyway, so
+// the refusal is the same on the day the platform's own message changes and
+// the same in a suite that never reaches a real object.
+export const ROW_CEILING = 2_000_000;
+
+// The tab's bundle and the service worker's, as code. Built once by whoever
+// built this package, never by a route and never here.
+export type Code = { tab: string; worker: string };
+
+// The rows. Every field is absent until a root writes it, and a side asked
+// with none of them serves what a box with no configuration can: pages on
+// the worker's own origin, no apps, no doorbell.
+export type Settings = {
+  // the public faces of the four routes, as the proxy serves them, the same
+  // shape `routes.json` holds on a disk
+  routes?: Routes;
+  // the apps this world's links open, or none
+  apps?: Apps | null;
+  // the public half of this world's doorbell key. Without it no service
+  // worker is served and no page registers one.
+  bell?: string | null;
+};
+
+// The row, read and written whole: three small fields that a root sets
+// together and a side reads at every request.
+export type SettingsStore = {
+  load(): Promise<Settings>;
+  save(settings: Settings): Promise<void>;
+};
+
+// What the deploy carries, which the worker module is constructed with.
+// A deployment that names no bundles serves no pages: the web side is not
+// mounted at all, because a page carrying no tab code is a page that loads
+// and then does nothing. That is what the conformance exercise inside the
+// platform is, and never a deploy.
+export type Deployed = {
+  code?: Code;
+  // being classes beyond the built-ins, this deployment's own
+  classes?: Record<string, BeingClass>;
+};
+
+// The whole of it, as a side is handed it: the deploy's half, the rows, and
+// the folder those rows make.
+export type Given = Deployed & { settings: Settings; folder: Folder };

package/harbor/edge/platform.d.ts

@@ -0,0 +1,39 @@
+// SPDX-License-Identifier: Apache-2.0
+// The edge platform, as much of it as the harbor touches and no more. The
+// vendor's own type package declares every global a worker has, and it
+// collides with the DOM library this tree compiles against; these few
+// lines are what the edge harbor and worker actually call.
+// The rows: everything the object keeps under a key. Whatever answers these
+// five is a place to keep rows, which is why what is kept in storage is
+// written against this and not against the object.
+export type Rows = {
+  get<T = unknown>(key: string): Promise<T | undefined>;
+  get<T = unknown>(keys: string[]): Promise<Map<string, T>>;
+  put(key: string, value: unknown): Promise<void>;
+  delete(key: string): Promise<boolean>;
+  list<T = unknown>(options?: { prefix?: string }): Promise<Map<string, T>>;
+};
+// The object's storage: its rows and its clock. One alarm per object,
+// replaced by the next set and gone when it is deleted, and the object's
+// `alarm` handler runs when it goes off, with no request behind it.
+export type Storage = Rows & {
+  setAlarm(at: number | Date): Promise<void>;
+  getAlarm(): Promise<number | null>;
+  deleteAlarm(): Promise<void>;
+};
+export type State = { id: { toString(): string; name?: string }; storage: Storage };
+export type Stub = { fetch(input: string | Request, init?: RequestInit): Promise<Response> };
+export type Namespace = { idFromName(name: string): unknown; get(id: unknown): Stub };
+export type Env = { HARBOR: Namespace; QUO_SEED_KEY?: string; QUO_ROOT?: string; QUO_EXERCISE?: string };
+// The server end of a WebSocketPair: the standard surface plus accept.
+export type ServerSocket = { accept(): void; readyState: number; binaryType: string; send(data: string | Uint8Array): void; close(): void; addEventListener(type: string, fn: (e: never) => void): void };
+declare global {
+  // eslint-disable-next-line no-var
+  var WebSocketPair: new () => { 0: ServerSocket; 1: ServerSocket };
+  interface ResponseInit {
+    webSocket?: unknown;
+  }
+  interface Response {
+    readonly webSocket?: unknown;
+  }
+}

package/harbor/edge/storage.ts

@@ -0,0 +1,179 @@
+// SPDX-License-Identifier: Apache-2.0
+// The store as Durable Object storage: one object per harbor, its storage
+// holding one row per ward under `ward:<name>`, seed and record, one row per
+// row of its partition under `row:<name> <row>`, and one row per hint under
+// `hint:<pk>`. A being is a row of her own because a being's cells are the
+// one part of a partition that grows without limit, and a ward kept as one
+// value would write every being in it down whenever any one was asked.
+//
+// The seed is kept sealed under a
+// key from the platform's secrets, `QUO_SEED_KEY`, with the seal in
+// `../seal.ts`, so the storage holds ciphertext and the secret store holds
+// the one key, which is what the harbor document's table says the edge
+// does. Values cross as JSON, as they do into a file, because the ward
+// hands the partition out through a guard that structured clone refuses.
+// The same storage answers the mcp route's dance, under `oauth`, the box's
+// own settings, under `settings`, and the design a world wears, one row per
+// file under `design:<file>`, because the object is the whole of what this
+// terrain has to keep anything in.
+import { fromRows, rowsIn, rowsOf, type Kept, type Store, type WardRecord } from '@nervur-org/nervur/harbor';
+import { seal, open } from '../seal.ts';
+import { emptyDance, type Dance, type Store as DanceStore } from '../../mcp/oauth.ts';
+import type { Folder } from '../../human/web.ts';
+import { ROW_CEILING, type Settings, type SettingsStore } from './given.ts';
+import type { Rows, Storage } from './platform.d.ts';
+
+// The box's settings: the origins, the apps table and the bell key, one row
+// read whole and written whole. Nothing of Quo's is in it, so nothing here
+// is sealed, and a box a root has never configured reads an empty one.
+export function settingsInStorage(storage: Rows, prefix = ''): SettingsStore {
+  const key = `${prefix}settings`;
+  return {
+    load: async () => (await storage.get<Settings>(key)) ?? {},
+    save: (settings: Settings) => storage.put(key, settings),
+  };
+}
+
+// The design a world wears and the world's own code for the tab, as rows:
+// what a disk answers out of `design/` and `tab/index.js`, answered out of
+// storage instead. A row is text, because a stylesheet is text and so is a
+// bundle; a file the root has not put there answers nothing and the route
+// declines the path.
+export const DESIGN_ROW = 'design:';
+export const BEINGS_ROW = 'beings';
+
+export function folderInStorage(storage: Rows, prefix = ''): Folder {
+  const design = (file: string) => `${prefix}${DESIGN_ROW}${file}`;
+  const held = (file: string) => storage.get<string>(design(file)).then((v) => v ?? null);
+  return {
+    wearing: async () => ((await held('tokens.css')) === null ? { tokens: false, fonts: false } : { tokens: true, fonts: (await held('fonts.css')) !== null }),
+    design: (file) => held(file),
+    serving: async () => (await storage.get<string>(`${prefix}${BEINGS_ROW}`)) !== undefined,
+    beings: async () => (await storage.get<string>(`${prefix}${BEINGS_ROW}`)) ?? null,
+  };
+}
+
+// The writing half of that folder, which is the root's door and nothing
+// else: a file put there, a file taken away with null, and the names now
+// held so that a root sees what it wrote.
+export function wearInStorage(storage: Rows, prefix = '') {
+  const head = `${prefix}${DESIGN_ROW}`;
+  return {
+    put: async (file: string, text: string | null): Promise<void> => {
+      if (text === null) await storage.delete(head + file);
+      else await storage.put(head + file, text);
+    },
+    worn: async (): Promise<string[]> => [...(await storage.list({ prefix: head })).keys()].map((k) => k.slice(head.length)),
+  };
+}
+
+// The mcp route's dance, kept in the same object's storage under one key.
+// It is one value and not a row apiece: clients, pending requests and codes
+// all die in minutes, and the whole of it is smaller than one ward's seed.
+// Nothing of Quo's is in it, so nothing here is sealed.
+export function danceInStorage(storage: Rows, prefix = ''): DanceStore {
+  const key = `${prefix}oauth`;
+  return {
+    load: async () => ({ ...emptyDance(), ...((await storage.get<Partial<Dance>>(key)) ?? {}) }),
+    save: (dance: Dance) => storage.put(key, dance),
+  };
+}
+
+type Row = { seed: string; record: WardRecord };
+
+// `prefix` keeps more than one harbor apart in one object's storage: the
+// exercise does that, a deployment never does.
+// `ceiling` is the platform's, and is a parameter for the one suite that
+// has to see a row refused: a row of the real size crossing a real door
+// costs more than the fault it proves, and the ceiling a deployment runs
+// under is the platform's number and never an argument.
+export class DurableStorage implements Store {
+  readonly storage: Storage;
+  readonly key: CryptoKey;
+  readonly prefix: string;
+  readonly ceiling: number;
+  constructor(storage: Storage, key: CryptoKey, prefix = '', ceiling = ROW_CEILING) {
+    this.storage = storage;
+    this.key = key;
+    this.prefix = prefix;
+    this.ceiling = ceiling;
+  }
+  #k(kind: 'ward' | 'hint' | 'row', name: string) {
+    return `${this.prefix}${kind}:${name}`;
+  }
+  // A ward's rows sort together under one prefix, and nothing else falls
+  // between them: no name carries the separator.
+  #rows(name: string) {
+    return this.#k('row', `${name} `);
+  }
+
+  async list(): Promise<string[]> {
+    const head = this.#k('ward', '');
+    return [...(await this.storage.list({ prefix: head })).keys()].map((k) => k.slice(head.length));
+  }
+  async load(name: string): Promise<Kept | undefined> {
+    const row = await this.storage.get<Row>(this.#k('ward', name));
+    if (!row) return undefined;
+    const head = this.#rows(name);
+    const kept = [...(await this.storage.list<Record<string, unknown>>({ prefix: head }))].map(([k, v]) => [k.slice(head.length), v] as const);
+    return { seed: await open(this.key, row.seed), partition: fromRows(Object.fromEntries(kept)), record: row.record };
+  }
+  async put(name: string, kept: Kept): Promise<void> {
+    if ((await this.storage.get(this.#k('ward', name))) !== undefined) throw new Error(`ward ${name} already exists here`);
+    await this.storage.put(this.#k('ward', name), { seed: await seal(this.key, kept.seed), record: kept.record } satisfies Row);
+    await this.#keep(name, kept.partition, rowsIn(kept.partition));
+  }
+  async save(name: string, partition: Record<string, unknown>, rows: readonly string[]): Promise<void> {
+    if ((await this.storage.get(this.#k('ward', name))) === undefined) return; // a name not kept is nothing
+    await this.#keep(name, partition, rows);
+  }
+  // The rows named, written or deleted. A row whose being has left comes back
+  // undefined and her value goes with her.
+  //
+  // A row past the object's ceiling is refused here, before the platform is
+  // asked. The platform refuses it too, and the two refusals must be the
+  // same one: a store that let the platform decide would keep a row on the
+  // day the limit moved and refuse it the day after, with nothing in this
+  // tree saying so. The harbor turns the throw into the answer of the ask
+  // that wrote the row, and the being is stood back at what is kept.
+  //
+  // Every row is measured before any is written, so a save that is refused
+  // writes nothing at all. A store that wrote half a save and threw would
+  // leave one being moved and her counterpart not, and the harbor standing
+  // the ward back at what is kept would find a torn state to stand at: a
+  // caller's numbers rolled back and the door's mark not, which is a
+  // relation that can never speak again.
+  async #keep(name: string, partition: Record<string, unknown>, rows: readonly string[]): Promise<void> {
+    const head = this.#rows(name);
+    const write = rowsOf(partition, rows).map(([row, value]) => {
+      const key = head + row;
+      if (value === undefined) return { key, value };
+      const size = new TextEncoder().encode(JSON.stringify(value)).length + new TextEncoder().encode(key).length;
+      if (size > this.ceiling) throw new Error(`the row ${key} is ${size} bytes, past this object's ceiling of ${this.ceiling}`);
+      return { key, value };
+    });
+    for (const { key, value } of write) {
+      if (value === undefined) await this.storage.delete(key);
+      else await this.storage.put(key, value);
+    }
+  }
+  async record(name: string, record: WardRecord): Promise<void> {
+    const row = await this.storage.get<Row>(this.#k('ward', name));
+    if (row) await this.storage.put(this.#k('ward', name), { ...row, record } satisfies Row);
+  }
+  async take(name: string): Promise<Kept | undefined> {
+    const kept = await this.load(name);
+    if (!kept) return undefined;
+    const head = this.#rows(name);
+    for (const key of (await this.storage.list({ prefix: head })).keys()) await this.storage.delete(key); // her rows go with her, or the next put reads them
+    await this.storage.delete(this.#k('ward', name));
+    return kept;
+  }
+  async hints(): Promise<Record<string, string>> {
+    const head = this.#k('hint', '');
+    return Object.fromEntries([...(await this.storage.list<string>({ prefix: head }))].map(([k, v]) => [k.slice(head.length), v]));
+  }
+  async hint(pk: string, url: string): Promise<void> {
+    await this.storage.put(this.#k('hint', pk), url);
+  }
+}

package/harbor/edge/text.d.ts

@@ -0,0 +1,15 @@
+// SPDX-License-Identifier: Apache-2.0
+// A bundle, imported as text. The platform's build carries a file named by a
+// `type = "Text"` rule in the `wrangler.toml` into the worker as a string,
+// which is how a built artefact of a deploy reaches a side mounted there
+// without any of it being a row a ward keeps. This file says what that
+// import is worth to the typechecker, and nothing else in the tree imports
+// one: the daemon reads the same file off its disk instead.
+//
+// It declares an ambient module, so it holds no import and no export of its
+// own; a file with either would be a module and the declaration would not be
+// ambient.
+declare module '*.bundle.txt' {
+  const text: string;
+  export default text;
+}

package/harbor/edge/worker.ts

@@ -0,0 +1,70 @@
+// SPDX-License-Identifier: Apache-2.0
+// The worker: the edge harbor deployed. One Durable Object class, `Quo`,
+// one instance per harbor name, and the worker routes by the first path
+// segment: `/h/<name>/...` goes to that harbor. A world's quo. route on the
+// edge is `<origin>/h/<name>/quo`, and its health `<origin>/h/<name>/health`.
+// `wrangler.toml` beside this file names the class and the secrets.
+//
+// One thing lives here for the terrain test alone: with `QUO_EXERCISE` set,
+// which no deployment sets, `/exercise` runs the library's conformance
+// suite inside the platform against two harbors in this one object, over
+// two prefixed views of its storage, reaching each other by request
+// through the worker under `/x/<sub>/quo`. One object cannot touch
+// another's storage, the platform says so, and so the two harbors share an
+// object the way two tabs share a page.
+import { EdgeHarbor } from './edge.ts';
+import { exercise } from './exercise.ts';
+import type { Deployed } from './given.ts';
+import type { State, Env } from './platform.d.ts';
+import tab from '../../human/tab.bundle.txt';
+import serviceWorker from '../../human/worker.bundle.txt';
+
+// What the deploy carries, from this module's first line: the tab's bundle
+// and the service worker's, as text modules the `wrangler.toml` names. They
+// are built artefacts and never rows, so they arrive with the code and not
+// out of the object's storage. Everything a root configures while the worker
+// runs is a row, and `given.ts` holds the whole shape.
+export const DEPLOYED: Deployed = { code: { tab, worker: serviceWorker } };
+
+export class Quo {
+  readonly state: State;
+  readonly env: Env;
+  #harbor: Promise<EdgeHarbor> | undefined;
+  constructor(state: State, env: Env) {
+    this.state = state;
+    this.env = env;
+  }
+  harbor(): Promise<EdgeHarbor> {
+    return (this.#harbor ??= EdgeHarbor.open(this.state, this.env, DEPLOYED));
+  }
+  // The platform's one way of waking an object with nobody asking. The
+  // harbor opens as it does for a request, every ward boots from storage,
+  // and the box's timer runs her round: a home here with a sweep at three in
+  // the morning wakes once a night, and no request is made to cause it.
+  async alarm(): Promise<void> {
+    const harbor = await this.harbor();
+    await harbor.ready();
+    await harbor.rang();
+  }
+
+  async fetch(request: Request): Promise<Response> {
+    const url = new URL(request.url);
+    const m = /^\/h\/([\w.-]+)(\/.*)?$/.exec(url.pathname);
+    if (!m) return new Response(JSON.stringify({ error: 'no such route' }), { status: 404, headers: { 'content-type': 'application/json' } });
+    const path = m[2] ?? '/';
+    // Where this harbor answers, as the world outside sees it: the routes a
+    // page hands its tab are these unless a root has named public ones.
+    const base = `${url.origin}/h/${m[1]}`;
+    if (this.env.QUO_EXERCISE && (path === '/exercise' || path.startsWith('/x/'))) return exercise(request, base, path, this.state, this.env);
+    return (await this.harbor()).fetch(request, path, base);
+  }
+}
+
+export default {
+  async fetch(request: Request, env: Env): Promise<Response> {
+    const url = new URL(request.url);
+    const m = /^\/h\/([\w.-]+)(\/.*)?$/.exec(url.pathname);
+    if (!m) return new Response(JSON.stringify({ error: 'a harbor is /h/<name>/...' }), { status: 404, headers: { 'content-type': 'application/json' } });
+    return env.HARBOR.get(env.HARBOR.idFromName(m[1])).fetch(request);
+  },
+};

package/harbor/edge/wrangler.toml

@@ -0,0 +1,30 @@
+# The edge harbor as a worker. Deploy from `dock/` with
+#   npx wrangler deploy --config harbor/edge/wrangler.toml
+# and set the two secrets once, never in this file:
+#   npx wrangler secret put QUO_SEED_KEY --config harbor/edge/wrangler.toml   32 bytes as hex
+#   npx wrangler secret put QUO_ROOT     --config harbor/edge/wrangler.toml   the root's bearer
+name = "quo-edge"
+main = "worker.ts"
+compatibility_date = "2026-09-01"
+# A deployed worker answers on the account's workers.dev subdomain; a custom
+# domain wants a token with the zone's Workers Routes permission, which the
+# account's token does not hold. A world's quo. route on it is
+# <origin>/h/main/quo.
+workers_dev = true
+
+# The bundles a page runs, carried into the worker as strings. They are built
+# artefacts of a deploy, so the deploy carries them and no row keeps them; the
+# dock's build emits them beside `human/`, and this rule is what makes the
+# worker's import of one a string rather than a module.
+[[rules]]
+type = "Text"
+globs = ["**/*.bundle.txt"]
+fallthrough = false
+
+[[durable_objects.bindings]]
+name = "HARBOR"
+class_name = "Quo"
+
+[[migrations]]
+tag = "v1"
+new_sqlite_classes = ["Quo"]

package/harbor/files.ts

@@ -0,0 +1,221 @@
+// SPDX-License-Identifier: Apache-2.0
+// The store as a folder on disk, one folder per ward, in one of two forms.
+//
+// Plain, when the store has no key, what the droplets run:
+//
+//   <dir>/wards/<name>/seed             32 bytes, hex, mode 0600
+//   <dir>/wards/<name>/rows/head.json   the partition's head
+//   <dir>/wards/<name>/rows/b-<hex>.json  one being, her key as hex utf8
+//   <dir>/wards/<name>/ward.json        the ward record
+//
+// A being is a file of her own because a being's cells are the one part of a
+// partition that grows without limit, and a ward that wrote one file would
+// write every being in it down whenever any one of them was asked. Her key is
+// a being's own word and can be anything a string can be, so the file is
+// named for its bytes and never for the key itself.
+//
+// Sealed, when the store holds a key, what a device's daemon runs with the
+// key from its Keychain:
+//
+//   <dir>/wards/<name>/ward.sealed      seed, partition and record as one
+//                                       JSON, sealed under the key, hex
+//
+// and in both:
+//
+//   <dir>/reach.json                    the directory's hints
+//
+// A ward is whole in either form, and a store that meets the other form
+// refuses it by name: a daemon started without its key, or with one against
+// a plain folder, fails loudly instead of booting on what it cannot read.
+// Sealing a plain folder is a deliberate command, never a boot's doing.
+// Every write of a ward goes through a temp file and a rename, and writes
+// are queued per ward so two calls never race on one file.
+import { mkdir, readFile, writeFile, rename, readdir, rm, chmod } from 'node:fs/promises';
+import { existsSync } from 'node:fs';
+import { join } from 'node:path';
+import { arithmetic } from '@nervur-org/nervur/ward';
+import { HEAD, fromRows, rowsIn, rowsOf, type Kept, type Store, type WardRecord } from '@nervur-org/nervur/harbor';
+import { sealKey, seal, open } from './seal.ts';
+
+const { hex, unhex } = arithmetic;
+type Blob = { seed: string; partition: Record<string, unknown>; record: WardRecord };
+
+// A row's file. The head has a name of its own so that the empty key it goes
+// by never becomes an empty file name; a being's file is named for the digest
+// of her key, and her key is written inside it.
+//
+// The digest, and not the key itself in some spelling: a being's key is her
+// owner's own word and can be as long as a string can be, and a ward's own
+// key is a hundred and twenty-eight characters before anything is added to
+// it. Every encoding of a key grows it, and a file system stops at a length.
+// A digest is the same size whatever it is given.
+const utf8 = new TextEncoder();
+type Kind = { row: string; value: Record<string, unknown> };
+const fileOf = async (row: string): Promise<string> => (row === HEAD ? 'head.json' : `b-${hex(await arithmetic.sha256(utf8.encode(row)))}.json`);
+
+export class Files implements Store {
+  readonly dir: string;
+  readonly #key?: Promise<CryptoKey>;
+  readonly #queues = new Map<string, Promise<void>>();
+  constructor(dir: string, key?: string) {
+    this.dir = dir;
+    if (key) this.#key = sealKey(key);
+  }
+  #ward(name: string) {
+    return join(this.dir, 'wards', name);
+  }
+  get sealed(): boolean {
+    return this.#key !== undefined;
+  }
+  // The form a folder holds, checked against the form this store speaks.
+  #form(name: string): 'plain' | 'sealed' | undefined {
+    const wd = this.#ward(name);
+    const form = existsSync(join(wd, 'ward.sealed')) ? 'sealed' : existsSync(join(wd, 'seed')) ? 'plain' : undefined;
+    if (form === 'sealed' && !this.sealed) throw new Error(`ward ${name} in ${this.dir} is sealed and this harbor has no key`);
+    if (form === 'plain' && this.sealed) throw new Error(`ward ${name} in ${this.dir} is plain and this harbor holds a key`);
+    return form;
+  }
+  // One write at a time per ward, through a temp file and a rename.
+  #write(name: string, file: string, body: string): Promise<void> {
+    const next = (this.#queues.get(name) ?? Promise.resolve()).then(async () => {
+      const tmp = join(this.#ward(name), `${file}.tmp`);
+      await writeFile(tmp, body, { mode: 0o600 });
+      await rename(tmp, join(this.#ward(name), file));
+    });
+    this.#queues.set(name, next.catch(() => {}));
+    return next;
+  }
+  async #read(name: string): Promise<Blob> {
+    const blob = (await readFile(join(this.#ward(name), 'ward.sealed'), 'utf8')).trim();
+    return JSON.parse(new TextDecoder().decode(await open(await this.#key!, blob))) as Blob;
+  }
+  // A sealed ward is rewritten whole, so the read sits inside the queue
+  // with the write: two changes to one ward never lose each other's part.
+  #keep(name: string, change: (b: Blob | undefined) => Blob): Promise<void> {
+    const next = (this.#queues.get(name) ?? Promise.resolve()).then(async () => {
+      const wd = this.#ward(name);
+      const blob = change(existsSync(join(wd, 'ward.sealed')) ? await this.#read(name) : undefined);
+      const sealed = await seal(await this.#key!, new TextEncoder().encode(JSON.stringify(blob)));
+      await writeFile(join(wd, 'ward.sealed.tmp'), sealed + '\n', { mode: 0o600 });
+      await rename(join(wd, 'ward.sealed.tmp'), join(wd, 'ward.sealed'));
+    });
+    this.#queues.set(name, next.catch(() => {}));
+    return next;
+  }
+
+  async list(): Promise<string[]> {
+    const wards = join(this.dir, 'wards');
+    return existsSync(wards) ? (await readdir(wards)).filter((n) => existsSync(join(wards, n, 'seed')) || existsSync(join(wards, n, 'ward.sealed'))) : [];
+  }
+
+  async load(name: string): Promise<Kept | undefined> {
+    const form = this.#form(name);
+    if (!form) return undefined;
+    if (form === 'sealed') {
+      const b = await this.#read(name);
+      return { seed: unhex(b.seed), partition: b.partition, record: b.record };
+    }
+    const wd = this.#ward(name);
+    return {
+      seed: unhex((await readFile(join(wd, 'seed'), 'utf8')).trim()),
+      partition: fromRows(await this.#rows(name)),
+      record: JSON.parse(await readFile(join(wd, 'ward.json'), 'utf8')) as WardRecord,
+    };
+  }
+
+  // Every row a ward's folder holds. A file the naming does not recognise is
+  // not a row and is left where it is: a folder is a place a person looks.
+  async #rows(name: string): Promise<Record<string, Record<string, unknown>>> {
+    const dir = join(this.#ward(name), 'rows');
+    if (!existsSync(dir)) return {};
+    const out: Record<string, Record<string, unknown>> = {};
+    for (const file of await readdir(dir)) {
+      if (file === 'head.json') out[HEAD] = JSON.parse(await readFile(join(dir, file), 'utf8')) as Record<string, unknown>;
+      else if (/^b-[0-9a-f]{64}\.json$/.test(file)) {
+        const kept = JSON.parse(await readFile(join(dir, file), 'utf8')) as Kind;
+        out[kept.row] = kept.value;
+      }
+      // anything else is not a row and is left where it is: a folder is a
+      // place a person looks
+    }
+    return out;
+  }
+
+  // The rows named, written or removed. A row whose being has left comes back
+  // undefined and her file goes with her.
+  //
+  // The whole of it is one job in the ward's line, the folder included, so a
+  // save cannot lay a file down inside a ward that a take is removing: `take`
+  // waits for this line before it removes anything, and a mkdir outside it
+  // would build the folder again underneath.
+  #keepRows(name: string, partition: Record<string, unknown>, rows: readonly string[]): Promise<void> {
+    const written = rowsOf(partition, rows);
+    const next = (this.#queues.get(name) ?? Promise.resolve()).then(async () => {
+      // Read here and not before: a ward taken while this waited its turn is
+      // a ward this must not write, and a mkdir would build its folder again
+      // under whoever removed it. A name not kept is nothing, and that is as
+      // true at the head of the line as it was at the back of it.
+      if (!existsSync(this.#ward(name))) return;
+      const dir = join(this.#ward(name), 'rows');
+      await mkdir(dir, { recursive: true, mode: 0o700 });
+      for (const [row, value] of written) {
+        const file = join(dir, await fileOf(row));
+        if (value === undefined) {
+          await rm(file, { force: true });
+          continue;
+        }
+        const tmp = `${file}.tmp`;
+        await writeFile(tmp, JSON.stringify(row === HEAD ? value : ({ row, value } satisfies Kind)) + '\n', { mode: 0o600 });
+        await rename(tmp, file);
+      }
+    });
+    this.#queues.set(name, next.catch(() => {}));
+    return next;
+  }
+
+  async put(name: string, kept: Kept): Promise<void> {
+    if (this.#form(name)) throw new Error(`ward ${name} already exists in ${this.dir}`);
+    const wd = this.#ward(name);
+    await mkdir(wd, { recursive: true, mode: 0o700 });
+    if (this.sealed) return this.#keep(name, () => ({ seed: hex(kept.seed), partition: kept.partition, record: kept.record }));
+    await writeFile(join(wd, 'seed'), hex(kept.seed), { mode: 0o600 });
+    await chmod(join(wd, 'seed'), 0o600);
+    await writeFile(join(wd, 'ward.json'), JSON.stringify(kept.record, null, 2) + '\n', { mode: 0o600 });
+    await this.#keepRows(name, kept.partition, rowsIn(kept.partition));
+  }
+
+  // A sealed ward is one sealed value and is written whole; a plain one is
+  // rows, and only the rows the ward named are touched.
+  async save(name: string, partition: Record<string, unknown>, rows: readonly string[]): Promise<void> {
+    const form = this.#form(name);
+    if (!form) return; // a name not kept is nothing
+    if (form === 'sealed') return this.#keep(name, (b) => ({ ...b!, partition }));
+    return this.#keepRows(name, partition, rows);
+  }
+
+  async record(name: string, record: WardRecord): Promise<void> {
+    const form = this.#form(name);
+    if (!form) return;
+    if (form === 'sealed') return this.#keep(name, (b) => ({ ...b!, record }));
+    return this.#write(name, 'ward.json', JSON.stringify(record, null, 2) + '\n');
+  }
+
+  async take(name: string): Promise<Kept | undefined> {
+    const kept = await this.load(name);
+    if (!kept) return undefined;
+    await this.#queues.get(name);
+    await rm(this.#ward(name), { recursive: true, force: true });
+    return kept;
+  }
+
+  async hints(): Promise<Record<string, string>> {
+    const p = join(this.dir, 'reach.json');
+    return existsSync(p) ? (JSON.parse(await readFile(p, 'utf8')) as Record<string, string>) : {};
+  }
+
+  async hint(pk: string, url: string): Promise<void> {
+    const all = await this.hints();
+    all[pk] = url;
+    await writeFile(join(this.dir, 'reach.json'), JSON.stringify(all, null, 2) + '\n', { mode: 0o600 });
+  }
+}