@littlebigbrain/client 0.10.0 → 0.11.1

package/README.md

@@ -36,11 +36,10 @@ await graph.facts.create(
 const published = await lbb.readSnapshot();
 console.log(published.snapshot.served_at_seq, published.query_lag_commits);
 
-// 3. Hybrid search over the snapshot.
-const results = await graph.search.hybrid(
-  "How long are customer records retained?",
-  { topK: 10, consistency: "eventual" },
-);
+// 3. Query the snapshot with SPARQL.
+const rows = await lbb.sparqlRows({
+  query: "SELECT ?s ?o WHERE { ?s <policy:retention> ?o } LIMIT 10",
+});
 ```
 
 For hosted use, `baseUrl` is required and must be the exact `endpoint_url`
@@ -49,23 +48,6 @@ parameters; they are not encoded in the hostname.
 
 ## Examples
 
-**Search with filters.** Pass the request body to filter before ranking — here, only facts an ACL principal may see:
-
-```ts
-const results = await graph.search.hybrid({
-  query: "incident response runbook",
-  targets: ["entities"],
-  search: {
-    filters: {
-      op: "overlaps",
-      field: "acl",
-      values: ["user:rino@example.com", "group:engineering"],
-    },
-  },
-  top_k: 20,
-});
-```
-
 **Bulk import.** Load an array of records (or an NDJSON string) in one call:
 
 ```ts
@@ -86,17 +68,26 @@ 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 any search to a past instant — results reflect the graph as it was then:
+**Time-travel read.** Pin a SPARQL read to a past instant — results reflect the graph as it was then:
 
 ```ts
-const asOf = await graph.search.hybrid("retention policy", { asOf: "2026-01-01T00:00:00Z" });
+const asOf = await lbb.sparqlRows({
+  query: "SELECT ?s ?o WHERE { ?s <policy:retention> ?o }",
+  as_of_valid_time: "2026-01-01T00:00:00Z",
+});
 ```
 
 **SPARQL.** `sparqlRows` runs a SPARQL 1.1 SELECT/ASK and returns parsed rows:
@@ -110,12 +101,14 @@ 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
 
-The `graph(...)` scope exposes `facts`, `search`, `entities`, `ontology`,
-`query`, `schema`, and `context` namespaces. `context` includes vocabulary
-suggestion, term resolution, relation decoding, and groundability inspection; `schema`
+The `graph(...)` scope exposes `facts`, `entities`, `ontology`, `query`,
+`search` (feedback surfaces), and `schema` namespaces. `query` runs SPARQL,
+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"]`.

package/dist/client.d.ts

@@ -1,12 +1,11 @@
 import type { DurableImportSource, ImportLine, LbbClientOptions, ListResponse, RawLbbResponse, ReadConsistencyOptions, RdfImportOptions, Schemas, SearchConsistency, SparqlResults } from "./types.js";
 import { type CallOptions, type RequestOptions } from "./transport.js";
-import { ContextNamespace, EntityNamespace, GraphNamespace, OntologyNamespace, QueryNamespace, SchemaNamespace, SearchNamespace } from "./namespaces.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, SearchRequest, SearchResponse, SearchResult, Snapshot, } 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 { LbbCapabilityError, LbbError } from "./transport.js";
 export type { CallOptions, Query, QueryValue, RequestOptions, } from "./transport.js";
-export type { HybridSearchOptions } from "./namespaces.js";
-export { ContextNamespace, EntityNamespace, FactsNamespace, GraphNamespace, OntologyNamespace, QueryNamespace, SchemaNamespace, SearchNamespace, } from "./namespaces.js";
+export { EntityNamespace, FactsNamespace, GraphNamespace, OntologyNamespace, QueryNamespace, SchemaNamespace, SearchNamespace, } from "./namespaces.js";
 export interface IndexLineageObservation {
     metadata: Schemas["GraphMetadataResponse"];
     lineage: Schemas["IndexLineage"];
@@ -39,7 +38,6 @@ export declare class LbbClient {
     private capabilities?;
     /** A5 default read consistency applied when a read omits its own value. */
     readonly defaultConsistency?: SearchConsistency;
-    readonly context: ContextNamespace;
     readonly search: SearchNamespace;
     readonly entities: EntityNamespace;
     readonly schema: SchemaNamespace;
@@ -148,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.
@@ -213,47 +215,6 @@ export declare class LbbClient {
     deleteBranch(opts: {
         confirm: string;
     }): Promise<Schemas["GraphBranchDeleteResponse"]>;
-    embeddingConfig(): Promise<Schemas["ManagedEmbeddingConfigResponse"]>;
-    /** List the embedding models available on this deployment. */
-    embeddingModels(): Promise<Schemas["ManagedEmbeddingModelsResponse"]>;
-    /**
-     * Choose the model used automatically for writes and vector queries.
-     * Provider credentials and native dimension discovery stay server-side.
-     */
-    setEmbeddingModel(modelId: string, opts?: {
-        autoEmbedQuery?: boolean;
-    }): Promise<Schemas["ManagedEmbeddingConfigResponse"]>;
-    /** Advanced configuration escape hatch. Prefer `setEmbeddingModel`. */
-    setEmbeddingConfig(body: Schemas["ManagedEmbeddingConfigRequest"]): Promise<Schemas["ManagedEmbeddingConfigResponse"]>;
-    submitEmbeddingBackfill(opts?: {
-        batchSize?: number;
-        limit?: number;
-        full?: boolean;
-        idempotencyKey?: string;
-    }): Promise<Schemas["ManagedEmbeddingBackfillJobStatusResponse"]>;
-    embeddingBackfillJob(jobId: string): Promise<Schemas["ManagedEmbeddingBackfillJobStatusResponse"]>;
-    cancelEmbeddingBackfill(jobId: string): Promise<Schemas["ManagedEmbeddingBackfillJobStatusResponse"]>;
-    backfillEmbeddings(opts?: {
-        batchSize?: number;
-        limit?: number;
-        full?: boolean;
-        idempotencyKey?: string;
-        timeoutMs?: number;
-        pollIntervalMs?: number;
-    }): Promise<Schemas["ManagedEmbeddingBackfillResponse"]>;
-    promoteEmbedding(opts: {
-        runId: string;
-        allowRegression?: boolean;
-    }): Promise<Schemas["ManagedEmbeddingPromoteResponse"]>;
-    /**
-     * The graph's grounding vocabulary as byte-sorted, deduped string sections —
-     * the canonical input for a decoder-side automaton (FST/trie) and the
-     * vocabulary half of an export bundle.
-     */
-    vocabExport(opts?: {
-        sections?: string[];
-        limit?: number;
-    }): Promise<Schemas["VocabExportResponse"]>;
     /**
      * Captured signals by flush-seq range, oldest first — the model-training
      * feed. The `seq` on each signal is the temporal-split coordinate (train ≤ T,
@@ -366,29 +327,11 @@ export declare class LbbClient {
         runId: string;
         allowRegression?: boolean;
     }): Promise<unknown>;
-    /** Full semantic hybrid search from a request body (`POST /v1/graph/search`). */
-    graphSearch(body: Schemas["SemanticGraphSearchRequest"], opts?: ReadConsistencyOptions): Promise<Schemas["SemanticGraphSearchResponse"]>;
-    /** Reciprocal-rank-fusion across sub-queries. */
-    multiSearch(body: Schemas["HybridMultiSearchRequest"]): Promise<Schemas["HybridMultiSearchResponse"]>;
     /**
-     * Grounded prefix completion from the index vocabulary + ontology. Optionally
-     * narrow relation completions by a type-signature `context` — a type
-     * pair that admits a single relation flags `signature_forced`.
-     */
-    suggest(body: Schemas["SearchSuggestRequest"]): Promise<Schemas["SearchSuggestResponse"]>;
-    /** Snap free text to the nearest term in the pinned published vocabulary. */
-    resolveTerm(body: Schemas["ResolveTermRequest"]): Promise<Schemas["ResolveTermResponse"]>;
-    /** Decode a relation from the graph's admissible published vocabulary. */
-    decode(body: Schemas["DecodeRequest"]): Promise<Schemas["DecodeResponse"]>;
-    /** Report completion strategy fitness for the pinned published graph. */
-    groundability(opts?: {
-        sample?: number;
-    }): Promise<Schemas["GroundabilityReport"]>;
-    /**
-     * Append relevance labels for a set of search results — how little big brain
+     * Append relevance labels for a set of ranked results — how little big brain
      * gathers customer-specific qrels. Grade results (3 ideal/good, 1 partial,
-     * 0 bad), referencing the search response's `search_id` so labels tie back to
-     * that ranking. Stored apart from customer facts and exported via
+     * 0 bad), referencing the ranking's `search_id` so labels tie back to it.
+     * Stored apart from customer facts and exported via
      * {@link searchFeedbackExport} as training/eval data for embedding fine-tuning.
      */
     searchFeedback(body: Schemas["SearchFeedbackRequest"], opts?: {
@@ -396,10 +339,6 @@ export declare class LbbClient {
     }): Promise<Schemas["SearchFeedbackResponse"]>;
     /** Export the stored relevance labels as qrels-style rows for training. */
     searchFeedbackExport(): Promise<Schemas["SearchFeedbackExportResponse"]>;
-    /** BM25 search. */
-    fullTextSearch(body: Schemas["FullTextSearchRequest"], opts?: ReadConsistencyOptions): Promise<Schemas["FullTextSearchResponse"]>;
-    /** ANN/vector search. */
-    embeddingSearch(body: Schemas["EmbeddingSearchRequest"], opts?: ReadConsistencyOptions): Promise<Schemas["EmbeddingSearchResponse"]>;
     /**
      * Ranked incoming/outgoing neighborhood for a graph entity.
      *
@@ -476,14 +415,6 @@ export declare class LbbClient {
      * is the ASK answer (or `null` for a SELECT).
      */
     sparqlRows(body: Schemas["SparqlTextRequest"], opts?: ReadConsistencyOptions): Promise<SparqlResults>;
-    /**
-     * Basic-graph-pattern query with group-graph-pattern combinators
-     * (UNION / OPTIONAL / MINUS / EXISTS / NOT EXISTS) folded over the base
-     * patterns. The complement to {@link sparql}: this route carries the
-     * combinators (but not FILTER/aggregation), so use it when a query needs an
-     * optional/union/negated leg rather than a grouped aggregate.
-     */
-    analytics(body: Schemas["AnalyticQueryRequest"]): Promise<Schemas["AnalyticQueryResponse"]>;
     /**
      * The active ontology (entity types and relations) for the scoped graph.
      * Pass `{ counts: true }` to include a per-relation current-edge count
@@ -505,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
@@ -527,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,10 +1,10 @@
 import { parseSparqlResults } from "./types.js";
 import { bodyMarksTerminal, errorCodeFromBody, fullJitterBackoffMs, parseLbbError, parseResponseJson, retryAllowed, retryableStatus, retryDelayMs, sleep, } from "./transport.js";
-import { LbbCapabilityError } from "./transport.js";
-import { ContextNamespace, EntityNamespace, GraphNamespace, OntologyNamespace, QueryNamespace, SchemaNamespace, SearchNamespace, } from "./namespaces.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";
-export { ContextNamespace, EntityNamespace, FactsNamespace, GraphNamespace, OntologyNamespace, QueryNamespace, SchemaNamespace, SearchNamespace, } from "./namespaces.js";
+export { EntityNamespace, FactsNamespace, GraphNamespace, OntologyNamespace, QueryNamespace, SchemaNamespace, SearchNamespace, } from "./namespaces.js";
 function durableImportBytes(line) {
     if (line instanceof Uint8Array)
         return line;
@@ -105,7 +105,6 @@ export class LbbClient {
     capabilities;
     /** A5 default read consistency applied when a read omits its own value. */
     defaultConsistency;
-    context;
     search;
     entities;
     schema;
@@ -148,7 +147,6 @@ export class LbbClient {
             throw new Error("no fetch implementation available; pass options.fetch");
         }
         this.fetchImpl = chosen;
-        this.context = new ContextNamespace(this);
         this.search = new SearchNamespace(this);
         this.entities = new EntityNamespace(this);
         this.schema = new SchemaNamespace(this);
@@ -577,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");
     }
@@ -668,78 +670,7 @@ export class LbbClient {
             query: { confirm: opts.confirm },
         });
     }
-    embeddingConfig() {
-        return this.request("GET", "/v1/graph/embedding");
-    }
-    /** List the embedding models available on this deployment. */
-    embeddingModels() {
-        return this.request("GET", "/v1/graph/embedding/models");
-    }
-    /**
-     * Choose the model used automatically for writes and vector queries.
-     * Provider credentials and native dimension discovery stay server-side.
-     */
-    setEmbeddingModel(modelId, opts = {}) {
-        return this.setEmbeddingConfig({
-            model_id: modelId,
-            service: "open_router",
-            auto_embed_query: opts.autoEmbedQuery ?? true,
-        });
-    }
-    /** Advanced configuration escape hatch. Prefer `setEmbeddingModel`. */
-    setEmbeddingConfig(body) {
-        return this.request("POST", "/v1/graph/embedding", { body });
-    }
-    submitEmbeddingBackfill(opts = {}) {
-        return this.request("POST", "/v1/graph/embedding/backfill-jobs", {
-            body: {
-                batch_size: opts.batchSize,
-                limit: opts.limit,
-                full: opts.full ?? false,
-            },
-            idempotencyKey: opts.idempotencyKey ?? this.idempotencyKey("embedding-backfill"),
-        });
-    }
-    embeddingBackfillJob(jobId) {
-        return this.request("GET", "/v1/graph/embedding/backfill-jobs", {
-            query: { job_id: jobId },
-        });
-    }
-    cancelEmbeddingBackfill(jobId) {
-        return this.request("DELETE", "/v1/graph/embedding/backfill-jobs", {
-            query: { job_id: jobId },
-        });
-    }
-    async backfillEmbeddings(opts = {}) {
-        let status = await this.submitEmbeddingBackfill(opts);
-        const deadline = Date.now() + (opts.timeoutMs ?? 30 * 60_000);
-        while (status.status === "pending" || status.status === "running") {
-            if (Date.now() >= deadline)
-                throw new Error(`embedding backfill ${status.job_id} did not finish before timeout`);
-            await sleep(opts.pollIntervalMs ?? 2_000);
-            status = await this.embeddingBackfillJob(status.job_id);
-        }
-        if (status.status !== "succeeded" || status.result == null)
-            throw new Error(status.terminal_error ??
-                `embedding backfill ${status.job_id} ended ${status.status}`);
-        return status.result;
-    }
-    promoteEmbedding(opts) {
-        return this.request("POST", "/v1/graph/embedding/promote", {
-            query: { run_id: opts.runId, allow_regression: opts.allowRegression },
-        });
-    }
     // --- models as runs (training-run registry + eval machinery) ---
-    /**
-     * The graph's grounding vocabulary as byte-sorted, deduped string sections —
-     * the canonical input for a decoder-side automaton (FST/trie) and the
-     * vocabulary half of an export bundle.
-     */
-    vocabExport(opts = {}) {
-        return this.request("GET", "/v1/search/vocab", {
-            query: { sections: opts.sections?.join(","), limit: opts.limit },
-        });
-    }
     /**
      * Captured signals by flush-seq range, oldest first — the model-training
      * feed. The `seq` on each signal is the temporal-split coordinate (train ≤ T,
@@ -887,49 +818,12 @@ export class LbbClient {
             query: { run_id: opts.runId, allow_regression: opts.allowRegression },
         });
     }
-    // --- search ---
-    /** Full semantic hybrid search from a request body (`POST /v1/graph/search`). */
-    graphSearch(body, opts) {
-        // Consistency for hybrid graph search lives on the nested `search` options.
-        const consistency = this.resolveConsistency(opts);
-        const search = consistency !== undefined || opts?.minIndexedSeq !== undefined
-            ? this.mergeReadConsistency(body.search ?? {}, opts)
-            : body.search;
-        return this.request("POST", "/v1/graph/search", {
-            body: { ...body, search },
-        });
-    }
-    /** Reciprocal-rank-fusion across sub-queries. */
-    multiSearch(body) {
-        return this.request("POST", "/v1/search/multi", { body });
-    }
+    // --- relevance feedback ---
     /**
-     * Grounded prefix completion from the index vocabulary + ontology. Optionally
-     * narrow relation completions by a type-signature `context` — a type
-     * pair that admits a single relation flags `signature_forced`.
-     */
-    suggest(body) {
-        return this.request("POST", "/v1/search/suggest", { body });
-    }
-    /** Snap free text to the nearest term in the pinned published vocabulary. */
-    resolveTerm(body) {
-        return this.request("POST", "/v1/search/resolve-term", { body });
-    }
-    /** Decode a relation from the graph's admissible published vocabulary. */
-    decode(body) {
-        return this.request("POST", "/v1/decode", { body });
-    }
-    /** Report completion strategy fitness for the pinned published graph. */
-    groundability(opts = {}) {
-        return this.request("GET", "/v1/graph/groundability", {
-            query: opts.sample == null ? undefined : { sample: opts.sample },
-        });
-    }
-    /**
-     * Append relevance labels for a set of search results — how little big brain
+     * Append relevance labels for a set of ranked results — how little big brain
      * gathers customer-specific qrels. Grade results (3 ideal/good, 1 partial,
-     * 0 bad), referencing the search response's `search_id` so labels tie back to
-     * that ranking. Stored apart from customer facts and exported via
+     * 0 bad), referencing the ranking's `search_id` so labels tie back to it.
+     * Stored apart from customer facts and exported via
      * {@link searchFeedbackExport} as training/eval data for embedding fine-tuning.
      */
     searchFeedback(body, opts = {}) {
@@ -942,18 +836,6 @@ export class LbbClient {
     searchFeedbackExport() {
         return this.request("GET", "/v1/search/feedback/export");
     }
-    /** BM25 search. */
-    fullTextSearch(body, opts) {
-        return this.request("POST", "/v1/search/full-text", {
-            body: this.mergeReadConsistency(body, opts),
-        });
-    }
-    /** ANN/vector search. */
-    embeddingSearch(body, opts) {
-        return this.request("POST", "/v1/search/embedding", {
-            body: this.mergeReadConsistency(body, opts),
-        });
-    }
     /**
      * Ranked incoming/outgoing neighborhood for a graph entity.
      *
@@ -1075,16 +957,6 @@ export class LbbClient {
     async sparqlRows(body, opts) {
         return parseSparqlResults(await this.sparqlText(body, opts));
     }
-    /**
-     * Basic-graph-pattern query with group-graph-pattern combinators
-     * (UNION / OPTIONAL / MINUS / EXISTS / NOT EXISTS) folded over the base
-     * patterns. The complement to {@link sparql}: this route carries the
-     * combinators (but not FILTER/aggregation), so use it when a query needs an
-     * optional/union/negated leg rather than a grouped aggregate.
-     */
-    analytics(body) {
-        return this.request("POST", "/v1/query/analytics", { body });
-    }
     // --- ontology ---
     /**
      * The active ontology (entity types and relations) for the scoped graph.
@@ -1117,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 });
     }
@@ -1156,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/index.d.ts

@@ -1,3 +1,3 @@
 export { LbbCapabilityError, LbbClient, LbbError, parseSparqlResults, } from "./client.js";
-export type { DurableImportLine, DurableImportSource, LbbClientOptions, CallOptions, RequestOptions, HybridSearchOptions, LbbRequestEvent, LbbResponseEvent, FetchLike, ReadConsistencyOptions, SearchConsistency, Schemas, SparqlResults, SparqlResultsJson, SparqlTerm, CommitRequest, CommitResponse, Entity, EntitySelector, GraphMetadata, GraphSummary, SchemaView, SearchRequest, SearchResponse, SearchResult, Snapshot, } from "./client.js";
+export type { DurableImportLine, DurableImportSource, LbbClientOptions, CallOptions, RequestOptions, LbbRequestEvent, LbbResponseEvent, FetchLike, ReadConsistencyOptions, SearchConsistency, Schemas, SparqlResults, SparqlResultsJson, SparqlTerm, CommitRequest, CommitResponse, Entity, EntitySelector, GraphMetadata, GraphSummary, SchemaView, Snapshot, } from "./client.js";
 export type { components, paths, operations } from "./schema.js";