@littlebigbrain/create 0.2.0 → 0.3.0

package/templates/link/decide.test.ts

@@ -0,0 +1,368 @@
+// The candidates of a mention (general linking 4.3, 4.4) and the decision
+// (5.1 to 5.3): the bounds and stop keys, the rules without model reads,
+// the link rule of link version 7, and the packing of the requests.
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { ENTITY_IRI_NAMESPACE } from "@littlebigbrain/client";
+import {
+  BOUNDS,
+  candidatesFor,
+  neighbourPaths,
+  stopKeys,
+  type Candidate,
+  type KeyHit,
+} from "./candidates.js";
+import {
+  decideRequest,
+  effectIdOf,
+  linkRule,
+  packRequests,
+  rulesDecisions,
+  sameRecord,
+  type Asked,
+} from "./decide.js";
+import { blockKeys } from "./names.js";
+import {
+  identityItem,
+  itemKind,
+  rowsOfItem,
+  thingItems,
+  type Row,
+  type TargetView,
+} from "./items.js";
+
+const e = (n: number) => `${ENTITY_IRI_NAMESPACE}${String(n).padStart(32, "0")}`;
+const hit = (key: string, n: number, over: Partial<KeyHit> = {}): KeyHit => ({
+  key,
+  mention: e(n),
+  role: "self",
+  span: "Mira Tannenholt-Ruiz",
+  source: e(100 + n),
+  kind: "name",
+  window: null,
+  thing: e(500 + n),
+  label: "Mira Tannenholt-Ruiz",
+  ...over,
+});
+const mention = (span: string, keys = blockKeys(span, "text")) => ({
+  iri: e(1),
+  source: e(101),
+  role: "refers" as const,
+  span,
+  keys,
+  cannot: [],
+});
+
+test("a strong key comes first; a stop key, the mention's own record and a cannot-link find nothing", () => {
+  const m = {
+    ...mention("M. Tannenholt"),
+    keys: ["email:mira@northbay.example", ...blockKeys("M. Tannenholt", "name")],
+  };
+  const hits = [
+    hit("name:initial:tannenholt m", 2),
+    hit("email:mira@northbay.example", 3, { span: "mira@northbay.example", kind: "email" }),
+    hit("name:part:tannenholt", 4, { span: "Hanna Tannenholt", label: "Hanna Tannenholt" }),
+    hit("name:initial:tannenholt m", 5, { thing: e(505) }),
+  ];
+  const found = candidatesFor(m, hits, new Set(), []);
+  assert.equal(found[0]!.target, e(3));
+  assert.ok(found[0]!.strong);
+  assert.ok(
+    !found.some((c) => c.target === e(4)),
+    "a weak key alone and an unlike name stay below the score",
+  );
+  assert.deepEqual(
+    candidatesFor(
+      m,
+      hits,
+      new Set(["email:mira@northbay.example", "name:initial:tannenholt m"]),
+      [],
+    ).map((c) => c.target),
+    [],
+  );
+  assert.ok(
+    !candidatesFor({ ...m, cannot: [e(502)] }, hits, new Set(), []).some((c) => c.thing === e(502)),
+  );
+  const self = { ...m, role: "self" as const, source: e(103) };
+  assert.ok(
+    !candidatesFor(self, hits, new Set(), []).some((c) => c.target === e(3)),
+    "its own record's mentions",
+  );
+});
+
+test("a neighbour named alike is a candidate, with how it is reached", () => {
+  const m = mention("Mimi T.");
+  const neighbour = {
+    mention: {
+      record: e(200),
+      mention: e(7),
+      role: "refers",
+      span: "M. Tannenholt",
+      thing: e(507),
+      label: "Mira Tannenholt-Ruiz",
+    },
+    via: 'ABOUT → Deal "Northbay retrofit"',
+  };
+  const unlike = {
+    ...neighbour,
+    mention: { ...neighbour.mention, mention: e(8), span: "Northbay Water", thing: e(508) },
+  };
+  const found = candidatesFor(m, [], new Set(), [neighbour, unlike]);
+  assert.deepEqual(
+    found.map((c) => [c.target, c.found, c.via]),
+    [[e(7), "neighbour", 'named in ABOUT → Deal "Northbay retrofit"']],
+  );
+  const paths = neighbourPaths(
+    [e(1)],
+    [
+      [
+        {
+          from: e(1),
+          relation: "ABOUT",
+          to: e(2),
+          dir: "out",
+          name: "Northbay retrofit",
+          class: "deal",
+        },
+      ],
+      [{ from: e(2), relation: "INVOLVES", to: e(3), dir: "out", name: "Mira", class: "person" }],
+    ],
+  );
+  assert.equal(
+    paths.get(e(1))!.get(e(3)),
+    'ABOUT → deal "Northbay retrofit" → INVOLVES → person "Mira"',
+  );
+});
+
+test("the stop keys are the keys more than 200 mentions hold", () => {
+  const counts = new Map([
+    ["email:team@northbay.example", 260],
+    ["name:part:alex", BOUNDS.stopKey],
+    ["name:part:mira", 3],
+  ]);
+  assert.deepEqual(stopKeys(counts), ["email:team@northbay.example"]);
+});
+
+const candidate = (n: number, over: Partial<Candidate> = {}): Candidate => ({
+  target: e(n),
+  thing: e(500 + n),
+  label: "Mira Tannenholt-Ruiz",
+  spans: ["Mira Tannenholt-Ruiz"],
+  records: [e(100 + n)],
+  score: 0.9,
+  found: "name:initial",
+  strong: false,
+  ...over,
+});
+
+test("without model reads a strong key links at 1 and every other candidate goes to a person", () => {
+  const refers = { iri: e(1), role: "refers" as const, record: null };
+  assert.deepEqual(
+    rulesDecisions(refers, [
+      candidate(2, { strong: true, found: "email", score: 1 }),
+    ]).decisions.map((d) => [d.outcome, d.confidence, d.by]),
+    [["link", 1, "strong"]],
+  );
+  assert.deepEqual(
+    rulesDecisions(refers, [
+      candidate(2, { strong: true }),
+      candidate(3, { strong: true }),
+    ]).decisions.map((d) => d.outcome),
+    ["review"],
+    "two things share the strong key: a person decides",
+  );
+  assert.deepEqual(
+    rulesDecisions(refers, [candidate(2)]).decisions.map((d) => [d.outcome, d.confidence]),
+    [["review", 0.9]],
+  );
+  const alone = rulesDecisions(refers, []).decisions[0]!;
+  assert.equal(alone.outcome, "none");
+  // A self mention: another record is an identity, never a link.
+  const self = { iri: e(1), role: "self" as const, record: e(101) };
+  const near = new Map([
+    [e(101), { near: new Set(["brightmoor foods"]) }],
+    [e(102), { near: new Set(["brightmoor foods"]) }],
+    [e(103), { near: new Set(["ridgeway transit"]) }],
+  ]);
+  const strong = rulesDecisions(self, [candidate(2, { strong: true, found: "email" })], near);
+  assert.deepEqual(
+    strong.identities.map((i) => [i.b, i.confidence]),
+    [[e(102), 1]],
+  );
+  assert.deepEqual(strong.decisions, []);
+  const byName = rulesDecisions(
+    self,
+    [candidate(2, { found: "name" }), candidate(3, { found: "name" })],
+    near,
+  );
+  assert.deepEqual(
+    byName.identities.map((i) => [i.b, i.confidence]),
+    [[e(102), 0.9]],
+    "a name and a shared related record",
+  );
+});
+
+test("the link rule: the smaller of the linkable kinds and the names answer, against the gate", () => {
+  const asked: Asked = {
+    position: 0,
+    span: "M. Tannenholt",
+    context: "Deal",
+    kind: true,
+    candidates: [candidate(2), candidate(3)],
+  };
+  const kind = { choice: "person", confidence: 0.9, probabilities: { person: 0.9, other: 0.1 } };
+  const names = {
+    choice: "c0",
+    confidence: 0.95,
+    probabilities: { c0: 0.95, c1: 0.03, new_thing: 0.02 },
+  };
+  const link = linkRule(e(1), asked, kind, names, 0.8);
+  assert.deepEqual([link.outcome, link.target, link.confidence], ["link", e(2), 0.9]);
+  assert.equal(linkRule(e(1), asked, kind, names, 0.95).outcome, "review");
+  const value = { choice: "value", confidence: 0.8, probabilities: { value: 0.8, person: 0.2 } };
+  const noLink = linkRule(e(1), asked, value, names, 0.9);
+  assert.deepEqual(
+    [noLink.outcome, noLink.target, noLink.confidence],
+    ["nolink", e(2), 0.8],
+    "no link below the gate offers the best candidate",
+  );
+  const newThing = {
+    choice: "new_thing",
+    confidence: 0.97,
+    probabilities: { new_thing: 0.97, c0: 0.02 },
+  };
+  assert.equal(
+    linkRule(e(1), asked, kind, newThing, 0.8).outcome,
+    "none",
+    "a confident new thing writes nothing",
+  );
+  const strong = { ...asked, kind: false, candidates: [candidate(2, { strong: true })] };
+  assert.equal(
+    linkRule(e(1), strong, undefined, { choice: "c0", confidence: 0.6 }, 0.8).confidence,
+    1,
+  );
+  assert.equal(
+    sameRecord(
+      e(1),
+      e(2),
+      { choice: "same", confidence: 0.7, probabilities: { same: 0.7 } },
+      "name",
+    )?.confidence,
+    0.7,
+  );
+  assert.equal(
+    sameRecord(
+      e(1),
+      e(2),
+      { choice: "different", confidence: 0.8, probabilities: { same: 0.1 } },
+      "name",
+    ),
+    null,
+  );
+});
+
+test("requests hold at most 32 mentions and carry an effect id made of their content", () => {
+  const asked: Asked[] = Array.from({ length: 70 }, (_, n) => ({
+    position: n,
+    span: `Name ${n}`,
+    context: "Note",
+    kind: true,
+    candidates: [candidate(n + 2)],
+  }));
+  const parts = packRequests({ source: "Note" }, asked);
+  assert.deepEqual(
+    parts.map((p) => p.length),
+    [32, 32, 6],
+  );
+  const request = decideRequest({ source: "Note" }, parts[2]!);
+  assert.equal(Object.keys(request.questions).length, 12);
+  assert.equal(effectIdOf(request), effectIdOf(decideRequest({ source: "Note" }, parts[2]!)));
+  assert.notEqual(effectIdOf(request), effectIdOf(decideRequest({ source: "Note 2" }, parts[2]!)));
+  assert.match(effectIdOf(request), /^link\/d1\/[0-9a-f]{48}$/);
+});
+
+test("an item per thing holds its rows; an identity item names its records; the rows read back", () => {
+  const view = (n: number) => ({
+    iri: e(n),
+    span: `Name ${n}`,
+    line: `the line of ${n}`,
+    source: e(100 + n),
+    sourceName: `Note ${n}`,
+    sourceClass: "Note",
+    field: "body",
+  });
+  const target: TargetView = {
+    iri: e(900),
+    anchor: view(9),
+    label: "Mira Tannenholt-Ruiz",
+    kind: "Person",
+  };
+  const rows: Row[] = Array.from({ length: 55 }, (_, n) => ({
+    decision: {
+      mention: e(n + 1),
+      outcome: n === 0 ? "nolink" : "review",
+      target: e(9),
+      thing: e(900),
+      confidence: 0.6,
+      by: "rule",
+      found: "name",
+      kind: null,
+    },
+    mention: view(n + 1),
+  }));
+  const items = thingItems("link", 1, target, rows);
+  assert.deepEqual(
+    items.map((i) => [itemKind(i.key!), i.facts!.triplets!.length]),
+    [
+      ["link", 50],
+      ["link", 4],
+      ["nolink", 1],
+    ],
+  );
+  assert.ok(items.every((i) => i.origin?.id === "starter:link" && i.origin.label === "link"));
+  assert.match(items[0]!.key!, /^starter:link:link:0{29}900:[0-9a-f]{12}$/);
+  assert.match(items[1]!.key!, /:1$/);
+  // The parts of the pattern of the producer `link`: the sources' classes, the thing's kind, the key kind, link or no link.
+  const mapping = (items[0]!.mapping as { link: Record<string, unknown> }).link;
+  assert.deepEqual(
+    [mapping.sources, mapping.kind, mapping.found, mapping.answer],
+    [["Note"], "Person", ["name"], "link"],
+  );
+  const back = rowsOfItem({ ...items[0]!, status: "open", suggestion_id: "x" } as never);
+  assert.equal(back.length, 50);
+  assert.deepEqual(
+    [back[0]!.mention.iri, back[0]!.decision.target, back[0]!.mention.line],
+    [e(2), e(9), "the line of 2"],
+  );
+  const identity = identityItem(
+    "link",
+    0.99,
+    {
+      records: [e(101), e(102)],
+      confidence: 1,
+      pairs: [{ a: e(101), b: e(102), confidence: 1, reason: "the same email" }],
+    },
+    new Map([
+      [
+        e(101),
+        { iri: e(101), name: "Mira Ruiz", class: "Lead", self: { iri: e(1), span: "Mira Ruiz" } },
+      ],
+      [
+        e(102),
+        {
+          iri: e(102),
+          name: "Mira Tannenholt-Ruiz",
+          class: "Person",
+          self: { iri: e(2), span: "Mira Tannenholt-Ruiz" },
+        },
+      ],
+    ]),
+  )!;
+  assert.equal(itemKind(identity.key!), "identity");
+  assert.equal(identity.identities![0]!.members.length, 2);
+  assert.deepEqual(
+    (identity.mapping as { identity: { above_gate: boolean } }).identity.above_gate,
+    true,
+  );
+  assert.equal(identity.facts!.triplets![0]!.relation, "SAME_THING_AS");
+});

package/templates/link/decide.ts

@@ -0,0 +1,340 @@
+// The decision (general linking 5.1 to 5.3): which thing a mention names.
+// Pure functions: the questions, the state the model reads, the packing of
+// the requests, the link rule, and the decision by keys and rules alone.
+//
+// Without model reads of record values (`modelsReadRecords: false`, the
+// default, decision 1) a strong key links at confidence 1, and every other
+// candidate goes to a person: the rules use the gate 1. With them, the
+// decision model answers a kind question and a names question per mention
+// and a same-record question per record pair; the confidence of a link is
+// the smaller of the linkable kinds' probability and the names answer (the
+// rule of link version 7).
+import type { DecideAnswer, DecideQuestion, DecideRequest } from "@littlebigbrain/client";
+import type { Candidate } from "./candidates.js";
+import { hash, idOf, type IdentityPair } from "./things.js";
+
+/** What became of a mention's decision. */
+export type Outcome = "link" | "review" | "nolink" | "none";
+
+/** A decision about one mention and one candidate. */
+export interface Decision {
+  mention: string;
+  outcome: Outcome;
+  /** The mention a link pairs with (for `nolink`, the best candidate's). */
+  target: string | null;
+  thing: string | null;
+  /** The value the gate compared: the link's confidence, or the no-link answer's. */
+  confidence: number;
+  by: "strong" | "model" | "rule";
+  found: string | null;
+  /** The kind answer of a mention found in text. */
+  kind: string | null;
+  /** The names answer's probability of each candidate, by target id, the four highest. */
+  options?: Record<string, number>;
+  /** For a mention left alone: the ids of the candidates it was compared with (for the second look). */
+  seen?: string[];
+}
+
+/** The kinds of the kind question (5.1). */
+export const KINDS: Record<string, string> = {
+  person: "A person, by name, initials or a nickname.",
+  organization: "A company, a team or another organization.",
+  product: "A product, a part or a service that is offered.",
+  place: "A place, a site or an address.",
+  document: "A document, a file or a contract.",
+  code: "A code or an identifier of something.",
+  value: "A value: an amount, a date, a quantity or a property of something.",
+  external: "Something outside the records: a standard, a law or a public name.",
+  other: "No name: a common word or a phrase.",
+};
+
+/** The kinds that link: every kind but `value`, `external` and `other`. */
+export const LINKABLE = ["person", "organization", "product", "place", "document", "code"];
+
+const round = (x: number) => Math.round(x * 1000) / 1000;
+/** A short id in decisions and messages: the first 12 hex characters of an entity id. */
+export const shortId = (iri: string) => idOf(iri).slice(0, 12);
+
+/** Two candidates are one thing when they share a thing, else when they are one mention. */
+const sameCandidate = (a: Candidate, b: Candidate) =>
+  (a.thing ?? a.target) === (b.thing ?? b.target);
+
+// ---- by keys and rules ----------------------------------------------------------
+
+/** What the rules know of a self mention's record, for an identity: the names near it and in its context fields. */
+export interface RecordContext {
+  /** Normal forms of the names of the records it is related to and of its context field values. */
+  near: Set<string>;
+}
+
+/**
+ * The decisions of one mention by keys and rules. A `refers` mention links
+ * at 1 to the one thing with its strong key, and goes to a person when two
+ * things share it or when only a medium or a weak key, or a neighbour, found
+ * the best candidate. A `self` mention links at 1 to a thing without a
+ * record that holds its strong key; a candidate with another record is an
+ * identity: at 1 for a strong key, at 0.9 for a name when the records share
+ * a related record or a context value, else none.
+ */
+export function rulesDecisions(
+  m: { iri: string; role: "self" | "refers"; record: string | null },
+  candidates: Candidate[],
+  records: Map<string, RecordContext> = new Map(),
+): { decisions: Decision[]; identities: IdentityPair[] } {
+  const decisions: Decision[] = [];
+  const identities: IdentityPair[] = [];
+  const decision = (c: Candidate, outcome: Outcome, confidence: number): Decision => ({
+    mention: m.iri,
+    outcome,
+    target: c.target,
+    thing: c.thing,
+    confidence: round(confidence),
+    by: c.strong && outcome === "link" ? "strong" : "rule",
+    found: c.found,
+    kind: null,
+  });
+  if (m.role === "refers") {
+    const strong = candidates.filter((c) => c.strong);
+    const distinct = strong.filter((c, i) => strong.findIndex((d) => sameCandidate(c, d)) === i);
+    if (distinct.length === 1) decisions.push(decision(distinct[0]!, "link", 1));
+    else if (distinct.length > 1) decisions.push(decision(distinct[0]!, "review", 0.5));
+    else if (candidates[0])
+      decisions.push(decision(candidates[0], "review", Math.min(candidates[0].score, 0.99)));
+    else decisions.push(none(m.iri, candidates));
+    return { decisions, identities };
+  }
+  for (const c of candidates) {
+    const others = c.records.filter((r) => r !== m.record);
+    if (others.length && m.record) {
+      for (const other of others) {
+        const identity = ruleIdentity(m.record, other, c, records);
+        if (identity) identities.push(identity);
+      }
+      continue;
+    }
+    if (c.records.length) continue;
+    if (c.strong) decisions.push(decision(c, "link", 1));
+    else decisions.push(decision(c, "review", Math.min(c.score, 0.99)));
+  }
+  if (!decisions.length && !identities.length) decisions.push(none(m.iri, candidates));
+  return { decisions, identities };
+}
+
+function ruleIdentity(
+  record: string,
+  other: string,
+  c: Candidate,
+  records: Map<string, RecordContext>,
+): IdentityPair | null {
+  if (c.strong) return { a: record, b: other, confidence: 1, reason: `the same ${c.found}` };
+  if (!(c.found === "name" || c.found === "alias")) return null;
+  const [x, y] = [records.get(record)?.near, records.get(other)?.near];
+  const shared = x && y ? [...x].find((name) => y.has(name)) : undefined;
+  return shared
+    ? { a: record, b: other, confidence: 0.9, reason: `the same name, and both name ${shared}` }
+    : null;
+}
+
+/** A mention left alone: no candidate, or none it names. */
+export function none(mention: string, candidates: Candidate[], confidence = 1): Decision {
+  return {
+    mention,
+    outcome: "none",
+    target: null,
+    thing: null,
+    confidence: round(confidence),
+    by: "rule",
+    found: null,
+    kind: null,
+    seen: candidates.map((c) => shortId(c.target)),
+  };
+}
+
+// ---- by the decision model -------------------------------------------------------
+
+/** One mention a decide request asks about. */
+export interface Asked {
+  /** The position in the source's list: the question ids are `m<position>-kind` and `m<position>-names`. */
+  position: number;
+  span: string;
+  /** Where the span is: the sentence of a text field, or the field and its value. */
+  context: string;
+  /** Ask the kind question (a span found in text, not written as a key). */
+  kind: boolean;
+  candidates: Candidate[];
+}
+
+/** One record pair the same-record question asks about. */
+export interface AskedPair {
+  id: string;
+  a: string;
+  b: string;
+  match: string;
+}
+
+/** The state of a source's decide requests: the source and its relations one hop out. */
+export function sourceState(source: string, relations: string[]): Record<string, unknown> {
+  return {
+    source,
+    relations: relations.slice(0, 12),
+    rule: "A candidate is a thing of the graph: a record, or the mentions already linked to it.",
+  };
+}
+
+const describe = (c: Candidate) =>
+  [
+    c.label.slice(0, 120),
+    c.spans.length ? `names: ${c.spans.map((s) => s.slice(0, 60)).join(", ")}` : "",
+    `found by ${c.found}`,
+    c.via ? c.via.slice(0, 200) : "",
+  ]
+    .filter(Boolean)
+    .join("; ");
+
+/** One decide request: the questions of `asked` and `pairs` with the source's state. */
+export function decideRequest(
+  state: Record<string, unknown>,
+  asked: Asked[],
+  pairs: AskedPair[] = [],
+): DecideRequest {
+  const questions: Record<string, DecideQuestion> = {};
+  for (const { position, span, context, kind, candidates } of asked) {
+    if (kind)
+      questions[`m${position}-kind`] = {
+        instructions: `${context} What does the span "${span}" name here?`,
+        criteria: KINDS,
+      };
+    if (!candidates.length) continue;
+    const options: Record<string, string> = {};
+    candidates.forEach((c, k) => (options[`c${k}`] = describe(c)));
+    options.new_thing = "It names a thing that is not in this list.";
+    options.not_a_name = "It names no thing.";
+    questions[`m${position}-names`] = {
+      instructions: `${context} Which thing does the span "${span}" name? Choose a thing only when the span names it: its name in another spelling or order, its initials, a nickname, or one of its keys. A thing whose name is only alike, or that the text only mentions near the span, is no match.`,
+      criteria: options,
+    };
+  }
+  for (const pair of pairs)
+    questions[`${pair.id}-same`] = {
+      instructions: `Record A: ${pair.a}. Record B: ${pair.b}. They match by ${pair.match}. Are they the same thing?`,
+      criteria: {
+        same: "The two records describe one real thing.",
+        different: "They describe two different things.",
+        cannot_tell: "The records do not say.",
+      },
+    };
+  return { state, questions };
+}
+
+/** Estimated tokens of a request: its JSON length over four. */
+export const estimatedTokens = (request: DecideRequest) =>
+  Math.ceil(JSON.stringify(request).length / 4);
+
+/** Tokens of one request, at most (5.2). */
+export const REQUEST_TOKENS = 28_000;
+/** Mentions of one request: two questions each, 64 questions at most. */
+export const REQUEST_MENTIONS = 32;
+
+/** The mentions of one source in requests of at most 32 mentions and 28,000 estimated tokens. */
+export function packRequests(state: Record<string, unknown>, asked: Asked[]): Asked[][] {
+  const out: Asked[][] = [];
+  let current: Asked[] = [];
+  for (const one of asked) {
+    const trial = [...current, one];
+    const size = estimatedTokens(decideRequest(state, trial));
+    if (current.length && (trial.length > REQUEST_MENTIONS || size > REQUEST_TOKENS)) {
+      out.push(current);
+      current = [one];
+    } else current = trial;
+  }
+  if (current.length) out.push(current);
+  return out;
+}
+
+/** The effect id of a decide request, made from its content: the same request gets its first answer. */
+export const effectIdOf = (request: DecideRequest) =>
+  `link/d1/${hash(JSON.stringify(request)).slice(0, 48)}`;
+
+/**
+ * The link rule (5.3) for one asked mention. A chosen candidate with a
+ * strong key links at 1. Otherwise a chosen candidate links when the
+ * linkable kinds have a probability of at least 0.5, at the smaller of that
+ * and the names answer; at or above `gate` it is written, below it a person
+ * decides. An answer that chose no thing has the confidence of no link; with
+ * a candidate below the gate it goes to a person with the best candidate.
+ */
+export function linkRule(
+  mention: string,
+  asked: Asked,
+  kindAnswer: DecideAnswer | undefined,
+  namesAnswer: DecideAnswer | undefined,
+  gate: number,
+): Decision {
+  const probabilities = kindAnswer?.probabilities ?? {};
+  const pLink = !asked.kind
+    ? 1
+    : Object.keys(probabilities).length
+      ? LINKABLE.reduce((sum, id) => sum + (probabilities[id] ?? 0), 0)
+      : LINKABLE.includes(kindAnswer?.choice ?? "")
+        ? (kindAnswer?.confidence ?? 0)
+        : 1 - (kindAnswer?.confidence ?? 1);
+  const kind = kindAnswer?.choice ?? null;
+  if (!asked.candidates.length || !namesAnswer) {
+    const left = none(mention, asked.candidates, 1 - pLink);
+    return { ...left, kind, by: namesAnswer || kindAnswer ? "model" : "rule" };
+  }
+  const options: Record<string, number> = {};
+  const ranked = Object.entries(namesAnswer.probabilities ?? {})
+    .filter(([id]) => /^c\d+$/.test(id))
+    .sort((a, b) => b[1] - a[1]);
+  for (const [id, p] of ranked.slice(0, 4)) {
+    const c = asked.candidates[Number(id.slice(1))];
+    if (c) options[shortId(c.target)] = round(p);
+  }
+  const choice = namesAnswer.choice ?? "";
+  const namesConfidence = namesAnswer.confidence ?? 0;
+  const chosen = /^c\d+$/.test(choice) ? asked.candidates[Number(choice.slice(1))] : undefined;
+  if (chosen && (chosen.strong || pLink >= 0.5)) {
+    const confidence = chosen.strong ? 1 : round(Math.min(pLink, namesConfidence));
+    return {
+      mention,
+      outcome: confidence >= gate ? "link" : "review",
+      target: chosen.target,
+      thing: chosen.thing,
+      confidence,
+      by: chosen.strong ? "strong" : "model",
+      found: chosen.found,
+      kind,
+      options,
+    };
+  }
+  const best = ranked[0] ? asked.candidates[Number(ranked[0][0].slice(1))] : asked.candidates[0];
+  const confidence = round(Math.max(1 - pLink, chosen ? 0 : namesConfidence));
+  if (best && confidence < gate)
+    return {
+      mention,
+      outcome: "nolink",
+      target: best.target,
+      thing: best.thing,
+      confidence,
+      by: "model",
+      found: best.found,
+      kind,
+      options,
+    };
+  return { ...none(mention, asked.candidates, confidence), kind, by: "model", options };
+}
+
+/** The identity a same-record answer proposes: `same` with a probability of at least 0.5. */
+export function sameRecord(
+  a: string,
+  b: string,
+  answer: DecideAnswer | undefined,
+  match: string,
+): IdentityPair | null {
+  const p =
+    answer?.probabilities?.same ?? (answer?.choice === "same" ? (answer.confidence ?? 0) : 0);
+  return p >= 0.5
+    ? { a, b, confidence: round(p), reason: `the decision model: the same, by ${match}` }
+    : null;
+}