nervur 0.21.4 → 0.22.0

package/dist/core/harbor/carrying.d.ts

@@ -0,0 +1,51 @@
+import { Faculty, type BeingClass, type Stance } from '../being/index.ts';
+import type { RootRequest } from './root-line.ts';
+import type { Terrain } from './terrain.ts';
+export interface Arrivals {
+    arrive(pk: string, bytes: Uint8Array): Promise<Uint8Array | null>;
+}
+export interface Ground extends Arrivals {
+    readonly terrain: Terrain;
+}
+export declare const groundOf: (stance: Stance) => Ground;
+export declare const UNDIALED: unique symbol;
+export type Dialed = Uint8Array | null | typeof UNDIALED;
+export type WebListen = {
+    host: string;
+    port: number;
+    path: string;
+    origins: string[];
+};
+export interface WebListener {
+    readonly at: string[];
+    readonly port: number;
+    close(): Promise<void>;
+}
+export type WebServe = (ground: Arrivals, listen: WebListen) => Promise<WebListener>;
+export interface TcpListening {
+    readonly at: string;
+    close(): Promise<void>;
+}
+export interface Sockets {
+    dial(address: string, pk: string, bytes: Uint8Array): Promise<Dialed>;
+    listen(ground: Arrivals, host: string, port: number): Promise<TcpListening>;
+    close(): Promise<void>;
+}
+export declare abstract class CarrierFaculty extends Faculty {
+    static readonly kind: string;
+    static readonly carries: string | null;
+    abstract accepts(address: string): boolean;
+    abstract dial(address: string, pk: string, bytes: Uint8Array): Promise<Dialed>;
+    listening(): string[];
+    relays(_pk: string): boolean;
+    relay(_pk: string, _bytes: Uint8Array): Promise<Uint8Array | null>;
+    heard(): Promise<void>;
+    awake(): Promise<void>;
+    sleep(): Promise<void>;
+}
+export declare const carrierIn: (beings: Readonly<Record<string, {
+    class: string;
+}>>, classes: readonly BeingClass[], carries: string) => {
+    key: string;
+    open?: RootRequest;
+} | null;

package/dist/core/harbor/carrying.js

@@ -0,0 +1,69 @@
+// SPDX-License-Identifier: Apache-2.0
+// A carrier is a faculty. It speaks the schemes of the addresses it dials,
+// dials an address when the harbor carries a box there, and listens where
+// its cells say, handing each box it hears to the harbor. The harbor keeps
+// every route and walks it in order, handing each address to the carrier
+// that speaks its scheme.
+//
+// A ground ships its carriers as plain classes the terrain names, each of
+// a fixed kind and born of its stance alone. They are the kit's, of kinds
+// under `org.nervur.`, and the dock opens them as faculties on the root's
+// `open` alone.
+import { Faculty, ships } from '../being/index.js';
+// The ground a faculty of the box ward is born on.
+export const groundOf = (stance) => {
+    const { ground } = stance;
+    if (!ground)
+        throw new Error('a kit faculty stands in the box ward alone');
+    return ground;
+};
+// Beside a reply and nothing, a dial answers `undialed` when the address
+// could not be reached at all, so the harbor tries the next one. A box a
+// line took may have been heard, so after it no other address is tried.
+export const UNDIALED = Symbol('undialed');
+export class CarrierFaculty extends Faculty {
+    static kind = 'org.nervur.carrier';
+    static {
+        ships(this);
+    }
+    // The carrier of Quo it speaks, as `quo/` names one by the scheme of its
+    // addresses, `tcp` or `web`, or null for one it does not name. A front
+    // finds the carrier it opens by this, and opens it under this name.
+    static carries = null;
+    // The addresses it listens at now.
+    listening() {
+        return [];
+    }
+    // Whether it answers for a ward pk no door of this harbor holds, as a
+    // relay does, and its answer.
+    relays(_pk) {
+        return false;
+    }
+    relay(_pk, _bytes) {
+        return Promise.resolve(null);
+    }
+    // A push the device heard, which says only that something waits: a
+    // carrier that collects for this harbor collects now.
+    heard() {
+        return Promise.resolve();
+    }
+    // Once the harbor has unpacked, and once before it closes.
+    awake() {
+        return Promise.resolve();
+    }
+    sleep() {
+        return Promise.resolve();
+    }
+}
+// What a front asks so a carrier of Quo stands in the box ward, read from
+// the box's census and the classes its entry hands it: the key of a being
+// whose class carries it, or else an `open` under the carrier's name of the
+// class that carries it, or null where no class does.
+export const carrierIn = (beings, classes, carries) => {
+    const carrying = classes.filter((C) => C.prototype instanceof CarrierFaculty && C.carries === carries);
+    const standing = Object.entries(beings).find(([, being]) => carrying.some((C) => C.kind === being.class));
+    if (standing)
+        return { key: standing[0] };
+    const C = carrying[0];
+    return C ? { key: carries, open: { method: 'open', args: { key: carries, class: C.kind } } } : null;
+};

package/dist/core/harbor/catalogue.d.ts

@@ -0,0 +1,33 @@
+import { type AskSpec, type BeingClass, type JsonObject, type Stance } from '../being/index.ts';
+import { type ObjectStore } from '../git/index.ts';
+import { RegistryFaculty } from './registry.ts';
+import type { Terrain } from './terrain.ts';
+export declare const CATALOGUE = "catalogue";
+export interface Cataloguing {
+    readonly terrain: Terrain;
+    readonly dna: ObjectStore & {
+        collect(keep: Iterable<string>): Promise<number>;
+    };
+    readonly kit: readonly BeingClass[];
+    ran(): Promise<void>;
+    stands(kinds: readonly string[]): boolean;
+    kept(): string[];
+    keep(): Promise<boolean>;
+}
+export declare class Catalogue extends RegistryFaculty {
+    #private;
+    static readonly kind: string;
+    static asks: Record<string, AskSpec>;
+    constructor(stance: Stance);
+    classOf(kind: string): BeingClass | undefined;
+    wake(): Promise<void>;
+    add(args: JsonObject): Promise<JsonObject>;
+    remove(args: JsonObject): Promise<JsonObject>;
+    live(args: JsonObject): Promise<JsonObject>;
+    log(args: JsonObject): Promise<JsonObject>;
+    origin(args: JsonObject): JsonObject;
+    fetch(): Promise<JsonObject>;
+    gc(): Promise<JsonObject>;
+    sources(): Promise<JsonObject>;
+    modules(): JsonObject;
+}

package/dist/core/harbor/catalogue.js

@@ -0,0 +1,365 @@
+// SPDX-License-Identifier: Apache-2.0
+// The catalogue: the core's registry, the harbor's DNA. She keeps its
+// code as a git repository, from genesis, its objects in the root memory
+// under her own places and never in a cell. Her cells keep `live`, the
+// commit that stands, `origin`, where she fetches from, and `refs`, what
+// she fetched last. A commit holds one file per module,
+// `modules/<module id>.js`, and nothing else is read from it.
+//
+//   add     { source, name? }   the module's source committed on `live`,
+//                               and `live` moved to it
+//   remove  { module }          its file committed away, and `live` moved,
+//                               refused while a being stands on its kinds
+//   live    { commit? }         `live` moved to a commit or a fetched ref,
+//                               or, with none, the commit that stands
+//   log     { commit? }         the commits from `live` back, first
+//                               parents alone
+//   origin  { url }             where `fetch` reads, or null
+//   fetch                       every ref of `origin` and all it reaches,
+//                               kept, and the refs
+//   gc                          every object that neither `live` nor a
+//                               fetched ref reaches, forgotten
+//   modules                     what `live` runs, and why a module does not
+//   sources                     `live`, and the source of each module
+//                               file it holds, by its blob
+//
+// She resolves a kind to a class from the kit and the modules `live`
+// runs, and nothing else does it for her: the harbor stands her before any
+// registry, from the core alone. Moving `live` checks the commit's modules
+// out, hands each to the terrain's loader and indexes them all: a set that
+// does not run together is refused with its reason, and `live` stays. Once
+// it runs, every being a new class resolves is born again on her stance,
+// and what stands on what now resolves stands. A
+// wake stands `live` again from the objects kept, with no network, and
+// there a module that does not load, or splits a kind with one before it,
+// stays out alone with its reason, and the beings of its kinds stand
+// absent. At genesis `live` is an empty commit.
+//
+// What `add` and `remove` commit is staged aside and written to the DNA
+// only once the commit checks, so a refused one leaves no object. `gc`
+// takes its turn with every ask that writes the DNA, keeps her cells
+// first, and forgets only what the kept `live` and refs do not reach, so
+// a cut mid-collection loses nothing a restart stands.
+//
+// She is the core's, of kind `org.nervur.catalogue`, answers the root and an
+// owner alone, and is born of her stance alone, whose `ground` is her
+// harbor.
+import { ships } from '../being/index.js';
+import { blob, fetchPack, files, havesFrom, isId, listRefs, reachable, readCommit, StagedObjects, text, tree, writeCommit, writeTree } from '../git/index.js';
+import { ownerAsk } from '../ward/index.js';
+import { Registry, RegistryFaculty } from './registry.js';
+export const CATALOGUE = 'catalogue';
+const DIR = 'modules/';
+const SUFFIX = '.js';
+const pathOf = (module) => `${DIR}${module}${SUFFIX}`;
+const WHO = { name: 'nervur', email: 'catalogue@nervur.org' };
+const isText = (v) => typeof v === 'string';
+const domainOf = (name) => `${name.split('.').slice(0, 2).join('.')}.`;
+const failure = (e) => (e instanceof Error ? e.message : String(e));
+export class Catalogue extends RegistryFaculty {
+    static kind = 'org.nervur.catalogue';
+    static {
+        ships(this);
+    }
+    static asks = {
+        add: ownerAsk('a module committed on live, and live moved to it', { required: ['source'] }),
+        remove: ownerAsk('a module committed away, and live moved', { required: ['module'] }),
+        live: ownerAsk('live moved to a commit, or the commit that stands'),
+        log: ownerAsk('the commits from live back'),
+        origin: ownerAsk('where fetch reads', { required: ['url'] }),
+        fetch: ownerAsk('every ref of origin and all it reaches, kept'),
+        modules: ownerAsk('the modules live runs'),
+        sources: ownerAsk('the source of each module file live holds, by its blob'),
+        gc: ownerAsk('every object neither live nor a fetched ref reaches, forgotten'),
+    };
+    #harbor;
+    // Every kind the kit and what `live` runs bring.
+    #registry;
+    // What `live` runs, by module, and why a module it holds does not.
+    #running = new Map();
+    #failed = new Map();
+    // Why `live` itself did not check out at wake, where it did not.
+    #fault = null;
+    // The asks that write the DNA, one after another.
+    #turn = Promise.resolve();
+    constructor(stance) {
+        super(stance);
+        const { ground } = stance;
+        if (!ground)
+            throw new Error('the catalogue stands in the box ward alone');
+        this.#harbor = ground;
+        this.#registry = new Registry(ground.kit, []);
+    }
+    classOf(kind) {
+        return this.#registry.classOf(kind);
+    }
+    // Why these modules cannot run together, or null.
+    #check(modules) {
+        return Registry.refusal(this.#harbor.kit, modules);
+    }
+    get #live() {
+        return isId(this.cells.live) ? this.cells.live : undefined;
+    }
+    get #refs() {
+        return (this.cells.refs ?? {});
+    }
+    #signature() {
+        return { ...WHO, seconds: Math.floor(this.#harbor.terrain.clock.now() / 1000), zone: '+0000' };
+    }
+    // One ask that writes the DNA at a time, in the order asked.
+    #serial(work) {
+        const done = this.#turn.then(work, work);
+        this.#turn = done.catch(() => undefined);
+        return done;
+    }
+    async #commit(dna, paths, message) {
+        const root = paths.size === 0 ? (await dna.put([tree([])]))[0] : await writeTree(dna, paths);
+        const who = this.#signature();
+        return writeCommit(dna, { tree: root, parents: this.#live ? [this.#live] : [], author: who, committer: who, message: `${message}\n` });
+    }
+    // Each module file of a commit, in the tree's order, its source loaded.
+    async #checkout(commit, dna = this.#harbor.dna) {
+        const out = [];
+        for (const [path, id] of await files(dna, commit)) {
+            if (!path.startsWith(DIR) || !path.endsWith(SUFFIX) || path.slice(DIR.length).includes('/'))
+                continue;
+            const name = path.slice(DIR.length, -SUFFIX.length);
+            let loaded;
+            try {
+                const o = await dna.get(id);
+                if (!o)
+                    throw new Error(`blob ${id} is not kept`);
+                loaded = await this.#harbor.terrain.loader.load(text(o.body), id);
+                if (loaded.module !== name)
+                    throw new Error(`${path} declares module ${loaded.module}`);
+            }
+            catch (e) {
+                loaded = e instanceof Error ? e : new Error(String(e));
+            }
+            out.push({ name, blob: id, loaded });
+        }
+        return out;
+    }
+    // `live` stood again, as a wake finds it: a genesis commit on empty
+    // memory, and every module that loads and splits no kind with those
+    // before it run; the rest stay out, each with its reason.
+    async wake() {
+        if (!this.#live) {
+            this.cells.live = await this.#commit(this.#harbor.dna, new Map(), 'genesis');
+            await this.#harbor.keep();
+        }
+        const running = new Map();
+        try {
+            for (const { name, blob: id, loaded } of await this.#checkout(this.#live)) {
+                const refused = loaded instanceof Error ? loaded.message : this.#check([...[...running.values()].map((r) => r.module), loaded]);
+                if (refused === null)
+                    running.set(name, { module: loaded, blob: id });
+                else
+                    this.#failed.set(name, { blob: id, reason: refused });
+            }
+        }
+        catch (e) {
+            this.#fault = failure(e);
+        }
+        this.#running = running;
+        this.#registry = new Registry(this.#harbor.kit, [...running.values()].map((r) => r.module));
+    }
+    // `live` moved to a commit whose every module loads and runs with the
+    // rest, or the reason it stays. A commit staged is written to the DNA
+    // once it checks, before it runs and before `live` names it.
+    async #move(commit, staged) {
+        let checked;
+        try {
+            checked = await this.#checkout(commit, staged);
+        }
+        catch (e) {
+            return failure(e);
+        }
+        const bad = checked.find((c) => c.loaded instanceof Error);
+        if (bad)
+            return `${bad.name}: ${bad.loaded.message}`;
+        const modules = checked.map((c) => c.loaded);
+        const unfit = this.#check(modules);
+        if (unfit !== null)
+            return unfit;
+        await staged?.flush();
+        this.#registry = new Registry(this.#harbor.kit, modules);
+        this.#running = new Map(checked.map((c) => [c.name, { module: c.loaded, blob: c.blob }]));
+        this.#failed = new Map();
+        this.#fault = null;
+        this.cells.live = commit;
+        await this.#harbor.ran();
+        return null;
+    }
+    async #paths() {
+        return this.#live ? files(this.#harbor.dna, this.#live) : new Map();
+    }
+    add(args) {
+        return this.#serial(() => this.#add(args));
+    }
+    async #add(args) {
+        if (!isText(args.source))
+            return { error: 'source is text' };
+        if (args.name !== undefined && !isText(args.name))
+            return { error: 'name is text' };
+        const staged = new StagedObjects(this.#harbor.dna);
+        const [id] = await staged.put([blob(args.source)]);
+        let loaded;
+        try {
+            loaded = await this.#harbor.terrain.loader.load(args.source, id);
+        }
+        catch (e) {
+            return { error: failure(e) };
+        }
+        if (args.name !== undefined && args.name !== loaded.module)
+            return { error: `the source is module ${loaded.module}, not ${args.name}` };
+        const paths = await this.#paths();
+        paths.set(pathOf(loaded.module), id);
+        const commit = await this.#commit(staged, paths, `add ${loaded.module} ${loaded.version}`);
+        const refused = await this.#move(commit, staged);
+        if (refused !== null)
+            return { error: refused };
+        return { added: loaded.module, version: loaded.version, live: commit };
+    }
+    remove(args) {
+        return this.#serial(() => this.#remove(args));
+    }
+    async #remove(args) {
+        const module = args.module;
+        const paths = await this.#paths();
+        if (!isText(module) || !paths.has(pathOf(module)))
+            return { error: 'no such module' };
+        if (this.#harbor.stands(this.#kindsOf(module)))
+            return { error: 'a being stands on this module' };
+        paths.delete(pathOf(module));
+        const staged = new StagedObjects(this.#harbor.dna);
+        const commit = await this.#commit(staged, paths, `remove ${module}`);
+        const refused = await this.#move(commit, staged);
+        if (refused !== null)
+            return { error: refused };
+        return { removed: module, live: commit };
+    }
+    // The kinds a module stands: the registry's, where it runs, and where it
+    // does not, every kind a row keeps in its domain that nothing resolves.
+    #kindsOf(module) {
+        if (this.#running.has(module))
+            return this.#registry.kindsOf(module);
+        const domain = domainOf(module);
+        return this.#harbor.kept().filter((kind) => kind.startsWith(domain) && this.#registry.classOf(kind) === undefined);
+    }
+    live(args) {
+        if (args.commit === undefined)
+            return Promise.resolve({ live: this.#live ?? null });
+        return this.#serial(() => this.#goLive(args));
+    }
+    async #goLive(args) {
+        const named = args.commit;
+        const commit = isText(named) && Object.hasOwn(this.#refs, named) ? this.#refs[named] : named;
+        if (!isId(commit))
+            return { error: 'commit is a commit id or a fetched ref' };
+        const refused = await this.#move(commit);
+        return refused === null ? { live: commit } : { error: refused };
+    }
+    async log(args) {
+        const from = args.commit ?? this.#live;
+        if (!isId(from))
+            return { error: 'commit is a commit id' };
+        const log = [];
+        try {
+            for (let at = from; at !== undefined;) {
+                const o = await this.#harbor.dna.get(at);
+                if (!o)
+                    break;
+                const c = readCommit(o);
+                log.push({ commit: at, parents: [...c.parents], message: c.message.replace(/\n$/, ''), seconds: c.committer.seconds });
+                at = c.parents[0];
+            }
+        }
+        catch (e) {
+            return { error: failure(e) };
+        }
+        return { log };
+    }
+    origin(args) {
+        const url = args.url;
+        if (url === null) {
+            delete this.cells.origin;
+            return { origin: null };
+        }
+        if (!isText(url) || !/^https?:\/\/[^/\s]+/.test(url))
+            return { error: 'url is an http or https URL, or null' };
+        this.cells.origin = url;
+        return { origin: url };
+    }
+    // Read-only on the remote: its refs, and a pack of what they reach that
+    // is not kept here, each object kept. The commits `live` and the refs
+    // reach are its haves, so the pack carries only what is new.
+    fetch() {
+        return this.#serial(() => this.#fetch());
+    }
+    async #fetch() {
+        const url = this.cells.origin;
+        if (!isText(url))
+            return { error: 'no origin is set' };
+        try {
+            const refs = await listRefs(url);
+            const held = (id) => this.#harbor.dna.get(id);
+            const objects = await fetchPack(url, Object.values(refs), held, await havesFrom(this.#roots(), held));
+            await this.#harbor.dna.put([...objects.values()]);
+            this.cells.refs = refs;
+            return { refs, objects: objects.size };
+        }
+        catch (e) {
+            return { error: failure(e) };
+        }
+    }
+    // What the DNA keeps history from: `live` and every fetched ref.
+    #roots() {
+        return [...new Set([...(this.#live ? [this.#live] : []), ...Object.values(this.#refs)])];
+    }
+    // What `live` and every fetched ref reach stays, and the rest of the
+    // DNA is forgotten. Her cells are kept first, so she collects against
+    // what a restart stands; the whole reachable set is known before any
+    // object goes, and an object missing from it stops the collection.
+    gc() {
+        return this.#serial(async () => {
+            if (!(await this.#harbor.keep()))
+                throw new Error('her cells were not kept');
+            const dna = this.#harbor.dna;
+            const keep = new Set();
+            for (const root of this.#roots()) {
+                // An annotated tag is kept, and the commit it names walked; a
+                // missing object throws here, before anything is forgotten.
+                let at = root;
+                for (let o = await dna.get(at); o?.type === 'tag'; o = await dna.get(at)) {
+                    keep.add(at);
+                    at = /^object ([0-9a-f]{40})$/m.exec(text(o.body))?.[1] ?? '';
+                }
+                for (const id of await reachable(dna, at))
+                    keep.add(id);
+            }
+            return { collected: await dna.collect(keep), kept: keep.size };
+        });
+    }
+    // Each module file `live` holds, by its blob's id, with its source: what
+    // an edge's next child carries.
+    async sources() {
+        const sources = [];
+        for (const [path, id] of await this.#paths()) {
+            if (!path.startsWith(DIR) || !path.endsWith(SUFFIX))
+                continue;
+            const o = await this.#harbor.dna.get(id);
+            if (o)
+                sources.push({ blob: id, source: text(o.body) });
+        }
+        return { live: this.#live ?? null, sources };
+    }
+    modules() {
+        const modules = {};
+        for (const [name, r] of this.#running)
+            modules[name] = { running: r.module.version, blob: r.blob };
+        for (const [name, f] of this.#failed)
+            modules[name] = { running: null, blob: f.blob, failed: f.reason };
+        return { live: this.#live ?? null, modules, ...(this.#fault === null ? {} : { failed: this.#fault }) };
+    }
+}

package/dist/core/harbor/dna.d.ts

@@ -0,0 +1,13 @@
+import { type GitObject, type ObjectStore } from '../git/index.ts';
+import type { Memory } from '../contract/index.ts';
+import type { Package } from './package.ts';
+export declare class Dna implements ObjectStore {
+    #private;
+    static readonly prefix: string;
+    constructor(memory: Memory, pack: Package);
+    static occupies(place: string): boolean;
+    get(id: string): Promise<GitObject | null>;
+    put(objects: readonly GitObject[]): Promise<string[]>;
+    count(): Promise<number>;
+    collect(keep: Iterable<string>): Promise<number>;
+}

package/dist/core/harbor/dna.js

@@ -0,0 +1,120 @@
+var _a;
+// SPDX-License-Identifier: Apache-2.0
+// The DNA's objects, kept in the root memory under the catalogue's own
+// places and sealed under the package as every row is, so the terrain
+// reads no code and no object's id.
+//
+//   place     the hex of `catalogue`, then the first two digits of the
+//             entry's name, git's fan-out
+//   entry     16 bytes under ["dna", object id], as hex
+//   bytes     nonce (12) || AES-256-GCM( the object deflated as git keeps
+//             it loose ), under 32 bytes of ["seal", "dna"], the entry's
+//             name as additional data
+//
+// An object read back is checked against its id, so a store that hands
+// back other bytes hands back nothing.
+import { concat, decrypt, encrypt, hex, utf8 } from '../crypto/index.js';
+import { deflated, idOf, inflated } from '../git/index.js';
+const NONCE = 12;
+const FAN = 2;
+export class Dna {
+    // The places under this prefix are the catalogue's, never a ward's: a
+    // ward's place is 32 digits, and a memory faculty's is its key's hex and
+    // 32 more, never fewer than 34.
+    static prefix = hex(utf8('catalogue'));
+    #memory;
+    #pack;
+    #held = new Map();
+    #seal;
+    constructor(memory, pack) {
+        this.#memory = memory;
+        this.#pack = pack;
+    }
+    static occupies(place) {
+        return place.length === _a.prefix.length + FAN && place.startsWith(_a.prefix);
+    }
+    #key() {
+        return (this.#seal ??= this.#pack.derive(['seal', 'dna'], 32));
+    }
+    async #entry(id) {
+        const name = hex(await this.#pack.derive(['dna', id], 16));
+        return { place: _a.prefix + name.slice(0, FAN), name };
+    }
+    async get(id) {
+        const held = this.#held.get(id);
+        if (held)
+            return held;
+        const { place, name } = await this.#entry(id);
+        const bytes = (await this.#memory.read(place)).get(name);
+        if (!bytes || bytes.length <= NONCE)
+            return null;
+        const open = await decrypt(await this.#key(), bytes.subarray(0, NONCE), utf8(name), bytes.subarray(NONCE));
+        if (open === null)
+            return null;
+        const o = await inflated(open);
+        if ((await idOf(o)) !== id)
+            return null;
+        this.#held.set(id, o);
+        return o;
+    }
+    // Every object sealed and written, one keep for each place.
+    async put(objects) {
+        const ids = [];
+        const places = new Map();
+        const kept = new Map();
+        for (const o of objects) {
+            const id = await idOf(o);
+            ids.push(id);
+            if (this.#held.has(id) || kept.has(id))
+                continue;
+            const { place, name } = await this.#entry(id);
+            const nonce = this.#pack.entropy.draw(NONCE);
+            const sealed = concat(nonce, await encrypt(await this.#key(), nonce, utf8(name), await deflated(o)));
+            if (!places.has(place))
+                places.set(place, new Map());
+            places.get(place).set(name, sealed);
+            kept.set(id, o);
+        }
+        for (const [place, entries] of places)
+            await this.#memory.write(place, entries);
+        for (const [id, o] of kept)
+            this.#held.set(id, o);
+        return ids;
+    }
+    async #places() {
+        return (await this.#memory.places()).filter((place) => _a.occupies(place));
+    }
+    // How many objects are kept.
+    async count() {
+        let n = 0;
+        for (const place of await this.#places())
+            n += (await this.#memory.read(place)).size;
+        return n;
+    }
+    // Every object but those `keep` names forgotten, and how many were. The
+    // names kept are drawn before any entry is touched, and a place is
+    // written with only its forgotten entries, so a cut anywhere loses
+    // nothing `keep` names.
+    async collect(keep) {
+        const ids = new Set(keep);
+        const names = new Set();
+        for (const id of ids)
+            names.add((await this.#entry(id)).name);
+        let forgotten = 0;
+        for (const place of await this.#places()) {
+            const gone = new Map();
+            for (const name of (await this.#memory.read(place)).keys())
+                if (!names.has(name))
+                    gone.set(name, null);
+            if (gone.size === 0)
+                continue;
+            await this.#memory.write(place, gone);
+            forgotten += gone.size;
+        }
+        for (const id of [...this.#held.keys()])
+            if (!ids.has(id))
+                this.#held.delete(id);
+        return forgotten;
+    }
+}
+_a = Dna;