@littlebigbrain/create 0.1.0 → 0.3.0

package/README.md

@@ -15,9 +15,12 @@ npm test
 
 | Template | Does |
 | --- | --- |
-| `documents-link` | Finds the identifiers the documents define and the spans that mention them, and links each mention to its entry |
+| `documents-link` | Connects mentions of the same thing across the documents: each reference links to where that thing is defined or described |
 | `values-extract` | Fills properties of a class from the text of its instances, each value with a verbatim quote |
 | `ontology-fit` | Proposes the ontology changes the texts of a class support, as review items |
+| `documents-map` | Maps the links of `documents-link` into the graph's own ontology, as fact proposals |
+| `review` | Writes the fact proposals at or above a gate as facts and gives the others to a person |
+| `link` | Connects the mentions of one thing across the records of a graph into one thing, and proposes records of one thing as an identity |
 
 A template id is the id of its starter workflow, with dashes for dots:
 `documents-link` is the code of `documents.link`.
@@ -29,7 +32,8 @@ A template id is the id of its starter workflow, with dashes for dots:
 | `src/workflow.ts` | The workflow, its settings, the triggered workflow that sends it the instances (`trigger()`) and the ontology it writes (`ontology()`) |
 | `src/*.ts` | The template's helpers and `samples.ts`, which puts the samples on a graph |
 | `src/workflow.test.ts`, `src/testing.ts` | The workflow on its samples, with mock models and no server |
-| `src/worker.ts`, `src/setup.ts`, `src/try.ts` | `npm start`, `npm run setup` and `npm run try` |
+| `src/worker.ts`, `src/setup.ts`, `src/try.ts` | `npm start`, `npm run setup` and `npm run try`; a template that has its own (`link`) keeps them |
+| `src/grade-run.ts` | `npm run grade`, in a template that grades a run against a gold file (`link`) |
 | `samples/` | The samples and their answer key |
 
 `npm run try` creates a graph (`LBB_GRAPH`, default `try-<template>`), puts

package/lib/create.mjs

@@ -15,7 +15,14 @@ import { basename, dirname, join, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 
 /** The templates a project can start from: the folder names under `sdk/templates`. */
-export const TEMPLATES = ["documents-link", "values-extract", "ontology-fit"];
+export const TEMPLATES = [
+  "documents-link",
+  "documents-map",
+  "review",
+  "values-extract",
+  "ontology-fit",
+  "link",
+];
 
 const PACKAGE = resolve(dirname(fileURLToPath(import.meta.url)), "..");
 
@@ -113,15 +120,23 @@ export async function create({ template, dir, client, root = PACKAGE }) {
   const src = join(dir, "src");
   await mkdir(src, { recursive: true });
 
-  // The template's code, its test and the test support, all under src/.
-  for (const file of await readdir(from)) {
-    if (!file.endsWith(".ts")) continue;
+  // The template's code, its test and the test support, all under src/, the
+  // template's folders (`sources/`) as they are.
+  const code = await templateCode(from);
+  for (const file of code) {
     const text = await readFile(join(from, file), "utf8");
-    await writeFile(join(src, file), text.replaceAll("../_shared/testing.js", "./testing.js"));
+    const up = "../".repeat(file.split("/").length - 1);
+    await mkdir(dirname(join(src, file)), { recursive: true });
+    await writeFile(
+      join(src, file),
+      text.replaceAll(`../${up}_shared/testing.js`, `${up || "./"}testing.js`),
+    );
   }
   await cp(join(templates, "_shared", "testing.ts"), join(src, "testing.ts"));
   await cp(join(from, "samples"), join(dir, "samples"), { recursive: true });
+  // A template's own commands win: a workflow of several parts sets itself up.
   for (const file of ["worker.ts", "setup.ts", "try.ts"]) {
+    if (code.includes(file)) continue;
     const text = await readFile(join(root, "project", file), "utf8");
     await writeFile(join(src, file), text.replaceAll("__TEMPLATE__", template));
   }
@@ -138,6 +153,7 @@ export async function create({ template, dir, client, root = PACKAGE }) {
       try: "tsx src/try.ts",
       test: "tsx --test src/workflow.test.ts",
       typecheck: "tsc --noEmit",
+      ...(code.includes("grade-run.ts") ? { grade: "tsx src/grade-run.ts" } : {}),
     },
     dependencies: { "@littlebigbrain/client": client ?? `^${clientVersion(templates)}` },
     devDependencies: { "@types/node": "^22", tsx: "^4", typescript: "^5.6" },
@@ -203,6 +219,18 @@ ${projectReadme(readme).trim()}
   return listFiles(dir);
 }
 
+/**
+ * The TypeScript files of a template folder, relative, in its folders too;
+ * the samples are copied on their own.
+ * @param {string} from
+ * @returns {Promise<string[]>}
+ */
+async function templateCode(from) {
+  return (await listFiles(from)).filter(
+    (file) => file.endsWith(".ts") && !file.startsWith("samples/"),
+  );
+}
+
 /** Every file under `dir`, relative and sorted. @param {string} dir @returns {Promise<string[]>} */
 async function listFiles(dir, prefix = "") {
   /** @type {string[]} */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@littlebigbrain/create",
-  "version": "0.1.0",
+  "version": "0.3.0",
   "description": "Create a project from a little big brain starter workflow template: npm create @littlebigbrain",
   "license": "Apache-2.0",
   "repository": {

package/templates/_shared/testing.ts

@@ -26,6 +26,8 @@ import {
   type SparqlResults,
   type WorkflowContext,
   type WorkflowDefinition,
+  type WorkflowProgressCounts,
+  type WorkflowStepContext,
   type WorkflowTriggerMessage,
 } from "@littlebigbrain/client";
 
@@ -291,12 +293,13 @@ export class MockActivities implements LbbActivities {
   writeOwned(
     ctx: WorkflowContext,
     stepKey: string,
-    write: OwnedWrite | (() => OwnedWrite | Promise<OwnedWrite>),
+    write: OwnedWrite | ((step: WorkflowStepContext) => OwnedWrite | Promise<OwnedWrite>),
   ) {
-    return ctx.step(stepKey, async ({ effectId }) => {
+    return ctx.step(stepKey, async (step) => {
+      const { effectId } = step;
       const replayed = this.written.has(effectId);
       if (!replayed) {
-        this.graph.apply(typeof write === "function" ? await write() : write);
+        this.graph.apply(typeof write === "function" ? await write(step) : write);
         this.written.add(effectId);
       }
       return {
@@ -345,12 +348,33 @@ function assertNever(what: string): never {
 
 // ---- turns -------------------------------------------------------------------------
 
-/** One turn: its step keys, their saved outputs, and the model calls of its steps. */
+/** One progress report of a step (`s.progress`), as the worker would send it. */
+export interface ProgressCall extends WorkflowProgressCounts {
+  step: string;
+  phase: string;
+}
+
+/** One turn: its step keys, their saved outputs, and the progress its steps reported. */
 export interface Turn {
   message: WorkflowTriggerMessage;
   keys: string[];
   outputs: unknown[];
   bytes: number;
+  progress: ProgressCall[];
+}
+
+const UNIT = /^[\p{L}\p{N} _-]{1,32}$/u;
+const whole = (n: unknown) => Number.isSafeInteger(n) && (n as number) >= 0;
+
+/** A progress report checked as the worker checks it: the progress convention. */
+function progressCall(step: string, phase: string, counts: WorkflowProgressCounts): ProgressCall {
+  const text = phase.trim();
+  if (!text || [...text].length > 80) throw new Error(`step ${step}: progress phase "${phase}"`);
+  if (!whole(counts.done) || (counts.total !== undefined && !whole(counts.total)))
+    throw new Error(`step ${step}: progress counts ${JSON.stringify(counts)}`);
+  if (counts.unit !== undefined && !UNIT.test(counts.unit))
+    throw new Error(`step ${step}: progress unit "${counts.unit}"`);
+  return { step, phase: text, ...counts };
 }
 
 /** What a turn returns: its state, and a continuation when the work goes on in another turn. */
@@ -381,17 +405,24 @@ export async function runTurn<S>(
   definition: WorkflowDefinition<S, WorkflowTriggerMessage>,
   state: unknown,
   message: WorkflowTriggerMessage,
-  options: { prefix?: string; saved?: Turn; crashAfter?: number } = {},
+  options: {
+    prefix?: string;
+    saved?: Turn;
+    crashAfter?: number;
+    /** The engine identity that runs the turn (default `starter.test`), and the turn's number. */
+    workflowId?: string;
+    turn?: number;
+  } = {},
 ): Promise<{ result: TurnResult<S>; turn: Turn }> {
   const prefix = options.prefix ?? mockId(JSON.stringify(message));
-  const turn: Turn = { message, keys: [], outputs: [], bytes: 0 };
+  const turn: Turn = { message, keys: [], outputs: [], bytes: 0, progress: [] };
   let busy = false;
   let ran = 0;
   const ctx = {
     signal: new AbortController().signal,
-    workflowId: "starter.test",
+    workflowId: options.workflowId ?? "starter.test",
     messageId: "starter-test-1",
-    turn: 1,
+    turn: options.turn ?? 1,
     async step<T>(
       key: string,
       effect: (s: {
@@ -399,6 +430,7 @@ export async function runTurn<S>(
         signal: AbortSignal;
         checkpoint: unknown;
         heartbeat(): Promise<void>;
+        progress(phase: string, counts: WorkflowProgressCounts): void;
       }) => Promise<T>,
     ) {
       if (busy) throw new Error("steps run one at a time: await each step");
@@ -423,6 +455,7 @@ export async function runTurn<S>(
           signal: new AbortController().signal,
           checkpoint: null,
           heartbeat: async () => {},
+          progress: (phase, counts) => turn.progress.push(progressCall(key, phase, counts)),
         });
         const json = JSON.stringify(output ?? null);
         if (json.length > 64 * 1024)
@@ -454,17 +487,23 @@ export async function runTurn<S>(
 /**
  * Run a message and every continuation it leads to, from the empty state the
  * server creates the instance with. Returns the final state and the turns.
+ * With `workflowId` and `turn`, the turns run as that identity, numbered
+ * from `turn` on.
  */
 export async function runMessage<S>(
   definition: WorkflowDefinition<S, WorkflowTriggerMessage>,
   message: WorkflowTriggerMessage,
   state: unknown = {},
+  options: { workflowId?: string; turn?: number } = {},
 ) {
   const turns: Turn[] = [];
   let next: WorkflowTriggerMessage | undefined = message;
   while (next) {
     if (turns.length > 100) throw new Error("more than 100 turns");
-    const ran: { result: TurnResult<S>; turn: Turn } = await runTurn(definition, state, next);
+    const ran: { result: TurnResult<S>; turn: Turn } = await runTurn(definition, state, next, {
+      ...(options.workflowId ? { workflowId: options.workflowId } : {}),
+      ...(options.turn !== undefined ? { turn: options.turn + turns.length } : {}),
+    });
     turns.push(ran.turn);
     state = ran.result.state;
     next = ran.result.continuation?.message;
@@ -472,6 +511,11 @@ export async function runMessage<S>(
   return { state: state as S, turns };
 }
 
+/** The phases the steps of `turns` reported, each once, in the order they first came. */
+export function phases(turns: Turn[]): string[] {
+  return [...new Set(turns.flatMap((t) => t.progress.map((p) => p.phase)))];
+}
+
 /** A trigger message of the triggered workflow `workflow`. */
 export function triggerMessage(
   workflow: string,

package/templates/documents-link/README.md

@@ -1,10 +1,12 @@
 # documents-link
 
-Finds the identifiers the documents of a graph define (the codes of an
-equipment list, the sections of a specification) and the spans of other
-documents that mention them, and links each mention to its entry. A room
-sheet's `S1.1` gets a `REFERS_TO` link to `S 1.1` of the equipment list,
-with the line as evidence and the span's box on the page as its region.
+Connects mentions of the same thing across the documents of a graph. It
+finds the identifiers the documents define (the codes of a parts list, the
+sections of a specification) and the spans that refer to them. Each
+mention links to the entry of the same thing, in the same document or in
+another one. A manual's `P114` gets a `REFERS_TO` link to `P 114` of the
+parts list, with the line as evidence and the span's box on the page as
+its region.
 
 The LBB-run version is the starter workflow `documents.link@v1`
 (`docs/reference/starter-workflows.md`, "Document workflows"). This
@@ -97,12 +99,12 @@ classes `DocEntry` and `DocMention` and the relations `DEFINED_IN`,
   definition across the whole document; here it stops at the end of the
   window.
 - **Number tokens and page heads.** Candidates also come from the number
-  tokens of a span (`Pos.-Nr. 2.4` finds `RB-Pos. 2.4`), and an own number
+  tokens of a span (`Section 2.4` finds `Ref. 2.4`), and an own number
   gets candidates by the meaning of its page head.
 - **Roles as a setting.** `params.roles` of the triggered workflow, so a
   request changes them without new code.
 - **Same-item questions.** A span that is the number of the item its page
-  is about (a room sheet's own position) is asked which entry describes the
+  is about (a product sheet's own number) is asked which entry describes the
   same item, and links with `SAME_ITEM_AS`. Here `own_number` does not
   link.
 - **Request size estimate.** A decide request is packed by an estimate of

package/templates/documents-link/workflow.test.ts

@@ -17,6 +17,7 @@ import {
   Crash,
   MockActivities,
   mockId,
+  phases,
   readJson,
   runMessage,
   runTurn,
@@ -362,8 +363,34 @@ test("a long document is read in windows over several turns", async () => {
   assert.equal(lbb.graph.edgesOf("REFERS_TO").length, 225);
 });
 
+test("each step reports its phase as the LBB-run documents.link words it", async () => {
+  const { turns } = await run();
+  assert.deepEqual(phases(turns), [
+    "reading pages",
+    "writing facts",
+    "embedding the catalogue",
+    "linking mentions",
+  ]);
+  const first = turns[0]!.progress[0]!;
+  assert.deepEqual(
+    [first.step, first.phase, first.done, first.unit],
+    ["define-p1", "reading pages", 0, "pages"],
+  );
+  const linking = turns.at(-1)!.progress.filter((p) => p.phase === "linking mentions");
+  assert.deepEqual(
+    linking.map((p) => p.done),
+    linking.map((_, n) => n),
+  );
+  assert.ok(linking.every((p) => p.total === linking.length && p.unit === "pages"));
+});
+
 test("links below the gate go to review instead of the graph", async () => {
-  const { lbb, docs, state } = await run({ gate: 0.99 });
+  const { lbb, docs, state, turns } = await run({ gate: 0.99 });
+  const filing = turns.flatMap((t) => t.progress).filter((p) => p.phase === "filing review items");
+  assert.deepEqual(
+    filing.map((p) => [p.done, p.total, p.unit]),
+    filing.map((_, k) => [k, 13, "items"]),
+  );
   const reviewed = [...lbb.reviews.values()];
   const linked = reviewed.filter((r) => r.key!.includes(":link:"));
   // One item per document, span and entry: S1.1 and S 2.1 are on both room sheets.

package/templates/documents-link/workflow.ts

@@ -1,5 +1,6 @@
-// documents-link: find the identifiers the documents of a graph define and the spans that mention
-// them, and link each mention to its entry.
+// documents-link: connect mentions of the same thing across the documents of a graph. Find the
+// identifiers the documents define and the spans that refer to them, and link each mention to the
+// entry it names.
 //
 // A triggered workflow of the starter workflow `workflow` watches the class `Document` and its
 // field `parse_status` (LBB's parse writes it), and sends the parsed documents here. The workflow
@@ -12,8 +13,8 @@
 //    candidates from the catalogue (every `DocEntry` of the graph) by characters and by meaning
 //    (`embed`), and the decision model (`decide`) answers what the span is and which entry it
 //    names. A mention is written as a `DocMention` `MENTIONED_IN` the document, with a
-//    `REFERS_TO` link to its entry when the link's confidence reaches the gate; a link below the
-//    gate becomes a review item.
+//    `REFERS_TO` link to the entry it names when the link's confidence reaches the gate; a link
+//    below the gate becomes a review item.
 //
 // Each model call runs in a step and passes the step's effect id, so a turn that runs again after
 // a crash pays for nothing twice.
@@ -254,6 +255,7 @@ async function define(
   const found: link.Definition[] = [];
   for (let page = w.from; page < w.to; page++) {
     const kept = await ctx.step(`define-p${page + 1}`, async (s) => {
+      s.progress("reading pages", { done: page - w.from, total: w.to - w.from, unit: "pages" });
       const p = await read.page(page);
       const answer = await lbb.reason(link.definitionsRequest(p), {
         effectId: s.effectId,
@@ -266,9 +268,10 @@ async function define(
   // A commit names at most 1,000 entities: the entries go in parts of at most 900.
   const count = new Set(found.map((d) => d.identifier)).size;
   for (let n = 0; n * link.PART < count; n++)
-    await lbb.writeOwned(ctx, `entries-${n}`, async () =>
-      link.part(link.entriesWrite(doc, await read.pages(), found), n),
-    );
+    await lbb.writeOwned(ctx, `entries-${n}`, async (s) => {
+      s.progress("writing facts", { done: n * link.PART, total: count, unit: "items" });
+      return link.part(link.entriesWrite(doc, await read.pages(), found), n);
+    });
   return { ...state, entries: state.entries + count };
 }
 
@@ -287,6 +290,7 @@ async function linkMentions(
   const mentions: link.Mention[][] = [];
   for (const page of pages) {
     const kept = await ctx.step(`mention-p${page + 1}`, async (s) => {
+      s.progress("reading pages", { done: page - w.from, total: w.to - w.from, unit: "pages" });
       const p = await read.page(page);
       const answer = await lbb.reason(link.mentionsRequest(p), {
         effectId: s.effectId,
@@ -296,12 +300,16 @@ async function linkMentions(
     });
     mentions.push(kept);
   }
-  const byMeaning = await ctx.step("meaning", (s) => meaning(s.effectId, lbb, doc, read, mentions));
+  const byMeaning = await ctx.step("meaning", (s) => {
+    s.progress("embedding the catalogue", { done: 0, unit: "items" });
+    return meaning(s.effectId, lbb, doc, read, mentions);
+  });
   const resolved: link.Resolved[][] = [];
   for (const [n, page] of pages.entries()) {
-    const answers = await ctx.step(`decide-p${page + 1}`, (s) =>
-      decidePage(s.effectId, lbb, doc, read, page, mentions[n]!, byMeaning[n]!),
-    );
+    const answers = await ctx.step(`decide-p${page + 1}`, (s) => {
+      s.progress("linking mentions", { done: n, total: pages.length, unit: "pages" });
+      return decidePage(s.effectId, lbb, doc, read, page, mentions[n]!, byMeaning[n]!);
+    });
     resolved.push(answers);
   }
 
@@ -316,7 +324,7 @@ async function linkMentions(
   );
   const written = all.filter((x) => x.target !== null && x.confidence >= settings.gate);
   const below = all.filter((x) => x.target !== null && x.confidence < settings.gate);
-  await ctx.step("review", async () => {
+  await ctx.step("review", async (s) => {
     const catalogue = await read.catalogue();
     // One item per span and entry: S1.1 on two pages is one item with two links.
     const groups = new Map<string, typeof below>();
@@ -331,7 +339,8 @@ async function linkMentions(
         group: group.slice(n * 100, (n + 1) * 100),
       })),
     );
-    for (const { n, group } of items) {
+    for (const [k, { n, group }] of items.entries()) {
+      s.progress("filing review items", { done: k, total: items.length, unit: "items" });
       const entry = catalogue[group[0]!.target!]!;
       const span = group[0]!.m.span;
       const lowest = Math.min(...group.map((x) => x.confidence));
@@ -357,7 +366,8 @@ async function linkMentions(
     return items.length;
   });
   for (let n = 0; n * link.PART < all.length; n++)
-    await lbb.writeOwned(ctx, `mentions-${n}`, async () => {
+    await lbb.writeOwned(ctx, `mentions-${n}`, async (s) => {
+      s.progress("writing facts", { done: n * link.PART, total: all.length, unit: "mentions" });
       const [pages, catalogue] = [await read.pages(), await read.catalogue()];
       const links = written.map((x) => ({ ...x, entry: catalogue[x.target!]! }));
       return link.part(link.mentionsWrite(doc, pages, all, links), n);

package/templates/documents-map/README.md

@@ -0,0 +1,212 @@
+# documents-map
+
+Maps the links of `documents-link` into the graph's own ontology. A
+manual's line `Replace the filter P114 every 500 hours` links the span
+`P114` to the entry `P 114` of the parts list. This workflow asks which
+instance each entry is and which statement the line makes, and proposes
+the fact `procedure 4.2 USES_PART part P 114`. It writes each statement as a
+`FactProposal`; a `review` workflow (LBB's `review`, or the
+[`review`](../review/README.md) template) decides which become facts.
+
+The LBB-run version is the starter workflow `documents.map@v1`
+(`docs/reference/starter-workflows.md`, `documents.map`; design
+`docs/architecture/document-output-mapping.md`). This template is the same
+pipeline in TypeScript: the workflow in `workflow.ts`, its questions, rules
+and proposals in `map.ts`.
+
+## How it runs
+
+The triggered workflow watches the class `DocMention` and its links
+`REFERS_TO` and `SAME_ITEM_AS`. A new, changed or withdrawn link sends a
+message. A message is a signal: each one maps every link of the graph
+again, in one turn. The decision model's calls take an effect id made from
+the content of their request, so a question asked again in a later message
+gets its first answer from LBB's effect cache at no cost. Only new and
+changed questions cost.
+
+1. **Read the trace** (`readTrace`). The links with their confidence (on the
+   link's evidence statement node), the mentions of the documents that hold
+   them, and the entries, with SPARQL at the message's commit.
+2. **The subject of each link** (`map.subjects`). The object is the entry
+   the span names. The subject is what the line belongs to, in the line's
+   own document. The first mention of a page heads the page when all of
+   these are true: the page has at least two mentions, the mention starts in
+   the top 30% of the page, no entry the document defines on the page is on
+   its row or above it, and it is written unlike most of the page's other
+   mentions (a product sheet's number above the codes it uses). Then its
+   link's entry, or else a page entry made from it (the span is the
+   identifier, the rest of its line the description), is the subject of
+   every other mention of the page, and of the next page when that has
+   neither a head nor an entry. Otherwise the subject is the last anchor at
+   or before the line (the document's own entries written like its first
+   one, such as the positions of a bill).
+3. **Ground the entries.** Each end of a link gets candidates: the
+   instances whose `identifier`, `rdfs:label`, `skos:notation`,
+   `skos:prefLabel`, `schema:identifier` or `dcterms:identifier` is the
+   identifier as written, without spaces, or with one space after its
+   letters (at most 10, each with its class, label and four facts). The
+   decision model answers which instance the entry is: a candidate,
+   `new_instance` or `none`. A new instance gets a second question, its
+   class among at most 12 classes, or `no_class`. Its IRI is minted from the
+   document and the identifier, so the same entry always proposes the same
+   instance.
+4. **Type the links.** For a link whose two ends are instances with a
+   class, the options are the relations whose domain and range fit the two
+   classes (superclasses included, both ways round, an inverse written the
+   right way round), at most 12, and `same_item`, `no_fact` and
+   `missing_property`. The state holds the page's rows (the parsed page, or
+   the lines of its mentions when the file has no parse), the two instances
+   and the part of the ontology the questions use. A declared mapping types
+   its links without a question.
+5. **Propose.** One `FactProposal` per statement (its key is
+   `proposal:<hash>` of the statement and the proposer, `proposed_by` is
+   `workflow/<name>`): a typed link with the link's confidence times the
+   typing answer's probability; `same_item` as `owl:sameAs`; an entry
+   grounded to an instance as `DENOTES` from the entry (or from the mention
+   of a page head) to the instance; a new instance with a class as its
+   `rdf:type` (the grounding answer's probability times the class answer's),
+   its `rdfs:label`, its `identifier` and its `DENOTES`. `fact_evidence` holds
+   the line, the page, the box, the link and every option with its
+   probability. An entry whose class question chose `no_class` proposes
+   nothing (no type, label, identifier or `DENOTES`) until the ontology has a
+   class for it, and its links are not typed.
+6. **Suggest.** The answers `no_class` and `missing_property` with a
+   probability of at least 0.5 become ontology suggestions, one per pattern
+   (see below).
+7. **Write.** The proposals that changed since the graph's copy, owned with
+   `replace_owned` over the proposal's seven fields, in parts of 900. The
+   proposals of this workflow that no link states any more are retracted.
+
+## Ontology suggestions
+
+Each suggestion explains itself. Its rationale says what the decision model
+found, from how many lines or entries, and quotes them (page, line, the two
+ends and the probability). Its samples have the shape of a review item's
+(`document`, `page` from 1, `line`, `box`, plus `line_id`, `span`, `subject`
+and `object`, or `identifier` and `description` for an entry), with the
+answer: `choice`, `answer` in words, `probability` and every option's
+probability in `options`.
+
+- **A relation** (`Add a relation from Room to SpecSection: SIEHE_KAP`). Its
+  name comes from the words next to the span on its lines: the two nearest
+  words before the span (else after it) that are made of letters, at least
+  three long, and not words of the two ends or of the object's document. The
+  phrase most lines share wins, in upper case ASCII. Only when the lines have
+  no such words is it `HAS_<CLASS>`. A taken name gets a number.
+- **The overlap rule.** When an existing relation fits the two classes
+  (either way round), a line backs the suggestion only when its typing
+  question offered that relation and the answer chose `missing_property`
+  over it. The suggestion is then filed only with at least 2 such lines, or
+  one at 0.8 or more (`OVERLAP_LINES`, `OVERLAP_ALONE_AT` in `map.ts`), and
+  its rationale names the relation and the most probability the answers gave
+  it. Otherwise nothing is filed, and the lines are unmapped links.
+- **A class** (`Add a class for 3.1 Bodenbeläge`, or `Add a class for 2
+  entries of baubeschreibung.pdf: 3.1 …, 3.2 …`). Its title and rationale
+  name its entries; the rationale lists the classes the answers weighed and
+  the entries of the same document, written the same way, that got a class
+  of the ontology. A person who finds those belong to the new class too
+  dismisses their types in the review.
+
+Edit the name, then accept (the accept request's `change`, or **Edit, then
+accept** in the console): the next message maps the links of the pattern
+again.
+
+**Unmapped links.** A link that makes no proposal and backs no filed
+suggestion stays in the workflow's state: `unmapped` counts them and
+`unmappedLinks` holds the first 50, by document, page and line, each with
+its line, the two ends, its `outcome` (`no_subject`, `ungrounded`,
+`same_instance`, `unclassed`, `unanswered`, `no_fact`, `lacks`), a `reason`
+in words and the typing answer when it has one.
+
+The questions go in requests of at most 32 questions and 60,000 characters:
+grounding and classes per defining document, typing per page. A refused
+request is asked in halves.
+
+## Settings
+
+`defaults` in `workflow.ts`:
+
+| Setting | Default | Meaning |
+| --- | --- | --- |
+| `mappings` | none | Declared mappings: `{ from: { document?, entry_class }, to: { entry_class }, property }`. A link from an instance of `from.entry_class` (in `document`) to one of `to.entry_class` (subclasses too) states `property`, with the link's confidence, and no model is asked |
+
+`trigger()` names the triggered workflow `documents-map` and owns the class
+`FactProposal` and its seven proposer fields. `ontology()` adds
+`FactProposal` and its fields, `identifier`, and the relation `DENOTES`,
+open on both sides (from an entry or a page's head mention to any
+instance), as LBB's `documents.map` declares it. Do not run it beside an
+LBB-run
+`documents.map` on the same graph: they own the same class.
+
+## What the LBB-run version adds
+
+- **Links below the gate.** It reads the stored outputs of the graph's
+  `documents.link` workflows, so it maps the links held for review too, with
+  their confidence. The template reads the links in the graph.
+- **The RDF schema.** It reads the RDFS and OWL schema of the published
+  generation beside the records ontology, and shows each term's
+  `rdfs:label` and `rdfs:comment` in the options. The template reads the
+  records ontology (`GET /v1/ontology`).
+- **More candidates.** The name index of `POST /v1/query/ask` and search by
+  meaning over the graph's embeddings; class options by meaning. The
+  template finds candidates by identifier and orders classes by shared
+  words.
+- **Descriptions.** An entry's description comes from the definitions
+  model. The graph holds the entry's context, which can run on to the next
+  rows; the template uses it.
+- **Both graph kinds by name.** It proposes the records relation
+  `DENOTES` (`https://littlebigbrain.com/r/denotes`) on a records graph, and
+  `lbb:denotes` (`https://littlebigbrain.com/ns#denotes`) and the schema's
+  own property IRIs on an RDF-native graph. The template proposes the
+  records relations (`https://littlebigbrain.com/r/<name>`), `DENOTES`
+  included, on both graph kinds.
+- **Scopes per document.** On an RDF-native graph it owns its proposals per
+  document (a proposal from several documents in the scope of the smallest
+  SHA-256), in one owned write per step. The template writes the proposals
+  with `replace_owned` on both graph kinds.
+- **Any number of links.** It runs in time-limited steps over any number of
+  documents and keeps its typed links per document. The template maps at
+  most 1,000 linked mentions in one turn and fails the turn (no retry) when
+  a graph needs more steps.
+- **Requests by tokens.** Requests are packed by an estimate of their
+  tokens (28,000), per page, four at once.
+- **A new ontology version maps again**, and a new decision model asks
+  again (its version holds the model). The template maps on a message: call
+  `client.workflows.triggered.refresh` after an ontology change, and change
+  `m1` in the effect id to ask a new model.
+- **Stale suggestions.** It supersedes the open suggestions a later run no
+  longer finds.
+- **Status and budget.** Counters per outcome, the `map` model job on the
+  Models page, a monthly budget and a preview. The template's calls count
+  as `decide` activities.
+
+## Samples and test
+
+`samples/` holds the three invented PDFs of `documents-link`, the parsed
+pages of the room sheets, `trace.json` (what a correct `documents-link` run
+writes on them: 15 entries, 21 mentions, 15 links) and the answer key
+`expected.json` ([`../_samples/README.md`](../_samples/README.md)).
+`node sdk/templates/_samples/make-trace.mjs` writes `trace.json` and the
+copies from the samples of `documents-link`.
+
+`npm run try` uploads the three PDFs and waits until LBB's
+`documents.parse` has read them, so the typing questions show the rows of
+each page. Then it adds the ontology of the samples (`Room`, `Equipment`,
+`SpecSection`, `HAS_EQUIPMENT`, `SPECIFIED_IN`) and commits the trace
+itself. This is the simplest way to run the map on known links: a link run
+first would need its own models and give links that vary from run to run.
+On your graph, run `documents.link` (or the `documents-link` template)
+first.
+
+`workflow.test.ts` runs the workflow on the trace with mock models: the
+grounding question picks a candidate whose label holds the identifier, else
+a new instance; the class question picks `Room` for the room sheets,
+`SpecSection` for a section and `Equipment` for the rest; the typing
+question picks the relation whose range is the object's class. The run makes
+the 15 facts of the answer key and the 60 statements of the 15 new
+instances, and nothing for `M 7`, `S 1.3` or `3.3`. The test also checks the
+confidences, a second message answered from the effect cache, a turn
+stopped part way, an existing instance, the ontology suggestions (their
+titles, rationales, samples, names from the lines, the overlap rule, and
+the links of an entry without a class as unmapped), a withdrawn link, a
+refused request split in halves, a declared mapping, and the subject rules.