@littlebigbrain/client 0.6.1 → 0.8.0

package/dist/client.d.ts

@@ -1,8 +1,8 @@
-import type { ImportLine, LbbClientOptions, LbbStackActivityResponse, LbbStackActivityWindow, ListResponse, RawLbbResponse, RdfExportOptions, RdfImportOptions, Schemas, SparqlResults } from "./types.js";
-import { type RequestOptions } from "./transport.js";
+import type { ImportLine, LbbClientOptions, ListResponse, RawLbbResponse, ReadConsistencyOptions, RdfExportOptions, RdfImportOptions, Schemas, SearchConsistency, SparqlResults } from "./types.js";
+import { type CallOptions, type RequestOptions } from "./transport.js";
 import { ContextNamespace, EntityNamespace, GraphNamespace, IndexNamespace, OntologyNamespace, QueryNamespace, SchemaNamespace, SearchNamespace } from "./namespaces.js";
 export { parseSparqlResults } from "./types.js";
-export type { AttributeFilter, AttributeFilterOp, AttributeFilterValue, EntityAttributeFilterOptions, EntityPropertiesLine, FetchLike, FlatProperties, ImportLine, LbbClientOptions, LbbRequestEvent, LbbResponseEvent, LbbRetryEvent, LbbErrorPayload, LbbStackActivityResponse, LbbStackActivityWindow, ListResponse, RawLbbResponse, RdfExportOptions, RdfImportOptions, Schemas, SparqlResults, SparqlResultsJson, SparqlTerm, AskRequest, AskResponse, CommitRequest, CommitResponse, Entity, EntitySelector, GraphMetadata, GraphSummary, SchemaView, SearchRequest, SearchResponse, SearchResult, Snapshot, } from "./types.js";
+export type { AttributeFilter, AttributeFilterOp, AttributeFilterValue, EntityAttributeFilterOptions, EntityPropertiesLine, FetchLike, FlatProperties, ImportLine, LbbClientOptions, LbbRequestEvent, LbbResponseEvent, LbbRetryEvent, LbbErrorPayload, ListResponse, RawLbbResponse, ReadConsistencyOptions, RdfExportOptions, RdfImportOptions, Schemas, SearchConsistency, SparqlResults, SparqlResultsJson, SparqlTerm, AskRequest, AskResponse, CommitRequest, CommitResponse, Entity, EntitySelector, GraphMetadata, GraphSummary, SchemaView, SearchRequest, SearchResponse, SearchResult, Snapshot, } from "./types.js";
 export { LbbError } from "./transport.js";
 export type { CallOptions, Query, QueryValue, RequestOptions, } from "./transport.js";
 export type { EntityListOptions, HybridSearchOptions } from "./namespaces.js";
@@ -36,6 +36,8 @@ export declare class LbbClient {
     private readonly onRequest?;
     private readonly onResponse?;
     private readonly onRetry?;
+    /** A5 default read consistency applied when a read omits its own value. */
+    readonly defaultConsistency?: SearchConsistency;
     readonly context: ContextNamespace;
     readonly search: SearchNamespace;
     readonly indexes: IndexNamespace;
@@ -58,6 +60,17 @@ export declare class LbbClient {
         branch?: string;
         stack?: string;
     }): LbbClient;
+    /**
+     * A5: fold read-consistency options into a request body's own `consistency` /
+     * `min_indexed_seq` fields (the shape used by full-text, embedding, and
+     * structured-SPARQL bodies). A per-call value wins over the client
+     * `defaultConsistency`; an explicit body field wins over both.
+     */
+    resolveConsistency(opts?: ReadConsistencyOptions): SearchConsistency | undefined;
+    private mergeReadConsistency;
+    /** A5: read-consistency options rendered as URL query params, for the routes
+     * that carry consistency on the URL (SPARQL-text, graph summary). */
+    private readConsistencyQuery;
     private buildUrl;
     rawRequest<T>(method: string, path: string, opts?: RequestOptions): Promise<RawLbbResponse<T>>;
     request<T>(method: string, path: string, opts?: RequestOptions): Promise<T>;
@@ -66,7 +79,9 @@ export declare class LbbClient {
     /** Commit triplets and optional entity embeddings. Prefer `client.graph("main").facts.create(...)`. */
     commit(body: Schemas["TripletCommitFile"], opts?: {
         idempotencyKey?: string;
-    }): Promise<Schemas["GraphCommitResponse"]>;
+    }): Promise<Schemas["GraphCommitResponse"] & {
+        commitSeq: number;
+    }>;
     /**
      * Validate-only preflight: run the same ontology/schema validation a real
      * commit would and report the would-be effect (`op_count`, `written_properties`,
@@ -95,7 +110,9 @@ export declare class LbbClient {
         observedAt?: string;
         index?: boolean;
         idempotencyKey?: string;
-    }): Promise<Schemas["GraphImportResponse"]>;
+    }): Promise<Schemas["GraphImportResponse"] & {
+        commitSeq: number | null;
+    }>;
     /**
      * Bulk-ingest N-Triples, Turtle, N-Quads, or TriG without client-side conversion. Resource-object
      * triples become keyed Resource edges; literal-object triples become text
@@ -115,6 +132,42 @@ export declare class LbbClient {
     }): Promise<Schemas["GraphRetractResponse"]>;
     /** Create the scoped graph/branch. Construct the client with the desired graph/branch first. */
     createGraph(): Promise<Schemas["CreateGraphResponse"]>;
+    /**
+     * Fork a whole graph into a brand-new destination graph in the same tenant.
+     * The copy runs as a durable background job (`confirm` is fixed to `dst`, which
+     * the route requires to authorize the fork); the destination must not already
+     * exist, so the create-only CAS on the server side makes the call safe to
+     * retry. The response only acknowledges the enqueue — poll the destination
+     * graph's metadata (see `response.poll`) to observe the fork completing: the
+     * destination becomes readable once its head is published.
+     */
+    forkGraph(opts: {
+        src: string;
+        dst: string;
+    }): Promise<Schemas["GraphForkResponse"]>;
+    /**
+     * Declarative full-state replace: reconcile the scoped graph so its current
+     * state matches exactly the NDJSON payload (same line grammar as
+     * {@link import} — triplets or `{type,name,properties}` entity records; pass an
+     * array, serialized here, or a pre-built NDJSON string). The whole
+     * reconciliation lands as one atomic cutover: payload records are upserted, and
+     * entities present at the pre-reload head but absent from the payload leave
+     * current state (retraction semantics — history is preserved, so an `as_of`
+     * read pinned before the cutover still sees the old state). `confirm` must
+     * equal the target graph id (reload is semi-destructive). `dryRun` previews the
+     * full delta with zero durable changes. The response carries
+     * `prior_commit_seq` / `prior_snapshot_token` as the rollback anchor — read
+     * them back with `?as_of_commit_seq=<prior_commit_seq>` to see the pre-reload
+     * state. An Idempotency-Key scopes the single cutover commit, so a retry
+     * replays rather than re-applying.
+     */
+    reload(lines: ImportLine[] | string, opts: {
+        confirm: string;
+        dryRun?: boolean;
+        strict?: boolean;
+        observedAt?: string;
+        idempotencyKey?: string;
+    }): Promise<Schemas["GraphReloadResponse"]>;
     /** Fork the scoped branch from an existing branch in the same graph. */
     createBranch(body: Schemas["GraphBranchCreateRequest"]): Promise<Schemas["GraphBranchCreateResponse"]>;
     /**
@@ -324,7 +377,7 @@ export declare class LbbClient {
         allowRegression?: boolean;
     }): Promise<unknown>;
     /** Full semantic hybrid search from a request body (`POST /v1/graph/search`). */
-    graphSearch(body: Schemas["SemanticGraphSearchRequest"]): Promise<Schemas["SemanticGraphSearchResponse"]>;
+    graphSearch(body: Schemas["SemanticGraphSearchRequest"], opts?: ReadConsistencyOptions): Promise<Schemas["SemanticGraphSearchResponse"]>;
     /** Reciprocal-rank-fusion across sub-queries. */
     multiSearch(body: Schemas["HybridMultiSearchRequest"]): Promise<Schemas["HybridMultiSearchResponse"]>;
     /**
@@ -371,9 +424,9 @@ export declare class LbbClient {
     /** Export the stored relevance labels as qrels-style rows for training. */
     searchFeedbackExport(): Promise<Schemas["SearchFeedbackExportResponse"]>;
     /** BM25 search. */
-    fullTextSearch(body: Schemas["FullTextSearchRequest"]): Promise<Schemas["FullTextSearchResponse"]>;
+    fullTextSearch(body: Schemas["FullTextSearchRequest"], opts?: ReadConsistencyOptions): Promise<Schemas["FullTextSearchResponse"]>;
     /** ANN/vector search. */
-    embeddingSearch(body: Schemas["EmbeddingSearchRequest"]): Promise<Schemas["EmbeddingSearchResponse"]>;
+    embeddingSearch(body: Schemas["EmbeddingSearchRequest"], opts?: ReadConsistencyOptions): Promise<Schemas["EmbeddingSearchResponse"]>;
     /** Bounded k-hop graph traversal. */
     traverse(body: Schemas["TraverseRequest"]): Promise<Schemas["TraverseResponse"]>;
     /** Resolve a query to seed entities, then return bounded paths. */
@@ -385,7 +438,14 @@ export declare class LbbClient {
         name?: string;
         relations?: string[];
         asOf?: string;
+        /** Require the bounded ranged-adjacency path; returns `index_busy` while unavailable. */
+        indexed?: boolean;
     }): Promise<Schemas["EntityNeighborhoodResponse"]>;
+    /** Exact type cardinality plus a bounded deterministic sample from ranged adjacency. */
+    entityTypeSample(opts: {
+        type: string;
+        limit?: number;
+    } & CallOptions): Promise<Schemas["EntityTypeSampleResponse"]>;
     /** Stored entity object-ref status and index-coverage metadata (no
      * attributes — read those from `entityDetail`'s top-level `attributes`). */
     entityMetadata(opts: {
@@ -459,9 +519,9 @@ export declare class LbbClient {
      * keys come back per group in `groups[].value_keys[<as>]`, entity keys in
      * `groups[].keys`.
      */
-    sparql(body: Schemas["SparqlSelectRequest"]): Promise<Schemas["SparqlSelectResponse"]>;
-    /** SPARQL 1.1 query from text (SELECT/ASK) over the live graph; `results` is SPARQL 1.1 Query Results JSON. */
-    sparqlText(body: Schemas["SparqlTextRequest"]): Promise<Schemas["SparqlTextResponse"]>;
+    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. */
+    sparqlText(body: Schemas["SparqlTextRequest"], opts?: ReadConsistencyOptions): Promise<Schemas["SparqlTextResponse"]>;
     /**
      * Run a SPARQL 1.1 text query and return parsed results — the ergonomic
      * complement to {@link sparqlText} (which hands back the raw results string).
@@ -469,7 +529,7 @@ export declare class LbbClient {
      * `rows` is the bindings flattened to `{ variable: lexicalValue }`, `boolean`
      * is the ASK answer (or `null` for a SELECT).
      */
-    sparqlRows(body: Schemas["SparqlTextRequest"]): Promise<SparqlResults>;
+    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
@@ -581,16 +641,18 @@ export declare class LbbClient {
     }): Promise<Schemas["WalCompactResponse"]>;
     /** Server, graph, and persisted-index status. */
     status(): Promise<unknown>;
-    /** Graph footprint, WAL tail, and index coverage. */
-    metadata(): Promise<Schemas["GraphMetadataResponse"]>;
+    /** Graph footprint, WAL tail, and index coverage. Exact object inventory is opt-in. */
+    metadata(opts?: {
+        includeObjects?: boolean;
+        includeIndexes?: boolean;
+        includeTemporalCoverage?: boolean;
+    }): Promise<Schemas["GraphMetadataResponse"]>;
     waitForIndexLineage(targetSeq: number, opts?: {
         timeoutMs?: number;
         pollIntervalMs?: number;
     }): Promise<IndexLineageObservation>;
-    /** Graph counts and type/relation buckets. */
-    summary(): Promise<Schemas["GraphSummaryResponse"]>;
+    /** Graph counts and type/relation buckets. Carries `consistency`/`min_indexed_seq` on the URL. */
+    summary(opts?: ReadConsistencyOptions): Promise<Schemas["GraphSummaryResponse"]>;
     /** List the graphs (and branches) under the scoped tenant. */
     listGraphs(): Promise<Schemas["GraphListResponse"]>;
-    /** Activity for the stack selected by the bearer stack key or session. */
-    stackActivity(window?: LbbStackActivityWindow): Promise<LbbStackActivityResponse>;
 }

package/dist/client.js

@@ -24,6 +24,8 @@ export class LbbClient {
     onRequest;
     onResponse;
     onRetry;
+    /** A5 default read consistency applied when a read omits its own value. */
+    defaultConsistency;
     context;
     search;
     indexes;
@@ -49,6 +51,7 @@ export class LbbClient {
         this.onRequest = options.onRequest;
         this.onResponse = options.onResponse;
         this.onRetry = options.onRetry;
+        this.defaultConsistency = options.defaultConsistency;
         if (!Number.isInteger(this.maxRetries) || this.maxRetries < 0) {
             throw new RangeError("maxRetries must be a non-negative integer");
         }
@@ -103,8 +106,38 @@ export class LbbClient {
             onRequest: this.onRequest,
             onResponse: this.onResponse,
             onRetry: this.onRetry,
+            defaultConsistency: this.defaultConsistency,
         });
     }
+    /**
+     * A5: fold read-consistency options into a request body's own `consistency` /
+     * `min_indexed_seq` fields (the shape used by full-text, embedding, and
+     * structured-SPARQL bodies). A per-call value wins over the client
+     * `defaultConsistency`; an explicit body field wins over both.
+     */
+    resolveConsistency(opts) {
+        return opts?.consistency ?? this.defaultConsistency;
+    }
+    mergeReadConsistency(body, opts) {
+        const consistency = this.resolveConsistency(opts);
+        const merged = { ...body };
+        if (consistency !== undefined && merged.consistency === undefined) {
+            merged.consistency = consistency;
+        }
+        if (opts?.minIndexedSeq !== undefined &&
+            merged.min_indexed_seq === undefined) {
+            merged.min_indexed_seq = opts.minIndexedSeq;
+        }
+        return merged;
+    }
+    /** A5: read-consistency options rendered as URL query params, for the routes
+     * that carry consistency on the URL (SPARQL-text, graph summary). */
+    readConsistencyQuery(opts) {
+        return {
+            consistency: this.resolveConsistency(opts),
+            min_indexed_seq: opts?.minIndexedSeq,
+        };
+    }
     buildUrl(path, query) {
         const params = [];
         const push = (key, value) => params.push(`${encodeURIComponent(key)}=${encodeURIComponent(String(value))}`);
@@ -292,11 +325,14 @@ export class LbbClient {
     }
     // --- writes ---
     /** Commit triplets and optional entity embeddings. Prefer `client.graph("main").facts.create(...)`. */
-    commit(body, opts = {}) {
-        return this.request("POST", "/v1/graph/commit", {
+    async commit(body, opts = {}) {
+        const response = await this.request("POST", "/v1/graph/commit", {
             body,
             idempotencyKey: opts.idempotencyKey ?? this.idempotencyKey("facts.create"),
         });
+        // A5: surface the committed sequence as `commitSeq` so the write→floor→read
+        // loop reads naturally: `const { commitSeq } = await client.commit(…)`.
+        return { ...response, commitSeq: response.commit_seq };
     }
     /**
      * Validate-only preflight: run the same ontology/schema validation a real
@@ -325,11 +361,11 @@ export class LbbClient {
      * the throttle): import the whole dataset, index once. The response's `index`
      * object reports whether the build ran or was skipped.
      */
-    import(lines, opts = {}) {
+    async import(lines, opts = {}) {
         const ndjson = typeof lines === "string"
             ? lines
             : lines.map((line) => JSON.stringify(line)).join("\n");
-        return this.request("POST", "/v1/graph/import", {
+        const response = await this.request("POST", "/v1/graph/import", {
             rawBody: ndjson,
             contentType: "application/x-ndjson",
             query: {
@@ -340,6 +376,9 @@ export class LbbClient {
             },
             idempotencyKey: opts.idempotencyKey ?? this.idempotencyKey("import"),
         });
+        // A5: surface the last committed sequence (null for an empty import) so the
+        // write→floor→read loop reads naturally after a bulk load.
+        return { ...response, commitSeq: response.committed_commit_seq ?? null };
     }
     /**
      * Bulk-ingest N-Triples, Turtle, N-Quads, or TriG without client-side conversion. Resource-object
@@ -400,6 +439,53 @@ export class LbbClient {
     createGraph() {
         return this.request("POST", "/v1/graph/create");
     }
+    /**
+     * Fork a whole graph into a brand-new destination graph in the same tenant.
+     * The copy runs as a durable background job (`confirm` is fixed to `dst`, which
+     * the route requires to authorize the fork); the destination must not already
+     * exist, so the create-only CAS on the server side makes the call safe to
+     * retry. The response only acknowledges the enqueue — poll the destination
+     * graph's metadata (see `response.poll`) to observe the fork completing: the
+     * destination becomes readable once its head is published.
+     */
+    forkGraph(opts) {
+        return this.request("POST", "/v1/graph/fork", {
+            query: { src: opts.src, dst: opts.dst, confirm: opts.dst },
+            retry: true,
+        });
+    }
+    /**
+     * Declarative full-state replace: reconcile the scoped graph so its current
+     * state matches exactly the NDJSON payload (same line grammar as
+     * {@link import} — triplets or `{type,name,properties}` entity records; pass an
+     * array, serialized here, or a pre-built NDJSON string). The whole
+     * reconciliation lands as one atomic cutover: payload records are upserted, and
+     * entities present at the pre-reload head but absent from the payload leave
+     * current state (retraction semantics — history is preserved, so an `as_of`
+     * read pinned before the cutover still sees the old state). `confirm` must
+     * equal the target graph id (reload is semi-destructive). `dryRun` previews the
+     * full delta with zero durable changes. The response carries
+     * `prior_commit_seq` / `prior_snapshot_token` as the rollback anchor — read
+     * them back with `?as_of_commit_seq=<prior_commit_seq>` to see the pre-reload
+     * state. An Idempotency-Key scopes the single cutover commit, so a retry
+     * replays rather than re-applying.
+     */
+    reload(lines, opts) {
+        const ndjson = typeof lines === "string"
+            ? lines
+            : lines.map((line) => JSON.stringify(line)).join("\n");
+        return this.request("POST", "/v1/graph/reload", {
+            rawBody: ndjson,
+            contentType: "application/x-ndjson",
+            query: {
+                confirm: opts.confirm,
+                dry_run: opts.dryRun,
+                strict: opts.strict,
+                observed_at: opts.observedAt,
+            },
+            idempotencyKey: opts.idempotencyKey ?? this.idempotencyKey("reload"),
+        });
+    }
     /** Fork the scoped branch from an existing branch in the same graph. */
     createBranch(body) {
         return this.request("POST", "/v1/graph/branch", { body });
@@ -692,8 +778,15 @@ export class LbbClient {
     }
     // --- search ---
     /** Full semantic hybrid search from a request body (`POST /v1/graph/search`). */
-    graphSearch(body) {
-        return this.request("POST", "/v1/graph/search", { body });
+    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) {
@@ -758,12 +851,16 @@ export class LbbClient {
         return this.request("GET", "/v1/search/feedback/export");
     }
     /** BM25 search. */
-    fullTextSearch(body) {
-        return this.request("POST", "/v1/search/full-text", { body });
+    fullTextSearch(body, opts) {
+        return this.request("POST", "/v1/search/full-text", {
+            body: this.mergeReadConsistency(body, opts),
+        });
     }
     /** ANN/vector search. */
-    embeddingSearch(body) {
-        return this.request("POST", "/v1/search/embedding", { body });
+    embeddingSearch(body, opts) {
+        return this.request("POST", "/v1/search/embedding", {
+            body: this.mergeReadConsistency(body, opts),
+        });
     }
     // --- traversal ---
     /** Bounded k-hop graph traversal. */
@@ -783,9 +880,18 @@ export class LbbClient {
                 name: opts.name,
                 relations: opts.relations?.join(","),
                 as_of: opts.asOf,
+                indexed: opts.indexed,
             },
         });
     }
+    /** Exact type cardinality plus a bounded deterministic sample from ranged adjacency. */
+    entityTypeSample(opts) {
+        const { type, limit, ...request } = opts;
+        return this.request("GET", "/v1/graph/entities/sample", {
+            ...request,
+            query: { type, limit },
+        });
+    }
     /** Stored entity object-ref status and index-coverage metadata (no
      * attributes — read those from `entityDetail`'s top-level `attributes`). */
     entityMetadata(opts) {
@@ -890,12 +996,17 @@ export class LbbClient {
      * keys come back per group in `groups[].value_keys[<as>]`, entity keys in
      * `groups[].keys`.
      */
-    sparql(body) {
-        return this.request("POST", "/v1/query/sparql", { body });
+    sparql(body, opts) {
+        return this.request("POST", "/v1/query/sparql", {
+            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. */
-    sparqlText(body) {
-        return this.request("POST", "/v1/query/sparql-text", { body });
+    /** 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. */
+    sparqlText(body, opts) {
+        return this.request("POST", "/v1/query/sparql-text", {
+            body,
+            query: this.readConsistencyQuery(opts),
+        });
     }
     /**
      * Run a SPARQL 1.1 text query and return parsed results — the ergonomic
@@ -904,8 +1015,8 @@ export class LbbClient {
      * `rows` is the bindings flattened to `{ variable: lexicalValue }`, `boolean`
      * is the ASK answer (or `null` for a SELECT).
      */
-    async sparqlRows(body) {
-        return parseSparqlResults(await this.sparqlText(body));
+    async sparqlRows(body, opts) {
+        return parseSparqlResults(await this.sparqlText(body, opts));
     }
     /**
      * Basic-graph-pattern query with group-graph-pattern combinators
@@ -1078,9 +1189,15 @@ export class LbbClient {
     status() {
         return this.request("GET", "/v1/status");
     }
-    /** Graph footprint, WAL tail, and index coverage. */
-    metadata() {
-        return this.request("GET", "/v1/graph/metadata");
+    /** Graph footprint, WAL tail, and index coverage. Exact object inventory is opt-in. */
+    metadata(opts = {}) {
+        return this.request("GET", "/v1/graph/metadata", {
+            query: {
+                include_objects: opts.includeObjects,
+                include_indexes: opts.includeIndexes,
+                include_temporal_coverage: opts.includeTemporalCoverage,
+            },
+        });
     }
     async waitForIndexLineage(targetSeq, opts = {}) {
         const deadline = Date.now() + (opts.timeoutMs ?? 30_000);
@@ -1113,17 +1230,14 @@ export class LbbClient {
             await sleep(opts.pollIntervalMs ?? 250);
         }
     }
-    /** Graph counts and type/relation buckets. */
-    summary() {
-        return this.request("GET", "/v1/graph/summary");
+    /** Graph counts and type/relation buckets. Carries `consistency`/`min_indexed_seq` on the URL. */
+    summary(opts) {
+        return this.request("GET", "/v1/graph/summary", {
+            query: this.readConsistencyQuery(opts),
+        });
     }
     /** List the graphs (and branches) under the scoped tenant. */
     listGraphs() {
         return this.request("GET", "/v1/graphs");
     }
-    // --- stack activity ---
-    /** Activity for the stack selected by the bearer stack key or session. */
-    stackActivity(window = "24h") {
-        return this.request("GET", "/v1/stack/activity", { query: { window } });
-    }
 }

package/dist/index.d.ts

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

package/dist/namespaces.d.ts

@@ -1,10 +1,14 @@
 import type { LbbClient } from "./client.js";
 import type { CallOptions } from "./transport.js";
-import { type EntityAttributeFilterOptions, type ImportLine, type ListResponse, type RdfExportOptions, type RdfImportOptions, type Schemas } from "./types.js";
+import { type EntityAttributeFilterOptions, type ImportLine, type ListResponse, type ReadConsistencyOptions, type RdfExportOptions, type RdfImportOptions, type Schemas } from "./types.js";
 export interface HybridSearchOptions extends CallOptions {
     topK?: number;
     source?: string;
     consistency?: string;
+    /** A5 read-your-writes floor (`min_indexed_seq`): the committed sequence a
+     * write returned; under eventual, an uncovered floor yields a retryable
+     * `read_your_writes_pending` 429. */
+    minIndexedSeq?: number;
     lexical?: boolean;
     bm25?: boolean;
     vector?: boolean;
@@ -96,8 +100,8 @@ export declare class SearchNamespace {
     feedback(body: Schemas["SearchFeedbackRequest"], opts?: CallOptions): Promise<Schemas["SearchFeedbackResponse"]>;
     feedbackExport(opts?: CallOptions): Promise<Schemas["SearchFeedbackExportResponse"]>;
     feedbackSummary(opts?: CallOptions): Promise<Schemas["SearchFeedbackSummaryResponse"]>;
-    fullText(body: Schemas["FullTextSearchRequest"], opts?: CallOptions): Promise<Schemas["FullTextSearchResponse"]>;
-    vector(body: Schemas["EmbeddingSearchRequest"], opts?: CallOptions): Promise<Schemas["EmbeddingSearchResponse"]>;
+    fullText(body: Schemas["FullTextSearchRequest"], opts?: CallOptions & ReadConsistencyOptions): Promise<Schemas["FullTextSearchResponse"]>;
+    vector(body: Schemas["EmbeddingSearchRequest"], opts?: CallOptions & ReadConsistencyOptions): Promise<Schemas["EmbeddingSearchResponse"]>;
 }
 export declare class SchemaNamespace {
     private readonly client;
@@ -143,6 +147,15 @@ export declare class IndexNamespace {
 export declare class EntityNamespace {
     private readonly client;
     constructor(client: LbbClient);
+    /**
+     * Return the exact type cardinality and a bounded deterministic sample from
+     * the ranged adjacency index. The server returns `index_busy` rather than
+     * falling back to an exhaustive snapshot scan when the index is unavailable.
+     */
+    sample(opts: {
+        type: string;
+        limit?: number;
+    } & CallOptions): Promise<Schemas["EntityTypeSampleResponse"]>;
     /**
      * Browse entities as the unified list envelope. Pass `fields` (names or `*`)
      * to inline each row's typed attributes as native JSON (under `attributes`) —
@@ -216,9 +229,9 @@ export declare class OntologyNamespace {
 export declare class QueryNamespace {
     private readonly client;
     constructor(client: LbbClient);
-    structured(body: Schemas["SparqlSelectRequest"], opts?: CallOptions): Promise<Schemas["SparqlSelectResponse"]>;
-    sparql(body: Schemas["SparqlTextRequest"], opts?: CallOptions): Promise<import("./types.js").SparqlResults>;
-    sparqlRaw(body: Schemas["SparqlTextRequest"], opts?: CallOptions): Promise<Schemas["SparqlTextResponse"]>;
+    structured(body: Schemas["SparqlSelectRequest"], opts?: CallOptions & ReadConsistencyOptions): Promise<Schemas["SparqlSelectResponse"]>;
+    sparql(body: Schemas["SparqlTextRequest"], opts?: CallOptions & ReadConsistencyOptions): Promise<import("./types.js").SparqlResults>;
+    sparqlRaw(body: Schemas["SparqlTextRequest"], opts?: CallOptions & ReadConsistencyOptions): Promise<Schemas["SparqlTextResponse"]>;
     analytics(body: Schemas["AnalyticQueryRequest"], opts?: CallOptions): Promise<Schemas["AnalyticQueryResponse"]>;
     shacl(body: Schemas["ShaclQueryRequest"], opts?: CallOptions): Promise<Schemas["ShaclQueryResponse"]>;
     infer(body: Schemas["InferenceRunRequest"], opts?: CallOptions): Promise<Schemas["InferenceRunResponse"]>;

package/dist/namespaces.js

@@ -1,4 +1,18 @@
 import { attributeFilter, firstPatternVariable, parseSparqlResults, } from "./types.js";
+/** A5: fold read-consistency options into a request body's `consistency` /
+ * `min_indexed_seq` fields; a per-call value wins over the client default. */
+function withReadConsistency(client, body, opts) {
+    const consistency = opts.consistency ?? client.defaultConsistency;
+    const merged = { ...body };
+    if (consistency !== undefined && merged.consistency === undefined) {
+        merged.consistency = consistency;
+    }
+    if (opts.minIndexedSeq !== undefined &&
+        merged.min_indexed_seq === undefined) {
+        merged.min_indexed_seq = opts.minIndexedSeq;
+    }
+    return merged;
+}
 function transportOptions(options) {
     return {
         idempotencyKey: options.idempotencyKey,
@@ -186,10 +200,14 @@ export class SearchNamespace {
     }
     hybrid(input, opts = {}) {
         if (typeof input !== "string") {
+            const search = withReadConsistency(this.client, input.search ?? {}, {
+                consistency: opts.consistency,
+                minIndexedSeq: opts.minIndexedSeq,
+            });
             return this.client.request("POST", "/v1/graph/search", {
                 ...transportOptions(opts),
                 retry: opts.retry ?? true,
-                body: input,
+                body: { ...input, search },
             });
         }
         return this.client.request("GET", "/v1/search", {
@@ -198,7 +216,8 @@ export class SearchNamespace {
                 query: input,
                 top_k: opts.topK,
                 source: opts.source,
-                consistency: opts.consistency,
+                consistency: opts.consistency ?? this.client.defaultConsistency,
+                min_indexed_seq: opts.minIndexedSeq,
                 lexical: opts.lexical,
                 bm25: opts.bm25,
                 vector: opts.vector,
@@ -233,14 +252,14 @@ export class SearchNamespace {
         return this.client.request("POST", "/v1/search/full-text", {
             ...opts,
             retry: opts.retry ?? true,
-            body,
+            body: withReadConsistency(this.client, body, opts),
         });
     }
     vector(body, opts = {}) {
         return this.client.request("POST", "/v1/search/embedding", {
             ...opts,
             retry: opts.retry ?? true,
-            body,
+            body: withReadConsistency(this.client, body, opts),
         });
     }
 }
@@ -344,6 +363,14 @@ export class EntityNamespace {
     constructor(client) {
         this.client = client;
     }
+    /**
+     * Return the exact type cardinality and a bounded deterministic sample from
+     * the ranged adjacency index. The server returns `index_busy` rather than
+     * falling back to an exhaustive snapshot scan when the index is unavailable.
+     */
+    sample(opts) {
+        return this.client.entityTypeSample(opts);
+    }
     /**
      * Browse entities as the unified list envelope. Pass `fields` (names or `*`)
      * to inline each row's typed attributes as native JSON (under `attributes`) —
@@ -529,11 +556,20 @@ export class QueryNamespace {
         return this.client.request("POST", "/v1/query/sparql", {
             ...opts,
             retry: opts.retry ?? true,
-            body,
+            body: withReadConsistency(this.client, body, opts),
         });
     }
     async sparql(body, opts = {}) {
-        const response = await this.client.request("POST", "/v1/query/sparql-text", { ...opts, retry: opts.retry ?? true, body });
+        // The text dialect carries consistency/floor on the URL, not the body.
+        const response = await this.client.request("POST", "/v1/query/sparql-text", {
+            ...opts,
+            retry: opts.retry ?? true,
+            body,
+            query: {
+                consistency: opts.consistency ?? this.client.defaultConsistency,
+                min_indexed_seq: opts.minIndexedSeq,
+            },
+        });
         return parseSparqlResults(response);
     }
     sparqlRaw(body, opts = {}) {
@@ -541,6 +577,10 @@ export class QueryNamespace {
             ...opts,
             retry: opts.retry ?? true,
             body,
+            query: {
+                consistency: opts.consistency ?? this.client.defaultConsistency,
+                min_indexed_seq: opts.minIndexedSeq,
+            },
         });
     }
     analytics(body, opts = {}) {