@littlebigbrain/client 0.12.0 → 0.13.1

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
@@ -368,14 +361,18 @@ export declare class LbbClient {
         asOf?: string;
     }): Promise<Schemas["EntityMetadataResponse"]>;
     /**
-     * Entity detail: metadata, attributes, current state, edge history, and
-     * observations. Pass `asOf` / `asOfCommitSeq` to reproduce the node as of a
-     * past instant / commit (the state, edges, and history are pinned to it).
+     * Read projected attributes and current relationships from one RDF snapshot.
+     * Inspect `unavailable_sections` before interpreting legacy provenance arrays.
+     * Use strong consistency for read-after-write, or a retained commit sequence.
      */
     entityDetail(opts: {
         id?: string;
         type?: string;
         name?: string;
+        key?: string;
+        consistency?: "strong" | "eventual";
+        edges?: number;
+        /** @deprecated Valid-time reads are unsupported; use asOfCommitSeq. */
         asOf?: string;
         asOfCommitSeq?: number;
     }): Promise<Schemas["EntityDetailResponse"]>;
@@ -405,7 +402,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 +465,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
@@ -876,9 +900,9 @@ export class LbbClient {
         });
     }
     /**
-     * Entity detail: metadata, attributes, current state, edge history, and
-     * observations. Pass `asOf` / `asOfCommitSeq` to reproduce the node as of a
-     * past instant / commit (the state, edges, and history are pinned to it).
+     * Read projected attributes and current relationships from one RDF snapshot.
+     * Inspect `unavailable_sections` before interpreting legacy provenance arrays.
+     * Use strong consistency for read-after-write, or a retained commit sequence.
      */
     entityDetail(opts) {
         return this.request("GET", "/v1/graph/entity", {
@@ -886,6 +910,9 @@ export class LbbClient {
                 id: opts.id,
                 type: opts.type,
                 name: opts.name,
+                key: opts.key,
+                consistency: opts.consistency,
+                edges: opts.edges,
                 as_of: opts.asOf,
                 as_of_commit_seq: opts.asOfCommitSeq,
             },
@@ -940,7 +967,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 +1065,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 +1109,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
@@ -68,11 +77,7 @@ export declare class EntityNamespace {
         name?: string;
         asOf?: string;
     }): Promise<Schemas["EntityMetadataResponse"]>;
-    detail(opts: {
-        id?: string;
-        type?: string;
-        name?: string;
-    }): Promise<Schemas["EntityDetailResponse"]>;
+    detail(opts: Parameters<LbbClient["entityDetail"]>[0]): Promise<Schemas["EntityDetailResponse"]>;
     /**
      * Filter entities already bound by relation patterns using typed attributes,
      * without writing RDF property IRIs by hand. This is a convenience wrapper over
@@ -88,7 +93,9 @@ export declare class SchemaNamespace {
     /** Read active metadata without running request-time validation. */
     view(opts?: CallOptions): Promise<Schemas["SchemaBundleView"]>;
     /** Atomically publish a bundle; conformance is produced asynchronously. */
-    publish(body: Schemas["SchemaPublishRequest"], opts?: CallOptions): Promise<Schemas["SchemaPublishResponse"]>;
+    publish(body: Schemas["SchemaPublishRequest"], opts?: CallOptions & {
+        dryRun?: boolean;
+    }): Promise<Schemas["SchemaPublishResponse"]>;
 }
 /** Ontology discovery and lifecycle operations. */
 export declare class OntologyNamespace {
@@ -105,7 +112,9 @@ export declare class OntologyNamespace {
      * does not exist yet. Safe to repeat. See {@link LbbClient.ontologyDefine}.
      */
     define(body: Schemas["OntologyDefineRequest"], opts?: CallOptions): Promise<Schemas["OntologyDefineResponse"]>;
-    evolve(body: Schemas["OntologyEvolveRequest"], opts?: CallOptions): Promise<Schemas["OntologyEvolveResponse"]>;
+    evolve(body: Schemas["OntologyEvolveRequest"], opts?: CallOptions & {
+        dryRun?: boolean;
+    }): Promise<Schemas["OntologyEvolveResponse"]>;
     induce(body: Schemas["OntologyInduceRequest"], opts?: CallOptions): Promise<Schemas["OntologyInduceResponse"]>;
 }
 /** Structured and SPARQL-text query operations. */

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
@@ -201,6 +213,7 @@ export class SchemaNamespace {
     publish(body, opts = {}) {
         return this.client.request("POST", "/v1/schema/publish", {
             ...opts,
+            query: { dry_run: opts.dryRun },
             idempotencyKey: opts.idempotencyKey ?? this.client.idempotencyKey("schema-publish"),
             body,
         });
@@ -254,6 +267,7 @@ export class OntologyNamespace {
     evolve(body, opts = {}) {
         return this.client.request("POST", "/v1/ontology/evolve", {
             ...opts,
+            query: { dry_run: opts.dryRun },
             body,
         });
     }