@littlebigbrain/client 0.11.1 → 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
 
@@ -111,7 +113,9 @@ The `graph(...)` scope exposes `facts`, `entities`, `ontology`, `query`,
 the one query language on the API; `schema`
 reads or atomically publishes the active ontology/shapes bundle. Writes enqueue
 published-generation maintenance automatically. Every generated shape is
-available as `Schemas["TypeName"]`.
+available as `Schemas["TypeName"]`. Retired request-time JSON SHACL DTOs are
+intentionally absent: publish RDF shapes with `schema.publish`, then read
+`ontology.conformance`.
 
 Full reference and guides: [docs.littlebigbrain.com/sdks/typescript](https://docs.littlebigbrain.com/sdks/typescript/).
 

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