nervur 0.19.2 → 0.20.0

package/dist/ward/index.d.ts

@@ -1,10 +1,5 @@
-export { Ward } from './ward.ts';
-export type { Ground, WardPointers, Memory } from './ground.ts';
-export { BOX, OFFER, RETRACT, volatile } from './ground.ts';
-export type { Partition, Heir, Bind, StandingKeys } from './partition.ts';
-export { GONE, MINTED, KNOCKS } from './partition.ts';
-export type { AskPayload, ReplyPayload } from './seal.ts';
-export * as seal from './seal.ts';
-export * as arithmetic from './arithmetic.ts';
-export { allow, spent, DEFAULT, CEILING } from './allowance.ts';
-export type { Allowance } from './allowance.ts';
+export { allow, CEILING, DEFAULT } from './allowance.ts';
+export { HEAD_ROW, Partition, type BeingRow, type Head, type StandingRow } from './partition.ts';
+export { DEPTH } from './stance.ts';
+export { DOCK, Ward, type Catalogue, type Lender, type WardParts } from './ward.ts';
+export { ownerAsk, pilots, WardBeing, type Steward, type WardBeingStance } from './ward-being.ts';

package/dist/ward/index.js

@@ -1,14 +1,7 @@
 // SPDX-License-Identifier: Apache-2.0
-// nervur/ward — one function. Every ward is the same ward.
-export { Ward } from './ward.js';
-export { BOX, OFFER, RETRACT, volatile } from './ground.js';
-// The three bounds on what a partition may hold, for a kit that must keep
-// the same ones and for a test that pins them.
-export { GONE, MINTED, KNOCKS } from './partition.js';
-// The seal and the arithmetic, for a kit in another language to check its
-// bytes against, and for tests that speak to a door directly.
-export * as seal from './seal.js';
-export * as arithmetic from './arithmetic.js';
-// The allowance every ask carries, for a kit in another language and for
-// tests that speak to a door directly.
-export { allow, spent, DEFAULT, CEILING } from './allowance.js';
+// The ward: its partition, its stances, its ward-being, and the ward.
+export { allow, CEILING, DEFAULT } from './allowance.js';
+export { HEAD_ROW, Partition } from './partition.js';
+export { DEPTH } from './stance.js';
+export { DOCK, Ward } from './ward.js';
+export { ownerAsk, pilots, WardBeing } from './ward-being.js';

package/dist/ward/partition.d.ts

@@ -1,65 +1,49 @@
-import type { Cells } from '../being/types.ts';
-export declare const VERSION = "pre-1.0.0";
-export declare const READS: readonly string[];
-export type Heir = {
-    being: string;
-    id: string;
-    current: string;
-    announced: string | null;
-    fresh: boolean;
-    mark: number;
-    spent: number[];
-    last?: {
-        seq: number;
-        reply: string;
-    };
-};
-export type StandingKeys = {
-    ward: string;
-    heir: string | null;
-    current: string;
-    next: string | null;
-    seq: number;
-};
-export type Bind = {
-    standings: Record<string, StandingKeys>;
-    occupants: Record<string, string>;
-    knocks: Record<string, {
-        current: string;
-        next: string | null;
-        spoke: boolean;
-        sent: boolean;
-        seq: number;
+import type { Lock } from '../crypto/index.ts';
+import { type HeirRecord, type Invitation, type KeptLock, type Relations, type StandingState } from '../quo/index.ts';
+import type { Rows } from '../contract/index.ts';
+import type { JsonObject } from '../being/index.ts';
+export declare const HEAD_ROW = "";
+export type Head = {
+    lock?: KeptLock;
+    heirs: Record<string, HeirRecord>;
+    gone: string[];
+    bind: Record<string, {
+        being: string;
+        id: string;
     }>;
-    answered: Record<string, true>;
-    minted: string[];
+    public: string | null;
 };
-export type Gone = {
-    current: string;
-    announced: string | null;
+export type StandingRow = {
+    invitation: Invitation;
+    state: StandingState;
+    seen: string | null;
 };
-export declare const GONE = 256;
-export declare const MINTED = 8;
-export declare const KNOCKS = 64;
-export declare const prune: (knocks: Record<string, unknown>, answered: Record<string, true>) => void;
-export type Partition = {
-    version: string;
-    beings: Record<string, Cells & {
-        class?: string;
+export type BeingRow = {
+    class: string;
+    cells: JsonObject;
+    occupants: Record<string, {
+        heir: string;
+        notes: JsonObject;
     }>;
-    bind: Record<string, Bind>;
-    heirs: Record<string, Heir>;
-    gone: Record<string, Gone>;
-    public: string | null;
+    standings: Record<string, StandingRow>;
 };
-export declare function open(memory: Record<string, unknown>): Partition;
-export declare const at: <T>(rec: Record<string, T>, key: string) => T | undefined;
-export declare const put: <T>(rec: Record<string, T>, key: string, value: T) => T;
-export declare const drop: (rec: Record<string, unknown>, key: string) => void;
-export declare const emptyCells: () => Cells;
-export declare const emptyBind: () => Bind;
-export declare const HEAD = "";
-export declare const rowOf: (p: Partition, row: string) => Record<string, unknown> | undefined;
-export declare const rowsIn: (p: Record<string, unknown>) => string[];
-export declare const restoreRow: (p: Partition, row: string, value: Record<string, unknown> | undefined) => void;
-export declare const fromRows: (rows: Record<string, Record<string, unknown>>) => Record<string, unknown>;
+export declare class Partition {
+    readonly memory: Rows;
+    constructor(memory: Rows);
+    get head(): Head;
+    get beings(): Record<string, BeingRow>;
+    being(key: string): BeingRow | undefined;
+    told(key: string): void;
+    toldHead(): void;
+    kept(): Promise<boolean>;
+}
+export declare class PartitionRelations implements Relations {
+    #private;
+    constructor(partition: Partition);
+    lock(): Lock | undefined;
+    setLock(lock: Lock): void;
+    get(heir: string): HeirRecord | undefined;
+    set(heir: string, record: HeirRecord): void;
+    delete(heir: string): void;
+    kept(): Promise<boolean>;
+}

package/dist/ward/partition.js

@@ -1,295 +1,66 @@
-// SPDX-License-Identifier: Apache-2.0
-// The partition. The ward's cells, all the way down. Values only, so the
-// harbor may persist it as it likes. Everything durable a ward has is here,
-// every secret included. Nothing here is ever in a being's cells.
-import { unguarded } from './cells.js';
-// The shape of everything below. A ward stamps what it writes and refuses
-// what it cannot read: the partition outlives the ward that wrote it, and a
-// ward that guessed at a shape it did not know would not fail, it would answer
-// wrongly on relations it had silently misread.
-//
-// One value, and it does not move until 1.0.0. Before a release there is
-// nobody holding a partition of another shape to tell apart: if the types
-// below change, the partition is thrown away, not migrated to and not counted.
-// A number that climbed with every change would be a changelog, and the only
-// question asked here is answered by equality — is this a partition this ward
-// can read. At 1.0.0 this changes once, and from then on it means something.
-export const VERSION = 'pre-1.0.0';
-// Every version this ward can read, newest last. Today it is one, and the
-// seam below is what makes it able to be more than one later: a partition
-// written under an older readable version is carried forward by `upgrade`
-// before the ward touches it. The seam is here before 1.0.0 because after
-// 1.0.0 there is nowhere to put it. A partition holds every secret and every
-// relation a world has, so the first shape change after the freeze cannot be
-// answered by throwing it away, and a ward that meets a shape it has no seam
-// for refuses to boot with everything still inside it.
-export const READS = [VERSION];
-// Carry a partition written under an older readable version forward to this
-// one. There is nothing to carry today, because READS has one member. Each
-// step added here is from one member of READS to the next.
-function upgrade(p) {
-    return p;
-}
-export const GONE = 256;
-// The last few pks a relation minted, and no more. A relation rotates on
-// every ask, so a list of all of them is a partition that grows for as long
-// as she keeps talking and can never be written down. It lives here, beside
-// the other bound on the durable shape, because it is a fact about what a
-// partition may hold and not about how a ward mints.
-export const MINTED = 8;
-// A knock record is a key she minted for one invitation, kept until she takes
-// it. Only take deletes one, so a being who knocks and never takes would grow
-// her bind table for the life of the ward, one secret seed at a time. The
-// list is bounded like `gone`: past the count the oldest go, and a relation
-// that answered outlives one that never did, since an answered knock is one
-// she may still take.
-export const KNOCKS = 64;
-export const prune = (knocks, answered) => {
-    const names = Object.keys(knocks);
-    if (names.length <= KNOCKS)
-        return;
-    const order = [...names.filter((n) => !answered[n]), ...names.filter((n) => answered[n])];
-    for (const old of order.slice(0, names.length - KNOCKS)) {
-        delete knocks[old];
-        delete answered[old];
+import { GONE, keptLock, lockOf } from '../quo/index.js';
+export const HEAD_ROW = '';
+export class Partition {
+    memory;
+    constructor(memory) {
+        this.memory = memory;
+        const rows = memory.rows;
+        rows.ward ??= { heirs: {}, gone: [], bind: {}, public: null };
+        rows.beings ??= {};
     }
-};
-// The shape, read before anything acts on it. A partition this ward wrote is
-// this shape by construction; one it adopted was written by a hand, another
-// kit, or a file that was cut short, and every field below is one the ward,
-// the door or the heirs then act on without looking again. A `spent` that is
-// not an array rejects the door's promise on the first bound ask, a `mark`
-// that is not a number honours every number ever sent and grows without
-// bound, a being row that is null refuses the whole ward at birth by
-// accident and says nothing about why. So the shape is read once, here, and
-// what is not it throws with the path that failed, which names the trouble
-// to whoever is holding the file.
-//
-// The rule, so the reader does not grow into a schema: read every field the
-// ward acts on, and refuse only what would make it act wrongly. So `minted`
-// must be a list, because she pushes to it, and the truth in `answered` is
-// not read, because anything there says answered and nothing else follows.
-// `last` is reserved and nobody reads it, so nobody reads its shape either;
-// the run that gives it a reader gives it a line here. A being's own cells
-// are hers, of any shape JSON carries, and only the two records the ward
-// keeps inside them are read.
-const fault = (path, want) => {
-    throw new Error(`partition ${path} is not ${want}`);
-};
-const table = (v, path) => (typeof v === 'object' && v !== null && !Array.isArray(v) ? v : fault(path, 'an object'));
-const list = (v, path) => (Array.isArray(v) ? v : fault(path, 'an array'));
-const text = (v, path) => void (typeof v === 'string' || fault(path, 'a string'));
-const orNull = (v, path) => void (v === null || typeof v === 'string' || fault(path, 'a string or null'));
-const whole = (v, path) => void (Number.isSafeInteger(v) || fault(path, 'a whole number'));
-const flag = (v, path) => void (typeof v === 'boolean' || fault(path, 'true or false'));
-function read(p) {
-    for (const [key, cells] of Object.entries(table(p.beings, 'beings'))) {
-        const c = table(cells, `beings.${key}`);
-        table(c.standings, `beings.${key}.standings`);
-        table(c.occupants, `beings.${key}.occupants`);
-        if (c.class !== undefined)
-            text(c.class, `beings.${key}.class`);
+    get head() {
+        return this.memory.rows.ward;
     }
-    for (const [key, bind] of Object.entries(table(p.bind, 'bind'))) {
-        const b = table(bind, `bind.${key}`);
-        for (const [id, keys] of Object.entries(table(b.standings, `bind.${key}.standings`))) {
-            const w = `bind.${key}.standings.${id}`;
-            const s = table(keys, w);
-            text(s.ward, `${w}.ward`);
-            orNull(s.heir, `${w}.heir`);
-            text(s.current, `${w}.current`);
-            orNull(s.next, `${w}.next`);
-            whole(s.seq, `${w}.seq`);
-        }
-        for (const [id, pk] of Object.entries(table(b.occupants, `bind.${key}.occupants`)))
-            text(pk, `bind.${key}.occupants.${id}`);
-        for (const [name, keys] of Object.entries(table(b.knocks, `bind.${key}.knocks`))) {
-            const w = `bind.${key}.knocks.${name}`;
-            const k = table(keys, w);
-            text(k.current, `${w}.current`);
-            orNull(k.next, `${w}.next`);
-            flag(k.spoke, `${w}.spoke`);
-            flag(k.sent, `${w}.sent`);
-            whole(k.seq, `${w}.seq`);
-        }
-        table(b.answered, `bind.${key}.answered`);
-        for (const [i, pk] of list(b.minted, `bind.${key}.minted`).entries())
-            text(pk, `bind.${key}.minted[${i}]`);
+    get beings() {
+        return this.memory.rows.beings;
     }
-    for (const [pk, heir] of Object.entries(table(p.heirs, 'heirs'))) {
-        const h = table(heir, `heirs.${pk}`);
-        text(h.being, `heirs.${pk}.being`);
-        text(h.id, `heirs.${pk}.id`);
-        text(h.current, `heirs.${pk}.current`);
-        orNull(h.announced, `heirs.${pk}.announced`);
-        flag(h.fresh, `heirs.${pk}.fresh`);
-        whole(h.mark, `heirs.${pk}.mark`);
-        for (const [i, n] of list(h.spent, `heirs.${pk}.spent`).entries())
-            whole(n, `heirs.${pk}.spent[${i}]`);
+    being(key) {
+        return Object.hasOwn(this.beings, key) ? this.beings[key] : undefined;
     }
-    for (const [pk, gone] of Object.entries(table(p.gone, 'gone'))) {
-        const g = table(gone, `gone.${pk}`);
-        text(g.current, `gone.${pk}.current`);
-        orNull(g.announced, `gone.${pk}.announced`);
+    told(key) {
+        this.memory.told(key);
     }
-    orNull(p.public, 'public');
-    return p;
-}
-// The one place a ward reads state that another ward wrote. A fresh
-// memory becomes a partition of this version; anything already written must
-// say it is this version and be the shape this version names, and a ward that
-// cannot read it does not boot. Birth is where a ward is allowed to be loud:
-// silence is the door's word, for asks that were made, and no ask has been
-// made yet.
-export function open(memory) {
-    const p = memory;
-    if (Object.keys(memory).length > 0 && p.version !== VERSION) {
-        if (!READS.includes(p.version))
-            throw new Error(`partition is version ${p.version}, this ward reads ${READS.join(', ')}`);
-        upgrade(p).version = VERSION;
+    toldHead() {
+        this.memory.told(HEAD_ROW);
+    }
+    kept() {
+        return this.memory.kept().catch(() => false);
     }
-    p.version ??= VERSION;
-    p.beings ??= {};
-    p.bind ??= {};
-    p.heirs ??= {};
-    p.gone ??= {};
-    p.public ??= null;
-    return read(p);
 }
-// One record, reached by a key a being or an owner chose. A bare lookup finds
-// every name on Object's prototype, so `__proto__` answers with the prototype
-// itself: read, it is there where nothing was put; written, it reaches every
-// object alive in the runtime. Own keys only, both ways, and a write that
-// names one of those lands on the record where it belongs.
-export const at = (rec, key) => (Object.hasOwn(rec, key) ? rec[key] : undefined);
-export const put = (rec, key, value) => {
-    Object.defineProperty(rec, key, { value, writable: true, enumerable: true, configurable: true });
-    return value;
-};
-export const drop = (rec, key) => {
-    if (Object.hasOwn(rec, key))
-        delete rec[key];
-};
-export const emptyCells = () => ({ standings: {}, occupants: {} });
-export const emptyBind = () => ({ standings: {}, occupants: {}, knocks: {}, answered: {}, minted: [] });
-// ---- the partition in rows, for a store that keeps it
-//
-// A ward hands a harbor one object, so a being who writes one cell has every
-// other being in her ward written down beside her. What a being holds is the
-// one thing here that grows without limit, so she is a row: her cells and her
-// bind table, under her key. Everything else is one head row, and every part
-// of it is bounded already, one record per occupant and two lists that drop
-// their oldest.
-//
-// The split is here, where the shape is, and not in the harbor, which keeps
-// what it is given and reads none of it. A store is handed the rows that
-// moved; what it does with that is its own, and one that writes every row is
-// as correct as one that writes the few.
-export const HEAD = ''; // the row that is not a being: no being's key is empty
-// What a put back never moves: the two sides of a relation. `beings` and
-// `bind` are the tables the rows hang under and are never written whole.
-// `heirs` and `gone` are the door's side of every relation this ward holds,
-// and a being's own `bind` row is her side of hers.
-//
-// A relation cannot be put back, only broken. Her keys rotate when a reply
-// opens and the door's rotate when it honours, so the two move at different
-// moments and neither side holds the seed of a key it has moved past. Stand
-// either one at an earlier moment and it speaks under a key the other will
-// not admit, with no way back: the seed is gone. The count needs no help
-// here, because a door honours any unseen number inside its span and a
-// caller's count climbs at every attempt, so numbers find each other again
-// on their own. Keys do not.
-//
-// Ahead of the device is survivable and behind the far side is not, so what
-// a refusal puts back is what a being wrote and never what her relations are
-// standing on. What it costs is that her keys are then ahead of what the
-// store kept, which a restart can undo: a smaller hole, and the same one a
-// restart has anyway.
-const STANDING = new Set(['beings', 'bind', 'heirs', 'gone']);
-// One row's value: a being, or the head, which is everything the partition
-// holds that is not filed under a being. The head is read as what is left
-// rather than as a list of names, so a store keeps whatever it was handed and
-// hands the same thing back, and a field this file grows later needs no line
-// in a store to survive a round trip.
-//
-// Undefined where the key names nobody, which is a row the store drops.
-export const rowOf = (p, row) => {
-    const all = p;
-    if (row === HEAD)
-        return Object.fromEntries(Object.entries(all).filter(([k]) => k !== 'beings' && k !== 'bind'));
-    const cells = at(p.beings ?? {}, row);
-    return cells === undefined ? undefined : { cells, bind: at(p.bind ?? {}, row) ?? emptyBind() };
-};
-export const rowsIn = (p) => [HEAD, ...Object.keys(p.beings ?? {})];
-// One row put back to what a store holds for it. A store that refused a row
-// left the ward's memory ahead of the device, and everything written to that
-// being afterwards would be lost at the next reload while she went on
-// answering out of a memory nobody keeps. So the row is written back to the
-// last value that was kept, and she stands at what is on the device.
-//
-// In place, always. A booted being holds her cells and her bind table by
-// reference: her stance, her guard and her door all point at the objects the
-// partition already has, so a row replaced by a fresh object would strand her
-// on cells nothing keeps. Only the head may be written whole, because
-// everything under it is read through the partition each time.
-//
-// A row the store does not hold is a being it never kept, and what is kept
-// for her is nothing: her row goes, the way the store's own is already gone.
-export const restoreRow = (p, row, value) => {
-    const all = p;
-    if (row === HEAD) {
-        for (const k of Object.keys(all))
-            if (!STANDING.has(k))
-                drop(all, k);
-        for (const [k, v] of Object.entries(value ?? {}))
-            if (!STANDING.has(k))
-                put(all, k, v);
-        return;
+// The door's memory, written into the head.
+export class PartitionRelations {
+    #partition;
+    constructor(partition) {
+        this.#partition = partition;
+    }
+    get #head() {
+        return this.#partition.head;
     }
-    if (value === undefined) {
-        drop(p.beings ?? {}, row);
-        // Her bind goes with her: a being the store never kept has no relation
-        // anybody is standing on, so there is nothing to leave forward.
-        drop(p.bind ?? {}, row);
-        return;
+    lock() {
+        return lockOf(this.#head.lock);
     }
-    // Behind the guard and never through it: a being's cells in a partition
-    // are the guarded object her stance writes through, and the guard is hers.
-    // What the harbor puts back is not a write of hers, so it says nothing to
-    // the ward and marks nothing dirty.
-    const into = (rows, kept) => {
-        const guarded = at(rows, row);
-        if (guarded === undefined)
-            return void put(rows, row, kept);
-        const held = unguarded(guarded);
-        for (const k of Object.keys(held))
-            drop(held, k);
-        for (const [k, v] of Object.entries(kept))
-            put(held, k, v);
-    };
-    into(p.beings ?? {}, (value.cells ?? emptyCells()));
-};
-// The partition back from its rows. A head that is absent is a partition
-// nobody has written, and `open` makes an empty one of it.
-export const fromRows = (rows) => {
-    const out = { ...(rows[HEAD] ?? {}) };
-    const beings = {};
-    const bind = {};
-    let any = Object.keys(out).length > 0;
-    for (const [row, value] of Object.entries(rows)) {
-        if (row === HEAD)
-            continue;
-        put(beings, row, value.cells);
-        put(bind, row, value.bind);
-        any = true;
+    setLock(lock) {
+        this.#head.lock = keptLock(lock);
+        this.#partition.toldHead();
     }
-    // Nothing kept is nothing handed back. Rows that say only that there are no
-    // rows must come back as the empty memory they are, because `open` reads an
-    // empty one as a ward's first breath and anything else as a partition
-    // somebody wrote, which must then say which version wrote it.
-    if (!any)
-        return {};
-    out.beings = beings;
-    out.bind = bind;
-    return out;
-};
+    get(heir) {
+        return Object.hasOwn(this.#head.heirs, heir) ? this.#head.heirs[heir] : undefined;
+    }
+    set(heir, record) {
+        const head = this.#head;
+        head.heirs[heir] = record;
+        if (record.state === 'kept') {
+            head.gone.push(heir);
+            while (head.gone.length > GONE)
+                delete head.heirs[head.gone.shift()];
+        }
+        this.#partition.toldHead();
+    }
+    delete(heir) {
+        delete this.#head.heirs[heir];
+        this.#partition.toldHead();
+    }
+    kept() {
+        return this.#partition.kept();
+    }
+}

package/dist/ward/stance.d.ts

@@ -1,20 +1,29 @@
-import type { Cells, Invitation, JsonObject, Silence, Stance, Wanted, Word } from '../being/types.ts';
-import { type Bind, type StandingKeys } from './partition.ts';
-import { type ReplyPayload } from './seal.ts';
-export type Inside = {
-    pk: string;
-    live(): boolean;
-    mintKey(bind: Bind): Promise<{
-        seed: string;
-        pk: string;
-    }>;
-    openHeir(heir: string, being: string, id: string): void;
-    closeHeir(heir: string): void;
-    send(bind: Bind, keys: StandingKeys, method: string | undefined, args: JsonObject, wanted: Wanted | undefined): Promise<ReplyPayload | Silence | Word>;
-    instantiate(className: string, key: string): string | null;
-    relate(key: string, id: string): Promise<Invitation | null>;
-    lend(name: string, take: (invitation: Invitation) => Promise<boolean>): Promise<boolean>;
-    unmake(key: string): void;
-    wrote(): void;
-};
-export declare function buildStance(inside: Inside, key: string, cells: Cells, bind: Bind): Stance;
+import { type Door, type Draw, type Invitation } from '../quo/index.ts';
+import type { Clock } from '../contract/index.ts';
+import { type JsonObject, type Occupants, type Stance, type Standings } from '../being/index.ts';
+import type { BeingRow, Partition } from './partition.ts';
+import { DEPTH } from './cells.ts';
+export { DEPTH };
+export interface Inside {
+    readonly partition: Partition;
+    readonly door: Door;
+    readonly draw: Draw;
+    readonly clock: Clock;
+    live(key: string, row: BeingRow): boolean;
+    send(pk: string, bytes: Uint8Array): Promise<Uint8Array | null>;
+    boot(maker: string, className: string, key: string, id?: string): Promise<string | null>;
+    offer(contract: string): Promise<Invitation | null>;
+    retract(contract: string, heir: string): Promise<void>;
+}
+export declare class WardStance implements Stance {
+    #private;
+    readonly key: string;
+    readonly occupants: Occupants;
+    readonly standings: Standings;
+    constructor(inside: Inside, key: string, row: BeingRow);
+    get cells(): JsonObject;
+    boot(className: string, key: string, id?: string): Promise<string | null>;
+    lend(contract: {
+        readonly name: string;
+    }, id: string): Promise<string | null>;
+}