@littlebigbrain/create 0.2.0 → 0.4.0

package/templates/link/things.test.ts

@@ -0,0 +1,204 @@
+// Things (general linking 2.4, 5.4): the grouping with must-links and
+// cannot-links, the identity proposals, the anchors, the deterministic IRIs,
+// and the merges and splits from one grouping to the next.
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { ENTITY_IRI_NAMESPACE } from "@littlebigbrain/client";
+import {
+  anchorKeyOf,
+  anchorOf,
+  group,
+  mentionIri,
+  nameThings,
+  thingIri,
+  type Member,
+  type Pair,
+} from "./things.js";
+
+const e = (n: number | string) => `${ENTITY_IRI_NAMESPACE}${String(n).padStart(32, "0")}`;
+const self = (n: number, record: number, span: string, keyed = false): Member => ({
+  iri: e(n),
+  role: "self",
+  record: e(`r${record}`.replace("r", "9")),
+  span,
+  kind: "Person",
+  keyed,
+});
+const refers = (n: number, span: string): Member => ({
+  iri: e(n),
+  role: "refers",
+  record: null,
+  span,
+  kind: "person",
+});
+const pair = (a: number, b: number, confidence: number, by: Pair["by"] = "model"): Pair => ({
+  a: e(a),
+  b: e(b),
+  confidence,
+  by,
+});
+
+test("the IRIs of mentions and things are hashes: pinned", () => {
+  const source = "https://littlebigbrain.com/e/0123456789abcdef0123456789abcdef";
+  assert.equal(
+    mentionIri("samples", source, "name", "Mira Tannenholt-Ruiz", 0),
+    "https://littlebigbrain.com/e/2b8a3464c3a38d435f59f67efdc1b28b",
+  );
+  assert.equal(
+    mentionIri("samples", source, "body", "Mimi T.", 1),
+    "https://littlebigbrain.com/e/baa1d4333f2ef9b8f8724c9399ef988c",
+  );
+  assert.equal(
+    thingIri("samples", "record:0123456789abcdef0123456789abcdef"),
+    "https://littlebigbrain.com/e/bb0279d177d2971f056cf6d82a726bf2",
+  );
+  assert.equal(
+    thingIri("samples", "mention:fedcba9876543210fedcba9876543210"),
+    "https://littlebigbrain.com/e/6632612e562605c43a8309e54eee34dd",
+  );
+  assert.notEqual(
+    thingIri("other", "record:0123456789abcdef0123456789abcdef"),
+    thingIri("samples", "record:0123456789abcdef0123456789abcdef"),
+  );
+});
+
+test("a record's self mentions are one thing, anchored by the record, named by its name", () => {
+  const members = [self(2, 1, "mira@northbay.example", true), self(1, 1, "Mira Ruiz")];
+  const { groups } = group({ members, pairs: [], cannot: [], sameAs: [] });
+  assert.deepEqual(groups, [[e(1), e(2)]]);
+  const anchor = anchorOf(members);
+  assert.equal(anchor.iri, e(1), "the name before the key");
+  assert.equal(anchorKeyOf(anchor), `record:${e(91).slice(-32)}`);
+  const naming = nameThings("samples", groups, new Map(members.map((m) => [m.iri, m])));
+  assert.equal(naming.things[0]!.label, "Mira Ruiz");
+  assert.equal(naming.things[0]!.iri, thingIri("samples", anchorKeyOf(anchor)));
+});
+
+test("the things of two records stay apart without an accepted identity, and the pair becomes a proposal", () => {
+  const members = [
+    self(1, 1, "Mira Ruiz"),
+    self(2, 2, "Mira Tannenholt-Ruiz"),
+    refers(3, "M. Tannenholt"),
+  ];
+  const pairs = [pair(3, 2, 0.9), pair(3, 1, 0.85)];
+  const apart = group({ members, pairs, cannot: [], sameAs: [] });
+  assert.equal(apart.groups.length, 2);
+  assert.equal(apart.blockedByRecords, 1);
+  assert.deepEqual(
+    apart.proposals.map((p) => p.records),
+    [[e(91), e(92)]],
+  );
+  // An accepted identity joins them; nothing is proposed.
+  const joined = group({ members, pairs, cannot: [], sameAs: [[e(91), e(92)]] });
+  assert.deepEqual(joined.groups, [[e(1), e(2), e(3)]]);
+  assert.deepEqual(joined.proposals, []);
+});
+
+test("a cannot-link keeps two mentions apart, also through other pairs; a person's pairs join first", () => {
+  const members = [refers(1, "Lena Fair"), refers(2, "L. Fair"), refers(3, "Lena Fairweather")];
+  const pairs = [pair(1, 2, 0.95), pair(2, 3, 0.9)];
+  const kept = group({ members, pairs, cannot: [[e(1), e(3)]], sameAs: [] });
+  assert.deepEqual(
+    kept.groups,
+    [[e(1), e(2)], [e(3)]],
+    "the higher pair joins, the lower one is blocked",
+  );
+  assert.equal(kept.blockedByPerson, 1);
+  // A person's must-link joins before the model's higher pair.
+  const person = group({
+    members,
+    pairs: [...pairs, pair(2, 3, 0.5, "person")],
+    cannot: [[e(1), e(3)]],
+    sameAs: [],
+  });
+  assert.deepEqual(person.groups, [[e(1)], [e(2), e(3)]]);
+});
+
+test("an identity of more than 10 records is not proposed; a dismissed identity is not proposed again", () => {
+  const members = Array.from({ length: 12 }, (_, n) => self(n + 1, n + 1, "Alex Brandt"));
+  const identities = members.slice(1).map((m) => ({
+    a: members[0]!.record!,
+    b: m.record!,
+    confidence: 1,
+    reason: "a team address",
+  }));
+  const big = group({ members, pairs: [], cannot: [], sameAs: [], identities });
+  assert.equal(big.tooLarge, 1);
+  assert.deepEqual(big.proposals, []);
+  const two = members.slice(0, 2);
+  const dismissed = group({
+    members: two,
+    pairs: [],
+    cannot: [[two[0]!.iri, two[1]!.iri]],
+    sameAs: [],
+    identities: [identities[0]!],
+  });
+  assert.deepEqual(dismissed.proposals, []);
+});
+
+test("a thing of mentions alone takes the smallest key; a record that joins becomes its anchor, and the old IRI points to it", () => {
+  const notes = [refers(5, "Bob Haldane"), refers(4, "Bob Haldane")];
+  const first = group({ members: notes, pairs: [pair(5, 4, 0.96)], cannot: [], sameAs: [] });
+  const map1 = new Map(notes.map((m) => [m.iri, m]));
+  const before = nameThings("samples", first.groups, map1);
+  assert.equal(before.things[0]!.anchorKey, `mention:${e(4).slice(-32)}`);
+
+  const robert = self(1, 7, "Robert Haldane");
+  const all = [...notes, robert];
+  const second = group({
+    members: all,
+    pairs: [pair(5, 4, 0.96), pair(1, 4, 0.9)],
+    cannot: [],
+    sameAs: [],
+  });
+  const after = nameThings("samples", second.groups, new Map(all.map((m) => [m.iri, m])), [
+    { iri: before.things[0]!.iri, anchorKey: before.things[0]!.anchorKey, members: [e(4), e(5)] },
+  ]);
+  assert.equal(after.things.length, 1);
+  assert.equal(after.things[0]!.anchorKey, `record:${e(97).slice(-32)}`);
+  assert.deepEqual(after.merged, [{ from: before.things[0]!.iri, into: after.things[0]!.iri }]);
+  assert.deepEqual(after.things[0]!.aliases, [], "a nickname of the label is no alias");
+});
+
+test("a split keeps the anchor's part at its IRI, and the other part gets the IRI of its own anchor", () => {
+  const members = [self(1, 7, "Robert Haldane"), refers(4, "Bob Haldane"), refers(5, "R. Haldane")];
+  const map = new Map(members.map((m) => [m.iri, m]));
+  const together = nameThings(
+    "samples",
+    group({ members, pairs: [pair(4, 1, 0.9), pair(5, 4, 0.9)], cannot: [], sameAs: [] }).groups,
+    map,
+  );
+  assert.equal(together.things.length, 1);
+  const recordThing = together.things[0]!.iri;
+  // A person keeps "Bob Haldane" apart from the record: the pair to it goes.
+  const split = group({
+    members,
+    pairs: [pair(4, 1, 0.9), pair(5, 4, 0.9)],
+    cannot: [[e(4), e(1)]],
+    sameAs: [],
+  });
+  const named = nameThings("samples", split.groups, map, [
+    {
+      iri: recordThing,
+      anchorKey: together.things[0]!.anchorKey,
+      members: members.map((m) => m.iri),
+    },
+  ]);
+  const byIri = new Map(named.things.map((t) => [t.iri, t]));
+  assert.deepEqual(byIri.get(recordThing)?.members, [e(1)], "the record keeps its IRI");
+  const other = named.things.find((t) => t.iri !== recordThing)!;
+  assert.deepEqual(other.members, [e(4), e(5)]);
+  assert.equal(other.iri, thingIri("samples", `mention:${e(4).slice(-32)}`));
+  assert.deepEqual(named.merged, []);
+  assert.deepEqual(named.gone, []);
+});
+
+test("a mention alone is no thing; a thing whose members are all gone is gone", () => {
+  const lone = refers(3, "Kim Oak");
+  const naming = nameThings("samples", [[lone.iri]], new Map([[lone.iri, lone]]), [
+    { iri: thingIri("samples", "mention:x"), anchorKey: "mention:x", members: [e(8)] },
+  ]);
+  assert.deepEqual(naming.things, []);
+  assert.deepEqual(naming.lone, [lone.iri]);
+  assert.deepEqual(naming.gone, [thingIri("samples", "mention:x")]);
+});

package/templates/link/things.ts

@@ -0,0 +1,426 @@
+// Things: the groups of mentions that name the same real thing (general
+// linking 2.1 to 2.4, 5.4). Pure functions: the grouping with must-links and
+// cannot-links, the identity proposals, the anchors, the IRIs, and the merges
+// and splits from one grouping to the next.
+//
+// The rules that keep a thing stable:
+//
+// - A person's decision is a constraint: a kept link is a must-link, a link
+//   left out or dismissed is a cannot-link. No model answer joins what a
+//   cannot-link keeps apart.
+// - The things of two records are never joined without an accepted identity
+//   (`SAME_AS`). A pair that would join them becomes an identity proposal.
+// - The anchor names the thing: a record's self mention first, then a
+//   definition, then a page's self mention, then any other mention; inside
+//   a rank the smallest stable key. The thing's IRI is a hash of the graph
+//   and the anchor's key, so the same inputs give the same IRIs.
+// - A thing whose anchor changed, or that merged into another, keeps one
+//   statement: `MERGED_INTO` the thing that holds its members now.
+import { createHash } from "node:crypto";
+import { ENTITY_IRI_NAMESPACE } from "@littlebigbrain/client";
+import { normalName } from "./names.js";
+
+/** A SHA-256 of the parts, as hex. */
+export const hash = (...parts: string[]) =>
+  createHash("sha256").update(parts.join("\u0000")).digest("hex");
+
+/** The 32-hex id of an entity IRI. */
+export const idOf = (iri: string) =>
+  iri.startsWith(ENTITY_IRI_NAMESPACE)
+    ? iri.slice(ENTITY_IRI_NAMESPACE.length)
+    : hash(iri).slice(0, 32);
+
+/**
+ * The IRI of a mention: a hash of the graph, its source, its field, its
+ * span and which equal span of the field it is. A mention keeps its IRI
+ * while that text stays, also when text before it changes.
+ */
+export function mentionIri(
+  graph: string,
+  source: string,
+  field: string,
+  span: string,
+  occurrence: number,
+): string {
+  return (
+    ENTITY_IRI_NAMESPACE +
+    hash("lbb.link.mention.v1", graph, idOf(source), field, span, String(occurrence)).slice(0, 32)
+  );
+}
+
+/** The IRI of a thing: a hash of the graph and its anchor's key. */
+export function thingIri(graph: string, anchorKey: string): string {
+  return ENTITY_IRI_NAMESPACE + hash("lbb.link.thing.v1", graph, anchorKey).slice(0, 32);
+}
+
+/** A mention as the grouping sees it. */
+export interface Member {
+  iri: string;
+  role: "self" | "refers" | "defines";
+  /** The record whose self mention this is. */
+  record: string | null;
+  span: string;
+  /** What the thing is called by its kind: the record's class, or the mention's kind. */
+  kind: string;
+  /** The span is a key (an email, a web address, a phone number, a handle, a code), no name. */
+  keyed?: boolean;
+}
+
+/** The rank of a member as an anchor: a record's self mention, a definition, a page's self mention, any other. */
+export const rankOf = (m: Member): number =>
+  m.role === "self" && m.record ? 0 : m.role === "defines" ? 1 : m.role === "self" ? 2 : 3;
+
+/** The stable key a member anchors a thing by: its record's id, else its own id. */
+export const anchorKeyOf = (m: Member): string =>
+  rankOf(m) === 0 ? `record:${idOf(m.record!)}` : `mention:${idOf(m.iri)}`;
+
+/** Who made a pair. A person's pairs and the identities join first, then the others by confidence. */
+export type PairBy = "person" | "strong" | "model" | "rule";
+
+/** A decided or kept pair: the two mentions name the same thing. */
+export interface Pair {
+  a: string;
+  b: string;
+  confidence: number;
+  by: PairBy;
+}
+
+/** Two records a decision proposes as one identity, with why. */
+export interface IdentityPair {
+  a: string;
+  b: string;
+  confidence: number;
+  reason: string;
+}
+
+export interface GroupInput {
+  members: Member[];
+  pairs: Pair[];
+  /** Pairs of mentions a person keeps apart. */
+  cannot: [string, string][];
+  /** Pairs of records a person accepted as one identity (`SAME_AS`). */
+  sameAs: [string, string][];
+  /** Identities the decisions propose between records. */
+  identities?: IdentityPair[];
+}
+
+/** Records proposed as one identity: 2 to 10 of them, with the pairs that matched. */
+export interface IdentityProposal {
+  records: string[];
+  confidence: number;
+  pairs: IdentityPair[];
+}
+
+export interface Grouping {
+  /** The groups of mention IRIs, each sorted, ordered by their first member. */
+  groups: string[][];
+  proposals: IdentityProposal[];
+  /** Pairs a cannot-link kept apart. */
+  blockedByPerson: number;
+  /** Pairs that would have joined the things of two records without an accepted identity. */
+  blockedByRecords: number;
+  /** Identity groups of more than 10 records: not proposed. */
+  tooLarge: number;
+  /** The records of each identity group of more than 10. */
+  tooLargeGroups: string[][];
+}
+
+/** Records of one identity, at most: the server's limit. */
+export const MAX_IDENTITY = 10;
+
+const ORDER: Record<PairBy, number> = { person: 0, strong: 1, model: 2, rule: 3 };
+
+/**
+ * Group the members by their pairs. The self mentions of one record join
+ * first, then the records of each accepted identity, then a person's pairs,
+ * then the other pairs from the highest confidence down. A join that a
+ * cannot-link forbids is skipped. A join of two groups that both hold a
+ * record and no accepted identity is skipped and proposed as an identity.
+ */
+export function group(input: GroupInput): Grouping {
+  const members = new Map(input.members.map((m) => [m.iri, m]));
+  const parent = new Map<string, string>();
+  const sets = new Map<string, { members: Set<string>; records: Set<string> }>();
+  for (const m of members.values()) {
+    parent.set(m.iri, m.iri);
+    sets.set(m.iri, { members: new Set([m.iri]), records: new Set(m.record ? [m.record] : []) });
+  }
+  const find = (x: string): string => {
+    let root = x;
+    while (parent.get(root) !== root) root = parent.get(root)!;
+    for (let at = x; parent.get(at) !== root;) {
+      const next = parent.get(at)!;
+      parent.set(at, root);
+      at = next;
+    }
+    return root;
+  };
+  const cannot = new Map<string, Set<string>>();
+  for (const [a, b] of input.cannot) {
+    if (a === b) continue;
+    (cannot.get(a) ?? cannot.set(a, new Set()).get(a)!).add(b);
+    (cannot.get(b) ?? cannot.set(b, new Set()).get(b)!).add(a);
+  }
+  const kept = (ra: string, rb: string) => {
+    const [small, large] = [sets.get(ra)!, sets.get(rb)!].sort(
+      (x, y) => x.members.size - y.members.size,
+    );
+    for (const m of small!.members)
+      for (const other of cannot.get(m) ?? []) if (large!.members.has(other)) return true;
+    return false;
+  };
+  const union = (ra: string, rb: string) => {
+    const [keep, drop] = ra < rb ? [ra, rb] : [rb, ra];
+    parent.set(drop, keep);
+    const into = sets.get(keep)!;
+    for (const m of sets.get(drop)!.members) into.members.add(m);
+    for (const r of sets.get(drop)!.records) into.records.add(r);
+    sets.delete(drop);
+  };
+  const out: Grouping = {
+    groups: [],
+    proposals: [],
+    blockedByPerson: 0,
+    blockedByRecords: 0,
+    tooLarge: 0,
+    tooLargeGroups: [],
+  };
+  const proposed: IdentityPair[] = [...(input.identities ?? [])];
+
+  // The self mentions of one record name the record.
+  const selfOf = new Map<string, string>();
+  for (const m of [...members.values()].sort((x, y) => (x.iri < y.iri ? -1 : 1))) {
+    if (!m.record || m.role !== "self") continue;
+    const first = selfOf.get(m.record);
+    if (first === undefined) selfOf.set(m.record, m.iri);
+    else if (find(first) !== find(m.iri)) union(find(first), find(m.iri));
+  }
+  // An accepted identity joins its records.
+  for (const [a, b] of [...input.sameAs].sort()) {
+    const [x, y] = [selfOf.get(a), selfOf.get(b)];
+    if (x && y && find(x) !== find(y)) union(find(x), find(y));
+  }
+  const pairs = input.pairs
+    .filter((p) => p.a !== p.b && members.has(p.a) && members.has(p.b))
+    .sort(
+      (x, y) =>
+        (x.by === "person" ? 0 : 1) - (y.by === "person" ? 0 : 1) ||
+        y.confidence - x.confidence ||
+        ORDER[x.by] - ORDER[y.by] ||
+        (x.a + x.b < y.a + y.b ? -1 : x.a + x.b > y.a + y.b ? 1 : 0),
+    );
+  for (const pair of pairs) {
+    const [ra, rb] = [find(pair.a), find(pair.b)];
+    if (ra === rb) continue;
+    if (kept(ra, rb)) {
+      out.blockedByPerson += 1;
+      continue;
+    }
+    const [x, y] = [sets.get(ra)!.records, sets.get(rb)!.records];
+    if (x.size && y.size) {
+      out.blockedByRecords += 1;
+      const [first, second] = [[...x].sort()[0]!, [...y].sort()[0]!];
+      proposed.push({
+        a: first,
+        b: second,
+        confidence: pair.confidence,
+        reason: `a mention links ${members.get(pair.a)!.span} and ${members.get(pair.b)!.span}`,
+      });
+      continue;
+    }
+    union(ra, rb);
+  }
+
+  out.groups = [...sets.values()]
+    .map((s) => [...s.members].sort())
+    .sort((a, b) => (a[0]! < b[0]! ? -1 : 1));
+  out.proposals = proposals(proposed, find, selfOf, cannot, sets, out);
+  return out;
+}
+
+/** The identity proposals of the pairs: components over records, without the pairs already joined or kept apart. */
+function proposals(
+  pairs: IdentityPair[],
+  find: (x: string) => string,
+  selfOf: Map<string, string>,
+  cannot: Map<string, Set<string>>,
+  sets: Map<string, { members: Set<string>; records: Set<string> }>,
+  out: Grouping,
+): IdentityProposal[] {
+  const groupOf = (record: string) => {
+    const self = selfOf.get(record);
+    return self ? find(self) : `record:${record}`;
+  };
+  const recordsOf = (record: string) => {
+    const self = selfOf.get(record);
+    return self ? [...sets.get(find(self))!.records] : [record];
+  };
+  const apart = (a: string, b: string) => {
+    const left = sets.get(groupOf(a))?.members ?? new Set<string>();
+    const right = sets.get(groupOf(b))?.members ?? new Set<string>();
+    for (const m of left)
+      for (const other of cannot.get(m) ?? []) if (right.has(other)) return true;
+    return false;
+  };
+  const parent = new Map<string, string>();
+  const find2 = (x: string): string => {
+    if (!parent.has(x)) parent.set(x, x);
+    let root = x;
+    while (parent.get(root) !== root) root = parent.get(root)!;
+    parent.set(x, root);
+    return root;
+  };
+  const kept: IdentityPair[] = [];
+  for (const pair of pairs) {
+    if (pair.a === pair.b || groupOf(pair.a) === groupOf(pair.b) || apart(pair.a, pair.b)) continue;
+    kept.push(pair);
+    const [x, y] = [find2(groupOf(pair.a)), find2(groupOf(pair.b))];
+    if (x !== y) parent.set(x < y ? y : x, x < y ? x : y);
+  }
+  const components = new Map<string, { groups: Set<string>; pairs: IdentityPair[] }>();
+  for (const pair of kept) {
+    const root = find2(groupOf(pair.a));
+    const entry = components.get(root) ?? { groups: new Set<string>(), pairs: [] };
+    entry.groups.add(groupOf(pair.a)).add(groupOf(pair.b));
+    entry.pairs.push(pair);
+    components.set(root, entry);
+  }
+  const result: IdentityProposal[] = [];
+  for (const { pairs: matched } of components.values()) {
+    const records = [
+      ...new Set(matched.flatMap((p) => [...recordsOf(p.a), ...recordsOf(p.b)])),
+    ].sort();
+    if (records.length > MAX_IDENTITY) {
+      out.tooLarge += 1;
+      out.tooLargeGroups.push(records);
+      continue;
+    }
+    if (records.length < 2) continue;
+    const best = new Map<string, IdentityPair>();
+    for (const p of matched) {
+      const key = [p.a, p.b].sort().join("\u0000");
+      if ((best.get(key)?.confidence ?? -1) < p.confidence) best.set(key, p);
+    }
+    const unique = [...best.values()].sort((x, y) => y.confidence - x.confidence);
+    result.push({
+      records,
+      confidence: Math.min(...unique.map((p) => p.confidence)),
+      pairs: unique,
+    });
+  }
+  return result.sort((a, b) => (a.records[0]! < b.records[0]! ? -1 : 1));
+}
+
+// ---- naming ----------------------------------------------------------------------
+
+/** A thing as the graph held it before this grouping. */
+export interface PreviousThing {
+  iri: string;
+  anchorKey: string;
+  members: string[];
+}
+
+/** A thing as this grouping names it. */
+export interface NamedThing {
+  iri: string;
+  anchorKey: string;
+  anchor: string;
+  label: string;
+  kind: string;
+  members: string[];
+  records: string[];
+  /** The other names its members use, in their normal form. */
+  aliases: string[];
+}
+
+export interface Naming {
+  things: NamedThing[];
+  /** Things of before whose members another thing holds now: `from` keeps `MERGED_INTO` `into`. */
+  merged: { from: string; into: string }[];
+  /** Things of before whose members no thing holds now. */
+  gone: string[];
+  /** Mentions in no thing: alone, and anchoring nothing. */
+  lone: string[];
+}
+
+/** The aliases a thing keeps, at most. */
+export const MAX_ALIASES = 16;
+
+/** The anchor of a group: the best rank, then the smallest key. */
+export function anchorOf(members: Member[]): Member {
+  return [...members].sort(
+    (a, b) =>
+      rankOf(a) - rankOf(b) ||
+      (anchorKeyOf(a) < anchorKeyOf(b) ? -1 : anchorKeyOf(a) > anchorKeyOf(b) ? 1 : 0) ||
+      // The self mentions of one record share a key: a name before a key.
+      Number(Boolean(a.keyed)) - Number(Boolean(b.keyed)) ||
+      (a.iri < b.iri ? -1 : 1),
+  )[0]!;
+}
+
+/**
+ * Name the groups. A group of two or more members, or with a record's self
+ * mention or a definition, is a thing with the IRI of its anchor; the other
+ * groups are lone mentions. A thing of before that this grouping does not
+ * name again points to the thing that holds its anchor now, else to the
+ * one that holds most of its members, else it is gone.
+ */
+export function nameThings(
+  graph: string,
+  groups: string[][],
+  members: Map<string, Member>,
+  previous: PreviousThing[] = [],
+): Naming {
+  const naming: Naming = { things: [], merged: [], gone: [], lone: [] };
+  for (const iris of groups) {
+    const list = iris.map((iri) => members.get(iri)!).filter(Boolean);
+    if (!list.length) continue;
+    const anchor = anchorOf(list);
+    if (list.length < 2 && rankOf(anchor) > 1) {
+      naming.lone.push(anchor.iri);
+      continue;
+    }
+    const anchorKey = anchorKeyOf(anchor);
+    // The label is the anchor's name; an anchor that is a key (a lead known by its email) takes the best name of its thing.
+    const names = list.filter((m) => !m.keyed);
+    const label = anchor.keyed && names.length ? anchorOf(names).span : anchor.span;
+    const aliases = [
+      ...new Set(
+        list
+          .filter((m) => !m.keyed)
+          .map((m) => normalName(m.span))
+          .filter((name) => name && name !== normalName(label)),
+      ),
+    ]
+      .sort()
+      .slice(0, MAX_ALIASES);
+    naming.things.push({
+      iri: thingIri(graph, anchorKey),
+      anchorKey,
+      anchor: anchor.iri,
+      label,
+      kind: anchor.kind,
+      members: [...iris],
+      records: [...new Set(list.map((m) => m.record).filter((r): r is string => !!r))].sort(),
+      aliases,
+    });
+  }
+  const live = new Map(naming.things.map((t) => [t.iri, t]));
+  for (const before of previous) {
+    if (live.has(before.iri)) continue;
+    const holding = naming.things.find((t) =>
+      t.members.some((m) => {
+        const member = members.get(m);
+        return member !== undefined && anchorKeyOf(member) === before.anchorKey;
+      }),
+    );
+    const most = [...naming.things]
+      .map((t) => ({ t, n: t.members.filter((m) => before.members.includes(m)).length }))
+      .filter((x) => x.n > 0)
+      .sort((a, b) => b.n - a.n || (a.t.iri < b.t.iri ? -1 : 1))[0]?.t;
+    const into = holding ?? most;
+    if (into) naming.merged.push({ from: before.iri, into: into.iri });
+    else naming.gone.push(before.iri);
+  }
+  return naming;
+}

package/templates/link/try.ts

@@ -0,0 +1,28 @@
+// Try the workflow on its samples: create a graph (default try-link), put the
+// invented CRM on it, and create the workflow there. Then serve it with
+// npm start and the same LBB_GRAPH, and grade the run with npm run grade.
+//
+//   LBB_URL=... LBB_API_KEY=... LBB_GRAPH=try-link npm run try
+import { fileURLToPath } from "node:url";
+import { LbbClient, LbbError, lbbActivities } from "@littlebigbrain/client";
+import { loadSamples } from "./samples.js";
+import { setup } from "./workflow.js";
+
+const graph = process.env.LBB_GRAPH ?? "try-link";
+const client = new LbbClient({
+  baseUrl: process.env.LBB_URL ?? "http://127.0.0.1:7400",
+  apiKey: process.env.LBB_API_KEY,
+  graph,
+});
+try {
+  await client.graph(graph).create();
+  console.log(`Created the graph ${graph}`);
+} catch (error) {
+  // 409: the graph exists already.
+  if (!(error instanceof LbbError && error.status === 409)) throw error;
+}
+await loadSamples(client, fileURLToPath(new URL("../samples/", import.meta.url)));
+const names = await setup(client, lbbActivities(client));
+console.log(`Created ${names.join(", ")} on the graph ${graph}.`);
+console.log(`Serve them with LBB_GRAPH=${graph} npm start, then grade the run with:`);
+console.log(`  LBB_GRAPH=${graph} npx tsx src/grade-run.ts --gold samples/gold.json`);

package/templates/link/worker.ts

@@ -0,0 +1,24 @@
+// Serve the workflow: the worker claims the turns of the source shards and
+// of the things identity and runs them, one at a time. Run more workers for
+// more at once.
+//
+//   LBB_URL=... LBB_API_KEY=... LBB_GRAPH=... npm start
+import { LbbClient, WorkflowWorker, lbbActivities } from "@littlebigbrain/client";
+import { createWorkflow, linkPorts } from "./workflow.js";
+
+const graph = process.env.LBB_GRAPH ?? "main";
+const client = new LbbClient({
+  baseUrl: process.env.LBB_URL ?? "http://127.0.0.1:7400",
+  apiKey: process.env.LBB_API_KEY,
+  graph,
+});
+const workflow = createWorkflow(lbbActivities(client), linkPorts(client));
+const stop = new AbortController();
+process.once("SIGINT", () => stop.abort());
+process.once("SIGTERM", () => stop.abort());
+console.log(
+  `Serving ${workflow.name}@${workflow.version} for the graph ${graph}. Stop with Ctrl-C.`,
+);
+await new WorkflowWorker(client, [workflow], {
+  worker: process.env.LBB_WORKER_ID ?? `${workflow.name}-1`,
+}).run({ signal: stop.signal });