@littlebigbrain/client 0.7.0 → 0.8.0

package/dist/client.d.ts

@@ -1,8 +1,8 @@
-import type { ImportLine, LbbClientOptions, ListResponse, RawLbbResponse, RdfExportOptions, RdfImportOptions, Schemas, SparqlResults } from "./types.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, 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
@@ -360,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"]>;
     /**
@@ -407,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. */
@@ -502,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).
@@ -512,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
@@ -634,8 +651,8 @@ export declare class LbbClient {
         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"]>;
 }

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
@@ -739,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) {
@@ -805,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. */
@@ -946,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
@@ -960,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
@@ -1175,9 +1230,11 @@ 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() {

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, 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;
@@ -225,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),
         });
     }
 }
@@ -537,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 = {}) {
@@ -549,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 = {}) {

package/dist/schema.d.ts

@@ -2969,6 +2969,7 @@ export interface components {
             facets?: components["schemas"]["FacetRequest"][] | null;
             filters?: null | components["schemas"]["SearchFilterExpr"];
             max_clusters?: number | null;
+            min_indexed_seq?: null | components["schemas"]["CommitSeq"];
             probe_count?: number | null;
             provider?: null | components["schemas"]["EmbeddingProviderConfig"];
             query: string;
@@ -3474,6 +3475,7 @@ export interface components {
             explain: boolean;
             facets?: components["schemas"]["FacetRequest"][] | null;
             filters?: null | components["schemas"]["SearchFilterExpr"];
+            min_indexed_seq?: null | components["schemas"]["CommitSeq"];
             /**
              * @description Number of leading results to skip after ordering, for stateless paging:
              *     `offset = page * top_k` walks pages deterministically. Defaults to 0.
@@ -6347,7 +6349,19 @@ export interface components {
             /** Format: float */
             weighted_score: number;
         };
-        /** @enum {string} */
+        /**
+         * @description Read consistency for a query surface (search, graph summary, SPARQL).
+         *
+         *     A5 (2026-07-21 product decision): `Eventual` is the **default**. It serves the
+         *     last published index/dataset state at its watermark with no in-memory fold of
+         *     the un-indexed tail — the lowest-latency mode and the availability floor
+         *     during any indexing backlog. The served watermark rides back on
+         *     `SnapshotView::served_at_seq`. `Strong` (fold the un-indexed tail up to the
+         *     query head) is now explicit opt-in; the precise read-your-writes contract
+         *     (`min_indexed_seq`) replaces most former uses of strong. See
+         *     `docs/architecture/segment-native-indexing.md` §6.
+         * @enum {string}
+         */
         SearchConsistency: "strong" | "eventual";
         SearchEngineOptions: {
             bm25?: boolean;
@@ -6360,6 +6374,7 @@ export interface components {
             graph_anchor?: null | components["schemas"]["GraphAnchor"];
             lexical?: boolean;
             max_clusters?: number | null;
+            min_indexed_seq?: null | components["schemas"]["CommitSeq"];
             probe_count?: number | null;
             profile?: null | components["schemas"]["RetrievalProfileId"];
             provider?: null | components["schemas"]["EmbeddingProviderConfig"];
@@ -7688,6 +7703,7 @@ export interface components {
              *     `GET /v1/graph/metadata` and on the entity read's metadata.
              */
             compacted_seq: components["schemas"]["CommitSeq"];
+            served_at_seq?: null | components["schemas"]["CommitSeq"];
             /**
              * @description F2 (roadmap 18.3): true when this snapshot was served from the in-memory
              *     cache while storage was degraded and the latest head could not be
@@ -7697,8 +7713,9 @@ export interface components {
              */
             stale?: boolean;
             /**
-             * @description The reason a read is `stale` (F2). `"storage_degraded"` today; omitted
-             *     when not stale.
+             * @description The reason a read is `stale`. `"storage_degraded"` (F2) or
+             *     `"eventual_consistency"` (A3: served from the last published index/dataset
+             *     state at [`Self::served_at_seq`], not head); omitted when not stale.
              */
             stale_reason?: string | null;
         };
@@ -7875,6 +7892,7 @@ export interface components {
              *     Projection, DISTINCT, and limit/offset are ignored.
              */
             ask?: boolean;
+            consistency?: null | components["schemas"]["SearchConsistency"];
             /** @description `SELECT DISTINCT`: drop duplicate projected rows. */
             distinct?: boolean;
             /**
@@ -7919,6 +7937,7 @@ export interface components {
              *     (see `AnalyticQueryRequest::max_solutions`).
              */
             max_solutions?: number | null;
+            min_indexed_seq?: null | components["schemas"]["CommitSeq"];
             /** @description Skip this many rows before `limit`. */
             offset?: number | null;
             /**
@@ -8035,6 +8054,7 @@ export interface components {
             /** @description SPARQL 1.1 Query Results JSON, serialized. */
             results: string;
             row_page: components["schemas"]["RowPage"];
+            snapshot?: null | components["schemas"]["SnapshotView"];
         };
         /**
          * @description A literal constant operand in a FILTER. Scalars compare by typed value;

package/dist/types.d.ts

@@ -192,6 +192,32 @@ export interface LbbClientOptions {
     onResponse?: (event: LbbResponseEvent) => void;
     /** Called before each backoff sleep, so absorbed retries are observable. Bodies and credentials are never included. */
     onRetry?: (event: LbbRetryEvent) => void;
+    /**
+     * A5 default read consistency, applied when a read call omits its own
+     * `consistency`. Since A5 the server default is `eventual`; set `"strong"`
+     * here to keep every read head-exact by default (carried across `withScope`).
+     * A per-call `consistency` always wins.
+     */
+    defaultConsistency?: SearchConsistency;
+}
+/** A5 read consistency level. Since A5 the server default is `eventual`. */
+export type SearchConsistency = "strong" | "eventual";
+/**
+ * A5 read-consistency options shared by the query / search / summary surfaces.
+ * Merged into the request as `consistency` / `min_indexed_seq`; a per-call value
+ * wins over the client's `defaultConsistency`.
+ */
+export interface ReadConsistencyOptions {
+    /** Read consistency. Omit to use the client's `defaultConsistency`, else the
+     * server default (`eventual`). */
+    consistency?: SearchConsistency;
+    /**
+     * Read-your-writes floor: require the read to be served from state whose
+     * watermark ≥ this `commit_seq` (the committed sequence a write returned).
+     * Under eventual, a floor not yet covered yields a retryable
+     * `read_your_writes_pending` `429` — poll until the write lands.
+     */
+    minIndexedSeq?: number;
 }
 export interface LbbRequestEvent {
     method: string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@littlebigbrain/client",
-  "version": "0.7.0",
+  "version": "0.8.0",
   "description": "TypeScript client for the little big brain graph + hybrid search HTTP API",
   "license": "Apache-2.0",
   "repository": {