nervur 0.19.2 → 0.20.0

package/src/ward/partition.ts

@@ -1,353 +1,113 @@
 // 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.ts';
-import type { Cells } from '../being/types.ts';
-
-// 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.
+// The partition: everything one ward keeps, as rows of values in the memory
+// its terrain opened for it.
 //
-// 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: readonly string[] = [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: Partition): Partition {
-  return p;
-}
-
-// One occupant, as the door knows her: by the heir pk her invitation carried.
-// `current` is the pk that may speak now. `announced` is the pk `current`
-// vouched for on its last call, and may speak next. Both may speak until one
-// does, so a lost reply after a rotation strands nobody. `fresh` is true
-// until the knock: the heir is a key the inviter handed out, and it dies the
-// moment it is used.
-export type Heir = {
-  being: string; // the key of the being who minted the id
-  id: string; // her id for the occupant
-  current: string; // pk hex
-  announced: string | null; // pk hex
-  fresh: boolean;
-  // Once-only delivery. The highest number honoured, and which numbers below
-  // it are already spent. Durable, because a door that forgets what it
-  // honoured honours it again after a restart.
-  mark: number;
-  spent: number[];
-  // Reserved, and nothing writes it. A door refuses a number at or below the
-  // span, which is right for an accident and for an interception. A kit that
-  // grows retry may want the other answer, giving back what it already said
-  // rather than one silence, and that answer has to live somewhere durable.
-  // The slot is cut now because a Heir that grows a field after 1.0.0 is a
-  // partition shape change, and this is the cheapest thing in this file.
-  last?: { seq: number; reply: string };
-};
-
-// One standing, as the caller's ward keeps it: where to send, how to seal,
-// which key to sign with, and the key it has announced for next time.
-export type StandingKeys = {
-  ward: string; // the far ward's pk, 128 hex: signing pk then padlock
-  heir: string | null; // the heir pk this standing was born on. null: the far ward's public being
-  current: string; // seed hex of the signing key that speaks now
-  next: string | null; // seed hex of the key announced on the last call, if any
-  seq: number; // the last number she spoke under. the next call is this plus one
+//   rows.ward           the door's lock, heirs and gone, which being and id
+//                       each heir belongs to, and the public being
+//   rows.beings[key]    one being: her class, cells, occupants and standings
+//
+// The ward writes into the rows directly and tells the memory which row it
+// wrote: the head as the empty name, which no being's key is, or the
+// being's key.
+import type { Lock } from '../crypto/index.ts';
+import { GONE, keptLock, lockOf, 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 const HEAD_ROW = '';
+
+export type Head = {
+  lock?: KeptLock;
+  heirs: Record<string, HeirRecord>;
+  gone: string[];
+  bind: Record<string, { being: string; id: string }>;
+  public: string | null;
 };
 
-export type Bind = {
-  standings: Record<string, StandingKeys>; // id -> keys
-  occupants: Record<string, string>; // id -> heir pk
-  knocks: Record<string, { current: string; next: string | null; spoke: boolean; sent: boolean; seq: number }>; // <ward pk>:<heir pk>, or public:<ward pk> -> her keys for a knock, before take. spoke: bytes came back once. sent: bytes went out once, answered or not
-  answered: Record<string, true>; // <ward pk>:<heir pk>, or public:<ward pk>: knocked and answered
-  minted: string[]; // the last eight pks her side minted. nothing in the ward reads it: it is there to be looked at, and a kit that keeps it empty holds the same ward
+export type StandingRow = { invitation: Invitation; state: StandingState; seen: string | null };
+export type BeingRow = {
+  class: string;
+  cells: JsonObject;
+  occupants: Record<string, { heir: string; notes: JsonObject }>;
+  standings: Record<string, StandingRow>;
 };
 
-// A relation she removed, as the door remembers it: the keys that may still
-// speak for it, so their holder hears `removed` and a stranger still hears
-// silence. Nothing else survives the removal. The list is bounded, oldest
-// out, because a door that remembered every relation ever ended would grow
-// for as long as she keeps inviting.
-export type Gone = { current: string; announced: string | null };
-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;
+export class Partition {
+  readonly memory: Rows;
 
-// 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: Record<string, unknown>, answered: Record<string, true>): void => {
-  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];
+  constructor(memory: Rows) {
+    this.memory = memory;
+    const rows = memory.rows as { ward?: Head; beings?: Record<string, BeingRow> };
+    rows.ward ??= { heirs: {}, gone: [], bind: {}, public: null };
+    rows.beings ??= {};
   }
-};
 
-export type Partition = {
-  version: string;
-  beings: Record<string, Cells & { class?: string }>; // key -> her cells
-  bind: Record<string, Bind>; // key -> her bind table
-  heirs: Record<string, Heir>; // heir pk -> occupant, across every being of the ward
-  gone: Record<string, Gone>; // heir pk -> the last keys of a relation she removed
-  public: string | null; // the one public being's key
-};
+  get head(): Head {
+    return this.memory.rows.ward as Head;
+  }
 
-// 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: string, want: string): never => {
-  throw new Error(`partition ${path} is not ${want}`);
-};
-const table = (v: unknown, path: string): Record<string, unknown> => (typeof v === 'object' && v !== null && !Array.isArray(v) ? (v as Record<string, unknown>) : fault(path, 'an object'));
-const list = (v: unknown, path: string): unknown[] => (Array.isArray(v) ? (v as unknown[]) : fault(path, 'an array'));
-const text = (v: unknown, path: string): void => void (typeof v === 'string' || fault(path, 'a string'));
-const orNull = (v: unknown, path: string): void => void (v === null || typeof v === 'string' || fault(path, 'a string or null'));
-const whole = (v: unknown, path: string): void => void (Number.isSafeInteger(v) || fault(path, 'a whole number'));
-const flag = (v: unknown, path: string): void => void (typeof v === 'boolean' || fault(path, 'true or false'));
+  get beings(): Record<string, BeingRow> {
+    return this.memory.rows.beings as Record<string, BeingRow>;
+  }
 
-function read(p: Partition): Partition {
-  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`);
+  being(key: string): BeingRow | undefined {
+    return Object.hasOwn(this.beings, key) ? this.beings[key] : undefined;
   }
-  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}]`);
+
+  told(key: string): void {
+    this.memory.told(key);
   }
-  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}]`);
+
+  toldHead(): void {
+    this.memory.told(HEAD_ROW);
   }
-  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`);
+
+  kept(): Promise<boolean> {
+    return this.memory.kept().catch(() => false);
   }
-  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: Record<string, unknown>): Partition {
-  const p = memory as Partition;
-  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;
+// The door's memory, written into the head.
+export class PartitionRelations implements Relations {
+  readonly #partition: Partition;
+
+  constructor(partition: Partition) {
+    this.#partition = partition;
   }
-  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 = <T>(rec: Record<string, T>, key: string): T | undefined => (Object.hasOwn(rec, key) ? rec[key] : undefined);
-export const put = <T>(rec: Record<string, T>, key: string, value: T): T => {
-  Object.defineProperty(rec, key, { value, writable: true, enumerable: true, configurable: true });
-  return value;
-};
-export const drop = (rec: Record<string, unknown>, key: string): void => {
-  if (Object.hasOwn(rec, key)) delete rec[key];
-};
+  get #head(): Head {
+    return this.#partition.head;
+  }
 
-export const emptyCells = (): Cells => ({ standings: {}, occupants: {} });
-export const emptyBind = (): Bind => ({ standings: {}, occupants: {}, knocks: {}, answered: {}, minted: [] });
+  lock(): Lock | undefined {
+    return lockOf(this.#head.lock);
+  }
 
-// ---- 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']);
+  setLock(lock: Lock): void {
+    this.#head.lock = keptLock(lock);
+    this.#partition.toldHead();
+  }
 
-// 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: Partition, row: string): Record<string, unknown> | undefined => {
-  const all = p as unknown as Record<string, unknown>;
-  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: Record<string, unknown>): string[] => [HEAD, ...Object.keys((p.beings as Record<string, unknown>) ?? {})];
+  get(heir: string): HeirRecord | undefined {
+    return Object.hasOwn(this.#head.heirs, heir) ? this.#head.heirs[heir] : undefined;
+  }
 
-// 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: Partition, row: string, value: Record<string, unknown> | undefined): void => {
-  const all = p as unknown as Record<string, unknown>;
-  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;
+  set(heir: string, record: HeirRecord): void {
+    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();
   }
-  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;
+
+  delete(heir: string): void {
+    delete this.#head.heirs[heir];
+    this.#partition.toldHead();
   }
-  // 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: Record<string, unknown>, kept: Record<string, unknown>): void => {
-    const guarded = at(rows, row) as Cells | undefined;
-    if (guarded === undefined) return void put(rows, row, kept);
-    const held = unguarded(guarded) as unknown as Record<string, unknown>;
-    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()) as unknown as Record<string, unknown>);
-};
 
-// 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: Record<string, Record<string, unknown>>): Record<string, unknown> => {
-  const out: Record<string, unknown> = { ...(rows[HEAD] ?? {}) };
-  const beings: Record<string, unknown> = {};
-  const bind: Record<string, unknown> = {};
-  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;
+  kept(): Promise<boolean> {
+    return this.#partition.kept();
   }
-  // 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;
-};
+}