@littlebigbrain/client 0.12.0 → 0.13.0

package/README.md

@@ -68,19 +68,19 @@ const accepted = await lbb.submitImport(records(), {
 });
 const completed = await lbb.waitForImportJob(accepted.job_id);
 console.log(completed.state, completed.committed_commit_seq);
-if (completed.committed_commit_seq != null) {
-  await lbb.waitForIndexLineage(completed.committed_commit_seq);
-}
 ```
 
 `records()` may be an iterable or async iterable. Success means every grouped
-commit is durable and final publication was enqueued; it does not mean indexes
-have already reached `committed_commit_seq`. Wait once after the final commit,
-not after each source row or chunk. The lineage waiter polls normal
-`index_caught_up=false` metadata until its own deadline, including on an
-RDF-only deployment. An empty iterable is rejected locally before an import
+commit is durable and immediately queryable by a strong SPARQL read. The same
+commits advance the graph's coalesced RDF reconciliation fence; waiting for base
+compaction is optional. An empty iterable is rejected locally before an import
 POST is sent.
 
+For several RDF documents, `facts.importRdfMany(...)` automatically defers
+intermediate reconciliation and triggers it on the last document. Call
+`graph.waitForPublished(result.finalSequence)` only when the caller needs the
+immutable base itself to cover the import; strong reads need no waiter.
+
 **Time-travel read.** Pin a SPARQL read to a past instant — results reflect the graph as it was then:
 
 ```ts
@@ -101,8 +101,10 @@ const { rows } = await lbb.sparqlRows({
 ## Errors & retries
 
 Methods return parsed JSON and throw `LbbError` (with `status`, `code`, `message`, `param`, `requestId`, `docUrl`) on any non-2xx response. Safe reads and idempotency-keyed writes retry `429`/`5xx` and network failures with full-jitter backoff, bounded by a retry budget (`retryBudgetMs`, default 60s) rather than a fixed count, and honor `Retry-After` — a terminal error the server marks non-retryable surfaces immediately. Use `rawRequest()` for response headers, request id, and retry/timing metadata.
-`waitForIndexLineage(...)` is a separate deadline-bounded poller, so the generic
-request retry-count cap cannot end publication waiting early.
+`waitForPublished(...)` is an optional, deadline-bounded maintenance poller for
+workflows that want the immutable RDF base itself to cover a commit. Strong
+SPARQL does not need it: acknowledged commits are queryable immediately from
+the branch head's base-plus-delta lineage.
 
 ## More
 

package/dist/client.d.ts

@@ -1,20 +1,11 @@
-import type { DurableImportSource, ImportLine, LbbClientOptions, ListResponse, RawLbbResponse, ReadConsistencyOptions, RdfImportOptions, Schemas, SearchConsistency, SparqlResults } from "./types.js";
+import type { DurableImportSource, ImportLine, LbbClientOptions, ListResponse, RawLbbResponse, ReadConsistencyOptions, RdfImportDocument, RdfImportManyResult, RdfImportOptions, Schemas, SearchConsistency, SparqlResults } from "./types.js";
 import { type CallOptions, type RequestOptions } from "./transport.js";
 import { EntityNamespace, GraphNamespace, OntologyNamespace, QueryNamespace, SchemaNamespace, SearchNamespace } from "./namespaces.js";
 export { parseSparqlResults } from "./types.js";
-export type { AttributeFilter, AttributeFilterOp, AttributeFilterValue, EntityAttributeFilterOptions, EntityPropertiesLine, DurableImportLine, DurableImportSource, FetchLike, FlatProperties, ImportLine, LbbClientOptions, LbbRequestEvent, LbbResponseEvent, LbbRetryEvent, LbbErrorPayload, ListResponse, RawLbbResponse, ReadConsistencyOptions, RdfImportOptions, Schemas, SearchConsistency, SparqlResults, SparqlResultsJson, SparqlTerm, CommitRequest, CommitResponse, Entity, EntitySelector, GraphMetadata, GraphSummary, SchemaView, Snapshot, } from "./types.js";
+export type { AttributeFilter, AttributeFilterOp, AttributeFilterValue, EntityAttributeFilterOptions, EntityPropertiesLine, DurableImportLine, DurableImportSource, FetchLike, FlatProperties, ImportLine, LbbClientOptions, LbbRequestEvent, LbbResponseEvent, LbbRetryEvent, LbbErrorPayload, ListResponse, RawLbbResponse, ReadConsistencyOptions, RdfImportDocument, RdfImportManyResult, RdfImportOptions, Schemas, SearchConsistency, SparqlResults, SparqlResultsJson, SparqlTerm, CommitRequest, CommitResponse, Entity, EntitySelector, GraphMetadata, GraphSummary, SchemaView, Snapshot, } from "./types.js";
 export { LbbCapabilityError, LbbError } from "./transport.js";
 export type { CallOptions, Query, QueryValue, RequestOptions, } from "./transport.js";
 export { EntityNamespace, FactsNamespace, GraphNamespace, OntologyNamespace, QueryNamespace, SchemaNamespace, SearchNamespace, } from "./namespaces.js";
-export interface IndexLineageObservation {
-    metadata: Schemas["GraphMetadataResponse"];
-    lineage: Schemas["IndexLineage"];
-    buildCommit?: string;
-    replica?: string;
-    requestId?: string;
-    attempts: number;
-    elapsedMs: number;
-}
 /**
  * A typed HTTP client for a little big brain graph server. One instance is scoped to a
  * single graph/branch; construct another for a different scope. All methods
@@ -137,6 +128,8 @@ export declare class LbbClient {
      * properties on the subject Resource.
      */
     importRdf(rdf: string, opts?: RdfImportOptions): Promise<Schemas["GraphRdfImportResponse"]>;
+    /** Import several RDF documents as truth-only chunks, then advance one final publication fence. */
+    importRdfMany(documents: readonly RdfImportDocument[], opts?: RdfImportOptions): Promise<RdfImportManyResult>;
     /**
      * Retract specific edges and/or every edge touching given entities. Appends
      * superseding retract events rather than deleting — history stays visible in an
@@ -405,7 +398,7 @@ export declare class LbbClient {
      * `groups[].keys`.
      */
     sparql(body: Schemas["SparqlSelectRequest"], opts?: ReadConsistencyOptions): Promise<Schemas["SparqlSelectResponse"]>;
-    /** SPARQL 1.1 query from text (SELECT/ASK) over the live graph; `results` is SPARQL 1.1 Query Results JSON. The text dialect carries `consistency`/`min_indexed_seq` on the URL. */
+    /** SPARQL 1.1 query from text (SELECT/ASK) over the live graph; `results` is SPARQL 1.1 Query Results JSON. The text dialect carries `consistency`/`min_indexed_seq` on the URL; a floor with no explicit consistency implies a strong base-plus-delta read. */
     sparqlText(body: Schemas["SparqlTextRequest"], opts?: ReadConsistencyOptions): Promise<Schemas["SparqlTextResponse"]>;
     /**
      * Run a SPARQL 1.1 text query and return parsed results — the ergonomic
@@ -468,21 +461,25 @@ export declare class LbbClient {
     metadata(opts?: {
         includeIndexes?: boolean;
     }): Promise<Schemas["GraphMetadataResponse"]>;
-    /**
-     * Wait until one published generation covers `targetSeq`.
-     *
-     * The returned lineage may name absent BM25/ANN families on an RDF-only
-     * deployment; `metadata.index_caught_up` is the generation-level readiness
-     * signal used by bulk loaders.
-     */
-    waitForIndexLineage(targetSeq: number, opts?: {
+    /** Automatic publication lifecycle, available before the first generation exists. */
+    publicationStatus(): Promise<Schemas["PublicationStatusResponse"]>;
+    /** Wait until background reconciliation folds `targetSeq` into the RDF base. */
+    waitForPublished(targetSeq: number, opts?: {
         timeoutMs?: number;
         pollIntervalMs?: number;
-    }): Promise<IndexLineageObservation>;
+    }): Promise<Schemas["PublicationStatusResponse"]>;
     /** Graph counts and type/relation buckets. Carries `consistency`/`min_indexed_seq` on the URL. */
     summary(opts?: ReadConsistencyOptions): Promise<Schemas["GraphSummaryResponse"]>;
     /** Pinned published read root and its query/conformance lag against one coherent head. */
     readSnapshot(): Promise<Schemas["PublishedReadStatusResponse"]>;
+    /**
+     * Compact observed RDF schema attached to the immutable published base:
+     * class populations, resource- and literal-valued predicate counts, and
+     * bounded OWL/RDFS statements. `literal_predicate_counts` is `null` when
+     * the stored summary artifact predates the field; the next full summary
+     * rebuild fills it.
+     */
+    schemaSummary(): Promise<Schemas["RdfSchemaSummaryResponse"]>;
     /** List the graphs (and branches) under the scoped tenant. */
     listGraphs(): Promise<Schemas["GraphListResponse"]>;
 }

package/dist/client.js

@@ -1,6 +1,6 @@
 import { parseSparqlResults } from "./types.js";
 import { bodyMarksTerminal, errorCodeFromBody, fullJitterBackoffMs, parseLbbError, parseResponseJson, retryAllowed, retryableStatus, retryDelayMs, sleep, } from "./transport.js";
-import { LbbCapabilityError, LbbError } from "./transport.js";
+import { LbbCapabilityError } from "./transport.js";
 import { EntityNamespace, GraphNamespace, OntologyNamespace, QueryNamespace, SchemaNamespace, SearchNamespace, } from "./namespaces.js";
 export { parseSparqlResults } from "./types.js";
 export { LbbCapabilityError, LbbError } from "./transport.js";
@@ -563,6 +563,30 @@ export class LbbClient {
             idempotencyKey: opts.idempotencyKey ?? this.idempotencyKey("import-rdf"),
         });
     }
+    /** Import several RDF documents as truth-only chunks, then advance one final publication fence. */
+    async importRdfMany(documents, opts = {}) {
+        if (documents.length === 0) {
+            throw new RangeError("importRdfMany requires at least one document");
+        }
+        const imports = [];
+        for (const [index, document] of documents.entries()) {
+            const merged = { ...opts, ...document.options };
+            const idempotencyKey = merged.idempotencyKey
+                ? `${merged.idempotencyKey}:${index + 1}`
+                : undefined;
+            imports.push(await this.importRdf(document.rdf, {
+                ...merged,
+                idempotencyKey,
+                build: index === documents.length - 1,
+            }));
+        }
+        const final = imports[imports.length - 1];
+        return {
+            imports,
+            finalSequence: final?.committed_commit_seq ?? undefined,
+            publication: final?.published_generation,
+        };
+    }
     /**
      * Retract specific edges and/or every edge touching given entities. Appends
      * superseding retract events rather than deleting — history stays visible in an
@@ -940,7 +964,7 @@ export class LbbClient {
             body: this.mergeReadConsistency(body, opts),
         });
     }
-    /** SPARQL 1.1 query from text (SELECT/ASK) over the live graph; `results` is SPARQL 1.1 Query Results JSON. The text dialect carries `consistency`/`min_indexed_seq` on the URL. */
+    /** SPARQL 1.1 query from text (SELECT/ASK) over the live graph; `results` is SPARQL 1.1 Query Results JSON. The text dialect carries `consistency`/`min_indexed_seq` on the URL; a floor with no explicit consistency implies a strong base-plus-delta read. */
     sparqlText(body, opts) {
         return this.request("POST", "/v1/query/sparql-text", {
             body,
@@ -1038,68 +1062,38 @@ export class LbbClient {
             },
         });
     }
-    /**
-     * Wait until one published generation covers `targetSeq`.
-     *
-     * The returned lineage may name absent BM25/ANN families on an RDF-only
-     * deployment; `metadata.index_caught_up` is the generation-level readiness
-     * signal used by bulk loaders.
-     */
-    async waitForIndexLineage(targetSeq, opts = {}) {
-        const deadline = Date.now() + (opts.timeoutMs ?? 30_000);
+    /** Automatic publication lifecycle, available before the first generation exists. */
+    publicationStatus() {
+        return this.request("GET", "/v1/graph/publication-status");
+    }
+    /** Wait until background reconciliation folds `targetSeq` into the RDF base. */
+    async waitForPublished(targetSeq, opts = {}) {
+        if (!Number.isSafeInteger(targetSeq) || targetSeq < 0) {
+            throw new RangeError("targetSeq must be a non-negative safe integer");
+        }
+        const timeoutMs = opts.timeoutMs ?? 30_000;
+        const pollIntervalMs = opts.pollIntervalMs ?? 250;
+        if (!Number.isFinite(timeoutMs) || timeoutMs < 0) {
+            throw new RangeError("timeoutMs must be a non-negative number");
+        }
+        if (!Number.isFinite(pollIntervalMs) || pollIntervalMs < 0) {
+            throw new RangeError("pollIntervalMs must be a non-negative number");
+        }
+        const deadline = Date.now() + timeoutMs;
         let last;
         while (true) {
-            try {
-                // This method is already an explicit, deadline-bounded poller. Avoid
-                // nesting the generic request retry count inside it: publication may
-                // legitimately take longer than that secondary cap.
-                last = await this.rawRequest("GET", "/v1/graph/metadata", {
-                    maxRetries: 0,
-                });
+            last = await this.publicationStatus();
+            if (last.state === "blocked") {
+                throw new Error(`publication blocked at ${last.current_stage ?? "unknown stage"}: ${last.retry.message}`);
             }
-            catch (error) {
-                const retryableHttpError = error instanceof LbbError &&
-                    retryableStatus(error.status) &&
-                    error.retryable !== false;
-                const retryableTransportError = error instanceof Error && !(error instanceof LbbError);
-                if (!retryableHttpError && !retryableTransportError)
-                    throw error;
-                const now = Date.now();
-                if (now >= deadline) {
-                    throw new Error(`index lineage did not reach ${targetSeq} before timeout (last_error=${error.message})`, { cause: error });
-                }
-                const retryAfterMs = error instanceof LbbError
-                    ? (error.retryAfterSeconds ?? 0) * 1_000
-                    : 0;
-                await sleep(Math.min(Math.max(opts.pollIntervalMs ?? 250, retryAfterMs), deadline - now));
-                continue;
-            }
-            const lineage = last.data.index_lineage;
-            const servedAt = last.data.snapshot.served_at_seq;
-            if (lineage != null &&
-                servedAt != null &&
-                servedAt >= targetSeq &&
-                (last.data.index_caught_up === true ||
-                    (lineage.bm25_indexed_commit_seq != null &&
-                        lineage.bm25_indexed_commit_seq >= targetSeq &&
-                        lineage.ann_indexed_commit_seq != null &&
-                        lineage.ann_indexed_commit_seq >= targetSeq))) {
-                return {
-                    metadata: last.data,
-                    lineage,
-                    buildCommit: last.headers?.get("lbb-build-commit") ?? undefined,
-                    replica: last.headers?.get("lbb-replica") ?? undefined,
-                    requestId: last.requestId,
-                    attempts: last.attempts,
-                    elapsedMs: last.elapsedMs,
-                };
+            if (last.state === "current" && last.published_seq >= targetSeq) {
+                return last;
             }
-            if (Date.now() >= deadline) {
-                const build = last.headers?.get("lbb-build-commit") ?? "unknown";
-                const replica = last.headers?.get("lbb-replica") ?? "unknown";
-                throw new Error(`index lineage did not reach ${targetSeq} before timeout (build=${build}, replica=${replica}, last=${JSON.stringify(last.data.index_lineage)})`);
+            const now = Date.now();
+            if (now >= deadline) {
+                throw new Error(`publication did not reach ${targetSeq} before timeout (state=${last.state}, head=${last.head_seq}, target=${last.target_seq}, published=${last.published_seq}, stage=${last.current_stage ?? "unknown"})`);
             }
-            await sleep(opts.pollIntervalMs ?? 250);
+            await sleep(Math.min(Math.max(pollIntervalMs, last.retry.retry_after_ms), deadline - now));
         }
     }
     /** Graph counts and type/relation buckets. Carries `consistency`/`min_indexed_seq` on the URL. */
@@ -1112,6 +1106,16 @@ export class LbbClient {
     readSnapshot() {
         return this.request("GET", "/v1/graph/read-snapshot");
     }
+    /**
+     * Compact observed RDF schema attached to the immutable published base:
+     * class populations, resource- and literal-valued predicate counts, and
+     * bounded OWL/RDFS statements. `literal_predicate_counts` is `null` when
+     * the stored summary artifact predates the field; the next full summary
+     * rebuild fills it.
+     */
+    schemaSummary() {
+        return this.request("GET", "/v1/graph/schema-summary");
+    }
     /** List the graphs (and branches) under the scoped tenant. */
     listGraphs() {
         return this.request("GET", "/v1/graphs");

package/dist/namespaces.d.ts

@@ -1,6 +1,6 @@
 import type { LbbClient } from "./client.js";
 import type { CallOptions } from "./transport.js";
-import { type EntityAttributeFilterOptions, type ImportLine, type ReadConsistencyOptions, type RdfImportOptions, type Schemas } from "./types.js";
+import { type EntityAttributeFilterOptions, type ImportLine, type ReadConsistencyOptions, type RdfImportDocument, type RdfImportManyResult, type RdfImportOptions, type Schemas } from "./types.js";
 export declare class GraphNamespace {
     private readonly client;
     readonly facts: FactsNamespace;
@@ -11,6 +11,13 @@ export declare class GraphNamespace {
     readonly search: SearchNamespace;
     constructor(client: LbbClient);
     branch(name: string): GraphNamespace;
+    /** Publication lifecycle for this graph/branch, including pre-first-publish state. */
+    publicationStatus(): Promise<Schemas["PublicationStatusResponse"]>;
+    /** Wait until this graph/branch has an exact generation covering `targetSeq`. */
+    waitForPublished(targetSeq: number, opts?: {
+        timeoutMs?: number;
+        pollIntervalMs?: number;
+    }): Promise<Schemas["PublicationStatusResponse"]>;
     create(opts?: CallOptions): Promise<Schemas["CreateGraphResponse"]>;
     delete(opts: {
         confirm: string;
@@ -39,6 +46,8 @@ export declare class FactsNamespace {
      * predicates and literal term details are preserved as edge metadata.
      */
     importRdf(rdf: string, opts?: CallOptions & RdfImportOptions): Promise<Schemas["GraphRdfImportResponse"]>;
+    /** Import several RDF documents and enqueue publication only for the final commit. */
+    importRdfMany(documents: readonly RdfImportDocument[], opts?: RdfImportOptions): Promise<RdfImportManyResult>;
 }
 /**
  * Relevance-label storage. The query surfaces this namespace once fronted were

package/dist/namespaces.js

@@ -35,6 +35,14 @@ export class GraphNamespace {
     branch(name) {
         return new GraphNamespace(this.client.withScope({ branch: name }));
     }
+    /** Publication lifecycle for this graph/branch, including pre-first-publish state. */
+    publicationStatus() {
+        return this.client.publicationStatus();
+    }
+    /** Wait until this graph/branch has an exact generation covering `targetSeq`. */
+    waitForPublished(targetSeq, opts = {}) {
+        return this.client.waitForPublished(targetSeq, opts);
+    }
     create(opts = {}) {
         return this.client.request("POST", "/v1/graph/create", opts);
     }
@@ -120,6 +128,10 @@ export class FactsNamespace {
             },
         });
     }
+    /** Import several RDF documents and enqueue publication only for the final commit. */
+    importRdfMany(documents, opts = {}) {
+        return this.client.importRdfMany(documents, opts);
+    }
 }
 /**
  * Relevance-label storage. The query surfaces this namespace once fronted were

package/dist/schema.d.ts

@@ -381,6 +381,23 @@ export interface paths {
         patch?: never;
         trace?: never;
     };
+    "/v1/graph/publication-status": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        /** Automatic publication lifecycle and exact read watermarks */
+        get: operations["get_v1_graph_publication_status"];
+        put?: never;
+        post?: never;
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
     "/v1/graph/read-snapshot": {
         parameters: {
             query?: never;
@@ -432,6 +449,23 @@ export interface paths {
         patch?: never;
         trace?: never;
     };
+    "/v1/graph/schema-summary": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        /** Compact observed RDF schema attached to the immutable F3 base */
+        get: operations["get_v1_graph_schema_summary"];
+        put?: never;
+        post?: never;
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
     "/v1/graph/summary": {
         parameters: {
             query?: never;
@@ -798,7 +832,7 @@ export interface paths {
             path?: never;
             cookie?: never;
         };
-        /** Read the durable ontology-conformance report referenced by the published snapshot, including its validation watermark and ontology/shapes provenance */
+        /** Read the immutable branch-owned ontology-conformance sidecar selected by the F3 checksum and schema identity */
         get: operations["get_v1_ontology_conformance"];
         put?: never;
         post?: never;
@@ -817,7 +851,7 @@ export interface paths {
         };
         get?: never;
         put?: never;
-        /** Import a custom ontology and create the scoped graph head with it; fails if the graph already exists */
+        /** Define or additively evolve a graph ontology, or preview the exact result without mutation */
         post: operations["post_v1_ontology_define"];
         delete?: never;
         options?: never;
@@ -1325,8 +1359,25 @@ export interface components {
             /** @description Whether the relation is transitive (default false). */
             transitive?: boolean;
         };
+        /**
+         * @description Add direct parent classes to an existing entity type. All named classes
+         *     must already exist, or be declared earlier in the same request with
+         *     `add_entity_type`. Existing links are skipped, so the op is idempotent.
+         *     Removing a parent is not additive and requires an explicit migration.
+         */
+        AddSuperTypesOp: {
+            /** @description Entity type whose direct parents should grow. */
+            entity_type: string;
+            /**
+             * @description discriminator enum property added by openapi-typescript
+             * @enum {string}
+             */
+            op: "add_super_types";
+            /** @description Direct parent entity-type names to add. */
+            super_types: string[];
+        };
         /** @description Governed proposal operation restricted to additive ontology changes. */
-        AdditiveOntologyEvolveOp: components["schemas"]["WidenRelationOp"] | components["schemas"]["AddEntityTypeOp"] | components["schemas"]["AddRelationOp"] | components["schemas"]["AddPropertyOp"];
+        AdditiveOntologyEvolveOp: components["schemas"]["WidenRelationOp"] | components["schemas"]["AddEntityTypeOp"] | components["schemas"]["AddSuperTypesOp"] | components["schemas"]["AddRelationOp"];
         /** @description Additive-only ontology proposal helper for structured-output systems. */
         AdditiveOntologyEvolveRequest: {
             ops: components["schemas"]["AdditiveOntologyEvolveOp"][];
@@ -3758,6 +3809,12 @@ export interface components {
          *     difference is refused with a typed error naming the route that applies it.
          */
         OntologyDefineRequest: {
+            /**
+             * @description Preview the exact definition without creating a graph, writing an
+             *     ontology object, or changing the graph head. Equivalent to the
+             *     `?dry_run=true` query parameter; either signal enables preview mode.
+             */
+            dry_run?: boolean;
             /** @description Import format hint. `auto` (the default) sniffs the content. */
             format?: string | null;
             /**
@@ -3773,29 +3830,28 @@ export interface components {
         };
         OntologyDefineResponse: {
             /**
-             * @description True when this call wrote a new ontology version, either by creating the
-             *     graph or by applying an additive difference. False when the proposed
-             *     ontology already matched the active one, which is what makes re-running
-             *     the same bootstrap request a no-op.
+             * @description True when this call wrote a new ontology version, or when a dry run
+             *     predicts that it would. False when the proposed ontology already matched
+             *     the active one, which is what makes re-running the same bootstrap request
+             *     a no-op.
              *
-             *     This tracks what was written, so it never reports `false` for a call
-             *     that changed the ontology: a widened relation domain or range and a new
-             *     property field both set it, even though neither appears in the
-             *     class-and-relation schema diff.
+             *     A widened relation domain or range and a new property field both set it,
+             *     even though neither appears in the class-and-relation schema diff.
              */
             changed?: boolean;
             /**
-             * @description The additive changes this call applied to an existing graph's ontology.
-             *     Empty when the graph was created and when nothing changed.
+             * @description The additive changes this call applied, or would apply during a dry run,
+             *     to an existing graph's ontology. Empty on create and no-op.
              */
             changes?: components["schemas"]["SchemaDiffEntry"][];
+            /** @description True when this response is a preview and no durable state changed. */
+            dry_run?: boolean;
             entity_types: components["schemas"]["OntologyTermView"][];
             format: string;
             graph: components["schemas"]["GraphKey"];
             /**
-             * @description True when this call created the graph head. False when the graph already
-             *     existed, whether the ontology then changed or not. This is the `created`
-             *     signal for the define route.
+             * @description True when this call created the graph head, or when a dry run predicts
+             *     that the real definition would create it.
              */
             graph_created: boolean;
             merged_default: boolean;
@@ -3840,6 +3896,8 @@ export interface components {
         OntologyDraftStatus: "draft" | "validated" | "promoted" | "rejected";
         /** @description The full definition of one entity type (class) in the active ontology. */
         OntologyEntityTypeView: {
+            /** @description Canonical query IRI minted by Little Big Brain for this class identity. */
+            iri?: string;
             name: string;
             properties: components["schemas"]["OntologyPropertyView"][];
             /** Format: int64 */
@@ -3848,6 +3906,17 @@ export interface components {
             resolvable: boolean;
             /** Format: int64 */
             since_version: number;
+            /**
+             * @description Frozen class identity used by commits and the RDF projection. This is
+             *     unique even when imported vocabularies reuse the same local name.
+             */
+            stable_id?: string;
+            /**
+             * @description Direct parent classes (`rdfs:subClassOf`), named by their frozen
+             *     `stable_id`s. Clients can build the full class lattice without a SPARQL
+             *     scan or a second ontology lookup.
+             */
+            super_types?: string[];
         };
         OntologyEvidenceSample: {
             /** @description Stable connector/source reference; sample content is never used as identity. */
@@ -3866,7 +3935,7 @@ export interface components {
          *     the supported "ontology evolution" path; identity-breaking changes (removals,
          *     narrowing) still require an explicit expand→migrate→contract plan.
          */
-        OntologyEvolveOp: components["schemas"]["WidenRelationOp"] | components["schemas"]["AddEntityTypeOp"] | components["schemas"]["AddRelationOp"] | components["schemas"]["AddPropertyOp"] | components["schemas"]["SetPropertyConstraintOp"] | components["schemas"]["RenameEntityTypeOp"] | components["schemas"]["RenameRelationOp"] | components["schemas"]["SetRelationInverseOp"] | components["schemas"]["SetRelationCardinalityOp"] | components["schemas"]["NarrowRelationOp"] | components["schemas"]["RemoveEntityTypeOp"] | components["schemas"]["RemoveRelationOp"];
+        OntologyEvolveOp: components["schemas"]["WidenRelationOp"] | components["schemas"]["AddEntityTypeOp"] | components["schemas"]["AddSuperTypesOp"] | components["schemas"]["AddRelationOp"] | components["schemas"]["AddPropertyOp"] | components["schemas"]["SetPropertyConstraintOp"] | components["schemas"]["RenameEntityTypeOp"] | components["schemas"]["RenameRelationOp"] | components["schemas"]["SetRelationInverseOp"] | components["schemas"]["SetRelationCardinalityOp"] | components["schemas"]["NarrowRelationOp"] | components["schemas"]["RemoveEntityTypeOp"] | components["schemas"]["RemoveRelationOp"];
         /**
          * @description Apply a list of additive ontology changes in order, writing a new ontology
          *     version when anything actually changes. Ops are applied against the
@@ -4344,6 +4413,42 @@ export interface components {
             /** @description Members of an `i64_set` field; canonicalized like `keyword_set`. */
             i64_set: number[];
         };
+        PublicationRetryGuidance: {
+            eventual_read_available: boolean;
+            message: string;
+            /** Format: int64 */
+            retry_after_ms: number;
+        };
+        /**
+         * @description Server-managed publication lifecycle for one graph epoch.
+         * @enum {string}
+         */
+        PublicationState: "current" | "queued" | "compacting" | "building" | "publishing" | "blocked";
+        /**
+         * @description One bounded status document for automatic exact-generation publication.
+         *     It is available before the first generation publishes, unlike
+         *     [`PublishedReadStatusResponse`], so SDKs can wait without probing SPARQL.
+         */
+        PublicationStatusResponse: {
+            current_stage?: string | null;
+            /** Format: int64 */
+            epoch: number;
+            /** Format: int64 */
+            head_generation: number;
+            head_seq: components["schemas"]["CommitSeq"];
+            /** Format: int64 */
+            lag_commits: number;
+            /** Format: int64 */
+            last_progress_at_micros: number;
+            /** Format: int64 */
+            published_generation?: number | null;
+            published_seq: components["schemas"]["CommitSeq"];
+            retry: components["schemas"]["PublicationRetryGuidance"];
+            state: components["schemas"]["PublicationState"];
+            /** Format: int64 */
+            target_head_generation: number;
+            target_seq: components["schemas"]["CommitSeq"];
+        };
         /**
          * @description Whether an import's deterministic published-generation job was newly
          *     queued or coalesced with equivalent pending work.
@@ -4467,6 +4572,52 @@ export interface components {
              */
             rerank_raw_bytes_fetched?: number;
         };
+        /**
+         * @description The RDF node kind of a bounded observed-schema statement object.
+         * @enum {string}
+         */
+        RdfSchemaObjectKind: "iri" | "blank_node" | "literal";
+        /** @description One OWL/RDFS vocabulary or annotation statement retained for schema UIs. */
+        RdfSchemaStatement: {
+            object: string;
+            object_kind: components["schemas"]["RdfSchemaObjectKind"];
+            predicate: string;
+            subject: string;
+        };
+        /**
+         * @description Compact, immutable observed-schema artifact attached to one exact F3 base.
+         *
+         *     This is the overview/read-model surface for Explorer and Ontology. It is
+         *     produced by maintenance while publishing F3 and is therefore cheap to read:
+         *     no request-time graph scan or base-plus-delta assembly is required.
+         */
+        RdfSchemaSummaryResponse: {
+            /**
+             * @description Per-predicate totals of literal-valued statements, the data-property
+             *     sibling of `resource_predicate_counts`. `None` when the stored summary
+             *     artifact predates this field; the next full summary rebuild fills it.
+             */
+            literal_predicate_counts?: components["schemas"]["RdfSchemaTermCount"][] | null;
+            /** Format: int64 */
+            ontology_version: number;
+            resource_predicate_counts: components["schemas"]["RdfSchemaTermCount"][];
+            snapshot: components["schemas"]["SnapshotView"];
+            statements: components["schemas"]["RdfSchemaStatement"][];
+            truncated: boolean;
+            type_counts: components["schemas"]["RdfSchemaTermCount"][];
+        };
+        /**
+         * @description One exact RDF term count in the compact observed-schema summary.
+         *
+         *     `term` is the complete IRI rather than a display-local name. This keeps
+         *     foreign vocabularies unambiguous; clients may choose their own prefix or
+         *     local-name presentation.
+         */
+        RdfSchemaTermCount: {
+            /** Format: int64 */
+            count: number;
+            term: string;
+        };
         /**
          * @description A page-region provenance anchor on a fact's evidence (region provenance
          *     §4.1/§6.4(b) BYO import): where the evidence appears in the source
@@ -4739,6 +4890,11 @@ export interface components {
         };
         SchemaAuditResult: {
             component: string;
+            /**
+             * @description Nested results explaining a composite violation (`sh:detail`), e.g.
+             *     which constraint inside a `sh:node` shape the value node failed.
+             */
+            details?: components["schemas"]["SchemaAuditResult"][];
             focus_node: string;
             message?: string | null;
             result_path?: string | null;
@@ -4786,6 +4942,8 @@ export interface components {
         /** @enum {string} */
         SchemaChangeKind: "additive" | "restrictive" | "identity_breaking";
         SchemaClassView: {
+            /** @description Canonical query IRI minted by Little Big Brain for this class identity. */
+            iri?: string;
             name: string;
             property_count: number;
             /** Format: int64 */
@@ -4793,6 +4951,8 @@ export interface components {
             /** Format: int64 */
             since_version: number;
             stable_id: string;
+            /** @description Direct parent classes (`rdfs:subClassOf`), named by `stable_id`. */
+            super_types?: string[];
         };
         /** @enum {string} */
         SchemaCompatibilityVerdict: "compatible" | "restrictive" | "migration_required";
@@ -5767,11 +5927,13 @@ export interface components {
          */
         SparqlCompareOp: "eq" | "ne" | "lt" | "le" | "gt" | "ge";
         /**
-         * @description RDFS entailment regime applied when projecting the graph for a conformant
-         *     SPARQL query. Controls whether a class term matches subtype instances.
+         * @description Entailment regime applied to a conformant SPARQL query. The regime is
+         *     evaluated at query time as a closure-driven pattern rewrite over the
+         *     dataset's asserted schema triples; the published dataset itself stays
+         *     asserted-only.
          * @enum {string}
          */
-        SparqlEntailment: "subclass" | "none";
+        SparqlEntailment: "owl" | "rdfs" | "subclass" | "none";
         /**
          * @description A FILTER over a solution: a comparison, or a boolean composition of filters.
          *     A comparison whose operands are unbound, incomparable, or a type mismatch is
@@ -5967,11 +6129,10 @@ export interface components {
             /** @description WHERE: the conjunctive basic graph pattern (shares the analytic engine). */
             patterns: components["schemas"]["AnalyticTriplePattern"][];
             /**
-             * @description Reason over the graph's stored inference rules so a pattern matches
-             *     asserted **and** derived edges in one shot. Off by default
-             *     (asserted-only). Public serving requires a compatible reasoned
-             *     projection in the pinned published generation and fails closed when it
-             *     is absent; it never forces an overlay reduce.
+             * @description Not available on the published SPARQL surface: a branch's stored
+             *     inference rules already run at publish time, folding derived facts into
+             *     the asserted dataset every query reads. Requesting `reason: true`
+             *     returns a typed, non-retryable error.
              */
             reason?: boolean;
             /**
@@ -6032,10 +6193,13 @@ export interface components {
          *     RDF graph, not a results table).
          */
         SparqlTextRequest: {
+            as_of_commit_seq?: null | components["schemas"]["CommitSeq"];
             /**
-             * @description RDFS entailment regime. `None` (default) reads the asserted published
-             *     projection. `Subclass` requires a compatible reasoned projection and
-             *     fails closed while one is unavailable.
+             * @description Entailment regime. `None` (default) matches asserted triples only.
+             *     `Rdfs` applies the practical RDFS core at query time, `Subclass` the
+             *     class-only subset, and `Owl` the OWL profile on top of `Rdfs`. All
+             *     derive the closure from the pinned generation's asserted schema
+             *     triples.
              */
             entailment?: components["schemas"]["SparqlEntailment"];
             /**
@@ -6048,12 +6212,10 @@ export interface components {
             /** @description The SPARQL query text (SELECT or ASK). */
             query: string;
             /**
-             * @description Reason over the branch's stored inference rules: project the rule-derived
-             *     facts into the dataset the conformant engine runs over, so a query reasons
-             *     over asserted **and** derived edges. Off by default; a no-op when the branch
-             *     has no stored rules. Combine with `entailment: subclass` for full
-             *     reasoning—rule-derived facts plus `rdfs:subClassOf` type closure—once
-             *     maintenance publishes a compatible reasoned projection.
+             * @description Not available on the published SPARQL surface: a branch's stored
+             *     inference rules already run at publish time, folding derived facts into
+             *     the asserted dataset every query reads. Requesting `reason: true`
+             *     returns a typed, non-retryable error.
              */
             reason?: boolean;
         };
@@ -10068,7 +10230,7 @@ export interface operations {
                 blank_node_scope?: string;
                 /** @description Entity type name for imported RDF resources (default Resource) */
                 resource_type?: string;
-                /** @description Set false to defer the published-generation enqueue; send build=false on every chunk except the last of a chunked bulk stream. Default true. */
+                /** @description Set false on intermediate chunks to defer eager publication. Each request still atomically commits a compacted truth segment and exact per-commit F3 delta; graph reconstruction, SHACL, and complete F3 construction run off-path. The server advances one coalesced safety fence when the deferred delta tail reaches 8 entries or 32 MiB, so a large stream cannot wedge itself. Omit build=false on the final chunk to advance the final fence. Default true. */
                 build?: string;
             };
             header?: {
@@ -10337,6 +10499,142 @@ export interface operations {
             };
         };
     };
+    get_v1_graph_publication_status: {
+        parameters: {
+            query?: {
+                /** @description Graph name (default `main`) */
+                graph?: string;
+                /** @description Branch name (default `main`) */
+                branch?: string;
+            };
+            header?: {
+                /** @description API contract version to pin. Use `2026-07-23` for this beta-breaking shape. */
+                "Lbb-Version"?: string;
+            };
+            path?: never;
+            cookie?: never;
+        };
+        requestBody?: never;
+        responses: {
+            /** @description OK */
+            200: {
+                headers: {
+                    /** @description API contract version used for the response */
+                    "Lbb-Version"?: string;
+                    /** @description Request correlation id */
+                    "X-Request-Id"?: string;
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["PublicationStatusResponse"];
+                };
+            };
+            /** @description Bad request */
+            400: {
+                headers: {
+                    /** @description API contract version used for the response */
+                    "Lbb-Version"?: string;
+                    /** @description Request correlation id */
+                    "X-Request-Id"?: string;
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["LbbErrorEnvelope"];
+                };
+            };
+            /** @description Unauthorized */
+            401: {
+                headers: {
+                    /** @description API contract version used for the response */
+                    "Lbb-Version"?: string;
+                    /** @description Request correlation id */
+                    "X-Request-Id"?: string;
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["LbbErrorEnvelope"];
+                };
+            };
+            /** @description Forbidden */
+            403: {
+                headers: {
+                    /** @description API contract version used for the response */
+                    "Lbb-Version"?: string;
+                    /** @description Request correlation id */
+                    "X-Request-Id"?: string;
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["LbbErrorEnvelope"];
+                };
+            };
+            /** @description Not found */
+            404: {
+                headers: {
+                    /** @description API contract version used for the response */
+                    "Lbb-Version"?: string;
+                    /** @description Request correlation id */
+                    "X-Request-Id"?: string;
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["LbbErrorEnvelope"];
+                };
+            };
+            /** @description Conflict */
+            409: {
+                headers: {
+                    /** @description API contract version used for the response */
+                    "Lbb-Version"?: string;
+                    /** @description Request correlation id */
+                    "X-Request-Id"?: string;
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["LbbErrorEnvelope"];
+                };
+            };
+            /** @description Rate limit exceeded */
+            429: {
+                headers: {
+                    /** @description API contract version used for the response */
+                    "Lbb-Version"?: string;
+                    /** @description Request correlation id */
+                    "X-Request-Id"?: string;
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["LbbErrorEnvelope"];
+                };
+            };
+            /** @description Internal server error */
+            500: {
+                headers: {
+                    /** @description API contract version used for the response */
+                    "Lbb-Version"?: string;
+                    /** @description Request correlation id */
+                    "X-Request-Id"?: string;
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["LbbErrorEnvelope"];
+                };
+            };
+            /** @description Service unavailable */
+            503: {
+                headers: {
+                    /** @description API contract version used for the response */
+                    "Lbb-Version"?: string;
+                    /** @description Request correlation id */
+                    "X-Request-Id"?: string;
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["LbbErrorEnvelope"];
+                };
+            };
+        };
+    };
     get_v1_graph_read_snapshot: {
         parameters: {
             query?: {
@@ -10761,6 +11059,142 @@ export interface operations {
             };
         };
     };
+    get_v1_graph_schema_summary: {
+        parameters: {
+            query?: {
+                /** @description Graph name (default `main`) */
+                graph?: string;
+                /** @description Branch name (default `main`) */
+                branch?: string;
+            };
+            header?: {
+                /** @description API contract version to pin. Use `2026-07-23` for this beta-breaking shape. */
+                "Lbb-Version"?: string;
+            };
+            path?: never;
+            cookie?: never;
+        };
+        requestBody?: never;
+        responses: {
+            /** @description OK */
+            200: {
+                headers: {
+                    /** @description API contract version used for the response */
+                    "Lbb-Version"?: string;
+                    /** @description Request correlation id */
+                    "X-Request-Id"?: string;
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["RdfSchemaSummaryResponse"];
+                };
+            };
+            /** @description Bad request */
+            400: {
+                headers: {
+                    /** @description API contract version used for the response */
+                    "Lbb-Version"?: string;
+                    /** @description Request correlation id */
+                    "X-Request-Id"?: string;
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["LbbErrorEnvelope"];
+                };
+            };
+            /** @description Unauthorized */
+            401: {
+                headers: {
+                    /** @description API contract version used for the response */
+                    "Lbb-Version"?: string;
+                    /** @description Request correlation id */
+                    "X-Request-Id"?: string;
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["LbbErrorEnvelope"];
+                };
+            };
+            /** @description Forbidden */
+            403: {
+                headers: {
+                    /** @description API contract version used for the response */
+                    "Lbb-Version"?: string;
+                    /** @description Request correlation id */
+                    "X-Request-Id"?: string;
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["LbbErrorEnvelope"];
+                };
+            };
+            /** @description Not found */
+            404: {
+                headers: {
+                    /** @description API contract version used for the response */
+                    "Lbb-Version"?: string;
+                    /** @description Request correlation id */
+                    "X-Request-Id"?: string;
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["LbbErrorEnvelope"];
+                };
+            };
+            /** @description Conflict */
+            409: {
+                headers: {
+                    /** @description API contract version used for the response */
+                    "Lbb-Version"?: string;
+                    /** @description Request correlation id */
+                    "X-Request-Id"?: string;
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["LbbErrorEnvelope"];
+                };
+            };
+            /** @description Rate limit exceeded */
+            429: {
+                headers: {
+                    /** @description API contract version used for the response */
+                    "Lbb-Version"?: string;
+                    /** @description Request correlation id */
+                    "X-Request-Id"?: string;
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["LbbErrorEnvelope"];
+                };
+            };
+            /** @description Internal server error */
+            500: {
+                headers: {
+                    /** @description API contract version used for the response */
+                    "Lbb-Version"?: string;
+                    /** @description Request correlation id */
+                    "X-Request-Id"?: string;
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["LbbErrorEnvelope"];
+                };
+            };
+            /** @description Service unavailable */
+            503: {
+                headers: {
+                    /** @description API contract version used for the response */
+                    "Lbb-Version"?: string;
+                    /** @description Request correlation id */
+                    "X-Request-Id"?: string;
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["LbbErrorEnvelope"];
+                };
+            };
+        };
+    };
     get_v1_graph_summary: {
         parameters: {
             query?: {
@@ -13988,7 +14422,7 @@ export interface operations {
                 graph?: string;
                 /** @description Branch name (default `main`) */
                 branch?: string;
-                /** @description eventual (default) serves the referenced durable report; strong requires validation at current head with current ontology/shapes */
+                /** @description eventual (default) serves the selected base sidecar; strong requires an exact-head sidecar with current ontology/shapes */
                 consistency?: string;
                 /** @description Maximum returned result rows; result_count remains exact */
                 limit?: string;
@@ -14128,6 +14562,8 @@ export interface operations {
                 graph?: string;
                 /** @description Branch name (default `main`) */
                 branch?: string;
+                /** @description Validate and return the exact predicted definition without creating a graph, writing an ontology object, or changing the graph head */
+                dry_run?: string;
             };
             header?: {
                 /** @description API contract version to pin. Use `2026-07-23` for this beta-breaking shape. */

package/dist/types.d.ts

@@ -53,13 +53,23 @@ export interface RdfImportOptions {
     resourceType?: string;
     edgeIdempotency?: "append" | "skip_unchanged";
     /**
-     * Set `false` to defer the published-generation enqueue. Send `build: false`
-     * on every chunk except the last of a chunked bulk stream, so derived
-     * families build once at the final head. Defaults to `true`.
+     * Set `false` on intermediate chunks to suppress the publication enqueue.
+     * Every request still commits durable truth and an exact per-commit F3 delta;
+     * omit `build: false` on the last chunk to advance one final coalesced fence.
+     * Defaults to `true`.
      */
     build?: boolean;
     idempotencyKey?: string;
 }
+export interface RdfImportDocument {
+    rdf: string;
+    options?: RdfImportOptions;
+}
+export interface RdfImportManyResult {
+    imports: Schemas["GraphRdfImportResponse"][];
+    finalSequence?: number;
+    publication?: Schemas["GraphImportPublishedGenerationOutcome"] | null;
+}
 export type AttributeFilterOp = "eq" | "ne" | "lt" | "le" | "gt" | "ge";
 export type AttributeFilterValue = string | number | boolean | {
     dateTime: string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@littlebigbrain/client",
-  "version": "0.12.0",
+  "version": "0.13.0",
   "description": "TypeScript client for the little big brain graph + hybrid search HTTP API",
   "license": "Apache-2.0",
   "repository": {