@nervur-org/dock 0.3.0

package/dist/harbor/edge/given.js

@@ -0,0 +1,42 @@
+import { GRANTS } from '../../dock/grants.js';
+import { TIMER } from '../../dock/index.js';
+// 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 = { [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;

package/dist/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/dist/harbor/edge/storage.d.ts

@@ -0,0 +1,30 @@
+import { type Kept, type Store, type WardRecord } from '@nervur-org/nervur/harbor';
+import { type Store as DanceStore } from '../../mcp/oauth.ts';
+import type { Folder } from '../../human/web.ts';
+import { type SettingsStore } from './given.ts';
+import type { Rows, Storage } from './platform.d.ts';
+export declare function settingsInStorage(storage: Rows, prefix?: string): SettingsStore;
+export declare const DESIGN_ROW = "design:";
+export declare const BEINGS_ROW = "beings";
+export declare function folderInStorage(storage: Rows, prefix?: string): Folder;
+export declare function wearInStorage(storage: Rows, prefix?: string): {
+    put: (file: string, text: string | null) => Promise<void>;
+    worn: () => Promise<string[]>;
+};
+export declare function danceInStorage(storage: Rows, prefix?: string): DanceStore;
+export declare class DurableStorage implements Store {
+    #private;
+    readonly storage: Storage;
+    readonly key: CryptoKey;
+    readonly prefix: string;
+    readonly ceiling: number;
+    constructor(storage: Storage, key: CryptoKey, prefix?: string, ceiling?: number);
+    list(): Promise<string[]>;
+    load(name: string): Promise<Kept | undefined>;
+    put(name: string, kept: Kept): Promise<void>;
+    save(name: string, partition: Record<string, unknown>, rows: readonly string[]): Promise<void>;
+    record(name: string, record: WardRecord): Promise<void>;
+    take(name: string): Promise<Kept | undefined>;
+    hints(): Promise<Record<string, string>>;
+    hint(pk: string, url: string): Promise<void>;
+}

package/dist/harbor/edge/storage.js

@@ -0,0 +1,180 @@
+// 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 } from '@nervur-org/nervur/harbor';
+import { seal, open } from '../seal.js';
+import { emptyDance } from '../../mcp/oauth.js';
+import { ROW_CEILING } from './given.js';
+// 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, prefix = '') {
+    const key = `${prefix}settings`;
+    return {
+        load: async () => (await storage.get(key)) ?? {},
+        save: (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, prefix = '') {
+    const design = (file) => `${prefix}${DESIGN_ROW}${file}`;
+    const held = (file) => storage.get(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(`${prefix}${BEINGS_ROW}`)) !== undefined,
+        beings: async () => (await storage.get(`${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, prefix = '') {
+    const head = `${prefix}${DESIGN_ROW}`;
+    return {
+        put: async (file, text) => {
+            if (text === null)
+                await storage.delete(head + file);
+            else
+                await storage.put(head + file, text);
+        },
+        worn: async () => [...(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, prefix = '') {
+    const key = `${prefix}oauth`;
+    return {
+        load: async () => ({ ...emptyDance(), ...((await storage.get(key)) ?? {}) }),
+        save: (dance) => storage.put(key, dance),
+    };
+}
+// `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 {
+    storage;
+    key;
+    prefix;
+    ceiling;
+    constructor(storage, key, prefix = '', ceiling = ROW_CEILING) {
+        this.storage = storage;
+        this.key = key;
+        this.prefix = prefix;
+        this.ceiling = ceiling;
+    }
+    #k(kind, name) {
+        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) {
+        return this.#k('row', `${name} `);
+    }
+    async list() {
+        const head = this.#k('ward', '');
+        return [...(await this.storage.list({ prefix: head })).keys()].map((k) => k.slice(head.length));
+    }
+    async load(name) {
+        const row = await this.storage.get(this.#k('ward', name));
+        if (!row)
+            return undefined;
+        const head = this.#rows(name);
+        const kept = [...(await this.storage.list({ prefix: head }))].map(([k, v]) => [k.slice(head.length), v]);
+        return { seed: await open(this.key, row.seed), partition: fromRows(Object.fromEntries(kept)), record: row.record };
+    }
+    async put(name, kept) {
+        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 });
+        await this.#keep(name, kept.partition, rowsIn(kept.partition));
+    }
+    async save(name, partition, rows) {
+        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, partition, rows) {
+        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, record) {
+        const row = await this.storage.get(this.#k('ward', name));
+        if (row)
+            await this.storage.put(this.#k('ward', name), { ...row, record });
+    }
+    async take(name) {
+        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() {
+        const head = this.#k('hint', '');
+        return Object.fromEntries([...(await this.storage.list({ prefix: head }))].map(([k, v]) => [k.slice(head.length), v]));
+    }
+    async hint(pk, url) {
+        await this.storage.put(this.#k('hint', pk), url);
+    }
+}

package/dist/harbor/edge/worker.d.ts

@@ -0,0 +1,17 @@
+import { EdgeHarbor } from './edge.ts';
+import type { Deployed } from './given.ts';
+import type { State, Env } from './platform.d.ts';
+export declare const DEPLOYED: Deployed;
+export declare class Quo {
+    #private;
+    readonly state: State;
+    readonly env: Env;
+    constructor(state: State, env: Env);
+    harbor(): Promise<EdgeHarbor>;
+    alarm(): Promise<void>;
+    fetch(request: Request): Promise<Response>;
+}
+declare const _default: {
+    fetch(request: Request, env: Env): Promise<Response>;
+};
+export default _default;

package/dist/harbor/edge/worker.js

@@ -0,0 +1,67 @@
+// 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.js';
+import { exercise } from './exercise.js';
+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 = { code: { tab, worker: serviceWorker } };
+export class Quo {
+    state;
+    env;
+    #harbor;
+    constructor(state, env) {
+        this.state = state;
+        this.env = env;
+    }
+    harbor() {
+        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() {
+        const harbor = await this.harbor();
+        await harbor.ready();
+        await harbor.rang();
+    }
+    async fetch(request) {
+        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, env) {
+        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/dist/harbor/files.d.ts

@@ -0,0 +1,15 @@
+import { type Kept, type Store, type WardRecord } from '@nervur-org/nervur/harbor';
+export declare class Files implements Store {
+    #private;
+    readonly dir: string;
+    constructor(dir: string, key?: string);
+    get sealed(): boolean;
+    list(): Promise<string[]>;
+    load(name: string): Promise<Kept | undefined>;
+    put(name: string, kept: Kept): Promise<void>;
+    save(name: string, partition: Record<string, unknown>, rows: readonly string[]): Promise<void>;
+    record(name: string, record: WardRecord): Promise<void>;
+    take(name: string): Promise<Kept | undefined>;
+    hints(): Promise<Record<string, string>>;
+    hint(pk: string, url: string): Promise<void>;
+}

package/dist/harbor/files.js

@@ -0,0 +1,220 @@
+// 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 } from '@nervur-org/nervur/harbor';
+import { sealKey, seal, open } from './seal.js';
+const { hex, unhex } = arithmetic;
+// 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();
+const fileOf = async (row) => (row === HEAD ? 'head.json' : `b-${hex(await arithmetic.sha256(utf8.encode(row)))}.json`);
+export class Files {
+    dir;
+    #key;
+    #queues = new Map();
+    constructor(dir, key) {
+        this.dir = dir;
+        if (key)
+            this.#key = sealKey(key);
+    }
+    #ward(name) {
+        return join(this.dir, 'wards', name);
+    }
+    get sealed() {
+        return this.#key !== undefined;
+    }
+    // The form a folder holds, checked against the form this store speaks.
+    #form(name) {
+        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, file, body) {
+        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) {
+        const blob = (await readFile(join(this.#ward(name), 'ward.sealed'), 'utf8')).trim();
+        return JSON.parse(new TextDecoder().decode(await open(await this.#key, 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, change) {
+        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() {
+        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) {
+        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')),
+        };
+    }
+    // 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) {
+        const dir = join(this.#ward(name), 'rows');
+        if (!existsSync(dir))
+            return {};
+        const out = {};
+        for (const file of await readdir(dir)) {
+            if (file === 'head.json')
+                out[HEAD] = JSON.parse(await readFile(join(dir, file), 'utf8'));
+            else if (/^b-[0-9a-f]{64}\.json$/.test(file)) {
+                const kept = JSON.parse(await readFile(join(dir, file), 'utf8'));
+                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, partition, rows) {
+        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 }) + '\n', { mode: 0o600 });
+                await rename(tmp, file);
+            }
+        });
+        this.#queues.set(name, next.catch(() => { }));
+        return next;
+    }
+    async put(name, kept) {
+        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, partition, rows) {
+        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, record) {
+        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) {
+        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() {
+        const p = join(this.dir, 'reach.json');
+        return existsSync(p) ? JSON.parse(await readFile(p, 'utf8')) : {};
+    }
+    async hint(pk, url) {
+        const all = await this.hints();
+        all[pk] = url;
+        await writeFile(join(this.dir, 'reach.json'), JSON.stringify(all, null, 2) + '\n', { mode: 0o600 });
+    }
+}

package/dist/harbor/http.d.ts

@@ -0,0 +1,19 @@
+import { type Server as HttpServer } from 'node:http';
+import { Socket as Held } from '@nervur-org/nervur/harbor';
+import type { Dialer } from '@nervur-org/nervur/harbor';
+import type { DiskHarbor } from './disk.ts';
+export type Handler = (req: Request, rest: string) => Response | undefined | Promise<Response | undefined>;
+export type Http = {
+    port: number;
+    host: string;
+    mount(prefix: string, handler: Handler): void;
+};
+export type Quo = {
+    sockets: Set<Held>;
+    dialers: Dialer[];
+};
+export declare function readAll(req: Request): Promise<Uint8Array | undefined>;
+export declare function readText(req: Request): Promise<string | undefined>;
+export declare function listenHttp(harbor: DiskHarbor, host: string, port: number, quo: Quo): Promise<Http & {
+    server: HttpServer;
+}>;