nervur 0.19.2 → 0.20.0

package/src/conformance/reach.ts

@@ -1,83 +0,0 @@
-// SPDX-License-Identifier: Apache-2.0
-// The reach conformance suite: what every reach must show, written against
-// the interface alone. A reach is handed in as a maker of a fresh line to a
-// far side the suite controls: `hold` puts a door behind a pk over there,
-// `drop` takes the far side away, the line down or the listener gone. The
-// suite asks for bytes and expects the door's bytes back, nothing for a pk
-// nobody holds, and nothing once the far side is gone. It cannot assert
-// that a reach which sent and then lost the line answers nothing at all,
-// since a suite cannot wait forever; that promise is read in the code.
-import { assert } from './assert.ts';
-import type { Reach } from '../harbor/reach.ts';
-import type { Runner } from './index.ts';
-
-export type FarSide = {
-  reach: Reach;
-  hold(pk: string, door: (bytes: Uint8Array) => Promise<Uint8Array>): Promise<void>;
-  drop(): Promise<void>;
-};
-
-const pk = (b: string) => b.repeat(64);
-const bytes = (...xs: number[]) => Uint8Array.from(xs);
-const wait = (ms: number) => new Promise<void>((ok) => setTimeout(ok, ms));
-
-export function conformReach(label: string, make: () => Promise<FarSide>, { test }: { test: Runner }) {
-  const t = (name: string, fn: () => Promise<void>) => test(`[${label}] ${name}`, {}, fn);
-
-  t('bytes to a pk the far side holds come back as the door answered', async () => {
-    const far = await make();
-    try {
-      await far.hold(pk('aa'), async (b) => bytes(...b, 9));
-      assert.deepEqual(await far.reach.carry(pk('aa'), bytes(1, 2, 3)), bytes(1, 2, 3, 9));
-    } finally {
-      await far.drop();
-    }
-  });
-
-  t('bytes to a pk nobody holds are nothing', async () => {
-    const far = await make();
-    try {
-      await far.hold(pk('aa'), async (b) => b);
-      assert.equal(await far.reach.carry(pk('bb'), bytes(1)), undefined);
-    } finally {
-      await far.drop();
-    }
-  });
-
-  t('asks in flight at once each get their own answer', async () => {
-    const far = await make();
-    try {
-      await far.hold(pk('aa'), async (b) => (await wait(b[0] * 10), bytes(b[0])));
-      const out = await Promise.all([far.reach.carry(pk('aa'), bytes(3)), far.reach.carry(pk('aa'), bytes(1)), far.reach.carry(pk('aa'), bytes(2))]);
-      assert.deepEqual(out, [bytes(3), bytes(1), bytes(2)]);
-    } finally {
-      await far.drop();
-    }
-  });
-
-  t('what comes back is a copy, and what was sent was one', async () => {
-    const far = await make();
-    try {
-      let seen: Uint8Array | undefined;
-      const reply = bytes(7, 7);
-      await far.hold(pk('aa'), async (b) => ((seen = b), reply));
-      const sent = bytes(4, 5);
-      const back = (await far.reach.carry(pk('aa'), sent))!;
-      assert.deepEqual(back, bytes(7, 7));
-      back[0] = 0;
-      assert.deepEqual(reply, bytes(7, 7), 'the caller wrote through to the door');
-      seen![0] = 0;
-      assert.deepEqual(sent, bytes(4, 5), 'the door wrote through to the caller');
-    } finally {
-      await far.drop();
-    }
-  });
-
-  t('once the far side is gone, bytes are nothing', async () => {
-    const far = await make();
-    await far.hold(pk('aa'), async (b) => b);
-    assert.deepEqual(await far.reach.carry(pk('aa'), bytes(1)), bytes(1));
-    await far.drop();
-    assert.equal(await far.reach.carry(pk('aa'), bytes(1)), undefined);
-  });
-}

package/src/conformance/store.ts

@@ -1,125 +0,0 @@
-// SPDX-License-Identifier: Apache-2.0
-// The store conformance suite: what every store must show, written against
-// the interface alone. A store is handed in as a maker of fresh ones: an
-// empty folder, a database nobody opened, a view of storage under a prefix
-// nobody used. Nothing here knows how a store keeps anything; it asks for
-// what it put and expects it back, as the harbor will.
-import { assert } from './assert.ts';
-import type { Kept, Store } from '../harbor/store.ts';
-import type { Runner } from './index.ts';
-
-const seed = (b: number) => new Uint8Array(32).fill(b);
-const kept = (b: number, extra: Record<string, unknown> = {}): Kept => ({ seed: seed(b), partition: { beings: {}, bind: {}, ...extra }, record: { pk: '', code: 'classes/index.ts', user: 'me' } });
-// A partition as a ward writes one: beings under their keys, a bind table
-// beside each, and whatever else the head carries.
-const ward = (beings: Record<string, unknown>, extra: Record<string, unknown> = {}): Record<string, unknown> => ({
-  beings,
-  bind: Object.fromEntries(Object.keys(beings).map((k) => [k, { standings: {} }])),
-  ...extra,
-});
-const ALL = (p: Record<string, unknown>): string[] => ['', ...Object.keys(p.beings as object)];
-
-export function conformStore(label: string, make: () => Promise<Store>, { test }: { test: Runner }) {
-  const t = (name: string, fn: () => Promise<void>) => test(`[${label}] ${name}`, {}, fn);
-
-  t('a fresh store keeps nothing', async () => {
-    const s = await make();
-    assert.deepEqual(await s.list(), []);
-    assert.equal(await s.load('main'), undefined);
-    assert.equal(await s.take('main'), undefined);
-  });
-
-  t('put, then load: seed, partition and record come back as they went in', async () => {
-    const s = await make();
-    await s.put('main', kept(7, { n: 1, deep: { list: [1, 'two', null], flag: true } }));
-    assert.deepEqual(await s.list(), ['main']);
-    const back = await s.load('main');
-    assert.ok(back);
-    assert.deepEqual(back.seed, seed(7));
-    assert.deepEqual(back.partition, { beings: {}, bind: {}, n: 1, deep: { list: [1, 'two', null], flag: true } });
-    assert.deepEqual(back.record, { pk: '', code: 'classes/index.ts', user: 'me' });
-  });
-
-  t('a name already kept is refused, and what was kept stands', async () => {
-    const s = await make();
-    await s.put('main', kept(1));
-    let refused = false;
-    try {
-      await s.put('main', kept(2));
-    } catch {
-      refused = true;
-    }
-    assert.ok(refused, 'a second put under one name must throw');
-    assert.deepEqual((await s.load('main'))!.seed, seed(1));
-  });
-
-  t('save writes every row it is given, and touches nothing else', async () => {
-    const s = await make();
-    await s.put('main', kept(3));
-    const p = ward({ a: { x: 1 } });
-    await s.save('main', p, ALL(p));
-    const back = (await s.load('main'))!;
-    assert.deepEqual(back.partition, p);
-    assert.deepEqual(back.seed, seed(3));
-    assert.deepEqual(back.record, kept(3).record);
-  });
-
-  // What a store may do with the rows it is told about is its own: writing
-  // the whole partition every time is correct. What it may never do is write
-  // less than it was told, or keep a being the rows say is gone.
-  t('save writes the rows it names, and a being the rows drop is gone', async () => {
-    const s = await make();
-    const p = ward({ a: { x: 1 }, b: { y: 1 } });
-    await s.put('main', { ...kept(3), partition: p });
-    // one being moves, and only her row is named
-    (p.beings as Record<string, { x: number }>).a.x = 2;
-    await s.save('main', p, ['a']);
-    assert.deepEqual((await s.load('main'))!.partition, p, 'the row that was named is written');
-    // she leaves: her row is named and her key is gone from the partition
-    delete (p.beings as Record<string, unknown>).a;
-    delete (p.bind as Record<string, unknown>).a;
-    await s.save('main', p, ['a']);
-    assert.deepEqual((await s.load('main'))!.partition, p, 'a row whose being is gone is dropped');
-  });
-
-  t('record replaces the record and touches nothing else', async () => {
-    const s = await make();
-    await s.put('main', kept(4, { n: 9 }));
-    await s.record('main', { pk: 'ab'.repeat(64), code: 'elsewhere.ts', user: 'her' });
-    const back = (await s.load('main'))!;
-    assert.deepEqual(back.record, { pk: 'ab'.repeat(64), code: 'elsewhere.ts', user: 'her' });
-    assert.deepEqual(back.partition, { beings: {}, bind: {}, n: 9 });
-  });
-
-  t('save and record on a name not kept are nothing', async () => {
-    const s = await make();
-    await s.save('ghost', { beings: {}, bind: {} }, ['']);
-    await s.record('ghost', { pk: '', code: '', user: '' });
-    assert.deepEqual(await s.list(), []);
-  });
-
-  t('the partition handed back is values, not the object that was put', async () => {
-    const s = await make();
-    const k = kept(5, { n: 1 });
-    await s.put('main', k);
-    (k.partition as { n: number }).n = 2;
-    assert.deepEqual((await s.load('main'))!.partition, { beings: {}, bind: {}, n: 1 });
-    const a = (await s.load('main'))!;
-    (a.partition as { n: number }).n = 3;
-    assert.deepEqual((await s.load('main'))!.partition, { beings: {}, bind: {}, n: 1 });
-  });
-
-  t('take hands the ward out and forgets it; the name is free again', async () => {
-    const s = await make();
-    await s.put('main', kept(6, { n: 6 }));
-    await s.put('other', kept(8));
-    const out = await s.take('main');
-    assert.ok(out);
-    assert.deepEqual(out.seed, seed(6));
-    assert.deepEqual(out.partition, { beings: {}, bind: {}, n: 6 });
-    assert.equal(await s.load('main'), undefined);
-    assert.deepEqual(await s.list(), ['other']);
-    await s.put('main', kept(9));
-    assert.deepEqual((await s.load('main'))!.seed, seed(9));
-  });
-}

package/src/harbor/box.ts

@@ -1,131 +0,0 @@
-// SPDX-License-Identifier: Apache-2.0
-// The box as one being. A harbor boots a ward of its own and one being in
-// it, the box's own, who holds a standing at every lent being the box
-// offers, under the name each is lent as, and keeps the roll of the wards
-// the box hosts. Every hosted ward is handed one invitation on her at boot
-// and takes it as its own standing; from then on the device is one
-// standing, what it offers is her describe, and a lend is the ask `offer`
-// on her.
-//
-// The harbor works in acts and holds no memory of its own. Act one boots the
-// box's ward on the plain ground, no box, because it is the box; her lent
-// beings come up, and the root places her standings and nothing else. Act
-// two asks her who is hosted and boots each with one invitation. Everything
-// the device is lives in her ward as a lent being's cells, placed through
-// asks and read from no file.
-//
-// A runtime that needs her to be more, a resolver of names or a carrier of
-// her lent beings' asks for a screen, extends her and overrides the asks.
-import { Being, isInvitation, OWNER } from '../being/index.ts';
-import { BOX } from '../being/lent.ts';
-import type { Asker, BeingClass, Invitation, JsonObject, OccupantRecord } from '../being/index.ts';
-import { OFFER, RETRACT, type WardPointers } from '../ward/ground.ts';
-
-// A ward as its root holds it: the ask pointer is all the acts need.
-export type Root = Pick<WardPointers, 'ask'>;
-
-export { BOX } from '../being/lent.ts';
-
-// The name of the box's own ward, one per harbor: the seed a memory harbor
-// boots it under, and the name a store keeps it by.
-export const BOX_SEED = 'box';
-
-// A ward the box vouches for: invited by the root at act two, with the one
-// note that says so. A screen or a model the root lets in has no such note
-// and is shown nothing of the lend seam.
-const ward = (occ: OccupantRecord | undefined) => occ?.notes.ward === true;
-const root = (_occ: OccupantRecord | undefined, asker: Asker) => asker.id === OWNER;
-
-export const BOX_ASKS = {
-  [OFFER]: { description: 'an invitation on the being lent under this name', input: { type: 'object', properties: { name: { type: 'string' } }, required: ['name'] }, for: ward },
-  [RETRACT]: { description: 'an offer under this name that was not taken, by its heir', input: { type: 'object', properties: { name: { type: 'string' }, heir: { type: 'string' } }, required: ['name', 'heir'] }, for: ward },
-  host: { description: 'a ward this box hosts from now', input: { type: 'object', properties: { seed: { type: 'string' } }, required: ['seed'] }, for: root },
-  roll: { description: 'the wards this box hosts', input: { type: 'object' }, for: root },
-};
-
-export class Box extends Being {
-  static override cells: JsonObject = { hosted: [], offers: {} };
-  static override asks = BOX_ASKS;
-
-  // Offer: the being under the name, asked to offer, answers her own
-  // invitation. A subclass that lends under more names than it holds
-  // standings, a contract's digest for one, resolves the name first and
-  // calls this with the standing's own.
-  async offer(args: JsonObject): Promise<JsonObject> {
-    const at = this.standings[args.name as string];
-    if (!at) return { error: 'lends none' };
-    const out = await at.ask(OFFER);
-    return isInvitation(out) ? out : { error: 'not offered' };
-  }
-
-  async retract(args: JsonObject): Promise<JsonObject> {
-    const at = this.standings[args.name as string];
-    if (!at) return { error: 'lends none' };
-    const out = await at.ask(RETRACT, { heir: args.heir as string });
-    return out !== null && typeof out === 'object' && !Array.isArray(out) ? out : { retracted: null };
-  }
-
-  // A ward on the roll, and its one invitation on her. She mints it the first
-  // time and keeps it, and hands the same one at every later boot until it
-  // is spent: a ward that could not take the box at birth, the box down or
-  // the knock lost, takes it at the next, as the spec promises. A ward that
-  // holds the standing already ignores it, and a spent heir opens no door,
-  // so handing it again costs nothing. The value never leaves her ward: it
-  // is read by the root alone and rides in the ground and nowhere else.
-  async host(args: JsonObject): Promise<JsonObject> {
-    const hosted = ((this.cells.hosted as string[] | undefined) ??= []);
-    const offers = ((this.cells.offers as Record<string, Invitation> | undefined) ??= {});
-    if (typeof args.seed !== 'string') return { error: 'a seed is a word' };
-    if (!hosted.includes(args.seed)) hosted.push(args.seed);
-    if (!Object.hasOwn(offers, args.seed)) {
-      const inv = await this.invite(args.seed, { ward: true });
-      if (inv !== null) offers[args.seed] = inv;
-    }
-    return { hosted: [...hosted], invitation: offers[args.seed] ?? null };
-  }
-
-  roll(): JsonObject {
-    return { hosted: [...((this.cells.hosted as string[] | undefined) ?? [])] };
-  }
-}
-
-// Act one's second half, on a box ward already booted: the box's being and
-// each lent being booted by key, and her standing placed at each under its
-// key by the root. A ward woken from its memory already holds all of it,
-// and a key already booted is refused and costs nothing, so this is run at
-// every boot and does the right thing at each.
-export async function stand(box: Root, lent: Record<string, BeingClass>, own = 'Box'): Promise<void> {
-  const up = async (key: string, cls: string) => {
-    const out = (await box.ask('boot', { key, class: cls })) as { booted?: string; error?: string };
-    return out.booted === key;
-  };
-  await up(BOX, own);
-  for (const name of Object.keys(lent)) {
-    const fresh = await up(name, lent[name].name);
-    if (!fresh) continue;
-    await hold(box, name);
-  }
-}
-
-// The box's standing at one lent being of her ward, under that being's key,
-// placed by the root: the lent being invites the box's being as `box`, and
-// she knocks. Refused where either already holds the relation.
-export async function hold(box: Root, key: string): Promise<boolean> {
-  const inv = await box.ask('invite', { being: key, id: BOX });
-  if (!isInvitation(inv)) return false;
-  const out = (await box.ask('knock', { being: BOX, id: key, invitation: inv as unknown as JsonObject })) as { taken?: unknown };
-  return out?.taken === key;
-}
-
-// One invitation on the box's being for the ward named, and the ward on the
-// roll: the same one at every boot, minted once by her and kept by her.
-export async function offerTo(box: Root, seed: string): Promise<Invitation | undefined> {
-  const out = (await box.ask('ask', { being: BOX, method: 'host', args: { seed } })) as { invitation?: unknown };
-  return isInvitation(out?.invitation) ? out.invitation : undefined;
-}
-
-// Who the box hosts, asked of the box's being.
-export async function roll(box: Root): Promise<string[]> {
-  const out = (await box.ask('ask', { being: BOX, method: 'roll' })) as { hosted?: string[] };
-  return out.hosted ?? [];
-}