@nervur-org/dock 0.3.0

package/beings/carry.ts

@@ -0,0 +1,159 @@
+// SPDX-License-Identifier: Apache-2.0
+// A carrier: a being who shows the asks of the standings she holds as asks
+// of her own, and forwards. Whoever she carries for sees, in one describe,
+// what she can be asked and what every being she holds can be asked, each
+// under that standing's name; asking one is an ask on that standing, in her
+// name, so the far being sees her and never who is behind her. A user being
+// carries acme for the human's devices; a house being could carry its
+// rooms; nothing here knows what she is.
+//
+// A carried ask is `<id>-<name>`, and the mapping back is kept in her cells
+// and never parsed from the name, so an id with a dash in it is no trouble.
+// The notes say which asks are whose, `standings: { id: { asks, look? } }`,
+// so a screen draws one section per standing and a model side keeps the
+// flat list it needs. Her own asks come first and are never shadowed: a
+// carried name that collides with one of hers is dropped.
+//
+// She asks a standing's describe again when its digest moved, and its
+// `look` once per digest, and keeps both in her cells. So a describe of
+// hers may cost one ask per stale standing, which is the price of a page
+// that is never more than one ask behind.
+import { Being, isSilence, isWord, wordOf } from '@nervur-org/nervur';
+import type { Asker, Blueprint, JsonObject, OccupantRecord, Reply } from '@nervur-org/nervur';
+import { sanitise, type Look } from './look.ts';
+
+type Carried = Record<string, { id: string; ask: string }>;
+type Looks = Record<string, { digest: string | null; look: Look }>;
+
+// The names a far being carries, read off her notes: every ask her
+// `standings` groups name, and each group's page. Empty when she carries
+// nothing, which a bare avatar does not.
+function carriedBy(bp: Blueprint): Set<string> {
+  const out = new Set<string>();
+  const notes = bp.notes;
+  const groups = notes !== null && typeof notes === 'object' && !Array.isArray(notes) ? (notes as { standings?: unknown }).standings : undefined;
+  if (!groups || typeof groups !== 'object' || Array.isArray(groups)) return out;
+  for (const g of Object.values(groups as Record<string, { asks?: unknown; page?: unknown }>)) {
+    if (Array.isArray(g?.asks)) for (const n of g.asks) if (typeof n === 'string') out.add(n);
+    if (typeof g?.page === 'string') out.add(g.page);
+  }
+  return out;
+}
+
+export class Carrier extends Being {
+  // Who sees what she carries. Nobody, until a subclass says who.
+  static carries(_occupant: OccupantRecord | undefined, _asker: Asker): boolean {
+    return false;
+  }
+  // Standings that are plumbing: their own asks are never carried, and
+  // what they carry is. A way back to a device is one, by the dock's own
+  // convention, so a bare avatar's inbox never shows on her and a presence
+  // being's faculties do, under `to:<id>-<name>`, which is how home carries
+  // her phone. A subclass may name more.
+  static hidden(id: string): boolean {
+    return id.startsWith('to:');
+  }
+  // Standings she never reads for carrying at all: a presence being's
+  // standing at her own user being is one, since carrying it would carry
+  // the user being's carrying of her, and round. None, until a subclass
+  // says which.
+  static skips(_id: string): boolean {
+    return false;
+  }
+  // Which of the standings she carries this asker may see. Every one,
+  // until a subclass keeps some for fewer: a user being shows her own door
+  // to a device that may mint and to nobody else.
+  static shows(_id: string, _occupant: OccupantRecord | undefined, _asker: Asker): boolean {
+    return true;
+  }
+
+  private get carried(): Carried {
+    return ((this.cells.carried as Carried | undefined) ??= {});
+  }
+  private get looks(): Looks {
+    return ((this.cells.looks as Looks | undefined) ??= {});
+  }
+
+  // Her describe with her standings carried into it, for an asker who may
+  // see them. Every other asker gets her describe alone.
+  async blueprint(asker: Asker): Promise<Blueprint> {
+    const C = this.constructor as typeof Carrier;
+    const bp = this.describe(asker);
+    if (!C.carries(this.occupant(asker), asker)) return bp;
+    const own = new Set(bp.asks.map((a) => a.name));
+    const carried: Carried = {};
+    const groups: Record<string, { asks: string[]; look?: Look }> = {};
+    const occ = this.occupant(asker);
+    // By id, and never in the order she happened to take them. Her cells keep
+    // standings in the order they were taken, which is the order a lend
+    // answered, a device came back or a relation was dropped and taken again:
+    // history, and no fact about her. Carried into her blueprint in that
+    // order, her shape would come out differently on two runs that made her
+    // the same way, and her digest with it. The digest is how everyone
+    // holding a standing on her learns she changed, so a shape that follows
+    // history says she changed when nothing about her did, and a watcher
+    // refreshes or walks away over the order two lends came back in.
+    for (const [id, rec] of [...Object.entries(this.cells.standings)].sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0))) {
+      if (C.skips(id)) continue;
+      const st = this.standings[id];
+      if (!st) continue;
+      if (!rec.blueprint || rec.seen !== rec.digest) await st.ask(); // her ward writes the record
+      if (!rec.blueprint) continue;
+      // plumbing carries what it carries and nothing of its own: the names
+      // the far being's notes group under her standings, or none
+      const through = C.hidden(id) ? carriedBy(rec.blueprint) : null;
+      if (through && through.size === 0) continue;
+      // The mapping is written for every standing she carries, whoever is
+      // asking: it is one map in her cells, and the last describe must not
+      // decide what the next asker may call. Who sees a standing is decided
+      // here and again at answer, by `shows`.
+      const shown = C.shows(id, occ, asker);
+      // her look is kept here once per digest and never carried as an ask;
+      // her page follows every call, so it is carried as one and named in
+      // the notes, where every side finds it and none takes it for a form
+      const names: string[] = [];
+      const group: { asks: string[]; look?: Look; page?: string } = { asks: names };
+      for (const a of rec.blueprint.asks) {
+        if (a.name === 'look') continue;
+        if (through && !through.has(a.name)) continue;
+        const name = `${id}-${a.name}`;
+        if (own.has(name)) continue;
+        carried[name] = { id, ask: a.name };
+        if (!shown) continue;
+        bp.asks.push({ ...a, name });
+        if (a.name === 'page') group.page = name;
+        else names.push(name);
+      }
+      if (!shown) continue;
+      if (rec.blueprint.asks.some((a) => a.name === 'look')) {
+        const kept = this.looks[id];
+        if (!kept || kept.digest !== rec.digest) {
+          const l = await st.ask('look');
+          this.looks[id] = { digest: rec.digest, look: isSilence(l) || isWord(l) ? {} : sanitise(l) };
+        }
+        group.look = this.looks[id].look;
+      }
+      groups[id] = group;
+    }
+    for (const id of Object.keys(this.looks)) if (!(id in groups)) delete this.looks[id];
+    this.cells.carried = carried;
+    const notes = bp.notes !== null && typeof bp.notes === 'object' && !Array.isArray(bp.notes) ? bp.notes : {};
+    return { asks: bp.asks, notes: { ...notes, standings: groups as unknown as JsonObject } };
+  }
+
+  override async answer(asker: Asker, method?: string, args: JsonObject = {}): Promise<Reply> {
+    if (method === undefined) return this.blueprint(asker);
+    const C = this.constructor as typeof Carrier;
+    const to = Object.hasOwn(this.carried, method) ? this.carried[method] : undefined;
+    const occ = this.occupant(asker);
+    if (to && C.carries(occ, asker) && C.shows(to.id, occ, asker)) {
+      const st = this.standings[to.id];
+      if (!st) return { error: 'unknown ask' };
+      const out = await st.ask(to.ask, args);
+      if (isSilence(out)) return out;
+      if (isWord(out)) return { error: wordOf(out) };
+      return out;
+    }
+    return super.answer(asker, method, args);
+  }
+}