nervur 0.19.2 → 0.20.1

package/src/harbor/catalogue.ts

@@ -0,0 +1,110 @@
+// SPDX-License-Identifier: Apache-2.0
+// The catalogue: the dock's first faculty, the code a harbor runs. Her
+// cells name each module by the name it declares, its version, and where
+// the terrain's loader finds it. The harbor wakes her before any other
+// faculty, loads every module she names, and refuses to stand when one is
+// missing.
+//
+//   add     { from }      the module the loader finds there, run from now
+//                         on; the same module again takes its new version
+//   remove  { module }    a module no being stands on, run no more
+//   modules               what she names, each with the version running
+//
+// She is the kit's, of kind `org.nervur.catalogue`, and answers the root
+// and an owner alone.
+import { Faculty, type AskSpec, type BeingClass, type JsonObject, type Stance } from '../being/index.ts';
+import type { Loaded } from '../contract/index.ts';
+import { ownerAsk } from '../ward/index.ts';
+
+export const CATALOGUE = 'catalogue';
+
+// One module, as her cells keep it.
+export type ModuleRow = { version: string; from: string };
+
+// What the catalogue asks of her harbor.
+export interface Cataloguing {
+  load(from: string): Promise<Loaded | null>;
+  // The modules run from now on, or why they cannot be.
+  run(modules: readonly Loaded[]): string | null;
+  // Whether a being of any ward stands on one of these kinds.
+  stands(kinds: readonly string[]): boolean;
+  kindsOf(module: string): string[];
+}
+
+const text = (v: unknown): v is string => typeof v === 'string';
+
+export class Catalogue extends Faculty {
+  static override readonly kind: string = 'org.nervur.catalogue';
+  static override cells: JsonObject = { modules: {} };
+  static override asks: Record<string, AskSpec> = {
+    add: ownerAsk('a module run from now on', { required: ['from'] }),
+    remove: ownerAsk('a module run no more', { required: ['module'] }),
+    modules: ownerAsk('the modules this harbor runs'),
+  };
+
+  readonly #harbor: Cataloguing;
+  readonly #running = new Map<string, Loaded>();
+
+  constructor(stance: Stance, harbor: Cataloguing) {
+    super(stance);
+    this.#harbor = harbor;
+  }
+
+  get #rows(): Record<string, ModuleRow> {
+    return this.cells.modules as Record<string, ModuleRow>;
+  }
+
+  // Every module her cells name, loaded and run, or a throw naming the one
+  // that cannot be.
+  async wake(): Promise<void> {
+    for (const [module, row] of Object.entries(this.#rows)) {
+      const loaded = await this.#harbor.load(row.from);
+      if (loaded === null) throw new Error(`module ${module} is not found at ${row.from}`);
+      if (loaded.module !== module) throw new Error(`${row.from} is module ${loaded.module}, not ${module}`);
+      this.#running.set(module, loaded);
+    }
+    const refused = this.#harbor.run([...this.#running.values()]);
+    if (refused !== null) throw new Error(refused);
+  }
+
+  async add(args: JsonObject): Promise<JsonObject> {
+    if (!text(args.from)) return { error: 'from is text' };
+    const loaded = await this.#harbor.load(args.from);
+    if (loaded === null) return { error: 'no such module' };
+    const running = new Map(this.#running);
+    running.set(loaded.module, loaded);
+    const refused = this.#harbor.run([...running.values()]);
+    if (refused !== null) return { error: refused };
+    this.#running.set(loaded.module, loaded);
+    this.#rows[loaded.module] = { version: loaded.version, from: loaded.from };
+    return { added: loaded.module, version: loaded.version };
+  }
+
+  remove(args: JsonObject): JsonObject {
+    const module = args.module;
+    if (!text(module) || !this.#running.has(module)) return { error: 'no such module' };
+    if (this.#harbor.stands(this.#harbor.kindsOf(module))) return { error: 'a being stands on this module' };
+    const running = new Map(this.#running);
+    running.delete(module);
+    this.#harbor.run([...running.values()]);
+    this.#running.delete(module);
+    delete this.#rows[module];
+    return { removed: module };
+  }
+
+  modules(): JsonObject {
+    const out: JsonObject = {};
+    for (const [module, row] of Object.entries(this.#rows)) out[module] = { version: row.version, running: this.#running.get(module)?.version ?? null, from: row.from };
+    return out;
+  }
+}
+
+// The catalogue class one harbor stands: a being is born of her class and
+// her stance alone, so the class holds its harbor.
+export const catalogueFor = (harbor: Cataloguing): BeingClass =>
+  class extends Catalogue {
+    static override readonly kind: string = Catalogue.kind;
+    constructor(stance: Stance) {
+      super(stance, harbor);
+    }
+  };

package/src/harbor/dock.ts

@@ -0,0 +1,137 @@
+// SPDX-License-Identifier: Apache-2.0
+// The dock: the box ward's ward-being. Beside the root's asks of every ward,
+// she opens faculties, hosts wards, and lends each contract a faculty
+// fulfils to the wards she hosts.
+//
+//   open    { key, class }      a faculty stands in the box ward, and the
+//                               dock holds a standing on her under her key
+//   host    { ward, seed? }     a hosted ward stands under the seed named,
+//                               or a drawn one, holding a standing on the
+//                               dock; the dock keeps its name and seed
+//   lend    { contract }        asked by a hosted ward: an offer from a
+//                               faculty that fulfils the contract
+//   retract { contract, heir }  an offer that was not taken
+//   route   { ward, at }        where a ward pk is reached, `host:port`, or
+//                               null to forget it; the dock keeps it and
+//                               the harbor hands it to its carrier
+import { Faculty, KIT, type Asker, type AskSpec, type Invitation, type JsonObject } from '../being/index.ts';
+import { CATALOGUE } from './catalogue.ts';
+import { readInvitation } from '../quo/index.ts';
+import { ownerAsk, WardBeing, type Lender, type WardBeingStance } from '../ward/index.ts';
+
+// What the dock asks of her harbor: a ward standing, and the seed, as hex,
+// it stands under.
+export interface Hosting {
+  host(name: string, invitation: Invitation, seed?: string): Promise<string | null>;
+  // Whether the harbor's carrier took the route.
+  route(pk: string, at: string | null): boolean;
+  // Whether the box ward's partition was kept.
+  keep(): Promise<boolean>;
+}
+
+// One hosted ward, as the dock's cells keep it.
+export type Hosted = { ward: string; seed: string };
+
+export const BOX = 'box';
+const text = (v: unknown): v is string => typeof v === 'string';
+const hosted: AskSpec['for'] = (_: Asker, notes: JsonObject | undefined) => notes?.hosted === true;
+
+export class Dock extends WardBeing implements Lender {
+  static override readonly kind: string = 'org.nervur.dock';
+  static override cells: JsonObject = { hosted: [], routes: {} };
+  static override asks: Record<string, AskSpec> = {
+    ...WardBeing.asks,
+    open: ownerAsk('a faculty of this harbor', { required: ['key', 'class'] }),
+    host: ownerAsk('a ward this harbor hosts', { required: ['ward'] }),
+    route: ownerAsk('where a ward is reached, or null', { required: ['ward', 'at'] }),
+    lend: { description: 'an offer from a faculty fulfilling a contract', input: { type: 'object', required: ['contract'] }, for: hosted },
+    retract: { description: 'an offer that was not taken', input: { type: 'object', required: ['contract', 'heir'] }, for: hosted },
+  };
+
+  readonly #hosting: Hosting;
+
+  constructor(stance: WardBeingStance, hosting: Hosting) {
+    super(stance);
+    this.#hosting = hosting;
+  }
+
+  get hosted(): Hosted[] {
+    return (this.cells.hosted as Hosted[]).map(({ ward, seed }) => ({ ward, seed }));
+  }
+
+  get routes(): Record<string, string> {
+    return { ...(this.cells.routes as Record<string, string>) };
+  }
+
+  route(args: JsonObject): JsonObject {
+    const { ward, at } = args;
+    if (!text(ward) || (at !== null && !text(at)) || !this.#hosting.route(ward, at)) return { error: 'not routed' };
+    const routes = this.cells.routes as Record<string, string>;
+    if (at === null) delete routes[ward];
+    else routes[ward] = at;
+    return { routed: ward };
+  }
+
+  // Genesis: the catalogue stands first, and is kept at once.
+  async standCatalogue(): Promise<void> {
+    const kind = 'org.nervur.catalogue';
+    if ((await this.stance.boot(kind, CATALOGUE, CATALOGUE)) === null || !(await this.#hosting.keep())) throw new Error('the catalogue did not stand');
+  }
+
+  async open(args: JsonObject): Promise<JsonObject> {
+    if (!text(args.key) || !text(args.class)) return { error: 'key and class are text' };
+    if (args.class.startsWith(KIT) || !Faculty.fulfils(this.steward.classOf(args.class))) return { error: 'no such faculty' };
+    const opened = await this.stance.boot(args.class, args.key, args.key);
+    return opened === null ? { error: 'not opened' } : { opened };
+  }
+
+  async host(args: JsonObject): Promise<JsonObject> {
+    const name = args.ward;
+    if (!text(name) || name === BOX || this.hosted.some((h) => h.ward === name)) return { error: 'no such ward to host' };
+    if (args.seed !== undefined && !text(args.seed)) return { error: 'seed is text' };
+    const invitation = await this.stance.occupants.invite(name, { hosted: true });
+    if (invitation === null) return { error: 'not hosted' };
+    const seed = await this.#hosting.host(name, invitation, args.seed);
+    if (seed === null) {
+      this.stance.occupants.remove(name);
+      return { error: 'not hosted' };
+    }
+    (this.cells.hosted as Hosted[]).push({ ward: name, seed });
+    return { hosted: name };
+  }
+
+  async lend(args: JsonObject): Promise<JsonObject> {
+    if (!text(args.contract)) return { error: 'contract is text' };
+    const invitation = await this.offer(args.contract);
+    return invitation ? { invitation } : { error: 'nothing lent' };
+  }
+
+  async retract(args: JsonObject): Promise<JsonObject> {
+    if (!text(args.contract) || !text(args.heir)) return { error: 'contract and heir are text' };
+    await this.withdraw(args.contract, args.heir);
+    return { retracted: args.heir };
+  }
+
+  // Lender: the first standing faculty that fulfils the contract offers.
+  async offer(contract: string): Promise<Invitation | null> {
+    for (const key of this.#fulfilling(contract)) {
+      const out = await this.stance.standings.get(key)?.ask('offer');
+      const invitation = readInvitation((out as { invitation?: unknown } | undefined)?.invitation);
+      if (invitation) return invitation;
+    }
+    return null;
+  }
+
+  async withdraw(contract: string, heir: string): Promise<void> {
+    for (const key of this.#fulfilling(contract)) await this.stance.standings.get(key)?.ask('retract', { heir });
+  }
+
+  #fulfilling(contract: string): string[] {
+    const beings = this.steward.beings();
+    return this.stance.standings.ids().filter((key) => {
+      const being = beings[key];
+      const C = being && !being.absent ? this.steward.classOf(being.class) : undefined;
+      return Faculty.fulfils(C) && Faculty.contracts(C).includes(contract);
+    });
+  }
+}

package/src/harbor/harbor.ts

@@ -0,0 +1,180 @@
+// SPDX-License-Identifier: Apache-2.0
+// The harbor: the onion, unpacked from a terrain alone.
+//
+//   1. the seed and the package   the harbor's one secret, from custody,
+//                                 opens its sealed memory
+//   2. the box ward               unpacked as every ward is, under the
+//                                 harbor's seed, its ward-being the dock
+//   3. the catalogue              the dock's first faculty, a kit class:
+//                                 every module her cells name is loaded
+//                                 through the terrain, or the harbor does
+//                                 not stand
+//   4. the faculties              the box ward's other beings, each from her
+//                                 own row, by the kinds the modules bring
+//   5. the routes                 as the dock's cells keep them, handed to
+//                                 the terrain's carrier
+//   6. the hosted wards           as the dock's cells list them, each under
+//                                 the seed the dock keeps for it
+//   7. the beings                 in each ward, each from her own row
+//
+// Genesis and wake are one path: empty memory unpacks a box ward holding
+// the dock, the dock stands the catalogue, and the root's asks write the
+// rest.
+import type { Answer, BeingClass, Invitation, JsonObject } from '../being/index.ts';
+import { Carrier, type Loaded } from '../contract/index.ts';
+import { hex, isHex, unhex } from '../crypto/index.ts';
+import { WardKey } from '../quo/index.ts';
+import { DOCK, Pilot, Ward, type Catalogue as Resolving, type WardParts } from '../ward/index.ts';
+import { Catalogue, CATALOGUE, catalogueFor, type Cataloguing } from './catalogue.ts';
+import { BOX, Dock, type Hosting } from './dock.ts';
+import { Package } from './package.ts';
+import { Registry } from './registry.ts';
+import type { Terrain } from './terrain.ts';
+
+export class Harbor extends Carrier implements Hosting, Cataloguing, Resolving {
+  readonly terrain: Terrain;
+  readonly #package: Package;
+  readonly #wards = new Map<string, Ward>();
+  readonly #kit: BeingClass[];
+  #registry: Registry;
+
+  private constructor(terrain: Terrain, pack: Package) {
+    super();
+    this.terrain = terrain;
+    this.#package = pack;
+    this.#kit = [catalogueFor(this), Pilot];
+    this.#registry = new Registry(this.#kit, []);
+  }
+
+  static async open(terrain: Terrain): Promise<Harbor> {
+    const seed = await terrain.custody.seed();
+    const harbor = new Harbor(terrain, await Package.open(terrain.memory, terrain.entropy, seed));
+    await harbor.#unpack(BOX, seed, undefined, (stance) => new Dock(stance, harbor));
+    if (!harbor.box.partition.being(CATALOGUE)) await harbor.dock.standCatalogue();
+    await harbor.catalogue.wake();
+    for (const [pk, at] of Object.entries(harbor.dock.routes)) terrain.carrier.route(pk, at);
+    for (const hosted of harbor.dock.hosted) await harbor.#unpack(hosted.ward, unhex(hosted.seed));
+    return harbor;
+  }
+
+  get box(): Ward {
+    return this.#wards.get(BOX)!;
+  }
+
+  get dock(): Dock {
+    return this.box.wardBeing as Dock;
+  }
+
+  get catalogue(): Catalogue {
+    return this.box.being(CATALOGUE) as Catalogue;
+  }
+
+  get registry(): Registry {
+    return this.#registry;
+  }
+
+  ward(name: string): Ward | undefined {
+    return this.#wards.get(name);
+  }
+
+  get names(): string[] {
+    return [...this.#wards.keys()].filter((name) => name !== BOX);
+  }
+
+  // The unsealed ask on the box ward: what a command line carries.
+  root(method?: string, args?: JsonObject): Promise<Answer> {
+    return this.box.root(method, args);
+  }
+
+  holds(pk: string): boolean {
+    return this.#door(pk) !== undefined;
+  }
+
+  // Bytes for one of this harbor's doors, or nothing.
+  async arrive(pk: string, bytes: Uint8Array): Promise<Uint8Array | null> {
+    const ward = this.#door(pk);
+    return ward ? (await ward.door.arrive(bytes)).bytes : null;
+  }
+
+  // Carrier: this harbor's own doors first, then the terrain's.
+  carry(pk: string, bytes: Uint8Array): Promise<Uint8Array | null> {
+    return this.holds(pk) ? this.arrive(pk, bytes) : this.terrain.carrier.carry(pk, bytes);
+  }
+
+  // Resolving: a kind, by the registry the catalogue runs.
+  classOf(kind: string): BeingClass | undefined {
+    return this.#registry.classOf(kind);
+  }
+
+  // Cataloguing: code through the terrain, and the modules run.
+  load(from: string): Promise<Loaded | null> {
+    return this.terrain.loader.load(from);
+  }
+
+  run(modules: readonly Loaded[]): string | null {
+    try {
+      this.#registry = new Registry(this.#kit, modules);
+    } catch (e) {
+      return (e as Error).message;
+    }
+    for (const ward of this.#wards.values()) ward.bearAnew();
+    return null;
+  }
+
+  stands(kinds: readonly string[]): boolean {
+    for (const ward of this.#wards.values()) {
+      for (const row of Object.values(ward.partition.beings)) if (kinds.includes(row.class)) return true;
+    }
+    return false;
+  }
+
+  kindsOf(module: string): string[] {
+    return this.#registry.kindsOf(module);
+  }
+
+  // Hosting: a ward the dock hosts stands now, under the seed named or a
+  // drawn one, and the seed it stands under comes back. A ward whose key
+  // another ward of this harbor already has does not stand.
+  async host(name: string, invitation: Invitation, seed?: string): Promise<string | null> {
+    if (this.#wards.has(name)) return null;
+    const bytes = seed === undefined ? this.terrain.entropy.draw(32) : isHex(seed, 32) ? unhex(seed) : null;
+    if (bytes === null || this.holds((await WardKey.from(bytes)).pk)) return null;
+    try {
+      await this.#unpack(name, bytes, invitation);
+    } catch {
+      return null;
+    }
+    if (this.#wards.get(name)!.wardBeing.stance.standings.get(DOCK)) return hex(bytes);
+    this.#wards.delete(name);
+    return null;
+  }
+
+  keep(): Promise<boolean> {
+    return this.box.partition.kept();
+  }
+
+  // Hosting: the terrain's carrier takes a route, or does not dial.
+  override route(pk: string, at: string | null): boolean {
+    return this.terrain.carrier.route(pk, at);
+  }
+
+  async #unpack(name: string, seed: Uint8Array, dock?: Invitation, root?: WardParts['root']): Promise<void> {
+    const { entropy, clock } = this.terrain;
+    const ward = await Ward.unpack({
+      seed,
+      memory: await this.#package.rows(name),
+      catalogue: this,
+      entropy,
+      clock,
+      carrier: this,
+      ...(dock ? { dock } : {}),
+      ...(root ? { root } : {}),
+    });
+    this.#wards.set(name, ward);
+  }
+
+  #door(pk: string): Ward | undefined {
+    for (const ward of this.#wards.values()) if (ward.pk === pk) return ward;
+    return undefined;
+  }
+}

package/src/harbor/index.ts

@@ -1,20 +1,10 @@
 // SPDX-License-Identifier: Apache-2.0
-// nervur/harbor — the Ground contract and the harbors. The only
-// place in the package that may know a wire, and it knows one on the
-// standard surface alone: fetch and WebSocket. MemoryHarbor knows none: it
-// is one process talking to itself, where every ward assertion is made.
-export { MemoryHarbor, type Booted, type WardFactory } from './memory.ts';
-export { Harbor, DEFAULT_CODE, type Hosted, type Bound, type Loader } from './core.ts';
-export { dial, type Dialer } from './dial.ts';
-export { MemoryStore, values, rowsOf, type Store, type Kept, type WardRecord } from './store.ts';
-// What a store keeping a ward in rows needs: the name of the row that is not
-// a being, and the partition back from the rows it was cut into.
-export { HEAD, fromRows, rowsIn } from '../ward/partition.ts';
-export { request, Socket, SUITE, REFUSED, type Reach, type Carry, type Line, type Announce } from './reach.ts';
-export type { Ground, WardPointers, Memory } from '../ward/ground.ts';
-export { BOX, OFFER, RETRACT, volatile } from '../ward/ground.ts';
-// The box as one being, and the acts a harbor runs to stand it.
-export { Box, BOX_SEED, BOX_ASKS, stand, hold, offerTo, roll } from './box.ts';
-// What a harbor builds a ground out of. Convenience, never contract: a kit
-// writing its own harbor may write these three again.
-export { maker, entropy, learnPk } from '../ward/ground.ts';
+// The onion: a terrain, the package, the dock, the catalogue and its
+// registry, and the harbor.
+export { Catalogue, CATALOGUE, type Cataloguing, type ModuleRow } from './catalogue.ts';
+export { BOX, Dock, type Hosted, type Hosting } from './dock.ts';
+export { Harbor } from './harbor.ts';
+export { Package } from './package.ts';
+export { readRootRequest, rootLine, type RootRequest } from './root-line.ts';
+export { Registry } from './registry.ts';
+export { Terrain } from './terrain.ts';

package/src/harbor/package.ts

@@ -0,0 +1,131 @@
+// SPDX-License-Identifier: Apache-2.0
+// The package: a harbor's memory, sealed under the harbor's seed. The
+// terrain keeps its bytes and reads neither a ward's name, nor a being's
+// key, nor anything a row holds.
+//
+//   key            HKDF-SHA-256 of the seed under `nervur-package`
+//   place          16 bytes under ["place", ward], as hex
+//   entry          16 bytes under ["entry", ward, row], as hex
+//   seal           32 bytes under ["seal", ward]
+//   entry bytes    nonce (12) || AES-256-GCM( JSON { row, value } ),
+//                  the entry's name as additional data
+//
+// A row is the head, under the empty name, or one being, under her key. An
+// entry that does not open refuses the whole ward, so nothing unpacks from
+// bytes the package did not seal.
+import { concat, decrypt, encrypt, hex, hkdf, utf8 } from '../crypto/index.ts';
+import type { Entropy, Memory, Rows } from '../contract/index.ts';
+import { HEAD_ROW } from '../ward/index.ts';
+
+const NONCE = 12;
+const LABEL = utf8('nervur-package');
+
+type Sealed = { row: string; value: unknown };
+
+class PackageRows implements Rows {
+  readonly rows: Record<string, unknown>;
+  readonly #ward: Ward;
+  readonly #told = new Set<string>();
+  #line: Promise<boolean> = Promise.resolve(true);
+
+  constructor(ward: Ward, rows: Record<string, unknown>) {
+    this.#ward = ward;
+    this.rows = rows;
+  }
+
+  told(row: string): void {
+    this.#told.add(row);
+  }
+
+  // Every row told since the last keep, sealed and written as one keep, one
+  // keep at a time.
+  kept(): Promise<boolean> {
+    const rows = [...this.#told];
+    this.#told.clear();
+    this.#line = this.#line.then(() => this.#write(rows)).catch(() => false);
+    return this.#line;
+  }
+
+  async #write(told: string[]): Promise<boolean> {
+    const beings = (this.rows.beings ?? {}) as Record<string, unknown>;
+    const entries = new Map<string, Uint8Array | null>();
+    for (const row of told) {
+      const value = row === HEAD_ROW ? (this.rows.ward ?? null) : Object.hasOwn(beings, row) ? beings[row] : undefined;
+      entries.set(await this.#ward.entry(row), value === undefined ? null : await this.#ward.seal(row, value));
+    }
+    await this.#ward.write(entries);
+    return true;
+  }
+}
+
+class Ward {
+  readonly #pack: Package;
+  readonly #name: string;
+  readonly #seal: Uint8Array;
+  readonly place: string;
+
+  constructor(pack: Package, name: string, seal: Uint8Array, place: string) {
+    this.#pack = pack;
+    this.#name = name;
+    this.#seal = seal;
+    this.place = place;
+  }
+
+  entry(row: string): Promise<string> {
+    return this.#pack.derive(['entry', this.#name, row], 16).then(hex);
+  }
+
+  async seal(row: string, value: unknown): Promise<Uint8Array> {
+    const nonce = this.#pack.entropy.draw(NONCE);
+    const text = utf8(JSON.stringify({ row, value } satisfies Sealed));
+    return concat(nonce, await encrypt(this.#seal, nonce, utf8(await this.entry(row)), text));
+  }
+
+  // The name is the additional data, so an entry moved under another name
+  // does not open either.
+  async open(name: string, bytes: Uint8Array): Promise<Sealed> {
+    const text = bytes.length > NONCE ? await decrypt(this.#seal, bytes.subarray(0, NONCE), utf8(name), bytes.subarray(NONCE)) : null;
+    if (text === null) throw new Error('an entry the package did not seal');
+    return JSON.parse(new TextDecoder().decode(text)) as Sealed;
+  }
+
+  write(entries: ReadonlyMap<string, Uint8Array | null>): Promise<void> {
+    return this.#pack.memory.write(this.place, entries);
+  }
+}
+
+export class Package {
+  readonly memory: Memory;
+  readonly entropy: Entropy;
+  readonly #key: Uint8Array;
+
+  private constructor(memory: Memory, entropy: Entropy, key: Uint8Array) {
+    this.memory = memory;
+    this.entropy = entropy;
+    this.#key = key;
+  }
+
+  static async open(memory: Memory, entropy: Entropy, seed: Uint8Array): Promise<Package> {
+    return new Package(memory, entropy, await hkdf(seed, LABEL, 32));
+  }
+
+  derive(info: string[], length: number): Promise<Uint8Array> {
+    return hkdf(this.#key, utf8(JSON.stringify(info)), length);
+  }
+
+  // One ward's rows, as the package kept them.
+  async rows(name: string): Promise<Rows> {
+    const ward = new Ward(this, name, await this.derive(['seal', name], 32), hex(await this.derive(['place', name], 16)));
+    const rows: Record<string, unknown> = {};
+    const beings: Record<string, unknown> = {};
+    let any = false;
+    for (const [entry, bytes] of await this.memory.read(ward.place)) {
+      const { row, value } = await ward.open(entry, bytes);
+      any = true;
+      if (row === HEAD_ROW) rows.ward = value;
+      else beings[row] = value;
+    }
+    if (any) rows.beings = beings;
+    return new PackageRows(ward, rows);
+  }
+}

package/src/harbor/registry.ts

@@ -0,0 +1,73 @@
+// SPDX-License-Identifier: Apache-2.0
+// The catalogue's index: every kind the harbor runs, from the kit's own
+// classes and the modules the catalogue loaded. It resolves a kind a row
+// keeps, and decides nothing about what stands. It refuses any set of
+// modules two readings could split:
+//
+//   a module whose name is no kind, or is the kit's, or two of one name
+//   a class with no kind of its own, or one outside its module's domain
+//   two classes of one kind, or one kind in two modules
+//   a contract with no kind of its own, or one kind for two contracts
+//   a kind that is a class and a contract
+//
+// A module's domain is its name's first two segments: `com.acme.shop`
+// stands classes under `com.acme.` alone. A contract may be any domain's,
+// so a faculty fulfils a contract another module declares. Two harbors hold
+// two registries, and nothing between them names a class.
+import { Faculty, isKind, KIT, kindOf, type BeingClass } from '../being/index.ts';
+import type { Module } from '../contract/index.ts';
+import type { Catalogue } from '../ward/index.ts';
+
+const domainOf = (name: string): string => `${name.split('.').slice(0, 2).join('.')}.`;
+
+export class Registry implements Catalogue {
+  readonly #classes = new Map<string, BeingClass>();
+  readonly #modules = new Map<string, string[]>();
+
+  // `kit` holds the kit's own classes, which alone may be of its kinds.
+  constructor(kit: readonly BeingClass[], modules: readonly Module[]) {
+    const contracts = new Map<string, unknown>();
+    const owners = new Map<string, string>();
+    const add = (C: BeingClass, kind: string): void => {
+      if (this.#classes.has(kind) && this.#classes.get(kind) !== C) throw new Error(`two classes are of kind ${kind}`);
+      this.#classes.set(kind, C);
+    };
+    for (const C of kit) add(C, kindOf(C));
+    for (const m of modules) {
+      if (!isKind(m.module) || m.module.startsWith(KIT)) throw new Error(`module ${String(m.module)} is no name a module may take`);
+      if (this.#modules.has(m.module)) throw new Error(`two modules are named ${m.module}`);
+      if (typeof m.version !== 'string' || m.version === '') throw new Error(`module ${m.module} declares no version`);
+      const kinds: string[] = [];
+      for (const C of m.classes) {
+        if (typeof C !== 'function') throw new Error(`module ${m.module} holds something that is no class`);
+        const kind = kindOf(C);
+        if (!kind.startsWith(domainOf(m.module))) throw new Error(`kind ${kind} is outside module ${m.module}`);
+        const owner = owners.get(kind);
+        if (owner !== undefined && owner !== m.module) throw new Error(`kind ${kind} is in modules ${owner} and ${m.module}`);
+        owners.set(kind, m.module);
+        add(C as BeingClass, kind);
+        kinds.push(kind);
+        if (!Faculty.fulfils(C)) continue;
+        for (let c: unknown = Object.getPrototypeOf(C); c !== Faculty; c = Object.getPrototypeOf(c)) {
+          const contract = kindOf(c);
+          if (contract.startsWith(KIT)) throw new Error(`kind ${contract} is the kit's`);
+          if (contracts.has(contract) && contracts.get(contract) !== c) throw new Error(`two contracts are of kind ${contract}`);
+          contracts.set(contract, c);
+        }
+      }
+      this.#modules.set(m.module, kinds);
+    }
+    for (const kind of contracts.keys()) {
+      if (this.#classes.has(kind)) throw new Error(`kind ${kind} is a class and a contract`);
+    }
+  }
+
+  classOf(kind: string): BeingClass | undefined {
+    return this.#classes.get(kind);
+  }
+
+  // The kinds a module stands, or none.
+  kindsOf(module: string): string[] {
+    return [...(this.#modules.get(module) ?? [])];
+  }
+}