@littlebigbrain/mcp 0.15.1 → 0.17.0

package/README.md

@@ -67,6 +67,11 @@ The client starts the server and communicates through standard input and output
 (stdio). Keep the key in your local configuration. Set `LBB_GRAPH` to change
 the default graph from `main`.
 
+A call that deletes or removes data asks you to approve it in the client. A
+client that cannot show the question gets the error `approval_required`, and
+nothing is sent. Set `LBB_MCP_DESTRUCTIVE=allow` in the server's environment
+to run such calls without a question.
+
 ## Run a first query
 
 This example stores three facts in a graph named `quickstart`: a service writes
@@ -159,7 +164,7 @@ its original identifiers; inspect it with SPARQL when choosing query predicates.
 | `lbb_workflows_manage` | Create a workflow from a starter workflow on a class (a developer workflow with its workflow type, owned outputs and batch), ask it to run now, or pause and resume a developer workflow. Define a workflow with triggers of your worker (shards, routing field, window) and run it now. |
 | `lbb_workflows_delete` | Delete a triggered workflow, or a workflow with triggers by its name. What it wrote stays. |
 | `lbb_files` | List the files of a graph, all or by parse status or a part of the name, and read the parsed pages of one: each line with its id, its box on the page and its text. |
-| `lbb_commit` | Write or retract JSON facts, or record search feedback. |
+| `lbb_commit` | Write legacy JSON facts, explicitly commit versioned records, retract facts, or record search feedback. |
 | `lbb_configure` | Define record types and relationships, list and apply ontology starters (CRM, documents, work), publish validation rules, or keep the graph's notes and worked examples for questions in plain words (`get_rewrite_profile`, `set_rewrite_profile`). |
 | `lbb_evals` | Label query results and check whether later queries return the expected answers. Read the model checks of a graph, and agree with or correct a check that the user confirmed. |
 | `lbb_model_choice` | Read which model each use runs (question answers, query routing, search rerank, ontology fit, eval labels), and the trials that test other models against the graph's ground truth. |
@@ -170,13 +175,79 @@ See [search by meaning](https://docs.littlebigbrain.com/guides/search-by-meaning
 for embedding setup. To define constraints with the Shapes Constraint Language
 (SHACL), see [query and validation](https://docs.littlebigbrain.com/guides/sparql-and-shacl/).
 
-RDF imports and JSON facts use different write workflows. A graph first written
-through `lbb_rdf` does not accept JSON fact writes through `lbb_commit`. Choose
-the workflow when creating the graph. RDF updates
-support additive `INSERT DATA`;
+Legacy `mode=facts` follows the graph's existing first-write restrictions; a
+graph first written through `lbb_rdf` refuses that legacy JSON path. Explicit
+`mode=records` uses the separate versioned contract described below and does not
+activate or convert an existing graph. RDF updates support additive `INSERT DATA`;
 see the [RDF guide](https://docs.littlebigbrain.com/guides/load-rdf/) for format and
 update limits.
 
+
+## Versioned records commits
+
+Use explicit `lbb_commit` `mode: "records"` with a nested `records` body whose
+`version` is `records/1`. The server must recognize `records_commit_v1` and the
+graph must already have qualified support; protocol recognition does not
+activate a graph or offer a graph-type choice. Ordinary/missing/unactivated
+graphs keep their typed refusal. There is no creation, conversion or activation
+option here. This requires the matching client release containing
+`records.commit`; publish that client before releasing this MCP update.
+
+```json
+{
+  "mode": "records",
+  "records": {
+    "version": "records/1",
+    "entities": [{
+      "id": "https://example.org/service/auth",
+      "add": {"https://example.org/title": {
+        "@value": "Auth Service",
+        "@type": "http://www.w3.org/2001/XMLSchema#string"
+      }}
+    }]
+  },
+  "idempotency_key": "auth-title:v1"
+}
+```
+
+The complete object is forwarded without dropping unknown fields, lowercasing
+IRIs, coercing literals or resolving schema keys locally. The server validates
+it strictly. Do not mix legacy facts/embeddings/properties/retract/feedback or
+`dry_run`/backfill arguments into records mode, even with empty or false values.
+`expected_graph_epoch` adds an exact decimal incarnation guard.
+
+An explicit idempotency key wins. When omitted, MCP derives a stable content key
+from the original body, graph and epoch guard. The snapshot and key are fixed
+before approval and transport retries. Keep the same original body/key after a
+lost reply; do not use a new key to investigate an unknown result. An exhausted
+POST transport failure or malformed success returns `record_outcome_unknown`,
+`outcome: "unknown"` and the original `idempotency_key`, without legacy fallback.
+A capability failure sends no POST and cannot become a write acceptance.
+Typed server errors keep their original code/status and also retain the recovery
+key; the tool does not invent an acceptance or refusal verdict for them.
+
+Edits that may remove support use the existing destructive approval policy:
+`set`, `unset`, `remove`, `delete`, `replace_scope`, or a relationship with
+`asserted: false`. A set may replace an existing field. The question names the
+graph and source owner/scope; refusal sends no API request. Add-only work needs
+no destructive approval. The existing person-controlled
+`LBB_MCP_DESTRUCTIVE=allow` setting applies; no body field can bypass approval.
+The server remains responsible for current authority and reserved source owners.
+
+Success returns the complete original receipt as compact JSON and structured
+content. Resolved IDs, schema, projection counts, no-op and replay are never
+compacted. Support can change with zero visible additions/removals. Acceptance,
+publication and class embedding readiness are separate observations. MCP keeps
+its 80,000 UTF-8 byte output ceiling: an unexpected oversized valid receipt reports
+`record_accepted_output_limit` with `outcome: "accepted"`, sequence and key so the
+full receipt can be recovered through the SDK/HTTP API. It never calls that
+known acceptance a failed mutation or unknown outcome. Oversized error messages
+are explicitly flagged while preserving ordinary typed codes/status.
+
+The records body is bounded to one MiB and its escaped recovery key to 8 KiB at
+the MCP boundary; the server's smaller total-request/idempotency limits still
+apply. These limits do not expand any graph/source budget or enable admin erasure.
+
 ## Pages and saved queries
 
 When a result includes `next`, pass those arguments to the same tool to read the

package/dist/approval.d.ts

@@ -0,0 +1,139 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import type { RequestHandlerExtra } from "@modelcontextprotocol/sdk/shared/protocol.js";
+import type { ServerNotification, ServerRequest } from "@modelcontextprotocol/sdk/types.js";
+import type { LbbClient } from "@littlebigbrain/client";
+import type { LbbServerOptions } from "./query-observer.js";
+import { errorResult } from "./tool-runtime.js";
+/** The `extra` argument of a tool callback. */
+export type ToolExtra = RequestHandlerExtra<ServerRequest, ServerNotification>;
+type ErrorResult = ReturnType<typeof errorResult>;
+/** The environment setting that lets destructive calls run without a question. */
+export declare const DESTRUCTIVE_SETTING = "LBB_MCP_DESTRUCTIVE";
+/** The approval rule, for the description of a destructive tool. */
+export declare const APPROVAL_TEXT = "The server asks the person to approve it through the client (MCP form elicitation) and sends nothing when they decline (approval_declined). A client that cannot show the question gets approval_required and nothing is sent, unless the MCP server's environment sets LBB_MCP_DESTRUCTIVE=allow.";
+/** What a destructive call asks the person. */
+export interface ApprovalRequest {
+    /**
+     * The question, naming what the call deletes or removes first. A
+     * function runs only when the person is asked, so the call can read the
+     * records it names; its error is the tool's error.
+     */
+    message: string | (() => Promise<string>);
+}
+/**
+ * A name or a value on one line of a question: newlines and other control
+ * characters escaped, so a name cannot add lines of its own; at most `max`
+ * characters.
+ */
+export declare function oneLine(text: unknown, max?: number): string;
+/**
+ * Text quoted under a line of a question: every line indented by four
+ * spaces, other control characters escaped, at most `max` characters.
+ */
+export declare function quoteBlock(text: string, max: number): string;
+/** `graph "<name>"`: the graph a call targets, for a person to read. */
+export declare function graphLabel(client: LbbClient, graph?: string): string;
+/** The tool registry of one MCP server: a call log, and the approval step. */
+export interface ToolHost {
+    readonly server: McpServer;
+    /** `server.registerTool`, with one log event per call. */
+    readonly register: McpServer["registerTool"];
+    /**
+     * Ask the person before a destructive call (principle 13: destructive
+     * writes need a person's approval). A client with form elicitation shows
+     * the question with one confirm box; a decline, a cancel or an unticked
+     * box sends nothing. A client without form elicitation cannot ask, so
+     * the call is refused with approval_required, unless the server's
+     * environment sets LBB_MCP_DESTRUCTIVE=allow. No tool argument lets a
+     * call through: an agent sets the arguments. Returns undefined when the
+     * call may go ahead, else the error result to return.
+     */
+    approve(extra: ToolExtra, request: ApprovalRequest): Promise<ErrorResult | undefined>;
+}
+/** The host of one server's tools; `options` name the approval setting and the log. */
+export declare function toolHost(server: McpServer, options?: LbbServerOptions): ToolHost;
+/** `1 link`, `2 links`. */
+export declare function counted(n: number, noun: string, plural?: string): string;
+type NamedRecord = {
+    type: string;
+    name: string;
+};
+/** The retract question: the counts, then every link and record it removes, the first 20 of each. */
+export declare function retractMessage(where: string, edges: {
+    source: NamedRecord;
+    relation: string;
+    target: NamedRecord;
+}[], entities: NamedRecord[]): string;
+/**
+ * An `evolve_ontology` operation, as the tool or a suggestion holds it.
+ * Only the fields a removal names are read.
+ */
+export type OntologyOpLike = {
+    op: string;
+    name?: unknown;
+    relation?: unknown;
+    remove_domain?: unknown;
+    remove_range?: unknown;
+};
+/** Whether an operation removes: a type, a relation, or a relation's source or target types. */
+export declare function removesFromOntology(op: OntologyOpLike): boolean;
+/**
+ * The question of an `evolve_ontology` call that removes: the counts, then
+ * what `remove_entity_type`, `remove_relation` and the `remove_domain` and
+ * `remove_range` of `narrow_relation` remove, the first 20. Undefined when
+ * the call removes nothing.
+ */
+export declare function ontologyRemovalMessage(where: string, ops: OntologyOpLike[]): string | undefined;
+/** The facts a review item commits, as far as a question names them. */
+export type FactsLike = {
+    triplets?: unknown[] | null;
+    entity_properties?: unknown[] | null;
+    replace_owned?: {
+        subjects?: unknown[] | null;
+        retract_entities?: unknown[] | null;
+    } | null;
+};
+/** `2 links and 1 field row; …`: what committing `facts` writes and removes. */
+export declare function factsSummary(facts: FactsLike): string | undefined;
+/** A review item an answer would commit or apply. */
+export interface ReviewTarget {
+    id: string;
+    title: string;
+    kind: string;
+    question?: {
+        property?: string | null;
+        value?: unknown;
+        unit?: string | null;
+    } | null;
+    subject?: {
+        name?: string | null;
+    } | null;
+    facts?: FactsLike | null;
+}
+/** A change item's suggestion: its operations and facts, or undefined when it could not be read. */
+export type ChangeDetail = {
+    ops: OntologyOpLike[];
+    facts?: FactsLike | null;
+} | undefined;
+/**
+ * The question of a review answer that commits or applies: the count and
+ * the effect first (how many value items commit a value, how many change
+ * items apply an ontology change, and what those changes remove), then
+ * each item, the first 20. `unchanged` counts the other answered items.
+ */
+export declare function reviewAnswerMessage(where: string, answer: {
+    decision: "accept" | "correct";
+    value?: unknown;
+}, items: ReviewTarget[], changes: Map<string, ChangeDetail>, unchanged: number): string;
+/** The question of a shape publish in reject mode. */
+export declare function shapesRejectMessage(where: string, shapes: {
+    source: string;
+    format?: string;
+}): string;
+/**
+ * The question of a SPARQL Update that can remove statements: the
+ * operations that remove come first (DELETE, CLEAR, DROP, MOVE, COPY),
+ * each quoted on lines of its own, then the forms of the other operations.
+ */
+export declare function sparqlUpdateMessage(where: string, update: string): string;
+export {};

package/dist/approval.js

@@ -0,0 +1,426 @@
+import { updateOperations } from "./sparql-update.js";
+import { ToolError, errorResult } from "./tool-runtime.js";
+/** How long the person has to answer an approval request. */
+const APPROVAL_TIMEOUT_MS = 10 * 60_000;
+/** The environment setting that lets destructive calls run without a question. */
+export const DESTRUCTIVE_SETTING = "LBB_MCP_DESTRUCTIVE";
+/** The approval rule, for the description of a destructive tool. */
+export const APPROVAL_TEXT = `The server asks the person to approve it through the client (MCP form elicitation) and sends nothing when they decline (approval_declined). A client that cannot show the question gets approval_required and nothing is sent, unless the MCP server's environment sets ${DESTRUCTIVE_SETTING}=allow.`;
+/** Control characters, line and paragraph separators, and bidirectional controls. */
+const UNSAFE = 
+// eslint-disable-next-line no-control-regex -- these are the characters a name must not carry into a question
+/[\u0000-\u001f\u007f-\u009f\u2028\u2029\u202a-\u202e\u2066-\u2069]/g;
+function escapeChar(c) {
+    switch (c) {
+        case "\n":
+            return "\\n";
+        case "\r":
+            return "\\r";
+        case "\t":
+            return "\\t";
+        default:
+            return `\\u${c.charCodeAt(0).toString(16).padStart(4, "0")}`;
+    }
+}
+/**
+ * A name or a value on one line of a question: newlines and other control
+ * characters escaped, so a name cannot add lines of its own; at most `max`
+ * characters.
+ */
+export function oneLine(text, max = 200) {
+    const escaped = String(text).replace(UNSAFE, escapeChar);
+    return escaped.length > max ? `${escaped.slice(0, max)} …` : escaped;
+}
+/**
+ * Text quoted under a line of a question: every line indented by four
+ * spaces, other control characters escaped, at most `max` characters.
+ */
+export function quoteBlock(text, max) {
+    const normal = text.replace(/\r\n?/g, "\n").replace(/\t/g, "  ");
+    const shown = normal.length > max ? normal.slice(0, max) : normal;
+    const body = shown
+        .split("\n")
+        .map((line) => `    ${line.replace(UNSAFE, escapeChar)}`)
+        .join("\n");
+    return normal.length > max
+        ? `${body}\n    … ${(normal.length - max).toLocaleString("en-US")} more characters`
+        : body;
+}
+/** `graph "<name>"`: the graph a call targets, for a person to read. */
+export function graphLabel(client, graph) {
+    const name = graph ?? client.graphName;
+    return name ? `graph "${oneLine(name)}"` : "the connection's graph";
+}
+/** A word of the log: an action or an error code, never free text. */
+function token(value, pattern) {
+    return typeof value === "string" && pattern.test(value) ? value : undefined;
+}
+function defaultLog(event) {
+    process.stderr.write(`${JSON.stringify(event)}\n`);
+}
+/** The host of one server's tools; `options` name the approval setting and the log. */
+export function toolHost(server, options = {}) {
+    const setting = options.destructiveWithoutApproval ??
+        (process.env[DESTRUCTIVE_SETTING]?.trim().toLowerCase() === "allow"
+            ? "allow"
+            : "refuse");
+    const log = options.log ?? defaultLog;
+    const calls = new WeakMap();
+    const registerTool = server.registerTool.bind(server);
+    const register = ((name, config, callback) => registerTool(name, config, async (...params) => {
+        const extra = params[params.length - 1];
+        const record = {};
+        calls.set(extra, record);
+        const args = (params.length > 1 ? params[0] : undefined);
+        const action = token(args?.action ?? args?.mode, /^[a-z_]{1,40}$/);
+        const emit = (outcome, code) => {
+            try {
+                log({
+                    event: "mcp_tool_call",
+                    tool: name,
+                    ...(action ? { action } : {}),
+                    outcome,
+                    ...(code ? { code } : {}),
+                    ...(record.approval ? { approval: record.approval } : {}),
+                    request_id: extra.requestId,
+                });
+            }
+            catch {
+                // A log that fails never fails the call.
+            }
+        };
+        try {
+            const result = (await callback(...params));
+            emit(result?.isError ? "error" : "ok", result?.isError
+                ? token(result.structuredContent?.error?.code, /^[a-z0-9_.]{1,64}$/)
+                : undefined);
+            return result;
+        }
+        catch (error) {
+            emit("error", "exception");
+            throw error;
+        }
+    }));
+    const approve = async (extra, request) => {
+        const record = calls.get(extra);
+        const decide = (decision) => {
+            if (record)
+                record.approval = decision;
+        };
+        if (!server.server.getClientCapabilities()?.elicitation?.form) {
+            if (setting === "allow") {
+                decide("allowed_by_setting");
+                return undefined;
+            }
+            decide("unavailable");
+            return errorResult(new ToolError("approval_required", `This call deletes or removes data, and this client cannot ask the person to approve it (it has no MCP form elicitation), so nothing was sent. Make this change in the console or with the TypeScript or Python SDK, or from an MCP client that can show the question. On an MCP server you run yourself, the person can set ${DESTRUCTIVE_SETTING}=allow in its environment; the hosted endpoint never allows it.`));
+        }
+        let message;
+        try {
+            message =
+                typeof request.message === "string"
+                    ? request.message
+                    : await request.message();
+        }
+        catch (error) {
+            return errorResult(error);
+        }
+        try {
+            const answer = await server.server.elicitInput({
+                mode: "form",
+                message,
+                requestedSchema: {
+                    type: "object",
+                    properties: {
+                        confirm: {
+                            type: "boolean",
+                            title: "Approve",
+                            description: "Tick to run this call. It cannot be undone.",
+                            default: false,
+                        },
+                    },
+                    required: ["confirm"],
+                },
+            }, {
+                relatedRequestId: extra.requestId,
+                signal: extra.signal,
+                timeout: APPROVAL_TIMEOUT_MS,
+            });
+            if (answer.action === "accept" && answer.content?.confirm === true) {
+                decide("approved");
+                return undefined;
+            }
+            decide(answer.action === "cancel" ? "cancelled" : "declined");
+        }
+        catch (error) {
+            decide("failed");
+            return errorResult(new ToolError("approval_failed", `The approval request failed, so nothing was sent: ${error instanceof Error ? error.message : String(error)}`));
+        }
+        return errorResult(new ToolError("approval_declined", "The person declined, so nothing was sent."));
+    };
+    return { server, register, approve };
+}
+/** `1 link`, `2 links`. */
+export function counted(n, noun, plural = `${noun}s`) {
+    return `${n.toLocaleString("en-US")} ${n === 1 ? noun : plural}`;
+}
+/** `a`, `a and b`, `a, b and c`. */
+function joined(parts) {
+    return parts.length <= 1
+        ? (parts[0] ?? "")
+        : `${parts.slice(0, -1).join(", ")} and ${parts[parts.length - 1]}`;
+}
+/** The first 20 lines, then a count of the rest. */
+function listed(lines, noun) {
+    return lines.length > 20
+        ? [...lines.slice(0, 20), `- and ${lines.length - 20} more ${noun}`]
+        : lines;
+}
+/** The retract question: the counts, then every link and record it removes, the first 20 of each. */
+export function retractMessage(where, edges, entities) {
+    const record = (r) => `${oneLine(r.name)} (${oneLine(r.type)})`;
+    const what = joined([
+        ...(edges.length ? [counted(edges.length, "link")] : []),
+        ...(entities.length
+            ? [`every current link of ${counted(entities.length, "record")}`]
+            : []),
+    ]);
+    return [
+        `Retract ${what} from ${where}?`,
+        ...listed(edges.map((edge) => `- the link ${record(edge.source)} ${oneLine(edge.relation)} ${record(edge.target)}`), "links"),
+        ...listed(entities.map((entity) => `- every current link of ${record(entity)}`), "records"),
+        "The records and their history stay readable in as_of reads.",
+    ].join("\n");
+}
+function names(value) {
+    return Array.isArray(value) ? value.map((name) => oneLine(name)) : [];
+}
+/** What one operation removes, one line each. */
+function removals(op) {
+    switch (op.op) {
+        case "remove_entity_type":
+            return [`- the entity type ${oneLine(op.name)}`];
+        case "remove_relation":
+            return [`- the relation ${oneLine(op.name)}`];
+        case "narrow_relation": {
+            const domain = names(op.remove_domain);
+            const range = names(op.remove_range);
+            return [
+                ...(domain.length
+                    ? [
+                        `- ${domain.join(", ")} from the source types (domain) of the relation ${oneLine(op.relation)}`,
+                    ]
+                    : []),
+                ...(range.length
+                    ? [
+                        `- ${range.join(", ")} from the target types (range) of the relation ${oneLine(op.relation)}`,
+                    ]
+                    : []),
+            ];
+        }
+        default:
+            return [];
+    }
+}
+/** Whether an operation removes: a type, a relation, or a relation's source or target types. */
+export function removesFromOntology(op) {
+    return removals(op).length > 0;
+}
+/** `1 entity type, 1 relation and 3 source or target types`. */
+function removalCounts(ops) {
+    const of = (kind) => ops.filter((op) => op.op === kind).length;
+    const types = ops.reduce((sum, op) => op.op === "narrow_relation"
+        ? sum + names(op.remove_domain).length + names(op.remove_range).length
+        : sum, 0);
+    return joined([
+        ...(of("remove_entity_type")
+            ? [counted(of("remove_entity_type"), "entity type")]
+            : []),
+        ...(of("remove_relation")
+            ? [counted(of("remove_relation"), "relation")]
+            : []),
+        ...(types
+            ? [
+                counted(types, "source or target type of a relation", "source or target types of relations"),
+            ]
+            : []),
+    ]);
+}
+/**
+ * The question of an `evolve_ontology` call that removes: the counts, then
+ * what `remove_entity_type`, `remove_relation` and the `remove_domain` and
+ * `remove_range` of `narrow_relation` remove, the first 20. Undefined when
+ * the call removes nothing.
+ */
+export function ontologyRemovalMessage(where, ops) {
+    const removing = ops.filter(removesFromOntology);
+    if (!removing.length)
+        return undefined;
+    const others = ops.length - removing.length;
+    const tombstones = removing.some((op) => op.op === "remove_entity_type" || op.op === "remove_relation");
+    return [
+        `Change the ontology of ${where}? The change removes ${removalCounts(removing)}:`,
+        ...listed(removing.flatMap(removals), "removals"),
+        ...(others
+            ? [`It also applies ${counted(others, "other operation")}.`]
+            : []),
+        ...(tombstones
+            ? [
+                "A removed type or relation stays readable in old records. New commits that use it fail.",
+            ]
+            : []),
+    ].join("\n");
+}
+/** `2 links and 1 field row; …`: what committing `facts` writes and removes. */
+export function factsSummary(facts) {
+    const writes = joined([
+        ...(facts.triplets?.length ? [counted(facts.triplets.length, "link")] : []),
+        ...(facts.entity_properties?.length
+            ? [counted(facts.entity_properties.length, "field row")]
+            : []),
+    ]);
+    const owned = facts.replace_owned;
+    const parts = [
+        ...(writes ? [`commits ${writes}`] : []),
+        ...(owned?.subjects?.length
+            ? [
+                `removes the owned links and fields it does not write again on ${counted(owned.subjects.length, "record")}`,
+            ]
+            : []),
+        ...(owned?.retract_entities?.length
+            ? [`retracts ${counted(owned.retract_entities.length, "record")}`]
+            : []),
+    ];
+    return parts.length ? parts.join("; ") : undefined;
+}
+/**
+ * The question of a review answer that commits or applies: the count and
+ * the effect first (how many value items commit a value, how many change
+ * items apply an ontology change, and what those changes remove), then
+ * each item, the first 20. `unchanged` counts the other answered items.
+ */
+export function reviewAnswerMessage(where, answer, items, changes, unchanged) {
+    const values = items.filter((item) => item.kind === "value");
+    const changeItems = items.filter((item) => item.kind === "change");
+    const total = items.length + unchanged;
+    const correct = answer.decision === "correct";
+    const effects = [
+        ...(values.length
+            ? [
+                values.length === 1
+                    ? `1 value item commits ${correct ? "the corrected value" : "its value"}`
+                    : `${counted(values.length, "value item")} commit ${correct ? "the corrected value" : "their values"}`,
+            ]
+            : []),
+        ...(changeItems.length
+            ? [
+                changeItems.length === 1
+                    ? "1 change item applies its ontology change"
+                    : `${counted(changeItems.length, "change item")} apply their ontology changes`,
+            ]
+            : []),
+    ];
+    const head = `${correct ? "Correct" : "Accept"} ${counted(total, "review item")} on ${where}${correct ? ` to ${oneLine(JSON.stringify(answer.value ?? null))}` : ""}? ${joined(effects)}.`;
+    const lines = [];
+    for (const item of items.slice(0, 20)) {
+        const label = `- "${oneLine(item.title)}" (${oneLine(item.id)})`;
+        const facts = item.facts ? factsSummary(item.facts) : undefined;
+        if (item.kind === "value") {
+            const property = item.question?.property;
+            const value = correct ? answer.value : item.question?.value;
+            const unit = !correct && item.question?.unit ? ` ${item.question.unit}` : "";
+            const subject = item.subject?.name
+                ? ` on ${oneLine(item.subject.name)}`
+                : "";
+            const what = property
+                ? `${oneLine(property)} = ${oneLine(JSON.stringify(value ?? null))}${oneLine(unit)}${subject}`
+                : "its value";
+            lines.push(`${label}: ${what}${facts ? `; ${facts}` : ""}`);
+            continue;
+        }
+        const detail = changes.get(item.id);
+        if (!detail) {
+            lines.push(`${label}: its ontology change and facts could not be read here`);
+            continue;
+        }
+        const removing = detail.ops.flatMap(removals);
+        const changeFacts = detail.facts ? factsSummary(detail.facts) : undefined;
+        lines.push(`${label}: ${counted(detail.ops.length, "ontology operation")}${changeFacts ? `; ${changeFacts}` : ""}${removing.length ? "; the change removes:" : ""}`);
+        lines.push(...listed(removing, "removals").map((line) => `    ${line}`));
+    }
+    if (items.length > 20)
+        lines.push(`- and ${counted(items.length - 20, "more item")}`);
+    return [
+        head,
+        ...lines,
+        ...(unchanged
+            ? [
+                unchanged === 1
+                    ? "1 other item changes nothing in the graph."
+                    : `${counted(unchanged, "other item")} change nothing in the graph.`,
+            ]
+            : []),
+    ].join("\n");
+}
+/** The target classes a SHACL source names, as written. */
+function targetClasses(source) {
+    const found = source.matchAll(/(?:\bsh:targetClass|<http:\/\/www\.w3\.org\/ns\/shacl#targetClass>)\s+(<[^>\s]*>|[A-Za-z][\w.-]*:[\w.-]*|:[\w.-]*)/g);
+    return [...new Set([...found].map((match) => oneLine(match[1])))];
+}
+/** The question of a shape publish in reject mode. */
+export function shapesRejectMessage(where, shapes) {
+    const targets = targetClasses(shapes.source);
+    return [
+        `Publish these SHACL rules on ${where} in reject mode? From then on, a write that breaks a rule fails, and the error lists the violations.`,
+        ...(targets.length
+            ? [
+                `The rules name ${counted(targets.length, "target class", "target classes")}:`,
+                ...listed(targets.map((target) => `- ${target}`), "target classes"),
+            ]
+            : ["No target class was read from the rules."]),
+        `The rules are ${counted(shapes.source.length, "character")} of ${oneLine(shapes.format ?? "auto")} text.`,
+    ].join("\n");
+}
+/** The most characters of one removing operation a question quotes. */
+const OPERATION_CHARS = 1_500;
+/** The most characters of removing operations one question quotes. */
+const UPDATE_CHARS = 6_000;
+/**
+ * The question of a SPARQL Update that can remove statements: the
+ * operations that remove come first (DELETE, CLEAR, DROP, MOVE, COPY),
+ * each quoted on lines of its own, then the forms of the other operations.
+ */
+export function sparqlUpdateMessage(where, update) {
+    const operations = updateOperations(update);
+    const removing = operations
+        .map((operation, i) => ({ operation, n: i + 1 }))
+        .filter(({ operation }) => operation.removes);
+    if (!removing.length) {
+        return [
+            `Run this SPARQL Update on ${where}? Its text names DELETE, CLEAR, DROP, MOVE or COPY, so it may remove statements:`,
+            quoteBlock(update, 2_000),
+        ].join("\n");
+    }
+    const lines = [
+        `Run this SPARQL Update on ${where}? ${operations.length === 1
+            ? "It removes statements:"
+            : removing.length === operations.length
+                ? `All ${operations.length} of its operations remove statements:`
+                : `${removing.length} of its ${operations.length} operations remove statements:`}`,
+    ];
+    let budget = UPDATE_CHARS;
+    for (const { operation, n } of removing.slice(0, 20)) {
+        const shown = Math.max(200, Math.min(OPERATION_CHARS, budget));
+        lines.push(`- operation ${n}, ${oneLine(operation.form)}:`);
+        lines.push(quoteBlock(operation.text, shown));
+        budget -= Math.min(operation.text.length, shown);
+    }
+    if (removing.length > 20)
+        lines.push(`- and ${counted(removing.length - 20, "more operation")} that remove`);
+    const others = operations.filter((operation) => !operation.removes);
+    if (others.length)
+        lines.push(`The other ${others.length === 1 ? "operation" : `${others.length} operations`}: ${[
+            ...new Set(others.map((operation) => oneLine(operation.form))),
+        ].join(", ")}.`);
+    return lines.join("\n");
+}