@littlebigbrain/mcp 0.4.3 → 0.5.0

package/README.md

@@ -1,6 +1,6 @@
 # @littlebigbrain/mcp
 
-Ten task-shaped [MCP](https://modelcontextprotocol.io) tools that let Claude, Cursor, Codex, or any MCP client search, query, and write a [Little Big Brain](https://littlebigbrain.com) graph. Ships two ways: a hosted endpoint with OAuth sign-in, and a local stdio server.
+Eight task-shaped [MCP](https://modelcontextprotocol.io) tools that let Claude, Cursor, Codex, or any MCP client search, query, and write a [Little Big Brain](https://littlebigbrain.com) graph. Ships two ways: a hosted endpoint with OAuth sign-in, and a local stdio server.
 
 ## Hosted (OAuth) — recommended
 
@@ -58,16 +58,95 @@ missing.
 
 | Tool | Use it for |
 | --- | --- |
-| `lbb_inspect` | ontology, schema, entity, state, history, and provenance |
+| `lbb_inspect` | graph discovery, complete paginated ontology/schema, publication status, entity, state, history, and provenance |
+| `lbb_rdf` | import full RDF/OWL or add axioms using INSERT DATA |
 | `lbb_query` | SPARQL text, structured SPARQL bodies, and canned analysis |
 | `lbb_commit` | facts, properties, and embeddings |
 | `lbb_observe` | conversation episodes plus reviewed extraction |
 | `lbb_branch` | isolation branches and validated merge |
 | `lbb_models` | shadow evaluation and training datasets |
-| `lbb_configure` | ontology definition and atomic schema publication |
+| `lbb_configure` | native ontology definition/evolution and SHACL preview/publication |
 
 Read tools return compact structured envelopes by default — use `detail`, `row_limit`, and returned cursors to page without silently truncating. Write tools derive an idempotency key unless you provide one.
 
+Both `lbb_query` SPARQL modes (`sparql` and `structured`) support retained commit reads
+through `as_of_commit_seq`. When omitted, the connector pins the current head
+commit and reuses it for cursor pages. Valid-time `as_of` is unsupported and is
+rejected before an API call, including when carried in an old cursor. Start a
+new query without that selector or choose a retained commit sequence.
+
+## Create and evolve an ontology through MCP
+
+Start with `lbb_inspect action=guide`; `action=graphs` helps select an existing
+scope, and a missing graph returns bootstrap guidance. Decide what questions
+the graph must answer before choosing classes and relations. Distinguish
+source-backed facts from hypotheses, and preserve evidence and dates.
+
+Native metadata and stored RDF axioms are separate:
+
+- `lbb_configure action=define_ontology` accepts a friendly `spec`, including
+  class `super_types`. Unknown spec fields fail explicitly. `lbb_json` expects
+  an internal serialized ontology, not a friendly spec. Raw OWL supplied to
+  configure is reduced to native metadata; it is not stored as a full document.
+- `lbb_rdf action=import` stores the complete Turtle, N-Triples, N-Quads, or TriG
+  document as queryable graph facts, including RDF lists, annotations, and OWL
+  axioms. Pass `source`; the published RDF tier supports only the default RDF
+  graph. Dataset formats must contain only default-graph quads. The first RDF
+  data write selects RDF-native storage, which refuses
+  later property-graph commits; choose the write workflow before bootstrap.
+- `lbb_configure action=evolve_ontology` supports explicit native changes,
+  including `add_super_types`. `dry_run: true` previews define/evolve/publish;
+  the same flag previews `lbb_commit mode=facts` without writing.
+- `lbb_rdf action=update` submits SPARQL Update unchanged; currently only
+  `INSERT DATA` is supported. DELETE, WHERE, and graph replacement are refused.
+  Re-importing is
+  additive and does not remove obsolete axioms. Content-based retry keys are
+  automatic; use a new explicit key for an intentional repeat after other edits.
+
+For example, add a superclass without a browser or RDF conversion:
+
+```json
+{
+  "action": "update",
+  "update": "INSERT DATA { <urn:Person> <http://www.w3.org/2000/01/rdf-schema#subClassOf> <urn:Contact> }"
+}
+```
+
+Removing or replacing RDF axioms requires native bounded update support in the
+engine. Until then, import a revised document into a new versioned LBB graph,
+verify it, and explicitly switch consumers. Do not implicitly delete the original.
+
+`publish_schema` activates SHACL shapes against unchanged native metadata.
+Its preview checks parsing and compatibility without writing objects or
+scheduling jobs; it does not audit the entire graph. Preview restrictive
+native edits with evolve, resolve conflicts, then apply. For restrictive
+SHACL, use warn → inspect conformance → repair → reject.
+
+After applying, inspect `action=publication`, then verify both asserted axioms
+and expected inferred answers. `lbb_query mode=sparql` accepts explicit
+`entailment: "none" | "subclass" | "rdfs" | "owl"` (default `none`),
+`consistency: "eventual" | "strong"`, and `min_indexed_seq`. Cursors retain
+these controls. OWL is the server's supported inference profile, not arbitrary
+OWL DL. An upload acknowledgement is not proof of successful reasoning.
+
+To read asserted axioms in the default graph, query with `entailment: "none"`
+and follow all returned row cursors:
+
+```sparql
+SELECT ?s ?p ?o WHERE {
+  ?s ?p ?o
+} ORDER BY ?s ?p ?o
+```
+
+`lbb_inspect action=ontology` and `action=schema` page complete native metadata
+with `page_size` (default 50, maximum 500), optional `section`, and `cursor`.
+Pass the returned `next` arguments until absent. These pages preserve nested
+values even with `detail=compact`; they never replace the remainder with a
+suggestion to repeat `detail=full`. If a single entry is too large, the result
+contains `entry_fragment`: concatenate `serialized_json` by `char_offset`, then
+JSON-parse the completed entry. Changed metadata invalidates the cursor rather
+than mixing versions. Restart inspection after applying edits.
+
 ## Embed the server
 
 For self-hosting behind your own auth, the package also serves the tools over HTTP:
@@ -85,3 +164,17 @@ createMcpHttpServer({
 The embedded server passes a key bearer to the data plane; the hosted endpoint's OAuth and ownership layer is served separately by the Little Big Brain API.
 
 Full tool schemas and examples: [docs.littlebigbrain.com/sdks/mcp](https://docs.littlebigbrain.com/sdks/mcp/).
+
+## Local end-to-end ontology check
+
+From the repository root, build the server and SDKs, then opt into the isolated
+real-server MCP test (it creates and removes its own temporary data root):
+
+```sh
+cargo build -p lbb-server
+npm run build -w @littlebigbrain/client
+LBB_TEST_SERVER_BIN="$PWD/target/debug/lbb-server" npm test -w @littlebigbrain/mcp
+```
+
+The test verifies native hierarchy evolution, preservation of RDF annotations,
+subclass/inverse inference, additive edits, and refusal of unsupported deletion.

package/dist/metadata-pages.d.ts

@@ -0,0 +1,33 @@
+import { z } from "zod";
+import { type LbbClient } from "@littlebigbrain/client";
+import { metadataPageSchema } from "./tool-contracts.js";
+type Request = z.infer<z.ZodObject<typeof metadataPageSchema>> & {
+    action: "ontology" | "schema";
+    graph?: string;
+    branch?: string;
+};
+/** Stateless pagination of complete entries, including their full nested values.
+ * A digest rejects mixed-version reads instead of skipping/repeating definitions
+ * when schema or population counts change between pages. */
+export declare function metadataPage(client: LbbClient, args: Request): Promise<{
+    summary: string;
+    data: Record<string, unknown>;
+    counts: Record<string, number> | undefined;
+    row_page: {
+        returned: number;
+        total: number;
+        offset: number;
+        limit: number;
+        has_more: boolean;
+        next_offset: number | undefined;
+    };
+    next: {
+        action: "ontology" | "schema";
+        graph: string | undefined;
+        branch: string | undefined;
+        section: string | undefined;
+        page_size: number;
+        cursor: string;
+    } | undefined;
+}>;
+export {};

package/dist/metadata-pages.js

@@ -0,0 +1,150 @@
+import { createHash } from "node:crypto";
+import { z } from "zod";
+import { HARD_OUTPUT_CHARS } from "./tool-contracts.js";
+import { countsFor, stableJson } from "./tool-runtime.js";
+const cursorSchema = z
+    .object({
+    v: z.literal(1),
+    action: z.enum(["ontology", "schema"]),
+    graph: z.string().optional(),
+    branch: z.string().optional(),
+    section: z.string().optional(),
+    page_size: z.number().int().min(1).max(500),
+    offset: z.number().int().nonnegative().safe(),
+    fragment_offset: z.number().int().nonnegative().safe().optional(),
+    fingerprint: z.string(),
+})
+    .strict();
+/** Stateless pagination of complete entries, including their full nested values.
+ * A digest rejects mixed-version reads instead of skipping/repeating definitions
+ * when schema or population counts change between pages. */
+export async function metadataPage(client, args) {
+    let cursor;
+    if (args.cursor) {
+        try {
+            cursor = cursorSchema.parse(JSON.parse(Buffer.from(args.cursor, "base64url").toString("utf8")));
+        }
+        catch {
+            throw new Error("invalid lbb_inspect cursor; restart without cursor");
+        }
+        for (const key of [
+            "action",
+            "graph",
+            "branch",
+            "section",
+            "page_size",
+        ]) {
+            if (args[key] !== undefined && args[key] !== cursor[key]) {
+                throw new Error(`cursor ${key} does not match the supplied ${key}`);
+            }
+        }
+    }
+    const graph = cursor?.graph ?? args.graph;
+    const branch = cursor?.branch ?? args.branch;
+    const section = cursor?.section ?? args.section;
+    const pageSize = cursor?.page_size ?? args.page_size ?? 50;
+    const target = client.withScope({ graph, branch });
+    const value = (args.action === "ontology"
+        ? await target.ontologyView({ counts: true })
+        : await target.schema.view());
+    if (section !== undefined && !Array.isArray(value[section])) {
+        throw new Error(`unknown metadata section '${section}'; choose ${Object.keys(value)
+            .filter((k) => Array.isArray(value[k]))
+            .join(", ")}`);
+    }
+    const fingerprint = createHash("sha256")
+        .update(stableJson(value))
+        .digest("hex");
+    if (cursor && cursor.fingerprint !== fingerprint) {
+        throw new Error("ontology/schema metadata changed during pagination; restart without cursor to avoid mixing versions");
+    }
+    const base = {
+        v: 1,
+        action: args.action,
+        graph,
+        branch,
+        section,
+        page_size: pageSize,
+        fingerprint,
+    };
+    const arrays = Object.entries(value).filter(([key, child]) => Array.isArray(child) && (section === undefined || key === section));
+    const entries = arrays.flatMap(([key, items]) => items.map((item) => ({ key, item })));
+    const data = Object.fromEntries(Object.entries(value).filter(([, child]) => !Array.isArray(child)));
+    for (const [key] of arrays)
+        data[key] = [];
+    const offset = cursor?.offset ?? 0;
+    if (offset > entries.length)
+        throw new Error("invalid lbb_inspect cursor offset");
+    const makeEnvelope = (returned, fragmentOffset) => {
+        const end = offset + returned;
+        const hasMore = end < entries.length;
+        return {
+            summary: `lbb_inspect.${args.action}: ${returned} complete metadata entries (${end}/${entries.length})`,
+            data,
+            counts: countsFor(value),
+            row_page: {
+                returned,
+                total: entries.length,
+                offset,
+                limit: pageSize,
+                has_more: hasMore,
+                next_offset: hasMore ? end : undefined,
+            },
+            next: hasMore
+                ? {
+                    action: args.action,
+                    graph,
+                    branch,
+                    section,
+                    page_size: pageSize,
+                    cursor: Buffer.from(JSON.stringify({
+                        ...base,
+                        offset: end,
+                        fragment_offset: fragmentOffset,
+                    })).toString("base64url"),
+                }
+                : undefined,
+        };
+    };
+    let returned = 0;
+    for (const { key, item } of entries.slice(offset, offset + pageSize)) {
+        data[key].push(item);
+        if (JSON.stringify(makeEnvelope(returned + 1), null, 2).length >
+            HARD_OUTPUT_CHARS) {
+            data[key].pop();
+            if (returned === 0) {
+                // Even one unusually large definition remains readable through MCP.
+                // Reassemble serialized_json in order, then JSON.parse the full entry.
+                const serialized = JSON.stringify(item);
+                const start = cursor?.fragment_offset ?? 0;
+                if (start >= serialized.length)
+                    throw new Error("invalid lbb_inspect fragment offset");
+                let size = Math.min(16_000, serialized.length - start);
+                for (;;) {
+                    const end = start + size;
+                    const complete = end === serialized.length;
+                    const result = {
+                        ...makeEnvelope(complete ? 1 : 0, complete ? undefined : end),
+                        summary: `lbb_inspect.${args.action}: fragment of ${key} entry ${offset}; concatenate serialized_json fragments then JSON.parse`,
+                        entry_fragment: {
+                            section: key,
+                            entry_offset: offset,
+                            char_offset: start,
+                            total_chars: serialized.length,
+                            serialized_json: serialized.slice(start, end),
+                            complete,
+                        },
+                    };
+                    if (JSON.stringify(result, null, 2).length <= HARD_OUTPUT_CHARS)
+                        return result;
+                    if (size === 1)
+                        throw new Error("metadata envelope exceeds MCP output budget");
+                    size = Math.max(1, Math.floor(size / 2));
+                }
+            }
+            break;
+        }
+        returned++;
+    }
+    return makeEnvelope(returned);
+}

package/dist/rdf-tool.d.ts

@@ -0,0 +1,3 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import type { LbbClient } from "@littlebigbrain/client";
+export declare function registerRdfTool(server: McpServer, client: LbbClient): void;

package/dist/rdf-tool.js

@@ -0,0 +1,81 @@
+import { z } from "zod";
+import { graphScope, detailSchema, advertiseUnion } from "./tool-contracts.js";
+import { contentHashKey, errorResult, run, scoped } from "./tool-runtime.js";
+const input = z.discriminatedUnion("action", [
+    z
+        .object({
+        action: z.literal("import"),
+        source: z
+            .string()
+            .min(1)
+            .describe("Complete RDF document. Preserves OWL axioms, RDF lists, labels, comments, and external IRIs as graph facts."),
+        format: z.enum(["turtle", "ntriples", "nquads", "trig"]).optional(),
+        base_iri: z.string().optional(),
+        blank_node_scope: z
+            .string()
+            .optional()
+            .describe("Stable document scope for blank labels across import chunks."),
+        idempotency_key: z.string().optional(),
+        ...graphScope,
+        detail: detailSchema,
+    })
+        .strict(),
+    z
+        .object({
+        action: z.literal("update"),
+        update: z
+            .string()
+            .min(1)
+            .describe("SPARQL INSERT DATA text to add axioms. Submitted unchanged. DELETE/WHERE/CLEAR and named graphs are currently unsupported and fail without mutation."),
+        idempotency_key: z.string().optional(),
+        ...graphScope,
+        detail: detailSchema,
+    })
+        .strict(),
+]);
+export function registerRdfTool(server, client) {
+    server.registerTool("lbb_rdf", {
+        description: "Store and extend complete RDF/OWL documents through MCP. import accepts Turtle/N-Triples/N-Quads/TriG without conversion; update executes INSERT DATA for additive edits. Replacing/removing axioms is unsupported; use a new versioned LBB graph for a revised document. Named RDF graphs are unsupported; Turtle/N-Triples use the default graph, and dataset formats must contain only default-graph quads. These write graph facts, distinct from lbb_configure's native schema metadata. A first RDF write selects RDF-native storage, which refuses later property-graph commits; choose the write workflow before bootstrap. Retries deduplicate by content unless idempotency_key is supplied. A completed write schedules publication; inspect action=publication and verify using lbb_query entailment=owl.",
+        inputSchema: advertiseUnion("action", input),
+        annotations: {
+            readOnlyHint: false,
+            destructiveHint: true,
+            idempotentHint: true,
+            openWorldHint: false,
+        },
+    }, (raw) => {
+        const parsed = input.safeParse(raw);
+        if (!parsed.success)
+            return errorResult(parsed.error);
+        const args = parsed.data;
+        return run(client, `lbb_rdf.${args.action}`, args.detail, async () => {
+            const target = scoped(client, args.graph, args.branch);
+            const { idempotency_key } = args;
+            const operation = { ...args };
+            delete operation.detail;
+            delete operation.idempotency_key;
+            const key = idempotency_key ??
+                contentHashKey({ graph: args.graph, branch: args.branch }, operation);
+            if (args.action === "import") {
+                return target.importRdf(args.source, {
+                    format: args.format ?? "turtle",
+                    baseIri: args.base_iri,
+                    blankNodeScope: args.blank_node_scope,
+                    strict: true,
+                    edgeIdempotency: "skip_unchanged",
+                    idempotencyKey: key,
+                });
+            }
+            await target.request("POST", "/update", {
+                rawBody: args.update,
+                contentType: "application/sparql-update",
+                idempotencyKey: key,
+            });
+            return {
+                accepted: true,
+                idempotency_key: key,
+                publication: "pending; inspect action=publication before verifying inferred results",
+            };
+        });
+    });
+}

package/dist/server.js

@@ -1,8 +1,10 @@
+import { readFileSync } from "node:fs";
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { registerLbbTools } from "./tools.js";
+const { version } = JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf8"));
 /** Build an MCP server exposing the little big brain tool belt, bound to one client. */
 export function buildLbbServer(client) {
-    const server = new McpServer({ name: "lbb", version: "0.1.0" });
+    const server = new McpServer({ name: "lbb", version });
     registerLbbTools(server, client);
     return server;
 }

package/dist/tool-contracts.js

@@ -42,6 +42,36 @@ export const graphScope = {
 export const jsonObjectSchema = z.record(z.string(), z.unknown());
 export const jsonObjectArraySchema = z.array(jsonObjectSchema);
 export const readScope = { detail: detailSchema, ...graphScope };
+export const metadataPageSchema = {
+    page_size: z
+        .number()
+        .int()
+        .min(1)
+        .max(500)
+        .optional()
+        .describe("Maximum complete metadata entries per page; defaults to 50. Nested fields are never truncated; an oversized single entry returns serialized_json fragments to concatenate and parse."),
+    cursor: z
+        .string()
+        .optional()
+        .describe("Opaque lbb_inspect continuation. Repeat action and pass the returned next arguments; rejects changed metadata."),
+    section: z
+        .string()
+        .optional()
+        .describe("Optional top-level array to inspect, e.g. entity_type_defs, relation_defs, property_defs, classes, or relations. Omit to page through all sections."),
+};
+const queryConsistencySchema = {
+    consistency: z
+        .enum(["eventual", "strong"])
+        .optional()
+        .describe("Read consistency. strong requires publication through head; a pending response is retryable."),
+    min_indexed_seq: z
+        .number()
+        .int()
+        .nonnegative()
+        .safe()
+        .optional()
+        .describe("Read-after-write publication floor. Preserved across cursor pages."),
+};
 export const entitySelectorSchema = z
     .object({
     entity_type: z
@@ -138,6 +168,13 @@ export const shapeSourceSchema = z
     .strict();
 export const schemaModeSchema = z.enum(["off", "warn", "reject"]);
 export const ontologyEvolveOpSchema = z.discriminatedUnion("op", [
+    z
+        .object({
+        op: z.literal("add_super_types"),
+        entity_type: z.string(),
+        super_types: z.array(z.string()).min(1),
+    })
+        .strict(),
     z
         .object({
         op: z.literal("widen_relation"),
@@ -284,11 +321,25 @@ export const ontologyEvolveOpSchema = z.discriminatedUnion("op", [
 ]);
 export const inspectInputSchema = z.discriminatedUnion("action", [
     z.object({ action: z.literal("guide"), ...readScope }).strict(),
-    z.object({ action: z.literal("ontology"), ...readScope }).strict(),
+    z
+        .object({
+        action: z.literal("ontology"),
+        ...metadataPageSchema,
+        ...readScope,
+    })
+        .strict(),
     z
         .object({ action: z.literal("ontology_conformance"), ...readScope })
         .strict(),
-    z.object({ action: z.literal("schema"), ...readScope }).strict(),
+    z
+        .object({
+        action: z.literal("schema"),
+        ...metadataPageSchema,
+        ...readScope,
+    })
+        .strict(),
+    z.object({ action: z.literal("graphs"), ...readScope }).strict(),
+    z.object({ action: z.literal("publication"), ...readScope }).strict(),
     z
         .object({
         action: z.literal("ontology_search"),
@@ -375,11 +426,12 @@ export const inspectInputSchema = z.discriminatedUnion("action", [
 // The graph's RDF projection uses a fixed IRI scheme; teaching it here lets an
 // agent write a valid query on the first attempt instead of round-tripping
 // through the ontology to reverse-engineer term IRIs.
-export const SPARQL_IRI_GUIDE = 'IRI scheme: relations are <https://littlebigbrain.com/r/NAME> (NAME lowercased, e.g. writes_to; reverse a relation with the ^ path operator, no stored inverse triple). Types are <https://littlebigbrain.com/class/NAME> (lowercased), matched as `?x a <…/class/NAME>` with rdfs:subClassOf closure on by default. Property fields are <https://littlebigbrain.com/p/NAME> (lowercased). The local name is ALWAYS lowercase — an uppercase one (e.g. <…/r/FOR_CLIENT>) is a different, non-existent IRI that silently matches nothing; this tool auto-lowercases the local name of /r/, /class/, and /p/ IRIs for you and adds a `notes` entry when it does, so a stray uppercase still resolves. (Structured mode\'s `predicate` is case-insensitive on its own.) Entities are content-addressed <https://littlebigbrain.com/e/HASH> — never build an entity IRI from a name; anchor a named entity by its label instead: `?e <http://www.w3.org/2000/01/rdf-schema#label> "Acme"`. Discover the exact relation and type names with lbb_inspect action=ontology. SELECT and ASK only (CONSTRUCT/DESCRIBE are rejected).';
+export const SPARQL_IRI_GUIDE = 'IRI scheme: relations are <https://littlebigbrain.com/r/NAME> (NAME lowercased, e.g. writes_to; reverse a relation with the ^ path operator, no stored inverse triple). Types are <https://littlebigbrain.com/class/NAME> (lowercased), matched as `?x a <…/class/NAME>` with explicit entailment=subclass, rdfs, or owl for inference (default none). Property fields are <https://littlebigbrain.com/p/NAME> (lowercased). The local name is ALWAYS lowercase — an uppercase one (e.g. <…/r/FOR_CLIENT>) is a different, non-existent IRI that silently matches nothing; this tool auto-lowercases the local name of /r/, /class/, and /p/ IRIs for you and adds a `notes` entry when it does, so a stray uppercase still resolves. (Structured mode\'s `predicate` is case-insensitive on its own.) Entities are content-addressed <https://littlebigbrain.com/e/HASH> — never build an entity IRI from a name; anchor a named entity by its label instead: `?e <http://www.w3.org/2000/01/rdf-schema#label> "Acme"`. Discover the exact relation and type names with lbb_inspect action=ontology. SELECT and ASK only (CONSTRUCT/DESCRIBE are rejected).';
 export const queryInputSchema = z.discriminatedUnion("mode", [
     z
         .object({
         mode: z.literal("structured"),
+        ...queryConsistencySchema,
         body: jsonObjectSchema
             .optional()
             .describe('Structured SPARQL-subset request body. Shape: { patterns: [{ subject, predicate, object }], filters?, group_by?, group_keys?, aggregates?, having?, order_by?, select?, limit?, distinct? }. Each pattern term is { var: "x" } or a fixed { entity: { entity_type, name } }; `predicate` is a relation name and is case-insensitive here (FOR_CLIENT and for_client both resolve — unlike SPARQL text, which needs the lowercased IRI local name). ' +
@@ -390,11 +442,11 @@ export const queryInputSchema = z.discriminatedUnion("mode", [
             '{ "value": <typed> } — and <typed> is exactly one wrapper: { "str": "…" }, { "i64": 5 }, { "f64": 0.9 }, { "bool": true }, { "date_time": "2026-01-01" } (RFC3339), or { "entity": { "entity_type": "T", "name": "N" } }. ' +
             'Complete runnable example — deals whose amount ≥ 1000000: { "patterns": [{ "subject": { "var": "d" }, "predicate": "for_client", "object": { "var": "c" } }], "filters": [{ "compare": { "op": "ge", "left": { "property": { "var": "d", "field": "amount" } }, "right": { "value": { "f64": 1000000 } } } }] }. ' +
             "Comparisons use the field's real declared type (numbers as numbers, datetimes as instants), so they run server-side. " +
-            'GROUP BY supports both entity-identity keys (group_by: ["s"]) and typed scalar keys via group_keys: a property value ({ property: { var, field, as } }) or a calendar bucket of a datetime property ({ date_bucket: { var, field, granularity: year|month|week|day|hour, as } }). Scalar keys come back per group under value_keys[as] — so a per-area breakdown or a commits-per-month time series is one server-side query, no client-side bucketing. Worked example -- commits per area per month in one query: { "patterns": [{ "subject": { "var": "c" }, "predicate": "committed_to", "object": { "var": "repo" } }], "group_keys": [{ "date_bucket": { "var": "c", "field": "committed_at", "granularity": "month", "as": "m" } }, { "property": { "var": "c", "field": "area", "as": "area" } }], "aggregates": [{ "func": "count", "as": "n" }], "order_by": [{ "var": "m" }] } -- area and committed_at are typed entity attributes (set via entity_properties; readable flat under attributes, never a nested metadata blob), and each group returns value_keys.m + value_keys.area + aggregates.n. `having: [...]` takes the same filter shape over the aggregated groups (e.g. { "compare": { "op": "gt", "left": { "var": "n" }, "right": { "value": { "i64": 10 } } } }). A `combinators` key (UNION/OPTIONAL/MINUS/EXISTS) is rejected here; express those with SPARQL text under mode=sparql. Cheap aggregate count: pair an equality having (e.g. { "compare": { "op": "eq", "left": { "var": "n" }, "right": { "value": { "i64": 4 } } } }) with row_limit: 1 -- the response row_page.total reports how many groups match without materializing them all, so you read the count off row_page.total instead of paging every matching row. For snapshot pinning prefer the top-level `as_of` / `as_of_commit_seq` arguments below; a bare `as_of` key inside the body is rejected (the body\'s valid-time field is `as_of_valid_time`).'),
+            'GROUP BY supports both entity-identity keys (group_by: ["s"]) and typed scalar keys via group_keys: a property value ({ property: { var, field, as } }) or a calendar bucket of a datetime property ({ date_bucket: { var, field, granularity: year|month|week|day|hour, as } }). Scalar keys come back per group under value_keys[as] — so a per-area breakdown or a commits-per-month time series is one server-side query, no client-side bucketing. Worked example -- commits per area per month in one query: { "patterns": [{ "subject": { "var": "c" }, "predicate": "committed_to", "object": { "var": "repo" } }], "group_keys": [{ "date_bucket": { "var": "c", "field": "committed_at", "granularity": "month", "as": "m" } }, { "property": { "var": "c", "field": "area", "as": "area" } }], "aggregates": [{ "func": "count", "as": "n" }], "order_by": [{ "var": "m" }] } -- area and committed_at are typed entity attributes (set via entity_properties; readable flat under attributes, never a nested metadata blob), and each group returns value_keys.m + value_keys.area + aggregates.n. `having: [...]` takes the same filter shape over the aggregated groups (e.g. { "compare": { "op": "gt", "left": { "var": "n" }, "right": { "value": { "i64": 10 } } } }). A `combinators` key (UNION/OPTIONAL/MINUS/EXISTS) is rejected here; express those with SPARQL text under mode=sparql. Cheap aggregate count: pair an equality having (e.g. { "compare": { "op": "eq", "left": { "var": "n" }, "right": { "value": { "i64": 4 } } } }) with row_limit: 1 -- the response row_page.total reports how many groups match without materializing them all, so you read the count off row_page.total instead of paging every matching row. For snapshot pinning use the top-level `as_of_commit_seq` argument or the same body field. Valid-time `as_of` and `as_of_valid_time` selectors are unsupported and rejected before HTTP.'),
         as_of: z
             .string()
             .optional()
-            .describe("Snapshot pin (valid-time, RFC3339): evaluate the body as of this instant. Folded into the request's `as_of_valid_time`. Top-level here is the supported spelling — a bare `as_of` inside the body is rejected, since the server silently ignores it."),
+            .describe("Unsupported in structured and SPARQL text modes; use as_of_commit_seq for a retained commit snapshot."),
         as_of_commit_seq: z
             .number()
             .int()
@@ -409,11 +461,20 @@ export const queryInputSchema = z.discriminatedUnion("mode", [
     z
         .object({
         mode: z.literal("sparql"),
+        ...queryConsistencySchema,
+        entailment: z
+            .enum(["none", "subclass", "rdfs", "owl"])
+            .optional()
+            .describe("Reasoning over the pinned RDF generation. Defaults to none. owl includes RDFS, inverse relationships and the supported OWL profile."),
         query: z
             .string()
             .optional()
-            .describe(`SPARQL 1.1 query text (SELECT or ASK). ${SPARQL_IRI_GUIDE} Example: SELECT ?service ?db WHERE { ?service <https://littlebigbrain.com/r/writes_to> ?db } LIMIT 10`),
-        as_of: z.string().optional(),
+            .describe(`SPARQL 1.1 query text (SELECT or ASK). Valid-time as_of is unsupported; use as_of_commit_seq for a retained commit snapshot. ${SPARQL_IRI_GUIDE} Example: SELECT ?service ?db WHERE { ?service <https://littlebigbrain.com/r/writes_to> ?db } LIMIT 10`),
+        // Kept for an actionable error when an older connector sends this field.
+        as_of: z
+            .string()
+            .optional()
+            .describe("Unsupported in SPARQL text mode; use as_of_commit_seq."),
         as_of_commit_seq: z
             .number()
             .int()
@@ -444,10 +505,14 @@ export const configureInputSchema = z.discriminatedUnion("action", [
     z
         .object({
         action: z.literal("define_ontology"),
+        dry_run: z
+            .boolean()
+            .optional()
+            .describe("Preview the exact definition without creating a graph or writing metadata."),
         graph: z.string().describe("Graph to create or redefine"),
         branch: graphScope.branch,
-        entity_types: jsonObjectArraySchema.optional(),
-        relations: jsonObjectArraySchema.optional(),
+        entity_types: z.array(z.union([z.string(), jsonObjectSchema])).optional(),
+        relations: z.array(z.union([z.string(), jsonObjectSchema])).optional(),
         source: z.string().optional(),
         format: ontologyFormatSchema.optional(),
         merge_default: z.boolean().optional(),
@@ -456,6 +521,10 @@ export const configureInputSchema = z.discriminatedUnion("action", [
     z
         .object({
         action: z.literal("publish_schema"),
+        dry_run: z
+            .boolean()
+            .optional()
+            .describe("Parse and check schema compatibility without activation or validation jobs. Does not audit all data."),
         ontology: ontologySourceSchema.optional(),
         shapes: shapeSourceSchema.optional(),
         desired_mode: schemaModeSchema.optional(),
@@ -466,6 +535,10 @@ export const configureInputSchema = z.discriminatedUnion("action", [
     z
         .object({
         action: z.literal("evolve_ontology"),
+        dry_run: z
+            .boolean()
+            .optional()
+            .describe("Preview ordered changes and current-data conflicts without writing metadata."),
         ops: z
             .array(ontologyEvolveOpSchema)
             .min(1)
@@ -473,7 +546,7 @@ export const configureInputSchema = z.discriminatedUnion("action", [
         allow_data_conflicts: z
             .boolean()
             .optional()
-            .describe("Apply subtractive ops (narrow/remove) even when current data conflicts; affected records are kept and begin to warn. Default false rejects a conflicting subtractive request and reports the conflicts."),
+            .describe("Deprecated compatibility flag; does not bypass conflicts. Preview subtractive changes with dry_run=true, repair the reported conflicts, then apply."),
         ...graphScope,
     })
         .strict(),

package/dist/tool-runtime.js

@@ -666,7 +666,20 @@ export function buildPossibilities(relations) {
     return possibilities;
 }
 export async function guide(scopedClient) {
-    const s = (await scopedClient.summary());
+    let summary;
+    try {
+        summary = await scopedClient.summary();
+    }
+    catch (error) {
+        if (!(error instanceof LbbError) || error.code !== "graph_not_found")
+            throw error;
+        return {
+            graph_exists: false,
+            graphs: await scopedClient.listGraphs(),
+            how_to: "Choose an existing graph explicitly, or bootstrap the requested graph. For native named entities use lbb_configure action=define_ontology with dry_run=true, inspect warnings, then publish and lbb_commit. For RDF/OWL use lbb_rdf action=import, then SPARQL INSERT DATA for further writes; an RDF-native graph refuses property-graph commits. Native schema definition alone does not store an OWL document as graph facts.",
+        };
+    }
+    const s = summary;
     const entityTypes = [...(s.entity_types ?? [])].sort((a, b) => b.count - a.count);
     const relations = [...(s.relations ?? [])].sort((a, b) => b.count - a.count);
     return {
@@ -684,7 +697,7 @@ export async function guide(scopedClient) {
             ontology_decorations: "lbb_inspect action=ontology returns a decoration_status catalog: each ontology decoration is enforced (the engine acts on it — state_reducer, value_type, super_types, properties, supernode_policy; cardinality, which GET /v1/ontology/conformance audits as sh:maxCount; and inverse_name/symmetric, which SPARQL resolves as relation aliases — an inverse name is queryable directly (lowered to ^forward, no stored inverse triple) and a symmetric relation matches both directions), advisory (transitive, temporal_semantics, required), or reserved (stored but unwired — default_weight, resolvable, alias/embedding_fields). You can also always reverse any relation in SPARQL by flipping the triple pattern or using ^forward. Each relation_def also carries edge_count — the number of current edges of that relation in this branch's snapshot — so you can tell at a glance which declared relations are actually populated (edge_count 0 = declared but unused) without a separate summary call.",
             query: "Use lbb_query for structured SPARQL-subset bodies, SPARQL text, and canned analysis. SPARQL is the only query surface. A mode=structured body is { patterns: [{ subject, predicate, object }], filters?, group_by?, group_keys?, aggregates?, having? }; a pattern `predicate` is a relation name and is case-insensitive. mode=structured GROUP BY is not limited to entity identity: group_keys can key on a typed scalar property or calendar bucket. In SPARQL text, relations are <https://littlebigbrain.com/r/NAME> and types <https://littlebigbrain.com/class/NAME>. Each query pins one published watermark.",
             write: "Use lbb_commit for fact writes and relevance feedback; omitted idempotency keys are content-derived so retries dedupe. Set typed scalar attributes via entity_properties once the field is registered (add it on a live graph with lbb_configure evolve_ontology add_property). For feedback, use mode=search_feedback rather than fact triplets.",
-            configure: "Use lbb_configure to define a new ontology, evolve an existing one in place, or atomically publish ontology/SHACL bundle metadata. Conformance validation runs durably after publication.",
+            configure: "Use lbb_configure dry_run=true to preview definitions, ordered evolution (including add_super_types), or SHACL publication. Definition extracts native metadata; use lbb_rdf import to store full RDF/OWL and lbb_rdf update for additive INSERT DATA; RDF deletion/replacement is unsupported. Follow every lbb_inspect ontology/schema next cursor; fields are complete and metadata changes invalidate the cursor. Publication is asynchronous: inspect action=publication, then verify asserted axioms AND expected answers with lbb_query entailment=owl. SHACL conformance alone does not prove ontology completeness. First identify the questions the model must answer, reusable vocabularies, dates, evidence, and distinctions such as hypothesis versus confirmed fact.",
         },
         possibilities: buildPossibilities(relations),
         how_to: "Ground with lbb_inspect action=guide, query with lbb_query (structured bodies or SPARQL text), rate useful/partial/bad result sets when you have a judgment, inspect exact entities/schema with lbb_inspect, then write graph facts with lbb_commit or configuration with lbb_configure only when intended.",
@@ -780,6 +793,7 @@ export function ontologyDefineBody(p) {
             source: p.source,
             format: p.format ?? "auto",
             merge_default: p.merge_default ?? false,
+            ...(p.dry_run !== undefined ? { dry_run: p.dry_run } : {}),
         };
     }
     if (!p.entity_types?.length || !p.relations?.length) {
@@ -792,6 +806,7 @@ export function ontologyDefineBody(p) {
         }),
         format: "spec",
         merge_default: p.merge_default ?? false,
+        ...(p.dry_run !== undefined ? { dry_run: p.dry_run } : {}),
     };
 }
 /**

package/dist/tools.js

@@ -1,9 +1,12 @@
 import { z } from "zod";
+import { metadataPage } from "./metadata-pages.js";
+import { registerRdfTool } from "./rdf-tool.js";
 import { IDEMPOTENT_WRITE, MUTATING, READ_ONLY, configureInputSchema, configureWireSchema, detailSchema, graphScope, inspectInputSchema, inspectWireSchema, jsonObjectSchema, queryInputSchema, queryWireSchema, searchFeedbackSchema, } from "./tool-contracts.js";
 import { analyze, assertCursorScope, contentHashKey, decodeQueryCursor, effectiveRowLimit, enrichError, errorResult, guide, normalizeDetail, normalizeLbbIris, ontologyDefineBody, queryCommitPin, queryEnvelope, requireString, rowPageFrom, rowPageNext, run, scoped, stableJson, toolResult, } from "./tool-runtime.js";
 export function registerLbbTools(server, client) {
+    registerRdfTool(server, client);
     server.registerTool("lbb_inspect", {
-        description: "Read graph context and exact graph facts. Actions: guide, ontology, ontology_conformance, schema, ontology_search, metadata, entity, state, history, transitions, why. schema reads active ontology/SHACL bundle metadata without running validation. ontology_conformance serves the durable report referenced by the pinned published root. entity returns one node's metadata, scalar attributes, bounded Base-backed edge neighborhood, history, and observations. Use lbb_query with SPARQL property paths for precise path selection.",
+        description: "Read graph context and exact graph facts. Actions: guide, graphs, publication, ontology, ontology_conformance, schema, ontology_search, metadata, entity, state, history, transitions, why. graphs works before bootstrap; publication reports whether writes are queryable. ontology and schema return complete entries with page_size, section and cursor; follow next until absent. schema reads active native ontology/SHACL metadata without running validation. Query asserted RDF/OWL axioms separately with lbb_query. ontology_conformance serves the durable report referenced by the pinned published root. entity returns one node's metadata, scalar attributes, bounded Base-backed edge neighborhood, history, and observations. Use lbb_query with SPARQL property paths for precise path selection.",
         inputSchema: inspectWireSchema,
         annotations: READ_ONLY,
     }, (rawArgs) => {
@@ -11,19 +14,22 @@ export function registerLbbTools(server, client) {
         if (!parsed.success)
             return errorResult(parsed.error);
         const args = parsed.data;
+        if (args.action === "ontology" || args.action === "schema") {
+            return metadataPage(client, args)
+                .then(toolResult)
+                .catch(async (error) => errorResult(await enrichError(client, error)));
+        }
         return run(client, `lbb_inspect.${args.action}`, args.detail, () => {
             const target = scoped(client, args.graph, args.branch);
             switch (args.action) {
                 case "guide":
                     return guide(target);
-                case "ontology":
-                    // Request per-relation edge counts so the listing flags which of the
-                    // declared relations are actually populated (edge_count: 0 = unused).
-                    return target.ontologyView({ counts: true });
+                case "graphs":
+                    return target.listGraphs();
+                case "publication":
+                    return target.publicationStatus();
                 case "ontology_conformance":
                     return target.ontologyConformance();
-                case "schema":
-                    return target.schema.view();
                 case "ontology_search":
                     return target.ontologySearch({
                         query: args.query,
@@ -115,6 +121,19 @@ export function registerLbbTools(server, client) {
                     const branch = cursor?.branch ?? args.branch;
                     const offset = cursor?.offset ?? 0;
                     const target = scoped(client, graph, branch);
+                    for (const key of [
+                        "entailment",
+                        "consistency",
+                        "min_indexed_seq",
+                    ]) {
+                        if (cursor &&
+                            args[key] !== undefined &&
+                            args[key] !== cursor[key]) {
+                            throw new Error(`cursor ${key} does not match the supplied ${key}`);
+                        }
+                    }
+                    const consistency = cursor?.consistency ?? args.consistency;
+                    const minIndexedSeq = cursor?.min_indexed_seq ?? args.min_indexed_seq;
                     if (args.mode === "structured") {
                         const body = (cursor?.body ?? args.body);
                         if (body === undefined)
@@ -124,38 +143,43 @@ export function registerLbbTools(server, client) {
                             stableJson(args.body) !== stableJson(cursor.body)) {
                             throw new Error("cursor body does not match the supplied body argument");
                         }
-                        // The body's valid-time field is `as_of_valid_time`; the server
-                        // ignores a bare `as_of` key, so a naive caller would chart
-                        // head-snapshot data and never know. Turn that silent no-op into a
-                        // clear error pointing at the right spelling.
-                        if (body.as_of !== undefined) {
-                            throw new Error("the structured body has an `as_of` key, which the server ignores — use the top-level `as_of` argument (valid-time, RFC3339) or rename it to `as_of_valid_time` inside the body");
+                        if (args.as_of !== undefined ||
+                            cursor?.as_of !== undefined ||
+                            body.as_of !== undefined ||
+                            body.as_of_valid_time !== undefined) {
+                            throw new Error("structured SPARQL valid-time selectors are not supported; use as_of_commit_seq for a retained commit snapshot, or start a new query without the valid-time selector");
                         }
-                        if (cursor &&
-                            args.as_of !== undefined &&
-                            args.as_of !== cursor.as_of) {
-                            throw new Error("cursor as_of does not match the supplied as_of argument");
+                        for (const key of ["consistency", "min_indexed_seq"]) {
+                            const requested = key === "consistency" ? consistency : minIndexedSeq;
+                            if (requested !== undefined &&
+                                body[key] !== undefined &&
+                                requested !== body[key])
+                                throw new Error(`body ${key} conflicts with the query's ${key}`);
+                        }
+                        // Resolve the top-level or body commit pin once and retain it
+                        // across cursor pages. The API validates its exact RDF lineage.
+                        if (body.as_of_commit_seq !== undefined &&
+                            body.as_of_commit_seq !== null &&
+                            (typeof body.as_of_commit_seq !== "number" ||
+                                !Number.isSafeInteger(body.as_of_commit_seq) ||
+                                body.as_of_commit_seq < 0)) {
+                            throw new Error("body as_of_commit_seq must be a nonnegative safe integer");
                         }
-                        // Commit-seq pin: top-level arg, else the body field, pinned for
-                        // continuation. Valid-time pin: cursor, else top-level arg, else the
-                        // body's `as_of_valid_time`. Both are resolved here and set
-                        // explicitly so the request never depends on the body's spelling.
                         const requestedCommitSeq = args.as_of_commit_seq ??
                             (typeof body.as_of_commit_seq === "number"
                                 ? body.as_of_commit_seq
                                 : undefined);
+                        if (cursor &&
+                            args.as_of_commit_seq !== undefined &&
+                            args.as_of_commit_seq !== cursor.as_of_commit_seq) {
+                            throw new Error("cursor as_of_commit_seq does not match the supplied as_of_commit_seq argument");
+                        }
                         const asOfCommitSeq = await queryCommitPin(target, requestedCommitSeq, cursor);
-                        const asOfValidTime = cursor?.as_of ??
-                            args.as_of ??
-                            (typeof body.as_of_valid_time === "string"
-                                ? body.as_of_valid_time
-                                : undefined);
                         const request = {
                             ...body,
                             limit: rowLimit,
                             offset,
                             as_of_commit_seq: asOfCommitSeq,
-                            as_of_valid_time: asOfValidTime ?? null,
                         };
                         // The analytics route is gone; structured bodies run only on the
                         // SPARQL-select path, which rejects unknown fields. Name the
@@ -165,7 +189,10 @@ export function registerLbbTools(server, client) {
                             request.combinators.length > 0) {
                             throw new Error("`combinators` (UNION/OPTIONAL/MINUS/EXISTS) is no longer accepted by structured mode; the analytics route was removed. Express the same query as SPARQL text with mode=sparql.");
                         }
-                        const response = await target.sparql(request);
+                        const response = await target.sparql(request, {
+                            consistency,
+                            minIndexedSeq,
+                        });
                         const rowPage = rowPageFrom(response);
                         const cursorBase = {
                             v: 1,
@@ -175,7 +202,8 @@ export function registerLbbTools(server, client) {
                             detail,
                             row_limit: rowLimit,
                             body,
-                            as_of: asOfValidTime,
+                            consistency,
+                            min_indexed_seq: minIndexedSeq,
                             as_of_commit_seq: asOfCommitSeq,
                         };
                         const next = rowPageNext(cursorBase, rowPage);
@@ -193,25 +221,23 @@ export function registerLbbTools(server, client) {
                         normalizeLbbIris(args.query).query !== cursor.query) {
                         throw new Error("cursor query does not match the supplied query argument");
                     }
-                    if (cursor &&
-                        args.as_of !== undefined &&
-                        args.as_of !== cursor.as_of) {
-                        throw new Error("cursor as_of does not match the supplied as_of argument");
+                    if (args.as_of !== undefined || cursor?.as_of !== undefined) {
+                        throw new Error("SPARQL text valid-time as_of is not supported; use as_of_commit_seq for a retained commit snapshot, or start a new query without as_of");
                     }
                     if (cursor &&
                         args.as_of_commit_seq !== undefined &&
                         args.as_of_commit_seq !== cursor.as_of_commit_seq) {
                         throw new Error("cursor as_of_commit_seq does not match the supplied as_of_commit_seq argument");
                     }
-                    const asOf = cursor?.as_of ?? args.as_of;
                     const asOfCommitSeq = await queryCommitPin(target, args.as_of_commit_seq, cursor);
+                    const entailment = cursor?.entailment ?? args.entailment ?? "none";
                     const response = await target.sparqlText({
                         query,
-                        as_of_valid_time: asOf ?? null,
+                        entailment,
                         as_of_commit_seq: asOfCommitSeq ?? null,
                         limit: rowLimit,
                         offset,
-                    });
+                    }, { consistency, minIndexedSeq });
                     const data = JSON.parse(response.results);
                     const rowPage = rowPageFrom(response);
                     const cursorBase = {
@@ -222,7 +248,9 @@ export function registerLbbTools(server, client) {
                         detail,
                         row_limit: rowLimit,
                         query,
-                        as_of: asOf,
+                        entailment,
+                        consistency,
+                        min_indexed_seq: minIndexedSeq,
                         as_of_commit_seq: asOfCommitSeq,
                     };
                     const next = rowPageNext(cursorBase, rowPage);
@@ -322,6 +350,10 @@ export function registerLbbTools(server, client) {
                 "Register a field first with lbb_configure evolve_ontology add_property; " +
                 "the commit response echoes written_properties so you can confirm what landed."),
             search_feedback: searchFeedbackSchema.optional(),
+            dry_run: z
+                .boolean()
+                .optional()
+                .describe("Validate a facts commit and return its structured SHACL report without writing. Only supported for mode=facts."),
             observed_at: z
                 .string()
                 .optional()
@@ -345,13 +377,15 @@ export function registerLbbTools(server, client) {
             ...graphScope,
         },
         annotations: IDEMPOTENT_WRITE,
-    }, ({ idempotency_key, mode, triplets, entity_embeddings, entity_properties, search_feedback, observed_at, edge_idempotency, retract_edges, retract_entities, graph, branch, }) => run(client, "lbb_commit", "standard", () => {
+    }, ({ idempotency_key, mode, triplets, entity_embeddings, entity_properties, search_feedback, dry_run, observed_at, edge_idempotency, retract_edges, retract_entities, graph, branch, }) => run(client, "lbb_commit", "standard", () => {
         const commitMode = mode ??
             (search_feedback
                 ? "search_feedback"
                 : retract_edges || retract_entities
                     ? "retract"
                     : "facts");
+        if (dry_run && commitMode !== "facts")
+            throw new Error("dry_run is supported only for lbb_commit mode=facts");
         if (commitMode === "retract") {
             const edges = retract_edges ?? [];
             const entities = retract_entities ?? [];
@@ -387,12 +421,14 @@ export function registerLbbTools(server, client) {
             throw new Error("lbb_commit requires at least one triplet, entity embedding, or entity property");
         }
         const key = idempotency_key ?? contentHashKey({ graph, branch }, payload);
+        if (dry_run)
+            return scoped(client, graph, branch).commitDryRun(payload);
         return scoped(client, graph, branch).commit(payload, {
             idempotencyKey: key,
         });
     }));
     server.registerTool("lbb_configure", {
-        description: "Mutate stored graph configuration. Actions: define_ontology, evolve_ontology, and publish_schema. Schema publication atomically activates metadata and enqueues durable conformance; it never validates the whole graph in the request.",
+        description: "Manage native schema metadata. Actions: define_ontology (friendly spec with super_types), evolve_ontology (ordered edits including add_super_types), publish_schema (SHACL activation). All support dry_run previews. Definition/import here extracts native metadata; it does NOT store the complete RDF/OWL document as queryable graph facts. Use lbb_rdf import for full OWL and lbb_rdf update for additive INSERT DATA revisions; RDF deletions are unsupported. Publish_schema accepts unchanged ontology plus shapes; use define/evolve for native ontology changes. Publication enqueues durable conformance; a preview does not validate the whole graph.",
         inputSchema: configureWireSchema,
         annotations: MUTATING,
     }, (rawArgs) => {
@@ -410,23 +446,24 @@ export function registerLbbTools(server, client) {
                     source: args.source,
                     format: args.format,
                     merge_default: args.merge_default,
+                    dry_run: args.dry_run,
                 }));
             }
             if (args.action === "evolve_ontology") {
-                return scoped(client, args.graph, args.branch).evolveOntology({
+                return scoped(client, args.graph, args.branch).ontology.evolve({
                     ops: args.ops,
                     allow_data_conflicts: args.allow_data_conflicts ?? false,
-                });
+                }, { dryRun: args.dry_run });
             }
-            if (args.ontology === undefined && args.shapes === undefined) {
-                throw new Error("publish_schema requires an ontology or shapes source");
+            if (args.shapes === undefined) {
+                throw new Error("publish_schema requires a SHACL shapes source; use define_ontology or evolve_ontology for native metadata changes");
             }
             return scoped(client, args.graph, args.branch).schema.publish({
                 ontology: args.ontology,
                 shapes: args.shapes,
                 desired_mode: args.desired_mode,
                 confirm_restrictive: args.confirm_restrictive,
-            });
+            }, { dryRun: args.dry_run });
         });
     });
     server.registerTool("lbb_branch", {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@littlebigbrain/mcp",
-  "version": "0.4.3",
+  "version": "0.5.0",
   "description": "MCP server for little big brain — graph and hybrid search tools for agents",
   "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.13.0",
+    "@littlebigbrain/client": "^0.13.1",
     "@modelcontextprotocol/sdk": "^1",
     "zod": "^3"
   },