@littlebigbrain/client 0.11.0 → 0.11.1

package/README.md

@@ -68,12 +68,18 @@ 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`. An empty iterable is rejected
-locally before an import POST is sent.
+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
+POST is sent.
 
 **Time-travel read.** Pin a SPARQL read to a past instant — results reflect the graph as it was then:
 
@@ -95,6 +101,8 @@ 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.
 
 ## More
 

package/dist/client.d.ts

@@ -146,7 +146,11 @@ export declare class LbbClient {
     retract(body: Schemas["GraphRetractRequest"], opts?: {
         idempotencyKey?: string;
     }): Promise<Schemas["GraphRetractResponse"]>;
-    /** Create the scoped graph/branch. Construct the client with the desired graph/branch first. */
+    /**
+     * Create the scoped graph/branch with an empty ontology. Construct the client
+     * with the desired graph/branch first, then call `ontology.define` before
+     * writing typed data.
+     */
     createGraph(): Promise<Schemas["CreateGraphResponse"]>;
     /**
      * Fork a whole graph into a brand-new destination graph in the same tenant.
@@ -432,7 +436,17 @@ export declare class LbbClient {
     ontologySearch(body: Schemas["OntologySearchRequest"]): Promise<Schemas["OntologySearchResponse"]>;
     /** Resolve mentions to concepts/entities. */
     ontologyResolve(body: Schemas["OntologyResolveRequest"]): Promise<Schemas["OntologyResolveResponse"]>;
-    /** Define the active ontology before the scoped graph's first commit. */
+    /**
+     * Put the scoped graph on an imported ontology, creating the graph when it
+     * does not exist yet. Safe to repeat: an unchanged ontology answers
+     * `changed: false` without writing. An additive difference is applied,
+     * including a wider relation domain or range and a new property field, and
+     * `changed` reports what was written. A document that narrows or drops what
+     * the graph already defines, or states a change no additive operation
+     * expresses, is refused with `ontology_restrictive_change`,
+     * `ontology_identity_breaking_change`, or `ontology_unsupported_change`, and
+     * writes nothing.
+     */
     ontologyDefine(body: Schemas["OntologyDefineRequest"]): Promise<Schemas["OntologyDefineResponse"]>;
     /**
      * Additively evolve the active ontology of an existing graph: widen relation
@@ -454,6 +468,13 @@ 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?: {
         timeoutMs?: number;
         pollIntervalMs?: number;

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 } from "./transport.js";
+import { LbbCapabilityError, LbbError } from "./transport.js";
 import { EntityNamespace, GraphNamespace, OntologyNamespace, QueryNamespace, SchemaNamespace, SearchNamespace, } from "./namespaces.js";
 export { parseSparqlResults } from "./types.js";
 export { LbbCapabilityError, LbbError } from "./transport.js";
@@ -575,7 +575,11 @@ export class LbbClient {
             idempotencyKey: opts.idempotencyKey ?? this.idempotencyKey("retract"),
         });
     }
-    /** Create the scoped graph/branch. Construct the client with the desired graph/branch first. */
+    /**
+     * Create the scoped graph/branch with an empty ontology. Construct the client
+     * with the desired graph/branch first, then call `ontology.define` before
+     * writing typed data.
+     */
     createGraph() {
         return this.request("POST", "/v1/graph/create");
     }
@@ -985,7 +989,17 @@ export class LbbClient {
     ontologyResolve(body) {
         return this.request("POST", "/v1/ontology/resolve", { body });
     }
-    /** Define the active ontology before the scoped graph's first commit. */
+    /**
+     * Put the scoped graph on an imported ontology, creating the graph when it
+     * does not exist yet. Safe to repeat: an unchanged ontology answers
+     * `changed: false` without writing. An additive difference is applied,
+     * including a wider relation domain or range and a new property field, and
+     * `changed` reports what was written. A document that narrows or drops what
+     * the graph already defines, or states a change no additive operation
+     * expresses, is refused with `ontology_restrictive_change`,
+     * `ontology_identity_breaking_change`, or `ontology_unsupported_change`, and
+     * writes nothing.
+     */
     ontologyDefine(body) {
         return this.request("POST", "/v1/ontology/define", { body });
     }
@@ -1024,17 +1038,52 @@ 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);
         let last;
         while (true) {
-            last = await this.rawRequest("GET", "/v1/graph/metadata");
+            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,
+                });
+            }
+            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 &&
-                lineage.bm25_indexed_commit_seq != null &&
-                lineage.bm25_indexed_commit_seq >= targetSeq &&
-                lineage.ann_indexed_commit_seq != null &&
-                lineage.ann_indexed_commit_seq >= targetSeq) {
+                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,

package/dist/namespaces.d.ts

@@ -100,6 +100,10 @@ export declare class OntologyNamespace {
     conformance(opts?: CallOptions & Pick<ReadConsistencyOptions, "consistency">): Promise<Schemas["SchemaAuditReport"]>;
     search(body: Schemas["OntologySearchRequest"], opts?: CallOptions): Promise<Schemas["OntologySearchResponse"]>;
     resolve(body: Schemas["OntologyResolveRequest"], opts?: CallOptions): Promise<Schemas["OntologyResolveResponse"]>;
+    /**
+     * Put the scoped graph on an imported ontology, creating the graph when it
+     * 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"]>;
     induce(body: Schemas["OntologyInduceRequest"], opts?: CallOptions): Promise<Schemas["OntologyInduceResponse"]>;

package/dist/namespaces.js

@@ -241,6 +241,10 @@ export class OntologyNamespace {
             body,
         });
     }
+    /**
+     * Put the scoped graph on an imported ontology, creating the graph when it
+     * does not exist yet. Safe to repeat. See {@link LbbClient.ontologyDefine}.
+     */
     define(body, opts = {}) {
         return this.client.request("POST", "/v1/ontology/define", {
             ...opts,

package/dist/schema.d.ts

@@ -183,7 +183,7 @@ export interface paths {
         };
         get?: never;
         put?: never;
-        /** Create the scoped graph and branch */
+        /** Create the scoped graph and branch with an empty ontology */
         post: operations["post_v1_graph_create"];
         delete?: never;
         options?: never;
@@ -3786,10 +3786,15 @@ export interface components {
             subject: string;
         };
         /**
-         * @description Define a custom ontology for the scoped graph before its first commit.
-         *     Imports `source` (any [`crate`]-supported format), optionally merges the
-         *     built-in default so the standard entity types/relations stay available, and
-         *     creates the graph head with the result. Fails if the graph already exists.
+         * @description Define the scoped graph's ontology. Imports `source` (any
+         *     [`crate`]-supported format), optionally merges the built-in default so the
+         *     standard entity types/relations stay available, and creates the graph head
+         *     with the result.
+         *
+         *     The call is re-runnable on a graph that already exists. An unchanged
+         *     ontology is a no-op; an additive difference is applied, including a widened
+         *     relation domain or range and a new property field; a narrowing or removing
+         *     difference is refused with a typed error naming the route that applies it.
          */
         OntologyDefineRequest: {
             /** @description Import format hint. `auto` (the default) sniffs the content. */
@@ -3806,9 +3811,31 @@ export interface components {
             source: string;
         };
         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.
+             *
+             *     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.
+             */
+            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.
+             */
+            changes?: components["schemas"]["SchemaDiffEntry"][];
             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.
+             */
             graph_created: boolean;
             merged_default: boolean;
             /** Format: int64 */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@littlebigbrain/client",
-  "version": "0.11.0",
+  "version": "0.11.1",
   "description": "TypeScript client for the little big brain graph + hybrid search HTTP API",
   "license": "Apache-2.0",
   "repository": {
@@ -53,5 +53,13 @@
     "openapi-typescript": "^7",
     "publint": "^0.3.21",
     "typescript": "^5.6"
+  },
+  "overrides": {
+    "@redocly/openapi-core": {
+      "js-yaml": "^4.3.1"
+    },
+    "minimatch": {
+      "brace-expansion": "^2.1.2"
+    }
   }
 }