@littlebigbrain/create 0.0.0-stage → 0.2.0

package/templates/ontology-fit/workflow.ts

@@ -0,0 +1,416 @@
+// ontology-fit: read the text of each new or changed instance of a class
+// and propose the ontology changes the text supports, as review items.
+//
+// A triggered workflow of the starter workflow `workflow` watches a class and
+// its text field, and sends the new and changed instances to this workflow.
+// For each instance the workflow asks the reasoning model (`reason`) which
+// classes, properties and relations the text needs that the ontology lacks,
+// each with a sentence of the text as its quote. It keeps a proposal when the
+// quote is in the text and a dry run of the change (`evolve` with `dryRun`)
+// says the ontology does not have it yet. Each kept change becomes a review
+// item with the change: a person accepts it, and the ontology changes.
+//
+// A change's key names it (`fit:<workflow>/add_class/mangel`), so the same
+// change from several texts is one review item.
+import {
+  LbbError,
+  triggeredWorkflow,
+  type LbbActivities,
+  type Schemas,
+  type WorkflowTriggerMessage,
+} from "@littlebigbrain/client";
+
+export interface Settings {
+  /** The class whose instances hold the text. */
+  className: string;
+  /** The property that holds each instance's text. */
+  textField: string;
+  /** One sentence about what the text is, for the model. */
+  context: string;
+}
+
+/** The settings: edit them for your class. These fit the samples. */
+export const defaults: Settings = {
+  className: "Baustellenbericht",
+  textField: "text",
+  context: "Site reports and meeting minutes of a school building project, in German",
+};
+
+/** The workflow type and version the triggered workflow names. */
+export const workflowType = { workflow_type: "ontology-fit", version: "v1" };
+
+/** The triggered workflow that sends the texts to this workflow. Its name starts every key. */
+export function trigger(settings: Settings = defaults): Schemas["TriggeredWorkflowRequest"] {
+  return {
+    starter: "workflow",
+    name: "berichte",
+    watch: { class: settings.className, fields: [settings.textField] },
+    workflow: workflowType,
+    batch: 8,
+  };
+}
+
+/** The class the workflow reads, for `lbb.evolve`. */
+export function ontology(settings: Settings = defaults): Schemas["OntologyEvolveOp"][] {
+  return [
+    { op: "add_entity_type", name: settings.className },
+    { op: "add_property", name: settings.textField, value_type: "text" },
+  ];
+}
+
+export interface FitState {
+  texts: number;
+  proposals: number;
+  filed: number;
+}
+
+/** One proposal as the model gives it: every field a string, empty when the kind does not use it. */
+interface Raw {
+  kind: string;
+  name: string;
+  parent: string;
+  class: string;
+  value_type: string;
+  domain: string;
+  range: string;
+  quote: string;
+  reason: string;
+}
+
+/** A proposal as a change: its key, title and evolve operations, and the quote that supports it. */
+export interface Change {
+  key: string;
+  title: string;
+  anchor: Schemas["SuggestionAnchor"];
+  change: Schemas["OntologyEvolveOp"][];
+  quote: string;
+  reason: string;
+}
+
+const SYSTEM = `You read text from a knowledge graph and propose changes to its ontology. The ontology has classes, relations between classes, and properties. Propose only changes that the text supports and that the ontology does not have yet:
+- add_class: a new kind of thing the text talks about, with its parent class when one in the ontology fits (\`name\`, \`parent\`).
+- add_property: a new fact that instances of a class carry (\`name\`, \`class\`, \`value_type\`).
+- add_relation: a new link between two classes (\`name\`, \`domain\`, \`range\`).
+- widen_relation: an existing relation that should also start at (\`domain\`) or point to (\`range\`) another class (\`name\` is the relation).
+Rules:
+- Propose kinds of things and links that many texts like this one hold. Do not propose one person, one date, one number, or one event as a class.
+- Each proposal quotes one sentence of the text in \`quote\`, copied exactly, character for character. A proposal without an exact quote is dropped.
+- Use the ontology's names for existing classes and relations. Name new classes as singular nouns, as the ontology names its classes. Name new relations as verbs and new properties as nouns, in the naming style the ontology states (UPPER_SNAKE_CASE relations and snake_case properties when it states none).
+- A list may follow of the changes already proposed and waiting for review. When the text supports one of them, propose it again with exactly the same names: it adds evidence. Never propose a synonym of a relation or property the ontology has or the list holds, and never the inverse of one.
+- \`reason\` is one short sentence.
+- Leave the fields a kind does not use empty.
+- Propose at most 12 changes. An empty list is a good answer when the ontology covers the text.`;
+
+const text = (description: string) => ({ type: "string", description });
+const SCHEMA = {
+  type: "object",
+  additionalProperties: false,
+  required: ["proposals"],
+  properties: {
+    proposals: {
+      type: "array",
+      items: {
+        type: "object",
+        additionalProperties: false,
+        required: [
+          "kind",
+          "name",
+          "parent",
+          "class",
+          "value_type",
+          "domain",
+          "range",
+          "quote",
+          "reason",
+        ],
+        properties: {
+          kind: {
+            type: "string",
+            enum: ["add_class", "add_property", "add_relation", "widen_relation"],
+          },
+          name: text(
+            "The new class, property or relation; for widen_relation the existing relation.",
+          ),
+          parent: text("add_class: the parent class, or empty."),
+          class: text("add_property: the class whose instances carry the property."),
+          value_type: {
+            type: "string",
+            enum: ["", "text", "keyword", "i64", "f64", "bool", "date_time"],
+            description: "add_property: the type of the values.",
+          },
+          domain: text("add_relation and widen_relation: the source class."),
+          range: text("add_relation and widen_relation: the target class."),
+          quote: text("One sentence of the text, copied exactly."),
+          reason: text("Why the text needs this change, one short sentence."),
+        },
+      },
+    },
+  },
+};
+
+/** Texts one turn reads: one step each. */
+const TURN_INSTANCES = 48;
+const TEXT_CHARS = 40_000;
+const PLAIN_IRI = /^[^\s<>"{}|\\^`]+$/;
+const normalize = (value: string) => value.split(/\s+/).filter(Boolean).join(" ");
+
+/** A part of a key: lowercase ASCII letters and digits, every other run as one dash. */
+export function keyPart(value: string): string {
+  const part = value
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, "-")
+    .replace(/^-+|-+$/g, "")
+    .slice(0, 48)
+    .replace(/-+$/, "");
+  return part || "x";
+}
+
+/** The ontology as the model reads it, and its names by lower case. */
+export function describe(view: Schemas["OntologyView"]) {
+  const types = (view.entity_type_defs ?? []).filter((t) => t.removed_version == null);
+  const relations = (view.relation_defs ?? []).filter((r) => r.removed_version == null);
+  const properties = view.property_defs ?? [];
+  const byId = new Map(types.map((t) => [t.stable_id, t.name]));
+  const side = (names: string[]) => (names.length ? names.join(" | ") : "any");
+  const lines = [
+    "Classes (name: parent classes):",
+    ...types.map(
+      (t) =>
+        `- ${t.name}${t.super_types?.length ? `: ${t.super_types.map((id) => byId.get(id) ?? id).join(", ")}` : ""}`,
+    ),
+    "Relations (name: domain -> range):",
+    ...relations.map((r) => `- ${r.name}: ${side(r.src_types)} -> ${side(r.dst_types)}`),
+    "Properties (graph-wide fields, name: value type):",
+    ...properties.map((p) => `- ${p.name}: ${p.value_type}`),
+  ];
+  const index = (names: string[]) => new Map(names.map((n) => [n.toLowerCase(), n]));
+  return {
+    text: lines.join("\n"),
+    classes: index(types.map((t) => t.name)),
+    relations: index(relations.map((r) => r.name)),
+    properties: index(properties.map((p) => p.name)),
+  };
+}
+type Ontology = ReturnType<typeof describe>;
+
+/** A raw proposal as a change with its key, or null when it has no shape. Adapted from fit_sources.rs. */
+export function shape(source: string, raw: Raw, onto: Ontology): Change | null {
+  const name = raw.name.trim();
+  if (!name || !["add_class", "add_property", "add_relation", "widen_relation"].includes(raw.kind))
+    return null;
+  const cls = (n: string) => onto.classes.get(n.trim().toLowerCase()) ?? n.trim();
+  const declare = (names: string[]): Schemas["OntologyEvolveOp"][] =>
+    [...new Set(names.filter((n) => n && !onto.classes.has(n.toLowerCase())))].map((n) => ({
+      op: "add_entity_type",
+      name: n,
+    }));
+  const base = { quote: raw.quote, reason: raw.reason.trim() };
+  // A new relation with the name of an existing one widens it.
+  const relation = onto.relations.get(name.toLowerCase());
+  const kind = raw.kind === "add_relation" && relation ? "widen_relation" : raw.kind;
+  const prefix = `fit:${source}/${kind}`;
+  if (kind === "add_class") {
+    const parent =
+      raw.parent.trim() && raw.parent.trim().toLowerCase() !== name.toLowerCase()
+        ? cls(raw.parent)
+        : "";
+    const change: Schemas["OntologyEvolveOp"][] = [
+      { op: "add_entity_type", name: cls(name) },
+      ...declare([parent]),
+    ];
+    if (parent)
+      change.push({ op: "add_super_types", entity_type: cls(name), super_types: [parent] });
+    return {
+      ...base,
+      key: `${prefix}/${keyPart(cls(name))}`,
+      title: parent ? `Add class ${cls(name)} under ${parent}` : `Add class ${cls(name)}`,
+      anchor: { kind: "class", name: cls(name) },
+      change,
+    };
+  }
+  if (kind === "add_property") {
+    if (!raw.class.trim()) return null;
+    const property = onto.properties.get(name.toLowerCase()) ?? name;
+    const type = ["text", "keyword", "i64", "f64", "bool", "date_time"].includes(raw.value_type)
+      ? raw.value_type
+      : "text";
+    return {
+      ...base,
+      key: `${prefix}/${keyPart(cls(raw.class))}/${keyPart(property)}`,
+      title: `Add property ${property} to ${cls(raw.class)}`,
+      anchor: { kind: "property", name: property },
+      change: [{ op: "add_property", name: property, value_type: type }],
+    };
+  }
+  const [domain, range] = [
+    raw.domain.trim() ? cls(raw.domain) : "",
+    raw.range.trim() ? cls(raw.range) : "",
+  ];
+  if (kind === "add_relation") {
+    if (!domain || !range) return null;
+    return {
+      ...base,
+      key: `${prefix}/${keyPart(domain)}/${keyPart(name)}/${keyPart(range)}`,
+      title: `Add relation ${name} from ${domain} to ${range}`,
+      anchor: { kind: "relation", name },
+      change: [
+        ...declare([domain, range]),
+        { op: "add_relation", name, domain: [domain], range: [range] },
+      ],
+    };
+  }
+  if (!domain && !range) return null;
+  const widened = relation ?? name;
+  const title =
+    domain && range
+      ? `Let ${widened} link ${domain} to ${range}`
+      : domain
+        ? `Let ${widened} start at ${domain}`
+        : `Let ${widened} point to ${range}`;
+  const widen: Schemas["OntologyEvolveOp"] = {
+    op: "widen_relation",
+    relation: widened,
+    add_domain: domain ? [domain] : [],
+    add_range: range ? [range] : [],
+  };
+  return {
+    ...base,
+    key: `${prefix}/${keyPart(widened)}/${keyPart(domain || "-")}/${keyPart(range || "-")}`,
+    title,
+    anchor: { kind: "relation", name: widened },
+    change: [...declare([domain, range]), widen],
+  };
+}
+
+/** A quote must be in the text, whitespace normalized, with at least three words. */
+export const quoteInText = (quote: string, value: string) =>
+  normalize(quote).split(" ").length >= 3 && normalize(value).includes(normalize(quote));
+
+/** The workflow, for a `WorkflowWorker`. `lbb` is `lbbActivities(client)`, or a mock in a test. */
+export function createWorkflow(lbb: LbbActivities, settings: Settings = defaults) {
+  return triggeredWorkflow<FitState>({
+    name: workflowType.workflow_type,
+    version: workflowType.version,
+    initialState: { texts: 0, proposals: 0, filed: 0 },
+    async onInstances(ctx, message, state) {
+      const batch = message.instances.slice(0, TURN_INSTANCES);
+      const texts = reader(message, batch);
+      let onto: Promise<Ontology> | undefined;
+      const kept: Change[][] = [];
+      for (const [i, iri] of batch.entries()) {
+        kept.push(
+          await ctx.step(`propose-${i}`, async (s) => {
+            s.progress("reading texts", { done: i, total: batch.length, unit: "instances" });
+            const record = (await texts())[iri];
+            if (!record?.text.trim()) return [];
+            const ontology = await (onto ??= lbb.ontology().then(describe));
+            // The changes the earlier texts of this turn proposed: the model proposes them again by the same names.
+            const earlier = [...new Set(kept.flat().map((c) => c.title))];
+            const system = [
+              SYSTEM,
+              `The ontology now:\n${ontology.text}`,
+              ...(earlier.length
+                ? [
+                    `Changes already proposed and waiting for review:\n${earlier.map((t) => `- ${t}`).join("\n")}`,
+                  ]
+                : []),
+            ].join("\n\n");
+            const prompt = JSON.stringify({
+              class: settings.className,
+              context: settings.context,
+              instance: record.label,
+              text: record.text,
+            });
+            const answer = await lbb.reason<{ proposals: Raw[] }>(
+              { system, prompt, schema: SCHEMA, max_tokens: 16_000 },
+              { effectId: s.effectId, label: `${record.label.slice(0, 50)} fit` },
+            );
+            const out: Change[] = [];
+            for (const raw of (answer.value.proposals ?? []).slice(0, 12)) {
+              const change = shape(message.workflow, raw, ontology);
+              if (
+                !change ||
+                out.some((c) => c.key === change.key) ||
+                !quoteInText(change.quote, record.text)
+              )
+                continue;
+              // A dry run: a change the ontology has already is a no-op.
+              const preview = await lbb
+                .evolve(change.change, { dryRun: true })
+                .catch((error: unknown) => {
+                  if (error instanceof LbbError && error.status === 400) return null;
+                  throw error;
+                });
+              if (preview && !preview.no_op && preview.publishable) out.push(change);
+            }
+            return out;
+          }),
+        );
+      }
+      const filed = await ctx.step("review", async (s) => {
+        const records = await texts();
+        const byKey = new Map<
+          string,
+          { change: Change; samples: { entity: string; label: string; quote: string }[] }
+        >();
+        for (const [i, changes] of kept.entries())
+          for (const change of changes) {
+            const group = byKey.get(change.key) ?? { change, samples: [] };
+            group.samples.push({
+              entity: batch[i]!,
+              label: records[batch[i]!]?.label ?? "",
+              quote: change.quote.slice(0, 600),
+            });
+            byKey.set(change.key, group);
+          }
+        for (const [n, { change, samples }] of [...byKey.values()].entries()) {
+          s.progress("filing review items", { done: n, total: byKey.size, unit: "items" });
+          await lbb.review({
+            workflow: message.workflow,
+            key: change.key,
+            title: change.title.slice(0, 200),
+            rationale: `${change.reason} "${change.quote.slice(0, 600)}"`.trim().slice(0, 4_000),
+            anchor: change.anchor,
+            change: change.change,
+            evidence: { records: samples.length, samples: samples.slice(0, 20) },
+          });
+        }
+        return byKey.size;
+      });
+      const next = {
+        texts: state.texts + batch.length,
+        proposals: state.proposals + kept.flat().length,
+        filed: state.filed + filed,
+      };
+      const rest = message.instances.slice(TURN_INSTANCES);
+      return rest.length
+        ? ctx.continue(next, { ...message, instances: rest, removed: [] })
+        : { state: next };
+    },
+  });
+
+  /** The label and text of each instance of the turn, read once per attempt at the message's commit. */
+  function reader(message: WorkflowTriggerMessage, iris: string[]) {
+    let read: Promise<Record<string, { label: string; text: string }>> | undefined;
+    return () =>
+      (read ??= (async () => {
+        const query = `# ontology-fit: texts
+SELECT ?s ?label ?text WHERE {
+  VALUES ?s { ${iris
+    .filter((iri) => PLAIN_IRI.test(iri))
+    .map((iri) => `<${iri}>`)
+    .join(" ")} }
+  OPTIONAL { ?s <http://www.w3.org/2000/01/rdf-schema#label> ?label }
+  OPTIONAL { ?s <https://littlebigbrain.com/p/${encodeURIComponent(settings.textField.toLowerCase())}> ?text }
+}`;
+        const { rows } = await lbb.sparql({ query, as_of_commit_seq: message.as_of_commit_seq });
+        const out: Record<string, { label: string; text: string }> = {};
+        for (const row of rows) {
+          const record = (out[row.s!] ??= { label: row.label ?? row.s!, text: "" });
+          if (row.text && !record.text.includes(row.text))
+            record.text = `${record.text}\n${row.text}`.trim().slice(0, TEXT_CHARS);
+        }
+        return out;
+      })());
+  }
+}

package/templates/review/README.md

@@ -0,0 +1,158 @@
+# review
+
+Decides which fact proposals become facts. A proposer (the
+[`documents-map`](../documents-map/README.md) template, LBB's
+`documents.map`, or a workflow of yours) does not write the facts of the
+graph's own ontology itself: it writes one `FactProposal` per statement,
+with its confidence and its evidence. This workflow writes a proposal at or
+above the gate as a fact, with the proposal as its evidence, and gives the
+others to a person: one review item per instance.
+
+The LBB-run version is the starter workflow `review@v1`
+(`docs/reference/starter-workflows.md`, "Review"; design
+`docs/architecture/document-output-mapping.md`). This template is the same
+decision in TypeScript: the workflow in `workflow.ts`, the rules and the
+facts in `decision.ts`. It calls no model.
+
+## How it runs
+
+The triggered workflow watches the class `FactProposal` and the fields of
+its statement (`fact_subject`, `fact_predicate`, `fact_object`), so a new
+proposal, or one whose statement changed, sends a message. A turn decides at
+most 20 proposals, two steps each, and files at most one review item per
+instance; the rest of a message goes to a new turn (`ctx.continue`). Each
+proposal is decided once: one that has a `fact_status` already is skipped.
+
+1. **Read** the proposal (`fact_subject`, `fact_predicate`, `fact_object`,
+   `fact_datatype`, `fact_confidence`, `fact_evidence`, `proposed_by`), the
+   entities its statement names, and the ontology (`GET /v1/ontology`). An
+   entity the graph does not have is a new instance: its class comes from an
+   `rdf:type` proposal of it, its name from an `rdfs:label` proposal.
+2. **What the statement is** (`classify`): an `rdf:type` of a class, an
+   `rdfs:label`, a relation between two instances (the entry's `DENOTES`
+   included), or a property value in its type. The ends of a relation must fit
+   its domain and range, superclasses included.
+3. **The decision** (`decide`), in this order:
+   - **refused** when the graph cannot hold the statement: a predicate that
+     is no relation or property of the records ontology (nor `rdf:type` or
+     `rdfs:label`), a value of another type, an object that is no instance,
+     an instance without a class, an end its relation does not take, a second
+     class, or a statement about a proposal;
+   - **to a person** when a rule of `alwaysReview` names it (`new_instance`:
+     a statement whose subject or object the graph does not have yet; or a
+     predicate IRI), when it would replace another writer's value (a records
+     graph holds one value per property) or name, or when its confidence is
+     below the gate. The proposal goes into the **review item of its
+     instance** (`groupOf`): its subject; the object of a link whose subject
+     the graph has and whose object is new; and always the object of the
+     trace (`DENOTES`). One item holds every proposal of its instance that
+     the turn sends to a person, in order: the type, the label, values,
+     links, the trace (`fileItem`). Its title names the instance (`New
+     Equipment M 7 Medienwagen`, or `Room Raum 0.12 Klassenraum: 1 fact to
+     check`), its rationale says why, and it has one evidence sample per
+     fact (what it states, its confidence, its line). Its facts are each
+     statement and its proposal's `fact_status: accepted`, and each sample
+     names the rows and triplets of its fact (`row`, `rows`, `triplets`), so
+     a person can leave facts out of the accept. The type of a new instance
+     is a required row: a person keeps it or dismisses the item;
+   - **written** otherwise: a relation as an edge whose evidence names the
+     proposal (`source_id` is the proposal's IRI, the text its evidence); a
+     property as its value; a new instance's `rdf:type` as the instance of
+     that class with `proposed_in` (a records graph holds an instance through
+     its facts); a label as the entity's name. A new instance takes the name
+     of its label proposal (the first in order) from its first write, so its
+     name does not depend on which statement is written first. A label is a
+     text: an IRI or an empty label is refused. A statement the graph holds
+     already is not written again. Nothing is taken back, a name included: a
+     records instance keeps one.
+4. **Write** (`writeOwned`): the proposal's `fact_status` (`written`,
+   `in_review` or `refused`) and `review_note`, owned by this workflow, and in
+   the same commit the facts of a written statement.
+
+## Settings
+
+`defaults` in `workflow.ts`, those of LBB's `review`:
+
+| Setting | Default | Meaning |
+| --- | --- | --- |
+| `className` | `FactProposal` | The class of the proposals |
+| `gate` | 0.8 | A proposal below this confidence goes to a person |
+| `alwaysReview` | `[]` | What goes to a person whatever its confidence: `new_instance`, and predicate IRIs (`https://littlebigbrain.com/r/has_equipment`). Empty: the gate decides everything, a new instance too |
+
+With `["new_instance"]` every statement about a new instance goes to a
+person, whatever its confidence. That was the default of LBB's `review`
+until 2026-10-12.
+
+`trigger(settings)` names the triggered workflow `review` and owns
+`fact_status` and `review_note`. `ontology(settings)` adds the class and the
+properties of a proposal and of the review (`proposed_in` too). Do not run it
+beside an LBB-run `review` on the same graph: they own the same properties.
+
+## What the LBB-run version adds
+
+- **It writes the accepted facts itself.** Its item carries the statuses
+  only; its sweep writes each kept fact, the type first, and dismisses the
+  facts a person left out. A link to another new instance waits until that
+  instance's item is accepted, and is dismissed with it. The template's item
+  commits its facts on accept, so such a link makes the other instance too.
+- **One item per instance over time.** Its items follow the open proposals
+  of an instance across messages: when they change, it supersedes the open
+  item with a new one, and an accept of the old item fails (409). The
+  template files one item per instance and turn: the key carries the
+  proposals, so a later turn with other proposals of the instance files
+  another item.
+- **Withdrawn proposals.** When a proposer withdraws a proposal, it takes
+  the proposal out of its item and retracts the fact it wrote, unless a
+  person accepted it or the fact held before; a record per proposal says
+  which fact. The template keeps both: dismiss the item, or retract the fact
+  yourself.
+- **Dismissed items.** It checks the open review items and sets
+  `dismissed` on the proposals of a dismissed one. The template leaves
+  `in_review`.
+- **Predicates another workflow owns.** It refuses a statement whose
+  predicate another workflow owns by predicate, since that workflow's owned
+  write would delete it.
+- **RDF-native graphs by IRI.** On an RDF-native graph it writes each
+  statement as one owned triple: `lbb:denotes`, the asserted schema's
+  properties (the OWL object, symmetric, transitive, functional,
+  inverse-functional and asymmetric properties take an IRI) and classes
+  (the ends of `rdfs:subClassOf` count), the records ontology's terms and
+  `rdfs:label`. There a subject or object is new when it is the subject of
+  no statement. The template writes through `POST /v1/graph/commit`, on both
+  graph kinds: the records ontology's relations (the records `DENOTES`
+  included), properties and classes, and `rdfs:label`. An instance is new
+  when it has no class of the records ontology. It refuses any other
+  predicate with a note that says so (`owl:sameAs`, `lbb:denotes`).
+- **Ownership by statement.** Its facts count as owned by statement, so it
+  conflicts with no other workflow on the predicates it writes. The template
+  owns `fact_status` and `review_note` only and writes the facts without
+  owning them.
+- **The graph refuses.** It lets the commit refuse a statement (a domain, a
+  range) and marks the proposal `refused`. The template checks domain and
+  range before it writes; another refusal stops the turn.
+- **Status and preview.** Counters per outcome, the open items it follows,
+  and a preview of what it would decide.
+
+## Samples and test
+
+`samples/proposals.json` holds a small invented graph (two rooms of the
+school building and five pieces of equipment, one `HAS_EQUIPMENT` edge) and
+14 proposals about it, one for each case; `samples/expected.json` gives the
+status each one gets with `alwaysReview` `["new_instance"]`, the facts the
+graph holds after the run, and the three review items with the proposals
+each one holds
+([`../_samples/README.md`](../_samples/README.md)).
+
+`npm run try` adds the sample ontology (`Room`, `Equipment`,
+`HAS_EQUIPMENT`, `identifier`, `area_m2`), commits the instances, reads
+their IRIs back, and commits the proposals as a proposer would
+(`proposed_by` is `samples/review`). This is the simplest input: the review
+calls no model and needs no proposer to run first. To review the proposals
+of `documents-map`, run it (or LBB's `documents.map`) on the same graph.
+
+`workflow.test.ts` runs the workflow on a graph in memory with the samples:
+the statuses and facts of the answer key, the evidence of a written fact,
+the notes, one item per instance (the order of its facts and its required
+type), the facts of an accepted item, the default settings (the gate
+decides a new instance), a predicate rule, a second message that changes
+nothing, and a message larger than a turn.