@littlebigbrain/mcp 0.16.0 → 0.17.0

package/README.md

@@ -164,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. |
@@ -175,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/files-tool.d.ts

@@ -33,6 +33,8 @@ export interface PageLinesAnswer {
         height: number;
         lines_total: number;
         lines_matching: number;
+        /** The page is mostly image and has fewer than 16 characters of text: the parse read almost none, and OCR is not built. */
+        ocr_required?: true;
         lines: string[];
     }>;
     shown: number;

package/dist/files-tool.js

@@ -66,6 +66,7 @@ export function pageLines(pages, window) {
             height: page.height,
             lines_total: page.lines.length,
             lines_matching: matching,
+            ...(page.ocr_required ? { ocr_required: true } : {}),
             lines: shown,
         });
         if (stoppedAt !== undefined) {
@@ -114,7 +115,7 @@ async function fileSha(target, args) {
 }
 export function registerFilesTool(host, client) {
     host.register("lbb_files", {
-        description: "Files of the graph, read only. A file is a document the graph holds (its bytes and a Document entity); the documents.parse workflow (lbb_workflows) reads the text layer of each PDF into pages with every line and its box. list shows 50 files a call, newest upload first, with their sha256, name, size, Document IRI and parse (status parsed, unsupported or failed, page_count); when more follow, next names the after of the next call (with the same filters). parse_status keeps the files of one parse status; waiting is a file not parsed yet. name keeps the files whose name holds a text, in any case. A filtered list reads the Documents of the published generation and names its commit (as_of_commit_seq). A file uploaded, renamed or parsed a moment ago can be missing from it until publication. pages reads parsed pages of one file (sha256, or name for an exact file name): from is the first 0-based page index (the page of a region and of a DocEntry or DocMention), to the page after the last one (default from+1). Each line comes as `<line id> [x0,y0,x1,y1] <text>`: the id is p<page number>-l<line number>, both from 1, and the box is normalized to the page (0 to 1, origin top left). contains keeps the lines that hold a text; max_lines caps the lines (default 200). When lines were left out, next names the from and line_offset of the next call. A file not parsed yet answers file_not_parsed.",
+        description: "Files of the graph, read only. A file is a document the graph holds (its bytes and a Document entity). A file a workflow run wrote (a generated file, with an origin and an expires_at) has no Document and no Document IRI. It expires unless a person keeps it, so the list shows it only after that, and it is never evidence for a fact. The documents.parse workflow (lbb_workflows) reads the text layer of each PDF into pages with every line and its box. list shows 50 files a call, newest upload first, with their sha256, name, size, Document IRI and parse (status parsed, unsupported or failed, page_count); when more follow, next names the after of the next call (with the same filters). parse_status keeps the files of one parse status; waiting is a file not parsed yet. name keeps the files whose name holds a text, in any case. A filtered list reads the Documents of the published generation and names its commit (as_of_commit_seq). A file uploaded, renamed or parsed a moment ago can be missing from it until publication. pages reads parsed pages of one file (sha256, or name for an exact file name): from is the first 0-based page index (the page of a region and of a DocEntry or DocMention), to the page after the last one (default from+1). Each line comes as `<line id> [x0,y0,x1,y1] <text>`: the id is p<page number>-l<line number>, both from 1, and the box is normalized to the page (0 to 1, origin top left). contains keeps the lines that hold a text; max_lines caps the lines (default 200). When lines were left out, next names the from and line_offset of the next call. A file not parsed yet answers file_not_parsed.",
         inputSchema: {
             action: z.enum(["list", "pages"]),
             after: z
@@ -212,8 +213,12 @@ export function registerFilesTool(host, client) {
             const range = answer.to - answer.from > 1
                 ? `pages ${answer.from} to ${answer.to - 1}`
                 : `page ${answer.from}`;
+            const scanned = lines.pages.filter((entry) => entry.ocr_required).length;
+            const needsOcr = scanned
+                ? `; ${scanned === 1 ? "1 page needs" : `${scanned} pages need`} OCR, almost no text was read`
+                : "";
             return toolResult({
-                summary: `${label}, ${range} of ${answer.page_count} (0-based): ${lines.shown} lines${lines.next ? ", more after next" : ""}`,
+                summary: `${label}, ${range} of ${answer.page_count} (0-based): ${lines.shown} lines${needsOcr}${lines.next ? ", more after next" : ""}`,
                 data: {
                     sha256: answer.sha256,
                     parser: answer.parser,

package/dist/records-write.d.ts

@@ -0,0 +1,101 @@
+import { type LbbClient } from "@littlebigbrain/client";
+import { type ToolExtra, type ToolHost } from "./approval.js";
+type Args = {
+    records?: Record<string, unknown>;
+    idempotencyKey?: string;
+    expectedGraphEpoch?: string;
+    graph?: string;
+    legacyInputs: boolean;
+};
+export declare function commitRecordsTool(host: ToolHost, client: LbbClient, extra: ToolExtra, args: Args): Promise<{
+    structuredContent: {
+        error: {
+            idempotency_key: string;
+            type: string;
+            code: string;
+            message: string;
+            outcome: string;
+            param: null;
+            request_id: null;
+            doc_url: null;
+            status: null;
+        } | {
+            idempotency_key?: string | undefined;
+            type: string;
+            code: string;
+            message: string;
+            param: string | null;
+            request_id: string | null;
+            doc_url: string | null;
+            status: number;
+            outcome?: undefined;
+        } | {
+            idempotency_key?: string | undefined;
+            type: string;
+            code: string;
+            message: string;
+            param: null;
+            request_id: null;
+            doc_url: null;
+            status: null;
+            outcome?: undefined;
+        };
+    };
+    content: {
+        type: "text";
+        text: string;
+    }[];
+    isError: true;
+} | {
+    isError: true;
+    content: {
+        type: "text";
+        text: string;
+    }[];
+    structuredContent: {
+        error: {
+            idempotency_key?: string | undefined;
+            type: string;
+            code: string;
+            message: string;
+            message_truncated: boolean;
+            status: number | null;
+            param: string | null;
+            request_id: string | null;
+            doc_url: string | null;
+        };
+    };
+} | {
+    isError: true;
+    content: {
+        type: "text";
+        text: string;
+    }[];
+    structuredContent: {
+        error: {
+            type: string;
+            code: string;
+            message: string;
+            outcome: string;
+            idempotency_key: string;
+            epoch: string;
+            commit_seq: number;
+        };
+    };
+} | {
+    content: {
+        type: "text";
+        text: string;
+    }[];
+    structuredContent: {
+        summary: string;
+        data: {
+            idempotent_replay: boolean;
+            object: import("@littlebigbrain/client").components["schemas"]["RecordCommitObject"];
+            receipt: import("@littlebigbrain/client").components["schemas"]["RecordCommitReceipt"];
+            version: import("@littlebigbrain/client").components["schemas"]["RecordsVersion"];
+        };
+    };
+    isError?: undefined;
+}>;
+export {};

package/dist/records-write.js

@@ -0,0 +1,150 @@
+/** Records-specific MCP framing; semantic admission belongs to the server. */
+import { Buffer } from "node:buffer";
+import { LbbCapabilityError, } from "@littlebigbrain/client";
+import { graphLabel, oneLine, } from "./approval.js";
+import { HARD_OUTPUT_CHARS } from "./tool-contracts.js";
+import { contentHashKey, enrichError, errorResult, scoped, ToolError, } from "./tool-runtime.js";
+const isObject = (value) => value !== null && typeof value === "object" && !Array.isArray(value);
+const nonempty = (value) => isObject(value)
+    ? Object.keys(value).length > 0
+    : Array.isArray(value) && value.length > 0;
+function mayRemove(body) {
+    if (body.replace_scope === true)
+        return true;
+    for (const rows of [body.entities, body.relationships]) {
+        if (!Array.isArray(rows))
+            continue;
+        for (const row of rows) {
+            if (isObject(row) &&
+                (row.delete === true ||
+                    row.asserted === false ||
+                    nonempty(row.set) ||
+                    nonempty(row.unset) ||
+                    nonempty(row.remove)))
+                return true;
+        }
+    }
+    return false;
+}
+function approvalMessage(client, graph, body) {
+    const entities = Array.isArray(body.entities) ? body.entities.length : 0;
+    const relationships = Array.isArray(body.relationships)
+        ? body.relationships.length
+        : 0;
+    const action = body.replace_scope === true
+        ? "Replace the complete desired support"
+        : "Apply record edits that may replace or remove support";
+    return `${action} in ${graphLabel(client, graph)}, owner "${oneLine(body.owner ?? "application")}", scope "${oneLine(body.scope ?? "default")}" (${entities} entities, ${relationships} relationships)? Other owners' support is retained. This does not erase retained history.`;
+}
+function boundedError(value, key) {
+    const original = errorResult(value);
+    // A typed server error can also need receipt recovery. Keep its code/status
+    // unchanged, but retain the derived key rather than making callers guess it.
+    const identity = {
+        ...original.structuredContent.error,
+        ...(key !== undefined ? { idempotency_key: key } : {}),
+    };
+    const result = {
+        ...original,
+        structuredContent: { error: identity },
+        content: [
+            {
+                type: "text",
+                text: JSON.stringify({ error: identity }, null, 2),
+            },
+        ],
+    };
+    if (Buffer.byteLength(result.content[0].text, "utf8") <= HARD_OUTPUT_CHARS)
+        return result;
+    const source = result.structuredContent.error;
+    const short = (value, max = 512) => typeof value === "string" &&
+        Buffer.byteLength(JSON.stringify(value), "utf8") <= max
+        ? value
+        : null;
+    const error = {
+        type: short(source.type) ?? "tool_error",
+        code: short(source.code) ?? "record_error_output_limit",
+        message: "The complete server error exceeds the MCP output budget. Its code/status are retained; inspect the SDK or HTTP response for the full message. No complete commit receipt was returned.",
+        message_truncated: true,
+        status: typeof source.status === "number" && Number.isSafeInteger(source.status)
+            ? source.status
+            : null,
+        param: short(source.param),
+        request_id: short(source.request_id),
+        doc_url: short(source.doc_url),
+        ...(key !== undefined ? { idempotency_key: key } : {}),
+    };
+    const payload = { error };
+    return {
+        isError: true,
+        content: [{ type: "text", text: JSON.stringify(payload) }],
+        structuredContent: payload,
+    };
+}
+export async function commitRecordsTool(host, client, extra, args) {
+    let requestKey;
+    try {
+        if (args.legacyInputs)
+            throw new ToolError("record_payload_ambiguous", "mode=records cannot include legacy facts, feedback, retract, dry_run, observed_at or edge_idempotency arguments, even when empty or false");
+        if (!isObject(args.records) || args.records.version !== "records/1") {
+            throw new ToolError("record_version_unsupported", "mode=records requires a records object with explicit version records/1");
+        }
+        // Capture before approval/capability I/O. Do not strip unknown fields,
+        // normalize IRIs, bind friendly keys or copy the server's source policy.
+        const raw = JSON.stringify(args.records);
+        if (Buffer.byteLength(raw, "utf8") > 1024 * 1024)
+            throw new ToolError("record_payload_budget", "The records body exceeds the MCP one MiB request budget; use a bounded SDK request");
+        const body = JSON.parse(raw);
+        if (!isObject(body) || body.version !== "records/1")
+            throw new ToolError("record_version_unsupported", "the encoded records object must retain version records/1");
+        const graph = args.graph;
+        const epoch = args.expectedGraphEpoch;
+        const key = args.idempotencyKey ??
+            contentHashKey({ graph: graph ?? client.graphName }, { mode: "records", expected_graph_epoch: epoch, body });
+        if (key.trim().length === 0)
+            throw new ToolError("record_payload_invalid", "records idempotency_key must not be empty");
+        // This is an output-identity allowance, not a duplicate of HTTP key syntax.
+        // It leaves room to return the FULL original key if receipt recovery fails.
+        if (Buffer.byteLength(JSON.stringify(key), "utf8") > 8192)
+            throw new ToolError("record_payload_budget", "The idempotency key exceeds the MCP recovery-identity budget");
+        requestKey = key;
+        if (mayRemove(body)) {
+            const refused = await host.approve(extra, {
+                message: approvalMessage(client, graph, body),
+            });
+            if (refused)
+                return refused;
+        }
+        const result = await scoped(client, graph).records.commit(body, { idempotencyKey: key, expectedGraphEpoch: epoch });
+        const envelope = { summary: "lbb_commit.records", data: result };
+        const text = JSON.stringify(envelope);
+        if (Buffer.byteLength(text, "utf8") > HARD_OUTPUT_CHARS) {
+            // Acceptance is already known; do not relabel it as a failed mutation or
+            // an unknown outcome just because the full result cannot fit this tool.
+            const error = {
+                type: "tool_error",
+                code: "record_accepted_output_limit",
+                message: "The record commit was accepted, but its complete receipt exceeds the MCP output budget. Recover the original receipt with the same body/key through the SDK or HTTP API.",
+                outcome: "accepted",
+                idempotency_key: key,
+                epoch: result.receipt.epoch,
+                commit_seq: result.receipt.commit_seq,
+            };
+            const payload = { error };
+            return {
+                isError: true,
+                content: [{ type: "text", text: JSON.stringify(payload) }],
+                structuredContent: payload,
+            };
+        }
+        return {
+            content: [{ type: "text", text }],
+            structuredContent: envelope,
+        };
+    }
+    catch (error) {
+        return boundedError(error instanceof LbbCapabilityError
+            ? new ToolError("record_capability_unavailable", error.message)
+            : await enrichError(client, error), requestKey);
+    }
+}

package/dist/reviews-tool.js

@@ -73,7 +73,7 @@ const questionSchema = z
     .strict();
 export function registerReviewsTools(host, client) {
     host.register("lbb_reviews", {
-        description: `Review items, read only: questions for a person (human in the loop) that workflows, integrations, agents and people file. ${KINDS_TEXT} list returns one page as the server sends it ({object, data, has_more, next_cursor}), the latest update first: pass next_cursor as cursor, with the same filters, for the next page. get reads one item (rev_…) with its question, evidence, answer and effects. patterns groups the live items that ask one decision, the largest first. Evals files the questions of model checks (origin_id evals:checks), calibration sessions (evals:calibration) and golden queries (evals:golden) as grade and choice items; eval_id keeps the items of one record, and their answer is the record's label. File, answer, comment on or withdraw items with lbb_reviews_manage.`,
+        description: `Review items, read only: questions for a person (human in the loop) that workflows, integrations, agents and people file. ${KINDS_TEXT} list returns one page as the server sends it ({object, data, has_more, next_cursor}), the latest update first: pass next_cursor as cursor, with the same filters, for the next page. get reads one item (rev_…) with its question, evidence, answer and effects. patterns groups the live items that ask one decision, the largest first. Evals files the questions of model checks (origin_id evals:checks), calibration sessions (evals:calibration), golden queries (evals:golden) and the values the two arms of an experiment differ on (evals:datasets) as grade and choice items; eval_id keeps the items of one record (for evals:datasets, the dataset), and their answer is the record's label. An item of evals:datasets asks whether one value is right or wrong, and the origin names the dataset item, the property and the value. File, answer, comment on or withdraw items with lbb_reviews_manage.`,
         inputSchema: {
             action: z.enum(["list", "get", "patterns"]),
             status: z
@@ -95,7 +95,7 @@ export function registerReviewsTools(host, client) {
             eval_id: z
                 .string()
                 .optional()
-                .describe("list, patterns: the items Evals filed for one record (eval.id): a calibration session, a model call's check, a golden."),
+                .describe("list, patterns: the items Evals filed for one record (eval.id): a calibration session, a model call's check, a golden, a dataset."),
             workflow: z
                 .string()
                 .optional()

package/dist/tool-contracts.js

@@ -551,6 +551,15 @@ const evalExpectedValueSchema = z
         .optional()
         .describe("Words of the text that state the value"),
     reason: z.string().optional().describe("Why a value is left out"),
+    source: z
+        .object({
+        kind: z.enum(["test", "review"]),
+        id: z.string(),
+        at: z.string(),
+    })
+        .strict()
+        .optional()
+        .describe("Who gave the label and when: a person's answer on a test (wtest_…) or a review item (rev_…). Send it back as read, or leave it out"),
 })
     .strict();
 /** One example of a values dataset. */
@@ -580,6 +589,33 @@ export const evalDatasetItemSchema = z
         .optional(),
 })
     .strict();
+/** What B changes in A in an experiment: the model of one use, or a revision. */
+export const experimentArmSchema = z
+    .object({
+    model: z
+        .object({
+        use: z
+            .enum(["extract", "decide"])
+            .describe("The use whose model B changes"),
+        model: z
+            .object({
+            provider: z.string().describe("anthropic, typesafe or mock"),
+            model: z.string().describe("A model of the use's options"),
+            effort: z
+                .string()
+                .optional()
+                .describe("The effort of a Claude model"),
+        })
+            .strict(),
+    })
+        .strict()
+        .optional(),
+    revision: z
+        .string()
+        .optional()
+        .describe("A kept settings revision of the workflow (wrev_…)"),
+})
+    .strict();
 export const inspectInputSchema = z.discriminatedUnion("action", [
     z.object({ action: z.literal("guide"), ...readScope }).strict(),
     z

package/dist/tool-runtime.js

@@ -1,6 +1,6 @@
 import { Buffer } from "node:buffer";
 import { createHash } from "node:crypto";
-import { LbbError } from "@littlebigbrain/client";
+import { LbbError, LbbRecordCommitOutcomeError, } from "@littlebigbrain/client";
 import { DEFAULT_DETAIL, HARD_OUTPUT_CHARS, MAX_QUERY_ROW_LIMIT, } from "./tool-contracts.js";
 export const scoped = (client, graph) => graph !== undefined ? client.withScope({ graph }) : client;
 export function normalizeDetail(detail) {
@@ -490,25 +490,37 @@ export class ToolError extends Error {
     }
 }
 export function errorResult(error) {
-    const payload = error instanceof LbbError
+    const payload = error instanceof LbbRecordCommitOutcomeError
         ? {
-            type: error.type ?? "api_error",
-            code: error.code ?? "unstructured_error",
-            message: error.message,
-            param: error.param ?? null,
-            request_id: error.requestId ?? null,
-            doc_url: error.docUrl ?? null,
-            status: error.status,
-        }
-        : {
             type: "tool_error",
-            code: error instanceof ToolError ? error.code : "tool_error",
-            message: error instanceof Error ? error.message : String(error),
+            code: "record_outcome_unknown",
+            message: error.message,
+            outcome: error.outcome,
+            idempotency_key: error.idempotencyKey,
             param: null,
             request_id: null,
             doc_url: null,
             status: null,
-        };
+        }
+        : error instanceof LbbError
+            ? {
+                type: error.type ?? "api_error",
+                code: error.code ?? "unstructured_error",
+                message: error.message,
+                param: error.param ?? null,
+                request_id: error.requestId ?? null,
+                doc_url: error.docUrl ?? null,
+                status: error.status,
+            }
+            : {
+                type: "tool_error",
+                code: error instanceof ToolError ? error.code : "tool_error",
+                message: error instanceof Error ? error.message : String(error),
+                param: null,
+                request_id: null,
+                doc_url: null,
+                status: null,
+            };
     const structuredContent = { error: payload };
     return {
         content: [

package/dist/tools.js

@@ -3,11 +3,12 @@ import { metadataPage } from "./metadata-pages.js";
 import { answerQuestion, } from "./question.js";
 import { commitAt, compareQuery, describeGraph, findNames, } from "./query-tools.js";
 import { registerRdfTool } from "./rdf-tool.js";
+import { commitRecordsTool } from "./records-write.js";
 import { registerFilesTool } from "./files-tool.js";
 import { registerReviewsTools } from "./reviews-tool.js";
 import { APPROVAL_TEXT, graphLabel, oneLine, ontologyRemovalMessage, retractMessage, shapesRejectMessage, toolHost, } from "./approval.js";
 import { queryTiming } from "./query-observer.js";
-import { DESTRUCTIVE, HARD_OUTPUT_CHARS, MUTATING, READ_ONLY, configureInputSchema, configureWireSchema, detailSchema, entityEmbeddingSchema, evalDatasetItemSchema, evalLabelItemSchema, evidenceSchema, graphScope, inspectInputSchema, inspectWireSchema, jsonObjectSchema, queryInputSchema, queryWireSchema, reviewAnswerSchema, searchFeedbackSchema, suggestedFactsBody, testInstallSchema, yearMonthSchema, } from "./tool-contracts.js";
+import { DESTRUCTIVE, HARD_OUTPUT_CHARS, MUTATING, READ_ONLY, configureInputSchema, configureWireSchema, detailSchema, entityEmbeddingSchema, evalDatasetItemSchema, experimentArmSchema, evalLabelItemSchema, evidenceSchema, graphScope, inspectInputSchema, inspectWireSchema, jsonObjectSchema, queryInputSchema, queryWireSchema, reviewAnswerSchema, searchFeedbackSchema, suggestedFactsBody, testInstallSchema, yearMonthSchema, } from "./tool-contracts.js";
 import { analyze, assertCursorScope, contentHashKey, decodeQueryCursor, effectiveRowLimit, enrichError, errorResult, guide, normalizeDetail, normalizeLbbIris, ontologyDefineBody, pageLimit, queryCommitPin, queryEnvelope, queryToolResult, requireString, rowPageFrom, rowPageNext, run, runPage, scoped, stableJson, toolResult, ToolError, } from "./tool-runtime.js";
 /** The most tests `GET /v1/workflows/named/tests` returns in one page. */
 const WORKFLOW_TESTS_PAGE_MAX = 50;
@@ -17,6 +18,7 @@ const WORKFLOW_QUEUE_PAGE_MAX = 100;
 const WORKFLOW_RUN_RESULTS_PAGE_MAX = 200;
 /** The most datasets `GET /v1/evals/datasets` returns in one page. */
 const EVAL_DATASETS_PAGE_MAX = 50;
+const EVAL_EXPERIMENTS_PAGE_MAX = 50;
 export function registerLbbTools(server, client, options = {}) {
     const host = toolHost(server, options);
     registerRdfTool(host, client);
@@ -904,7 +906,7 @@ export function registerLbbTools(server, client, options = {}) {
         return { name: args.name, ...inputs };
     };
     host.register("lbb_workflows", {
-        description: "Starter workflows and triggered workflows, read only. A starter workflow is a template; a triggered workflow is a workflow created from one on the graph. It watches a class: when a published commit adds or changes instances of the class (or changes the watched fields), the workflow reads them and does its work. search.embed keeps an embedding of the class (the same as lbb_embeddings); ontology.fit reads text fields and files ontology suggestions (the same as lbb_fit_sources); workflow (a developer workflow) sends the new and changed instances to a workflow of the developer's worker as trigger messages, and that code writes the facts the workflow owns. documents.parse reads uploaded PDF files into pages with line boxes, documents.link connects mentions of the same thing across the documents (it writes DocEntry and DocMention instances and links each mention to the entry that defines or describes it), documents.map proposes each link as a FactProposal in the graph's own ontology (fact_subject, fact_predicate, fact_object, fact_confidence, fact_evidence) for a review workflow, and values.extract fills chosen properties from text, each value with a quote; read the files and their pages with lbb_files. starters lists the starter workflows this server offers with their group, settings and whether each can run here. list shows every triggered workflow of the graph with its state (backfilling, ready, paused, failed, unavailable), lag, counters, this month's spend and last error; get shows one (starter and name) with its own status in details (for workflow: the messages sent, the instances waiting, the message in flight and whether it is paused). preview shows what creating one would do (the resolved watch, the instance count and the workflow's own preview; for workflow, the first messages it would send), calls no model and stores nothing. workflows lists the same workflows as workflows with triggers (/v1/workflows/named): each one's target workflow type (LBB's own are lbb.* types), its shards (engine identities starter.<name> and starter.<name>.<k>), its routing field, its window, its one watch trigger, its status and each shard's inbox, one page in data (has_more and next_cursor page them with cursor and limit); name for one. queue (name) shows what a workflow's watch has not sent yet: each waiting instance with its shard and its origin (a backfill, a commit range with the watched fields and the requests that changed it, a run now, a schema change), the pass in progress, and per shard its message in flight and its first unfinished turns with their origins; the items are in data, and has_more and next_cursor page them with cursor and limit. run_results (name) shows what the workflow's runs did with each input, newest run first: the input's IRI and label, its outcome (written, review, no_value, failed, duplicate) and its values (the value, the quote that states it, its support, the conversion, and the review item it went to); run keeps one run (with run_counts, every input by outcome), outcome keeps some outcomes, iri keeps one input; data, has_more and next_cursor page them. A run records its results when it ends; they are kept 30 days. revisions (name) shows the history of a workflow's settings, newest change first: each item is a revision (settings, the request that makes it, and an id wrev_… that is the hash of the settings) with who changed it, when, how (create, change, activate, existing) and bound (the one in use); a row whose revision was deleted has available false and no settings; has_more and next_cursor page it with cursor and limit (1 to 100, default 20). revision (name, revision) reads one revision; compare two by their settings to say what changed. Each run summary names the revision it ran on. Message workflows of the workflow engine are not listed here. tests lists the graph's workflow tests, newest first, without texts and results (name: one workflow's tests), one page with next_cursor; tests_get reads one test (id) with its inputs' texts and, per input, each value read with its quote, its support and what the live workflow does with it (writes it, gives it to review, or drops it). A test goes queued, running, then done, failed or cancelled. Create, refresh, pause or resume with lbb_workflows_manage, which also starts, answers and cancels tests and goes back to an earlier revision with its action activate; delete with lbb_workflows_delete.",
+        description: "Starter workflows and triggered workflows, read only. A starter workflow is a template; a triggered workflow is a workflow created from one on the graph. It watches a class: when a published commit adds or changes instances of the class (or changes the watched fields), the workflow reads them and does its work. search.embed keeps an embedding of the class (the same as lbb_embeddings); ontology.fit reads text fields and files ontology suggestions (the same as lbb_fit_sources); workflow (a developer workflow) sends the new and changed instances to a workflow of the developer's worker as trigger messages, and that code writes the facts the workflow owns. documents.parse reads uploaded PDF files into pages with line boxes, documents.link connects mentions of the same thing across the documents (it writes DocEntry and DocMention instances and links each mention to the entry that defines or describes it), documents.map proposes each link as a FactProposal in the graph's own ontology (fact_subject, fact_predicate, fact_object, fact_confidence, fact_evidence) for a review workflow, and values.extract fills chosen properties from text, each value with a quote; read the files and their pages with lbb_files. starters lists the starter workflows this server offers with their group, settings and whether each can run here. list shows every triggered workflow of the graph with its state (backfilling, ready, paused, failed, unavailable), lag, counters, this month's spend and last error; get shows one (starter and name) with its own status in details (for workflow: the messages sent, the instances waiting, the message in flight and whether it is paused). preview shows what creating one would do (the resolved watch, the instance count and the workflow's own preview; for workflow, the first messages it would send), calls no model and stores nothing. workflows lists the same workflows as workflows with triggers (/v1/workflows/named): each one's target workflow type (LBB's own are lbb.* types), its shards (engine identities starter.<name> and starter.<name>.<k>), its routing field, its window, its one watch trigger, its status and each shard's inbox, one page in data (has_more and next_cursor page them with cursor and limit); name for one. queue (name) shows what a workflow's watch has not sent yet: each waiting instance with its shard and its origin (a backfill, a commit range with the watched fields and the requests that changed it, a run now, a schema change), the pass in progress, and per shard its message in flight and its first unfinished turns with their origins; the items are in data, and has_more and next_cursor page them with cursor and limit. run_results (name) shows what the workflow's runs did with each input, newest run first: the input's IRI and label, its outcome (written, review, no_value, failed, duplicate) and its values (the value, the quote that states it, its support, the conversion, and the review item it went to); run keeps one run (with run_counts, every input by outcome), outcome keeps some outcomes, iri keeps one input; data, has_more and next_cursor page them. A run records its results when it ends; they are kept 30 days. revisions (name) shows the history of a workflow's settings, newest change first: each item is a revision (settings, the request that makes it, and an id wrev_… that is the hash of the settings) with who changed it, when, how (create, change, activate, existing) and bound (the one in use); a row whose revision was deleted has available false and no settings; has_more and next_cursor page it with cursor and limit (1 to 100, default 20). last_tested on a revision of a workflow that has tests (values.extract) says what the workflow's tests read with those exact settings: an object (test, finished, counts, and experiment when the test is an arm of an experiment) names the newest test that read inputs with them, null means no test is recorded for those settings, and no key means the workflow has no tests or the server does not say; it shows what happened and gives no verdict. revision (name, revision) reads one revision; compare two by their settings to say what changed. Each run summary names the revision it ran on. Message workflows of the workflow engine are not listed here. tests lists the graph's workflow tests, newest first, without texts and results (name: one workflow's tests), one page with next_cursor; tests_get reads one test (id) with its inputs' texts and, per input, each value read with its quote, its support and what the live workflow does with it (writes it, gives it to review, or drops it). A test goes queued, running, then done, failed or cancelled. Create, refresh, pause or resume with lbb_workflows_manage, which also starts, answers and cancels tests and goes back to an earlier revision with its action activate; delete with lbb_workflows_delete.",
         inputSchema: {
             action: z.enum([
                 "starters",
@@ -1030,7 +1032,7 @@ export function registerLbbTools(server, client, options = {}) {
         });
     });
     host.register("lbb_workflows_manage", {
-        description: "Create a workflow from a starter workflow, or refresh, pause or resume a triggered workflow. Run lbb_workflows action=preview first and show the user the watch and the instance count. use creates a workflow from a starter workflow of action=starters, under a name (default: the class's local name), with its watch (class, fields) and params; the workflow then reads every instance of the class and follows each published commit. A developer workflow (starter=workflow) also takes workflow (workflow_type and version of the developer's worker), owns and batch; it needs a server with the workflow engine. use again with the same starter and name changes only what you name, and the same request again changes nothing. A workflow that calls models (ontology.fit, documents.link, documents.map, values.extract) spends model budget as it reads. refresh asks the workflow to run now and returns at once with queued; poll lbb_workflows action=get for progress. pause stops a workflow (a developer workflow, documents.parse, documents.link, documents.map or values.extract) from reading and sending, and stops the claims of a developer workflow's shards; resume lets it catch up. Without starter, pause and resume name a workflow with triggers. search.embed and ontology.fit cannot be paused. define creates or changes a workflow with triggers of the developer's worker (/v1/workflows/named): name, workflow, one trigger (class and fields for a watch, media_types for a content trigger on uploads, schedule for one run per slot of a timer, or stream for the events a client sends, in batches), owns, batch, and shards (engine identities, 1 to 16), route_by (a field that keeps work in order) and window (messages queued per shard, default 4), and optionally budget_usd_per_month (the workflow's own monthly model budget), on_exhausted (block or skip) and fan_in (the id of a fan-in identity the shards send to); it needs a server with the workflow engine, and a change of shards waits for empty inboxes. run (name) runs a workflow with triggers now: its watch sends every instance again, a content trigger reads its log again, a schedule sends one run outside its slots, a stream sends its partial batches. activate (name, revision) makes an earlier revision of a workflow's settings (from lbb_workflows action=revisions) the one in use: it goes through the same checks as a change, and answers the workflow with its active_revision. Show the user what changes first (compare the settings of the two revisions), and pass expected_revision, the revision you read as bound, so a change by someone else since fails with workflow_revision_conflict. A revision whose settings the graph now reads differently fails with workflow_revision_stale; then change the workflow instead. Activating changes what the workflow does from then on and deletes no data, so it is not a destructive write; a change of the watch, the parameters or the gate makes the workflow read its class again, and work that waits or runs keeps the revision it started with. tests_create tests a values.extract workflow on chosen inputs before it writes: name (a workflow of the graph; starter defaults to values.extract) or install (a workflow not created yet, as use takes it: starter, name, watch, params, gate), and iris (at most 20) or sample (1 to 20, default 6), and models to try other models before choosing one. A test reads each input as the workflow would and calls its models (the calls count in the monthly workflow budget); it writes nothing to the graph. Poll lbb_workflows action=tests_get. tests_answer records the person's answer to one value of a read input (id, iri, property, answer: accept, reject, correct with value, or cant_tell; null removes it); it writes nothing to the graph. Answer only what the user decided. tests_cancel stops a queued or running test (id). Save a test's answers as a dataset with lbb_evals action=datasets_create.",
+        description: "Create a workflow from a starter workflow, or refresh, pause or resume a triggered workflow. Run lbb_workflows action=preview first and show the user the watch and the instance count. use creates a workflow from a starter workflow of action=starters, under a name (default: the class's local name), with its watch (class, fields) and params; the workflow then reads every instance of the class and follows each published commit. A developer workflow (starter=workflow) also takes workflow (workflow_type and version of the developer's worker), owns and batch; it needs a server with the workflow engine. use again with the same starter and name changes only what you name, and the same request again changes nothing. A workflow that calls models (ontology.fit, documents.link, documents.map, values.extract) spends model budget as it reads. refresh asks the workflow to run now and returns at once with queued; poll lbb_workflows action=get for progress. pause stops a workflow (a developer workflow, documents.parse, documents.link, documents.map or values.extract) from reading and sending, and stops the claims of a developer workflow's shards; resume lets it catch up. Without starter, pause and resume name a workflow with triggers. search.embed and ontology.fit cannot be paused. define creates or changes a workflow with triggers of the developer's worker (/v1/workflows/named): name, workflow, one trigger (class and fields for a watch, media_types for a content trigger on uploads, schedule for one run per slot of a timer, or stream for the events a client sends, in batches), owns, batch, and shards (engine identities, 1 to 16), route_by (a field that keeps work in order) and window (messages queued per shard, default 4), and optionally budget_usd_per_month (the workflow's own monthly model budget), on_exhausted (block or skip) and fan_in (the id of a fan-in identity the shards send to); it needs a server with the workflow engine, and a change of shards waits for empty inboxes. run (name) runs a workflow with triggers now: its watch sends every instance again, a content trigger reads its log again, a schedule sends one run outside its slots, a stream sends its partial batches. activate (name, revision) makes an earlier revision of a workflow's settings (from lbb_workflows action=revisions) the one in use: it goes through the same checks as a change, and answers the workflow with its active_revision. Show the user what changes first (compare the settings of the two revisions), and when the revision's last_tested is null say that no test is recorded for those settings and ask before you activate (activation stays allowed), and pass expected_revision, the revision you read as bound, so a change by someone else since fails with workflow_revision_conflict. A revision whose settings the graph now reads differently fails with workflow_revision_stale; then change the workflow instead. Activating changes what the workflow does from then on and deletes no data, so it is not a destructive write; a change of the watch, the parameters or the gate makes the workflow read its class again, and work that waits or runs keeps the revision it started with. tests_create tests a values.extract workflow on chosen inputs before it writes: name (a workflow of the graph; starter defaults to values.extract) or install (a workflow not created yet, as use takes it: starter, name, watch, params, gate), and iris (at most 20) or sample (1 to 20, default 6), and models to try other models before choosing one. A test reads each input as the workflow would and calls its models (the calls count in the monthly workflow budget); it writes nothing to the graph. Poll lbb_workflows action=tests_get. tests_answer records the person's answer to one value of a read input (id, iri, property, answer: accept, reject, correct with value, or cant_tell; null removes it); it writes nothing to the graph. Answer only what the user decided. tests_cancel stops a queued or running test (id). Save a test's answers as a dataset with lbb_evals action=datasets_create.",
         inputSchema: {
             action: z.enum([
                 "use",
@@ -1069,6 +1071,10 @@ export function registerLbbTools(server, client, options = {}) {
                 .string()
                 .optional()
                 .describe("activate: the revision the workflow had bound when you read it; another one fails with workflow_revision_conflict."),
+            experiment: z
+                .string()
+                .optional()
+                .describe("activate: an experiment (exp_…) whose B this activation applies; revision is B's revision. The workflow must still run the experiment's A, else experiment_outdated; when B's revision is active already, nothing changes."),
             install: testInstallSchema
                 .optional()
                 .describe("tests_create: a workflow not created yet, as use takes it: starter (values.extract), name, watch ({class, fields, exclude}), params and gate ({below})."),
@@ -1131,9 +1137,12 @@ export function registerLbbTools(server, client, options = {}) {
             case "run":
                 return workflows.named.run(workflowName(args));
             case "activate":
-                return workflows.named.activateRevision(workflowName(args), revisionId(args.revision), args.expected_revision
-                    ? { expectedRevision: args.expected_revision }
-                    : {});
+                return workflows.named.activateRevision(workflowName(args), revisionId(args.revision), {
+                    ...(args.expected_revision
+                        ? { expectedRevision: args.expected_revision }
+                        : {}),
+                    ...(args.experiment ? { experiment: args.experiment } : {}),
+                });
             case "tests_create":
                 return workflows.tests.create(testRequest(args));
             case "tests_answer":
@@ -1310,6 +1319,10 @@ export function registerLbbTools(server, client, options = {}) {
                 .string()
                 .optional()
                 .describe("put_choice / delete_choice: a named workflow of the graph; absent for the environment."),
+            experiment: z
+                .string()
+                .optional()
+                .describe("put_choice: an experiment (exp_…) whose B this choice applies, with workflow; use and the model are B's change. The workflow must still run the experiment's A, else experiment_outdated; when it runs B already, nothing changes."),
             detail: detailSchema,
             ...graphScope,
         },
@@ -1355,6 +1368,7 @@ export function registerLbbTools(server, client, options = {}) {
                         ...(args.effort ? { effort: args.effort } : {}),
                     },
                     ...(args.workflow ? { workflow: args.workflow } : {}),
+                    ...(args.experiment ? { experiment: args.experiment } : {}),
                 });
             case "delete_choice":
                 if (!args.use)
@@ -1370,8 +1384,24 @@ export function registerLbbTools(server, client, options = {}) {
             throw new Error("this action requires id");
         return id;
     };
+    const experimentId = (id) => {
+        if (!id)
+            throw new Error("this action requires id (the experiment's)");
+        return id;
+    };
+    const experimentRequest = (args) => {
+        if (!args.workflow || !args.dataset || !args.b)
+            throw new Error("this action requires workflow, dataset and b");
+        return {
+            workflow: args.workflow,
+            dataset: args.dataset,
+            b: args.b,
+            ...(args.max_items ? { max_items: args.max_items } : {}),
+            ...(args.max_cost_usd ? { max_cost_usd: args.max_cost_usd } : {}),
+        };
+    };
     host.register("lbb_evals", {
-        description: "Managed evals: ground truth for the questions an app asks and the searches it runs. A query run with `request` (lbb_query, also mode=question) records a trace: the question, the query that answered it, the type of that query (`query_type`: sparql, hybrid = search by meaning with conditions, search = search by meaning alone) and one item per result (hit or row); trace reads it back with the item ids. label has two forms. On a question's trace, valid alone judges the whole answer: valid=true makes the trace's query the golden query of the question; valid=false with sparql gives the right query, which becomes the golden query; valid=false alone marks the answer wrong; route with valid=true (or valid=false with sparql) names the route the question expects, and valid=true alone takes the trace's route. item + valid (or items) judges one result, a citation of the answer: the ground truth of the hits of a search by meaning, and a result marked wrong must not come back for any type. golden freezes a stored query or a search (every result it returns now is relevant). run checks every golden at the current commit: a question is asked again through the query rewriter, then the type of the query it wrote is compared with the expected type, its rows with the rows of the golden query at the same commit (`query_check`), and its results with the judged results, and the router's pick with the golden's route (route_check, which does not change the verdict); a search is done again; new results open a review trace. run_answers checks your own app's answers instead: ask each question golden's request with your own loop, then send answers=[{golden, sparql, route}] (route = the route of lbb_query mode=question with route mode, sparql absent for an unanswerable question, error for a failure); the server runs each query and checks it the same way, and the runs form the app's own series (runner; results with runner reads them). judge lets the platform's judge model (the hosted frontier model) label unlabeled results. summary, traces, goldens, results, and settings read state. Model checks: a judge model checks a sample of the model calls LBB makes for the graph (rerank, route, ask = the answer of a question, rewrite, fit, propose, label). checks_summary reads a month per job and model (checks, score, right, partly, wrong, reviews) and the judge's agreement with people; checks lists the month's checks, newest first, with the judge's verdict, score and reason and the ground truth (`truth`). review_check records a person's review of one check (call_id): agree=true keeps the judge's verdict; agree=false with verdict (and an optional score, reference and note) corrects it. The review becomes the call's ground truth, so show the check to the user and review only what the user confirmed. Datasets: named sets of examples with the outputs a correct run gives, which workflow tests and template evals share. The kind values holds per item an input text (name, text, iri), the property values a correct run writes (values) and those it must leave out (leave_out). datasets lists the graph's datasets, newest first, without their items (one page with next_cursor); datasets_get reads one (id) with its items; datasets_export returns it as a template's samples, records (records.json) and expected (expected.json). datasets_create makes one with name and items (at most 500), install (the settings it is graded with: each property's value type, units, context) and about, or from a workflow test's answers with source={kind: test, id}. datasets_items adds items to a dataset (id); an item with the name of one it holds replaces it. Delete a dataset with lbb_evals_delete, which asks the person first. A dataset ends with its graph.",
+        description: "Managed evals: ground truth for the questions an app asks and the searches it runs. A query run with `request` (lbb_query, also mode=question) records a trace: the question, the query that answered it, the type of that query (`query_type`: sparql, hybrid = search by meaning with conditions, search = search by meaning alone) and one item per result (hit or row); trace reads it back with the item ids. label has two forms. On a question's trace, valid alone judges the whole answer: valid=true makes the trace's query the golden query of the question; valid=false with sparql gives the right query, which becomes the golden query; valid=false alone marks the answer wrong; route with valid=true (or valid=false with sparql) names the route the question expects, and valid=true alone takes the trace's route. item + valid (or items) judges one result, a citation of the answer: the ground truth of the hits of a search by meaning, and a result marked wrong must not come back for any type. golden freezes a stored query or a search (every result it returns now is relevant). run checks every golden at the current commit: a question is asked again through the query rewriter, then the type of the query it wrote is compared with the expected type, its rows with the rows of the golden query at the same commit (`query_check`), and its results with the judged results, and the router's pick with the golden's route (route_check, which does not change the verdict); a search is done again; new results open a review trace. run_answers checks your own app's answers instead: ask each question golden's request with your own loop, then send answers=[{golden, sparql, route}] (route = the route of lbb_query mode=question with route mode, sparql absent for an unanswerable question, error for a failure); the server runs each query and checks it the same way, and the runs form the app's own series (runner; results with runner reads them). judge lets the platform's judge model (the hosted frontier model) label unlabeled results. summary, traces, goldens, results, and settings read state. Model checks: a judge model checks a sample of the model calls LBB makes for the graph (rerank, route, ask = the answer of a question, rewrite, fit, propose, label). checks_summary reads a month per job and model (checks, score, right, partly, wrong, reviews) and the judge's agreement with people; checks lists the month's checks, newest first, with the judge's verdict, score and reason and the ground truth (`truth`). review_check records a person's review of one check (call_id): agree=true keeps the judge's verdict; agree=false with verdict (and an optional score, reference and note) corrects it. The review becomes the call's ground truth, so show the check to the user and review only what the user confirmed. Datasets: named sets of examples with the outputs a correct run gives, which workflow tests and template evals share. The kind values holds per item an input text (name, text, iri), the property values a correct run writes (values) and those it must leave out (leave_out). datasets lists the graph's datasets, newest first, without their items (one page with next_cursor); datasets_get reads one (id) with its items; datasets_export returns it as a template's samples, records (records.json) and expected (expected.json). datasets_create makes one with name and items (at most 500), install (the settings it is graded with: each property's value type, units, context) and about, or from a workflow test's answers with source={kind: test, id}. datasets_items adds items to a dataset (id); an item with the name of one it holds replaces it. Delete a dataset with lbb_evals_delete, which asks the person first. A dataset ends with its graph. Experiments: two configurations of a workflow, A and B, on the items of a dataset, with the difference of B against A and its 95% interval. A is the workflow as it runs now; b changes one part: {model: {use: extract or decide, model: {provider, model, effort}}} (a model from lbb_model_choice action=choices options) or {revision: wrev_…} (a kept settings revision), not both. Each arm runs as a workflow test that writes nothing to the graph and spends model budget; each item is graded against the dataset's labels. experiments_estimate shows the cost first (items, the cost of both arms, the limit, the budget left): call it, show the user the figures, and start only what the user confirmed. experiments_create starts one (workflow, dataset, b, optionally max_items up to 200 and max_cost_usd up to 100, default 5); poll experiment (id) until its status is done, failed or cancelled, and read report.delta with ci_low and ci_high (outcome too_few under 10 items, else better, worse or same) and the item rows. experiments lists them (workflow, dataset, status, one page with next_cursor); experiments_cancel stops one, keeping what it compared. None of them changes the workflow or the graph. To use B, make the change with the experiment's id: lbb_model_choice_manage action=put_choice (or lbb_workflows_manage action=activate) with experiment, after the user confirmed; it fails with experiment_outdated when the workflow moved since.",
         inputSchema: {
             action: z.enum([
                 "summary",
@@ -1395,6 +1425,11 @@ export function registerLbbTools(server, client, options = {}) {
                 "datasets_export",
                 "datasets_create",
                 "datasets_items",
+                "experiments",
+                "experiment",
+                "experiments_estimate",
+                "experiments_create",
+                "experiments_cancel",
             ]),
             trace_id: z
                 .string()
@@ -1411,7 +1446,7 @@ export function registerLbbTools(server, client, options = {}) {
             items: z
                 .array(z.union([evalLabelItemSchema, evalDatasetItemSchema]))
                 .optional()
-                .describe("label: several results at once, each {id, valid, note}. datasets_create, datasets_items: the examples, at most 500, each {name, text, values, leave_out, iri, case}; values and leave_out hold {property, value, accept, stated, quote, reason}."),
+                .describe("label: several results at once, each {id, valid, note}. datasets_create, datasets_items: the examples, at most 500, each {name, text, values, leave_out, iri, case}; values and leave_out hold {property, value, accept, stated, quote, reason, source}; source says which person's answer gave a label (kind test or review, id, at): send it back as read, or leave it out."),
             by: z
                 .string()
                 .optional()
@@ -1555,11 +1590,39 @@ export function registerLbbTools(server, client, options = {}) {
             id: z
                 .string()
                 .optional()
-                .describe("datasets_get, datasets_export, datasets_items: the dataset's id (ds_…)."),
+                .describe("datasets_get, datasets_export, datasets_items: the dataset's id (ds_…). experiment, experiments_cancel: the experiment's id (exp_…)."),
             cursor: z
                 .string()
                 .optional()
-                .describe("datasets: the next_cursor of the page before."),
+                .describe("datasets, experiments: the next_cursor of the page before."),
+            workflow: z
+                .string()
+                .optional()
+                .describe("experiments_estimate, experiments_create: the workflow to compare. experiments: only the experiments of this workflow."),
+            dataset: z
+                .string()
+                .optional()
+                .describe("experiments_estimate, experiments_create: the dataset (ds_…) whose items both arms run. experiments: only the experiments on this dataset."),
+            b: experimentArmSchema
+                .optional()
+                .describe("experiments_estimate, experiments_create: what B changes in A: {model: {use, model: {provider, model, effort}}} or {revision}, not both."),
+            max_items: z
+                .number()
+                .int()
+                .min(1)
+                .max(200)
+                .optional()
+                .describe("experiments_estimate, experiments_create: run the dataset's first items only (default 200)."),
+            max_cost_usd: z
+                .number()
+                .positive()
+                .max(100)
+                .optional()
+                .describe("experiments_estimate, experiments_create: the cost limit of both arms in US dollars (default 5)."),
+            status: z
+                .enum(["queued", "running", "done", "failed", "cancelled"])
+                .optional()
+                .describe("experiments: only the experiments with this status."),
             name: z
                 .string()
                 .optional()
@@ -1596,7 +1659,17 @@ export function registerLbbTools(server, client, options = {}) {
             ...graphScope,
         },
         annotations: MUTATING,
-    }, ({ action, trace_id, item, valid, items, by, note, sparql, route, answers, runner, surface, embedding, top_k, request, golden_id, limit, unlabeled, consistency, month, job, verdict, reviewed, after, call_id, agree, score, reference, id, cursor, name, kind, install, about, source, detail, graph, }) => {
+    }, ({ action, trace_id, item, valid, items, by, note, sparql, route, answers, runner, surface, embedding, top_k, request, golden_id, limit, unlabeled, consistency, month, job, verdict, reviewed, after, call_id, agree, score, reference, id, cursor, workflow, dataset, b, max_items, max_cost_usd, status, name, kind, install, about, source, detail, graph, }) => {
+        if (action === "experiments") {
+            const experiments = scoped(client, graph).evals.experiments;
+            return runPage(client, "lbb_evals.experiments", detail, pageLimit(detail, limit, EVAL_EXPERIMENTS_PAGE_MAX), (pageSize) => experiments.list({
+                workflow,
+                dataset,
+                status,
+                limit: pageSize,
+                cursor,
+            }));
+        }
         if (action === "datasets") {
             const datasets = scoped(client, graph).evals.datasets;
             return runPage(client, "lbb_evals.datasets", detail, pageLimit(detail, limit, EVAL_DATASETS_PAGE_MAX), (pageSize) => datasets.list({ limit: pageSize, cursor }));
@@ -1728,6 +1801,26 @@ export function registerLbbTools(server, client, options = {}) {
                         throw new Error("datasets_items requires items");
                     return target.evals.datasets.addItems(datasetId(id), examples);
                 }
+                case "experiment":
+                    return target.evals.experiments.get(experimentId(id));
+                case "experiments_cancel":
+                    return target.evals.experiments.cancel(experimentId(id));
+                case "experiments_estimate":
+                    return target.evals.experiments.estimate(experimentRequest({
+                        workflow,
+                        dataset,
+                        b,
+                        max_items,
+                        max_cost_usd,
+                    }));
+                case "experiments_create":
+                    return target.evals.experiments.create(experimentRequest({
+                        workflow,
+                        dataset,
+                        b,
+                        max_items,
+                        max_cost_usd,
+                    }));
             }
         });
     });
@@ -1757,10 +1850,19 @@ export function registerLbbTools(server, client, options = {}) {
         return run(client, "lbb_evals_delete", detail, () => datasets.delete(id));
     });
     host.register("lbb_commit", {
-        description: `Write graph facts, retract them, or label ranked results. mode=facts writes triplets/embeddings/properties; mode=retract removes a wrongly-added fact (by edge or by entity) without a full reset; mode=search_feedback stores query/result relevance labels (Feedback grades: 3=ideal/good, 1=partial, 0=bad; include query, search_id when available, target, rank, score). Explicit idempotency_key wins; when omitted, MCP derives a stable content hash so content-identical retries dedupe. Facts mode defaults edge_idempotency to append; pass skip_unchanged for re-runnable backfills. A retract asks the person to approve the links and records it removes first. ${APPROVAL_TEXT}`,
+        description: `Write graph facts, retract them, or label ranked results. Explicit mode=records forwards a strict records/1 body, with exact IRIs/terms and the original receipt. It requires an existing support-enabled graph; protocol recognition never activates or converts a graph. Record edits that may remove support (set/unset/remove/delete/replace_scope or asserted=false) ask for approval. mode=facts writes triplets/embeddings/properties; mode=retract removes a wrongly-added fact (by edge or by entity) without a full reset; mode=search_feedback stores query/result relevance labels (Feedback grades: 3=ideal/good, 1=partial, 0=bad; include query, search_id when available, target, rank, score). Explicit idempotency_key wins; when omitted, MCP derives a stable content hash so content-identical retries dedupe. Facts mode defaults edge_idempotency to append; pass skip_unchanged for re-runnable backfills. A retract asks the person to approve the links and records it removes first. ${APPROVAL_TEXT}`,
         inputSchema: {
             idempotency_key: z.string().optional(),
-            mode: z.enum(["facts", "retract", "search_feedback"]).optional(),
+            mode: z
+                .enum(["facts", "retract", "search_feedback", "records"])
+                .optional(),
+            records: jsonObjectSchema
+                .optional()
+                .describe("Explicit mode=records only: the unchanged RecordCommitRequest object with version=records/1. Unknown fields are preserved for strict server validation; no native IRI normalization or scalar coercion. Cannot mix legacy write arguments."),
+            expected_graph_epoch: z
+                .string()
+                .optional()
+                .describe("mode=records only: exact decimal graph incarnation guard. Protocol support does not activate this graph."),
             triplets: z
                 .array(z.object({
                 source: z.object({ type: z.string(), name: z.string() }),
@@ -1821,7 +1923,30 @@ export function registerLbbTools(server, client, options = {}) {
         },
         // A retract removes facts, so the tool may destroy.
         annotations: DESTRUCTIVE,
-    }, async ({ idempotency_key, mode, triplets, entity_embeddings, entity_properties, search_feedback, dry_run, observed_at, edge_idempotency, retract_edges, retract_entities, graph, }, extra) => {
+    }, async ({ idempotency_key, mode, records, expected_graph_epoch, triplets, entity_embeddings, entity_properties, search_feedback, dry_run, observed_at, edge_idempotency, retract_edges, retract_entities, graph, }, extra) => {
+        if (mode === "records" ||
+            records !== undefined ||
+            expected_graph_epoch !== undefined) {
+            if (mode !== "records")
+                return errorResult(new ToolError("record_mode_required", "records and expected_graph_epoch require explicit mode=records; no implicit legacy write was sent"));
+            return commitRecordsTool(host, client, extra, {
+                records,
+                idempotencyKey: idempotency_key,
+                expectedGraphEpoch: expected_graph_epoch,
+                graph,
+                legacyInputs: [
+                    triplets,
+                    entity_embeddings,
+                    entity_properties,
+                    search_feedback,
+                    dry_run,
+                    observed_at,
+                    edge_idempotency,
+                    retract_edges,
+                    retract_entities,
+                ].some((value) => value !== undefined),
+            });
+        }
         const commitMode = mode ??
             (search_feedback
                 ? "search_feedback"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@littlebigbrain/mcp",
-  "version": "0.16.0",
+  "version": "0.17.0",
   "description": "MCP server for little big brain: search, graph queries, and data import",
   "license": "Apache-2.0",
   "repository": {
@@ -52,7 +52,7 @@
     "test:coverage": "npm run clean:test && tsc -p tsconfig.test.json && node --test --experimental-test-coverage --test-coverage-include=test-dist/*.js --test-coverage-exclude=test-dist/*.test.js --test-coverage-exclude=test-dist/stdio.js --test-coverage-exclude=test-dist/test-support.js --test-coverage-lines=90 --test-coverage-branches=70 --test-coverage-functions=85 \"test-dist/**/*.test.js\""
   },
   "dependencies": {
-    "@littlebigbrain/client": "^0.31.0",
+    "@littlebigbrain/client": "^0.32.0",
     "@modelcontextprotocol/sdk": "^1",
     "zod": "^4.6.6"
   },