@littlebigbrain/client 0.9.0 → 0.10.0

package/README.md

@@ -90,7 +90,8 @@ console.log(completed.state, 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`.
+have already reached `committed_commit_seq`. 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:
 

package/dist/client.d.ts

@@ -400,19 +400,22 @@ export declare class LbbClient {
     fullTextSearch(body: Schemas["FullTextSearchRequest"], opts?: ReadConsistencyOptions): Promise<Schemas["FullTextSearchResponse"]>;
     /** ANN/vector search. */
     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. */
-    semanticTraverse(body: Schemas["SemanticTraverseRequest"]): Promise<Schemas["SemanticTraverseResponse"]>;
-    /** Ranked incoming/outgoing neighborhood for a graph entity. */
+    /**
+     * Ranked incoming/outgoing neighborhood for a graph entity.
+     *
+     * `edges` caps the edges returned per direction (default 1000, maximum
+     * 10000). When a cap cuts a direction the response carries a `truncation`
+     * block; an uncut response omits it entirely.
+     */
     entityNeighborhood(opts: {
         id?: string;
         type?: string;
         name?: string;
         relations?: string[];
         asOf?: string;
+        edges?: number;
     }): Promise<Schemas["EntityNeighborhoodResponse"]>;
-    /** Exact type cardinality plus a bounded deterministic sample from ranged adjacency. */
+    /** Exact type cardinality plus a bounded deterministic sample from Base. */
     entityTypeSample(opts: {
         type: string;
         limit?: number;

package/dist/client.js

@@ -29,14 +29,27 @@ function durableImportIterator(source) {
         },
     };
 }
-function durableImportBody(source) {
+async function durableImportBody(source) {
     const iterator = durableImportIterator(source);
+    const first = await iterator.next();
+    if (first.done) {
+        await iterator.return?.();
+        throw new TypeError("submitImport requires at least one NDJSON record or byte chunk");
+    }
+    let firstPending = true;
+    const next = async () => {
+        if (firstPending) {
+            firstPending = false;
+            return { done: false, value: first.value };
+        }
+        return iterator.next();
+    };
     const Stream = globalThis.ReadableStream;
     if (Stream) {
         return new Stream({
             async pull(controller) {
                 try {
-                    const item = await iterator.next();
+                    const item = await next();
                     if (item.done) {
                         controller.close();
                     }
@@ -57,7 +70,7 @@ function durableImportBody(source) {
         async *[Symbol.asyncIterator]() {
             try {
                 for (;;) {
-                    const item = await iterator.next();
+                    const item = await next();
                     if (item.done)
                         return;
                     yield durableImportBytes(item.value);
@@ -467,8 +480,9 @@ export class LbbClient {
             throw new TypeError("submitImport requires a non-empty idempotencyKey");
         }
         await this.requireCapability("durable_import_jobs_v1");
+        const rawBody = await durableImportBody(lines);
         return this.request("POST", "/v1/graph/import-jobs", {
-            rawBody: durableImportBody(lines),
+            rawBody,
             contentType: "application/x-ndjson",
             duplex: "half",
             query: {
@@ -546,6 +560,7 @@ export class LbbClient {
                 blank_node_scope: opts.blankNodeScope,
                 resource_type: opts.resourceType,
                 edge_idempotency: opts.edgeIdempotency,
+                build: opts.build,
             },
             idempotencyKey: opts.idempotencyKey ?? this.idempotencyKey("import-rdf"),
         });
@@ -939,16 +954,13 @@ export class LbbClient {
             body: this.mergeReadConsistency(body, opts),
         });
     }
-    // --- traversal ---
-    /** Bounded k-hop graph traversal. */
-    traverse(body) {
-        return this.request("POST", "/v1/graph/traverse", { body });
-    }
-    /** Resolve a query to seed entities, then return bounded paths. */
-    semanticTraverse(body) {
-        return this.request("POST", "/v1/graph/semantic-traverse", { body });
-    }
-    /** Ranked incoming/outgoing neighborhood for a graph entity. */
+    /**
+     * Ranked incoming/outgoing neighborhood for a graph entity.
+     *
+     * `edges` caps the edges returned per direction (default 1000, maximum
+     * 10000). When a cap cuts a direction the response carries a `truncation`
+     * block; an uncut response omits it entirely.
+     */
     entityNeighborhood(opts) {
         return this.request("GET", "/v1/graph/entity/neighborhood", {
             query: {
@@ -957,10 +969,11 @@ export class LbbClient {
                 name: opts.name,
                 relations: opts.relations?.join(","),
                 as_of: opts.asOf,
+                edges: opts.edges,
             },
         });
     }
-    /** Exact type cardinality plus a bounded deterministic sample from ranged adjacency. */
+    /** Exact type cardinality plus a bounded deterministic sample from Base. */
     entityTypeSample(opts) {
         const { type, limit, ...request } = opts;
         return this.request("GET", "/v1/graph/entities/sample", {
@@ -1153,9 +1166,7 @@ export class LbbClient {
                 lineage.bm25_indexed_commit_seq != null &&
                 lineage.bm25_indexed_commit_seq >= targetSeq &&
                 lineage.ann_indexed_commit_seq != null &&
-                lineage.ann_indexed_commit_seq >= targetSeq &&
-                lineage.adjacency_indexed_commit_seq != null &&
-                lineage.adjacency_indexed_commit_seq >= targetSeq) {
+                lineage.ann_indexed_commit_seq >= targetSeq) {
                 return {
                     metadata: last.data,
                     lineage,

package/dist/namespaces.d.ts

@@ -99,8 +99,7 @@ export declare class EntityNamespace {
     constructor(client: LbbClient);
     /**
      * Return the exact type cardinality and a bounded deterministic sample from
-     * the ranged adjacency family pinned by the published generation. A missing
-     * family fails closed rather than falling back to an exhaustive scan.
+     * the Base family pinned by the published generation.
      */
     sample(opts: {
         type: string;

package/dist/namespaces.js

@@ -162,7 +162,7 @@ export class FactsNamespace {
      * predicates and literal term details are preserved as edge metadata.
      */
     importRdf(rdf, opts = {}) {
-        const { format = "ntriples", baseIri, graphUri, blankNodeScope, batch, strict, observedAt, resourceType, edgeIdempotency, ...request } = opts;
+        const { format = "ntriples", baseIri, graphUri, blankNodeScope, batch, strict, observedAt, resourceType, edgeIdempotency, build, ...request } = opts;
         return this.client.request("POST", "/v1/graph/import/rdf", {
             ...request,
             idempotencyKey: request.idempotencyKey ?? this.client.idempotencyKey("import-rdf"),
@@ -183,6 +183,7 @@ export class FactsNamespace {
                 blank_node_scope: blankNodeScope,
                 resource_type: resourceType,
                 edge_idempotency: edgeIdempotency,
+                build,
             },
         });
     }
@@ -261,8 +262,7 @@ export class EntityNamespace {
     }
     /**
      * Return the exact type cardinality and a bounded deterministic sample from
-     * the ranged adjacency family pinned by the published generation. A missing
-     * family fails closed rather than falling back to an exhaustive scan.
+     * the Base family pinned by the published generation.
      */
     sample(opts) {
         return this.client.entityTypeSample(opts);

package/dist/schema.d.ts

@@ -337,7 +337,7 @@ export interface paths {
             path?: never;
             cookie?: never;
         };
-        /** Bounded class sample from the ranged adjacency index */
+        /** Bounded class sample from the published Base family */
         get: operations["get_v1_graph_entities_sample"];
         put?: never;
         post?: never;
@@ -605,23 +605,6 @@ export interface paths {
         patch?: never;
         trace?: never;
     };
-    "/v1/graph/semantic-traverse": {
-        parameters: {
-            query?: never;
-            header?: never;
-            path?: never;
-            cookie?: never;
-        };
-        get?: never;
-        put?: never;
-        /** Resolve a query to seeds, then return bounded paths */
-        post: operations["post_v1_graph_semantic_traverse"];
-        delete?: never;
-        options?: never;
-        head?: never;
-        patch?: never;
-        trace?: never;
-    };
     "/v1/graph/summary": {
         parameters: {
             query?: never;
@@ -639,24 +622,6 @@ export interface paths {
         patch?: never;
         trace?: never;
     };
-    "/v1/graph/traverse": {
-        parameters: {
-            query?: never;
-            header?: never;
-            path?: never;
-            cookie?: never;
-        };
-        /** Bounded graph traversal (query-string convenience) */
-        get: operations["get_v1_graph_traverse"];
-        put?: never;
-        /** Bounded graph traversal */
-        post: operations["post_v1_graph_traverse"];
-        delete?: never;
-        options?: never;
-        head?: never;
-        patch?: never;
-        trace?: never;
-    };
     "/v1/graphs": {
         parameters: {
             query?: never;
@@ -1179,7 +1144,7 @@ export interface paths {
         };
         get?: never;
         put?: never;
-        /** Basic-graph-pattern (BGP) analytic query over the permutation view */
+        /** Basic-graph-pattern (BGP) analytic query over the published RDF dataset */
         post: operations["post_v1_query_analytics"];
         delete?: never;
         options?: never;
@@ -1807,7 +1772,7 @@ export interface components {
         /**
          * @description A basic-graph-pattern query: a conjunction of triple patterns evaluated over
          *     the graph's current edges (joined on shared variables), served from the
-         *     object-storage permutation view.
+         *     conformant published RDF dataset.
          */
         AnalyticQueryRequest: {
             /**
@@ -2430,6 +2395,22 @@ export interface components {
             observations: components["schemas"]["ObservationRow"][];
             outgoing: components["schemas"]["GraphEdgeRow"][];
             snapshot: components["schemas"]["SnapshotView"];
+            truncation?: null | components["schemas"]["EntityDetailTruncation"];
+        };
+        /**
+         * @description Which of an entity read's degree-proportional collections were cut, and by
+         *     how much. Only the cut collections appear.
+         */
+        EntityDetailTruncation: {
+            edges?: null | components["schemas"]["TruncatedCollection"];
+            history?: null | components["schemas"]["TruncatedCollection"];
+            observations?: null | components["schemas"]["TruncatedCollection"];
+            /**
+             * @description True when the request's object-read budget stopped the read before its
+             *     row caps did, so the counts below are floors for a different reason:
+             *     the read gave up rather than the collection being full.
+             */
+            truncated_by_read_budget?: boolean;
         };
         EntityEmbeddingInput: {
             /**
@@ -2512,7 +2493,6 @@ export interface components {
         };
         EntityId: string;
         EntityMetadataResponse: {
-            adjacency_indexed_commit_seq?: null | components["schemas"]["CommitSeq"];
             ann_indexed_commit_seq?: null | components["schemas"]["CommitSeq"];
             bm25_indexed_commit_seq?: null | components["schemas"]["CommitSeq"];
             entity: components["schemas"]["EntityView"];
@@ -2535,25 +2515,43 @@ export interface components {
             as_of_commit_seq?: number | null;
             as_of_valid_time?: string | null;
             entity: components["schemas"]["EntitySelector"];
+            /**
+             * @description Maximum edges returned **per direction**, clamped by the engine to
+             *     [`MAX_NEIGHBORHOOD_EDGES_PER_DIRECTION`] and defaulting to
+             *     [`DEFAULT_NEIGHBORHOOD_EDGES_PER_DIRECTION`]. Both read paths are scoped
+             *     to the entity's degree, but a supernode's degree is itself unbounded, so
+             *     this is the backstop that keeps one hub read from costing a serving node
+             *     its whole request budget.
+             *
+             *     The budget is per-direction rather than shared: a shared one is spent
+             *     entirely on whichever direction is walked first, so a hub's out-edges
+             *     consume it and the read reports no incoming edges at all.
+             */
+            max_edges_per_direction?: number | null;
             relations?: string[] | null;
         };
         /**
          * @description Result of an entity point lookup: the entity plus its out/in neighborhood.
-         *     Public reads use adjacency for the published watermark and the same
-         *     generation's Base family for historical pins; both paths cost the entity's
-         *     degree rather than the whole graph.
+         *     Public reads use the generation's Base family and cost the entity's degree
+         *     rather than the whole graph.
          */
         EntityNeighborhoodResponse: {
             entity: components["schemas"]["EntityView"];
             incoming: components["schemas"]["NeighborhoodEdge"][];
             outgoing: components["schemas"]["NeighborhoodEdge"][];
-            /**
-             * @description True when served directly from the persisted adjacency family. False
-             *     when an exact historical pin was reduced from the same published
-             *     generation's Base family.
-             */
+            /** @description True when served through immutable ranged Base blocks. */
             served_from_ranged: boolean;
             snapshot: components["schemas"]["SnapshotView"];
+            truncation?: null | components["schemas"]["EntityNeighborhoodTruncation"];
+        };
+        /**
+         * @description Which directions of a neighborhood listing were cut, and by how much. Only
+         *     the cut directions appear. The two directions are reported separately
+         *     because they are budgeted separately.
+         */
+        EntityNeighborhoodTruncation: {
+            incoming?: null | components["schemas"]["TruncatedCollection"];
+            outgoing?: null | components["schemas"]["TruncatedCollection"];
         };
         /**
          * @description Literal property values to attach to one entity (matched by type + name).
@@ -2638,8 +2636,7 @@ export interface components {
         };
         /**
          * @description Exact class cardinality plus a bounded deterministic sample served from the
-         *     ranged adjacency meta. `indexed_commit_seq` makes index lag explicit while
-         *     `snapshot.commit_seq` reports the current graph head.
+         *     published Base family. `indexed_commit_seq` makes publication lag explicit.
          */
         EntityTypeSampleResponse: {
             entities: components["schemas"]["EntityTypeSampleRow"][];
@@ -2649,10 +2646,9 @@ export interface components {
             total_count: number;
         };
         /**
-         * @description One bounded, index-backed class member for interactive graph exploration.
-         *     Unlike [`EntityExplorerRow`], this deliberately carries only fields the
-         *     adjacency build already knows; exhaustive attributes and observation counts
-         *     remain on the full entity/browse reads.
+         * @description One bounded class member for interactive graph exploration. Unlike
+         *     [`EntityExplorerRow`], this deliberately carries only identity and degree;
+         *     exhaustive attributes and observation counts remain on full entity reads.
          */
         EntityTypeSampleRow: {
             entity: components["schemas"]["EntityView"];
@@ -2681,8 +2677,6 @@ export interface components {
             /** Format: float */
             weight: number;
         };
-        /** @enum {string} */
-        ExpansionDirection: "out" | "in" | "both";
         ExportObservationView: {
             created_at_commit: components["schemas"]["CommitSeq"];
             id: components["schemas"]["ObservationId"];
@@ -2935,8 +2929,8 @@ export interface components {
          *     is the engine-native form of the query-conditional channel routing validated
          *     in the Stage-G ablation (quality-ledger R17) — "documents about X AND in the
          *     same group as Y" becomes one snapshot-consistent search rather than a blind
-         *     list fusion. The neighborhood is computed by a bounded, snapshot-reduced
-         *     traversal; final candidates are still re-verified against snapshot visibility.
+         *     list fusion. The neighborhood is computed from the snapshot-reduced Base
+         *     family; final candidates are still re-verified against snapshot visibility.
          */
         GraphAnchor: {
             /** @description The anchor entity to expand from. */
@@ -3243,12 +3237,30 @@ export interface components {
          *     structured server logs.
          */
         GraphImportJobFailure: {
+            /**
+             * Format: int32
+             * @description Delivery attempts consumed when the job became terminal.
+             */
+            attempts: number;
             code: string;
+            /**
+             * @description Stable opaque correlation id for server-side logs. It is intentionally
+             *     not an object key, worker id, or graph identity.
+             */
+            diagnostic_id: string;
             message: string;
             retryable: boolean;
+            /** @description Last durable low-cardinality stage reached by the worker. */
+            stage: components["schemas"]["GraphImportJobStage"];
         };
         /** @description Bounded progress persisted by an import worker after every grouped commit. */
         GraphImportJobProgress: {
+            /** Format: int64 */
+            active_group_bytes?: number;
+            /** Format: int64 */
+            active_group_index?: number | null;
+            /** Format: int64 */
+            active_group_records?: number;
             /** Format: int64 */
             bytes_processed: number;
             committed_commit_seq?: null | components["schemas"]["CommitSeq"];
@@ -3263,11 +3275,17 @@ export interface components {
             observations: number;
             /** Format: int64 */
             properties: number;
+            stage?: components["schemas"]["GraphImportJobStage"];
             /** Format: int64 */
             triplets: number;
             /** Format: int64 */
             upload_bytes: number;
         };
+        /**
+         * @description Low-cardinality execution stage exposed while a durable import is active.
+         * @enum {string}
+         */
+        GraphImportJobStage: "queued" | "reading_payload" | "committing_group" | "persisting_checkpoint" | "enqueueing_publication" | "completed";
         /**
          * @description Lifecycle of a durable NDJSON import submitted through
          *     `POST /v1/graph/import-jobs`.
@@ -3375,7 +3393,6 @@ export interface components {
             targets: components["schemas"]["AnnTargetKind"][];
         };
         GraphMetadataResponse: {
-            adjacency_indexed_commit_seq?: null | components["schemas"]["CommitSeq"];
             ann_indexed_commit_seq?: null | components["schemas"]["CommitSeq"];
             bm25_indexed_commit_seq?: null | components["schemas"]["CommitSeq"];
             graph: components["schemas"]["GraphKey"];
@@ -3383,11 +3400,16 @@ export interface components {
             head_generation: number;
             /**
              * @description One-shot "has the published generation caught up to head?" signal, so a
-             *     bulk-import caller does not hand-assemble the three-field predicate.
-             *     `Some(true)` iff both the BM25 and ANN persisted runs are current to the
-             *     head commit; `Some(false)` when publication is still
-             *     pending or absent; `None` when indexes were not inspected
-             *     (`include_indexes=false`).
+             *     bulk-import caller does not hand-assemble the predicate.
+             *     `Some(true)` iff the published generation is served at the head commit;
+             *     `Some(false)` when publication is still pending or absent; `None` when
+             *     indexes were not inspected (`include_indexes=false`).
+             *
+             *     This is a **publication lag** signal, not a statement about index
+             *     content. A generation whose BM25/ANN families are published as empty
+             *     roots — the steady state when the deployment runs without the search
+             *     stack — is caught up while holding no documents. Read
+             *     `index_lineage.bm25_empty` / `ann_empty` to tell the two apart.
              */
             index_caught_up?: boolean | null;
             index_lineage?: null | components["schemas"]["IndexLineage"];
@@ -3719,13 +3741,31 @@ export interface components {
         };
         /** @description Typed convergence view over the persisted serving families. */
         IndexLineage: {
-            adjacency_indexed_commit_seq?: null | components["schemas"]["CommitSeq"];
+            /**
+             * @description True when the published ANN family is an empty root. Same meaning as
+             *     `bm25_empty`.
+             */
+            ann_empty?: boolean;
             ann_indexed_commit_seq?: null | components["schemas"]["CommitSeq"];
+            /**
+             * @description True when the published BM25 family is an empty root — the deployment
+             *     runs without the search stack
+             *     (`LBB_PUBLISH_EMPTY_INDEX_FAMILIES`), or the corpus genuinely has no
+             *     indexable documents at this watermark. Either way the family is current
+             *     *and* contains nothing, so a health check must not read `caught_up`
+             *     alone as "search is serving results".
+             */
+            bm25_empty?: boolean;
             bm25_indexed_commit_seq?: null | components["schemas"]["CommitSeq"];
+            /**
+             * @description Both families are published at the head commit. This is a *publication
+             *     lag* signal — it says the derived families have caught up with graph
+             *     truth, not that they hold data. An empty family is caught up.
+             */
             caught_up: boolean;
             head_commit_seq: components["schemas"]["CommitSeq"];
             /**
-             * @description Content identity of the head generation plus the exact three manifest
+             * @description Content identity of the head generation plus the exact manifest
              *     views observed while constructing this response.
              */
             manifest_view_token: string;
@@ -3736,7 +3776,7 @@ export interface components {
          * @description One of the index families referenced by an atomic published read root.
          * @enum {string}
          */
-        IndexVisibilityFamily: "base" | "rdf" | "bm25" | "ann" | "adjacency";
+        IndexVisibilityFamily: "base" | "rdf" | "bm25" | "ann";
         /**
          * @description A single inference rule (SHACL-AF `sh:TripleRule` shape): a BGP `body` (the
          *     condition / `WHERE`) and a `head` triple template instantiated once per
@@ -4013,15 +4053,6 @@ export interface components {
             /** @enum {string} */
             kind: "temporal_state";
             relation: string;
-        } | {
-            from: components["schemas"]["EntitySelector"];
-            /** @enum {string} */
-            kind: "path";
-            /** Format: int32 */
-            max_hops: number;
-            relations?: string[] | null;
-            should_exist: boolean;
-            to: components["schemas"]["EntitySelector"];
         };
         ModelDataLineage: {
             /** Format: int64 */
@@ -4233,11 +4264,9 @@ export interface components {
             snapshot: components["schemas"]["SnapshotView"];
         };
         /**
-         * @description One current-edge projection touching the queried entity, materialized from
-         *     the entity's own adjacency slice (peer stub + relation + valid time). Unlike
+         * @description One current-edge projection touching the queried entity. Unlike
          *     `StateEntry`/`TripletView` it carries no `previous`/`evidence`/single
-         *     `edge_event_id`, because the ranged adjacency run does not store them — so
-         *     the ranged and snapshot code paths produce identical edges.
+         *     `edge_event_id`, keeping the point-read representation compact.
          */
         NeighborhoodEdge: {
             /** Format: float */
@@ -4794,12 +4823,6 @@ export interface components {
             /** @description Count of surface terms (labels/synonyms) in the semantic layer. */
             term_count?: number;
         };
-        PathResult: {
-            edges: components["schemas"]["EdgeEventId"][];
-            nodes: components["schemas"]["EntityView"][];
-            /** Format: float */
-            score: number;
-        };
         /**
          * @description `GET /v1/models/planner-dataset` — the planner fine-tune's training feed:
          *     accepted/corrected ask feedback joined to its traces (signals ≤ the split
@@ -4992,6 +5015,7 @@ export interface components {
              * @description That family's persisted root-codec version.
              */
             root_format_version: number;
+            served_at_seq?: null | components["schemas"]["CommitSeq"];
             target_hash?: string | null;
         };
         /**
@@ -5008,6 +5032,7 @@ export interface components {
             /** Format: int64 */
             generation?: number | null;
             graph: components["schemas"]["GraphKey"];
+            min_family_served_at_seq?: null | components["schemas"]["CommitSeq"];
             /** Format: int64 */
             predecessor_generation?: number | null;
             /** Format: int32 */
@@ -5082,43 +5107,6 @@ export interface components {
              */
             rerank_raw_bytes_fetched?: number;
         };
-        RangedTraverseStats: {
-            /** Format: int64 */
-            block_byte_budget: number;
-            /** Format: int64 */
-            block_bytes_fetched: number;
-            block_read_budget: number;
-            /** Format: int64 */
-            blocks_fetched: number;
-            /**
-             * Format: int64
-             * @description Backend ranged GETs saved by P27 coalescing: each value is one ranged
-             *     read that pre-warmed several byte-contiguous slices at once.
-             */
-            coalesced_range_gets?: number;
-            /** Format: int64 */
-            decoded_block_bytes_retained: number;
-            /** Format: int64 */
-            directory_blocks_fetched?: number;
-            /**
-             * Format: int64
-             * @description Cumulative-fetched-bytes budget (P27); 0 = disabled. Distinct from
-             *     `block_byte_budget`, which caps *resident* decoded bytes.
-             */
-            fetched_byte_budget?: number;
-            manifest_key: string;
-            /** Format: int64 */
-            meta_bytes_fetched: number;
-            /** Format: int64 */
-            payload_slices_fetched?: number;
-            /** Format: int64 */
-            shard_cache_hits: number;
-            /** Format: int64 */
-            topology_slices_fetched?: number;
-            truncated_by_block_budget: boolean;
-            truncated_by_block_byte_budget: boolean;
-            truncated_by_fetched_byte_budget?: boolean;
-        };
         /**
          * @description A page-region provenance anchor on a fact's evidence (region provenance
          *     §4.1/§6.4(b) BYO import): where the evidence appears in the source
@@ -5884,7 +5872,6 @@ export interface components {
         };
         SearchFilterValue: null | boolean | number | string;
         SearchHitContributions: {
-            adjacency_indexed_commit_seq?: null | components["schemas"]["CommitSeq"];
             bm25: components["schemas"]["SearchChannelContribution"];
             bm25_indexed_commit_seq?: null | components["schemas"]["CommitSeq"];
             bm25_manifest_key?: string | null;
@@ -6217,64 +6204,6 @@ export interface components {
         };
         /** @enum {string} */
         SemanticSearchTarget: "concepts" | "entities" | "assertions" | "paths" | "observations" | "subgraph";
-        SemanticTraverseExplain: {
-            bm25_candidates: number;
-            /** Format: int32 */
-            graph_hops: number;
-            paths_returned: number;
-            search_mode: string;
-            seeds_considered: number;
-            seeds_selected: number;
-            vector_candidates: number;
-        };
-        SemanticTraverseRequest: {
-            direction: components["schemas"]["ExpansionDirection"];
-            explain: boolean;
-            /**
-             * @description Entity properties to project for every returned seed and path node.
-             *     Projections are reduced from the same snapshot used for authorization
-             *     and traversal. Requesting fields routes the operation through the exact
-             *     snapshot path rather than ranged adjacency.
-             */
-            fields?: string[];
-            /**
-             * Format: int64
-             * @description Decoded adjacency-block working-set byte budget for persisted-vector
-             *     ranged expansion. Defaults to the server/store budget. A request may
-             *     lower the budget, but not raise it.
-             */
-            max_block_bytes?: number | null;
-            max_frontier_entities: number;
-            /** Format: int32 */
-            max_hops: number;
-            max_paths: number;
-            /** Format: float */
-            min_confidence?: number | null;
-            /** Format: float */
-            min_seed_score?: number | null;
-            ontology?: null | components["schemas"]["OntologySearchOptions"];
-            ontology_constraints?: null | components["schemas"]["OntologySearchConstraints"];
-            query: string;
-            relations?: string[] | null;
-            search?: null | components["schemas"]["SearchEngineOptions"];
-            seed_top_k: number;
-        };
-        SemanticTraverseResponse: {
-            explain?: null | components["schemas"]["SemanticTraverseExplain"];
-            paths: components["schemas"]["PathResult"][];
-            /**
-             * @description Requested properties keyed by entity id for every returned seed and
-             *     path node. Empty when `fields` was omitted.
-             */
-            projected_nodes?: {
-                [key: string]: {
-                    [key: string]: unknown;
-                };
-            };
-            ranged?: null | components["schemas"]["RangedTraverseStats"];
-            seeds: components["schemas"]["ScoredEntityView"][];
-            snapshot: components["schemas"]["SnapshotView"];
-        };
         /**
          * @description Set (or clear) the enforced allowed-value set on an **existing** property
          *     field — the tightening path for a field already in use (e.g. constrain
@@ -6312,7 +6241,7 @@ export interface components {
         };
         /**
          * @description Set (or replace) a relation's inverse-relation display name, enabling
-         *     one-hop reverse traversal (e.g. `PHASE_OF` for `HAS_PHASE`). Metadata
+         *     one-hop reverse lookup (e.g. `PHASE_OF` for `HAS_PHASE`). Metadata
          *     only — never touches stored edges.
          */
         SetRelationInverseOp: {
@@ -6390,7 +6319,7 @@ export interface components {
             unique?: components["schemas"]["ShaclUnique"][];
         };
         /**
-         * @description A SHACL property path expression, evaluated as a bounded graph traversal from
+         * @description A SHACL property path expression, evaluated by the bounded RDF path engine from
          *     the focus node to a set of value-node entities. Mirrors SHACL's path grammar:
          *     a single predicate, an inverse, a sequence, an alternative, and the
          *     `*`/`+`/`?` closures.
@@ -6763,8 +6692,7 @@ export interface components {
             /**
              * @description The reason a read is `stale`. `"storage_degraded"` (F2),
              *     `"eventual_consistency"` (served from the immutable published
-             *     generation) or `"adjacency_coverage"` (served from that generation's
-             *     bounded ranged-adjacency snapshot); omitted when not stale.
+             *     generation); omitted when not stale.
              */
             stale_reason?: string | null;
         };
@@ -6918,7 +6846,7 @@ export interface components {
         } | "null";
         /**
          * @description A SPARQL-subset SELECT/ASK query: a conjunctive basic graph pattern (the
-         *     WHERE) evaluated over the object-storage permutation view, with variable
+         *     WHERE) evaluated over the conformant published RDF dataset, with variable
          *     projection, DISTINCT, and LIMIT/OFFSET. Structured-request-first — the SPARQL
          *     text syntax is a later addition behind a dialect field, and FILTER plus
          *     aggregation arrive in later milestones.
@@ -7444,62 +7372,6 @@ export interface components {
             target: components["schemas"]["EntityView"];
             valid_time: components["schemas"]["ValidTime"];
         };
-        TraverseRequest: {
-            /**
-             * Format: int64
-             * @description Snapshot pin: reproduce the graph state as of this `commit_seq`, hiding
-             *     any event committed later. Public serving reduces the bounded edge
-             *     domains from the Base family in the one pinned published generation;
-             *     it never discovers or assembles another snapshot. Historical entity
-             *     filters/field projection fail explicitly because Base does not carry a
-             *     point-indexed entity-mutation history. Omit for the latest snapshot.
-             */
-            as_of_commit_seq?: number | null;
-            as_of_valid_time?: string | null;
-            direction: components["schemas"]["ExpansionDirection"];
-            /**
-             * @description Entity fields projected for every seed/intermediate/terminal node in
-             *     `TraverseResponse.projected_nodes`.
-             */
-            fields?: string[];
-            filter?: null | components["schemas"]["SearchFilterExpr"];
-            /**
-             * Format: int64
-             * @description Decoded adjacency-block working-set byte budget for the ranged path.
-             *     Defaults to the server/store budget. A request may lower the budget,
-             *     but not raise it. Ignored on the bounded Base-family reducer path.
-             */
-            max_block_bytes?: number | null;
-            /**
-             * @description Object-read budget for the ranged adjacency path; defaults to a value
-             *     derived from `max_frontier_entities`. Ignored on the bounded Base-family
-             *     reducer path.
-             */
-            max_block_reads?: number | null;
-            max_frontier_entities: number;
-            /** Format: int32 */
-            max_hops: number;
-            max_paths: number;
-            /** Format: float */
-            min_confidence?: number | null;
-            relations?: string[] | null;
-            start: components["schemas"]["EntitySelector"];
-        };
-        TraverseResponse: {
-            paths: components["schemas"]["PathResult"][];
-            /**
-             * @description Same-snapshot field evidence for every node appearing in `paths`, keyed
-             *     by stable entity-id hex. Present as an empty map when no fields were
-             *     requested.
-             */
-            projected_nodes?: {
-                [key: string]: {
-                    [key: string]: unknown;
-                };
-            };
-            ranged?: null | components["schemas"]["RangedTraverseStats"];
-            snapshot: components["schemas"]["SnapshotView"];
-        };
         TripletCommitFile: {
             edge_idempotency?: null | components["schemas"]["EdgeIdempotencyMode"];
             /**
@@ -7556,6 +7428,17 @@ export interface components {
             target: components["schemas"]["EntityView"];
             valid_time: components["schemas"]["ValidTime"];
         };
+        /** @description One capped collection: how many rows came back out of how many the read saw. */
+        TruncatedCollection: {
+            /** @description Rows present in this response. */
+            returned: number;
+            /**
+             * @description Rows the bounded read observed. This is a **lower bound**: establishing
+             *     the true total means walking the entity's whole degree, which is the
+             *     cost the cap exists to avoid. Render it as "returned of at least total".
+             */
+            total_observed: number;
+        };
         TypedAskFeedbackV1: {
             ask_id: string;
             note?: string | null;
@@ -10987,7 +10870,7 @@ export interface operations {
                 type?: string;
                 /** @description Max sampled rows (up to 128) */
                 limit?: string;
-                /** @description Accepted as strong or eventual; adjacency serves the exact immutable base pinned by the published generation without inspecting the live WAL in either mode */
+                /** @description Accepted as strong or eventual; Base serves the immutable generation without inspecting the live WAL */
                 consistency?: string;
             };
             header?: {
@@ -11421,6 +11304,8 @@ export interface operations {
                 relations?: string;
                 /** @description RFC3339 as-of timestamp */
                 as_of?: string;
+                /** @description Maximum edges per direction (default 1000, maximum 10000) */
+                edges?: string;
             };
             header?: {
                 /** @description API contract version to pin. Use `2026-07-23` for this beta-breaking shape. */
@@ -12123,8 +12008,6 @@ export interface operations {
                 strict?: string;
                 /** @description RFC3339 backfill instant stamped on every batch */
                 observed_at?: string;
-                /** @description Durably enqueue one atomic published-generation build after the final batch */
-                publish?: string;
             };
             header?: {
                 /** @description API contract version to pin. Use `2026-07-23` for this beta-breaking shape. */
@@ -12703,7 +12586,7 @@ export interface operations {
                 graph?: string;
                 /** @description Branch name (default `main`) */
                 branch?: string;
-                /** @description RDF statements per internal commit (default 1000, clamped 1-1000000) */
+                /** @description RDF statements per internal commit (default 1000000, the cap: one commit per fully-buffered request; clamped 1-1000000) */
                 batch?: string;
                 /** @description Abort on the first malformed RDF parse error instead of reporting it */
                 strict?: string;
@@ -12721,8 +12604,8 @@ export interface operations {
                 blank_node_scope?: string;
                 /** @description Entity type name for imported RDF resources (default Resource) */
                 resource_type?: string;
-                /** @description Durably enqueue one atomic published-generation build after the final batch */
-                publish?: string;
+                /** @description Set false to defer the published-generation enqueue; send build=false on every chunk except the last of a chunked bulk stream. Default true. */
+                build?: string;
             };
             header?: {
                 /** @description API contract version to pin. Use `2026-07-23` for this beta-breaking shape. */
@@ -13698,7 +13581,7 @@ export interface operations {
             };
         };
     };
-    post_v1_graph_semantic_traverse: {
+    get_v1_graph_summary: {
         parameters: {
             query?: {
                 /** @description Graph name (default `main`) */
@@ -13709,153 +13592,11 @@ export interface operations {
             header?: {
                 /** @description API contract version to pin. Use `2026-07-23` for this beta-breaking shape. */
                 "Lbb-Version"?: string;
-                /** @description Stable client-generated key for safely retrying mutations and supervision writes. */
-                "Idempotency-Key"?: string;
             };
             path?: never;
             cookie?: never;
         };
-        requestBody: {
-            content: {
-                "application/json": components["schemas"]["SemanticTraverseRequest"];
-            };
-        };
-        responses: {
-            /** @description OK */
-            200: {
-                headers: {
-                    /** @description API contract version used for the response */
-                    "Lbb-Version"?: string;
-                    /** @description Request correlation id */
-                    "X-Request-Id"?: string;
-                    [name: string]: unknown;
-                };
-                content: {
-                    "application/json": components["schemas"]["SemanticTraverseResponse"];
-                };
-            };
-            /** @description Bad request */
-            400: {
-                headers: {
-                    /** @description API contract version used for the response */
-                    "Lbb-Version"?: string;
-                    /** @description Request correlation id */
-                    "X-Request-Id"?: string;
-                    [name: string]: unknown;
-                };
-                content: {
-                    "application/json": components["schemas"]["LbbErrorEnvelope"];
-                };
-            };
-            /** @description Unauthorized */
-            401: {
-                headers: {
-                    /** @description API contract version used for the response */
-                    "Lbb-Version"?: string;
-                    /** @description Request correlation id */
-                    "X-Request-Id"?: string;
-                    [name: string]: unknown;
-                };
-                content: {
-                    "application/json": components["schemas"]["LbbErrorEnvelope"];
-                };
-            };
-            /** @description Forbidden */
-            403: {
-                headers: {
-                    /** @description API contract version used for the response */
-                    "Lbb-Version"?: string;
-                    /** @description Request correlation id */
-                    "X-Request-Id"?: string;
-                    [name: string]: unknown;
-                };
-                content: {
-                    "application/json": components["schemas"]["LbbErrorEnvelope"];
-                };
-            };
-            /** @description Not found */
-            404: {
-                headers: {
-                    /** @description API contract version used for the response */
-                    "Lbb-Version"?: string;
-                    /** @description Request correlation id */
-                    "X-Request-Id"?: string;
-                    [name: string]: unknown;
-                };
-                content: {
-                    "application/json": components["schemas"]["LbbErrorEnvelope"];
-                };
-            };
-            /** @description Conflict */
-            409: {
-                headers: {
-                    /** @description API contract version used for the response */
-                    "Lbb-Version"?: string;
-                    /** @description Request correlation id */
-                    "X-Request-Id"?: string;
-                    [name: string]: unknown;
-                };
-                content: {
-                    "application/json": components["schemas"]["LbbErrorEnvelope"];
-                };
-            };
-            /** @description Rate limit exceeded */
-            429: {
-                headers: {
-                    /** @description API contract version used for the response */
-                    "Lbb-Version"?: string;
-                    /** @description Request correlation id */
-                    "X-Request-Id"?: string;
-                    [name: string]: unknown;
-                };
-                content: {
-                    "application/json": components["schemas"]["LbbErrorEnvelope"];
-                };
-            };
-            /** @description Internal server error */
-            500: {
-                headers: {
-                    /** @description API contract version used for the response */
-                    "Lbb-Version"?: string;
-                    /** @description Request correlation id */
-                    "X-Request-Id"?: string;
-                    [name: string]: unknown;
-                };
-                content: {
-                    "application/json": components["schemas"]["LbbErrorEnvelope"];
-                };
-            };
-            /** @description Service unavailable */
-            503: {
-                headers: {
-                    /** @description API contract version used for the response */
-                    "Lbb-Version"?: string;
-                    /** @description Request correlation id */
-                    "X-Request-Id"?: string;
-                    [name: string]: unknown;
-                };
-                content: {
-                    "application/json": components["schemas"]["LbbErrorEnvelope"];
-                };
-            };
-        };
-    };
-    get_v1_graph_summary: {
-        parameters: {
-            query?: {
-                /** @description Graph name (default `main`) */
-                graph?: string;
-                /** @description Branch name (default `main`) */
-                branch?: string;
-            };
-            header?: {
-                /** @description API contract version to pin. Use `2026-07-23` for this beta-breaking shape. */
-                "Lbb-Version"?: string;
-            };
-            path?: never;
-            cookie?: never;
-        };
-        requestBody?: never;
+        requestBody?: never;
         responses: {
             /** @description OK */
             200: {
@@ -13976,290 +13717,6 @@ export interface operations {
             };
         };
     };
-    get_v1_graph_traverse: {
-        parameters: {
-            query?: {
-                /** @description Graph name (default `main`) */
-                graph?: string;
-                /** @description Branch name (default `main`) */
-                branch?: string;
-                /** @description Start entity id */
-                id?: string;
-                /** @description out, in, or both */
-                direction?: string;
-                /** @description Hop budget */
-                max_hops?: string;
-            };
-            header?: {
-                /** @description API contract version to pin. Use `2026-07-23` for this beta-breaking shape. */
-                "Lbb-Version"?: string;
-            };
-            path?: never;
-            cookie?: never;
-        };
-        requestBody?: never;
-        responses: {
-            /** @description OK */
-            200: {
-                headers: {
-                    /** @description API contract version used for the response */
-                    "Lbb-Version"?: string;
-                    /** @description Request correlation id */
-                    "X-Request-Id"?: string;
-                    [name: string]: unknown;
-                };
-                content: {
-                    "application/json": components["schemas"]["TraverseResponse"];
-                };
-            };
-            /** @description Bad request */
-            400: {
-                headers: {
-                    /** @description API contract version used for the response */
-                    "Lbb-Version"?: string;
-                    /** @description Request correlation id */
-                    "X-Request-Id"?: string;
-                    [name: string]: unknown;
-                };
-                content: {
-                    "application/json": components["schemas"]["LbbErrorEnvelope"];
-                };
-            };
-            /** @description Unauthorized */
-            401: {
-                headers: {
-                    /** @description API contract version used for the response */
-                    "Lbb-Version"?: string;
-                    /** @description Request correlation id */
-                    "X-Request-Id"?: string;
-                    [name: string]: unknown;
-                };
-                content: {
-                    "application/json": components["schemas"]["LbbErrorEnvelope"];
-                };
-            };
-            /** @description Forbidden */
-            403: {
-                headers: {
-                    /** @description API contract version used for the response */
-                    "Lbb-Version"?: string;
-                    /** @description Request correlation id */
-                    "X-Request-Id"?: string;
-                    [name: string]: unknown;
-                };
-                content: {
-                    "application/json": components["schemas"]["LbbErrorEnvelope"];
-                };
-            };
-            /** @description Not found */
-            404: {
-                headers: {
-                    /** @description API contract version used for the response */
-                    "Lbb-Version"?: string;
-                    /** @description Request correlation id */
-                    "X-Request-Id"?: string;
-                    [name: string]: unknown;
-                };
-                content: {
-                    "application/json": components["schemas"]["LbbErrorEnvelope"];
-                };
-            };
-            /** @description Conflict */
-            409: {
-                headers: {
-                    /** @description API contract version used for the response */
-                    "Lbb-Version"?: string;
-                    /** @description Request correlation id */
-                    "X-Request-Id"?: string;
-                    [name: string]: unknown;
-                };
-                content: {
-                    "application/json": components["schemas"]["LbbErrorEnvelope"];
-                };
-            };
-            /** @description Rate limit exceeded */
-            429: {
-                headers: {
-                    /** @description API contract version used for the response */
-                    "Lbb-Version"?: string;
-                    /** @description Request correlation id */
-                    "X-Request-Id"?: string;
-                    [name: string]: unknown;
-                };
-                content: {
-                    "application/json": components["schemas"]["LbbErrorEnvelope"];
-                };
-            };
-            /** @description Internal server error */
-            500: {
-                headers: {
-                    /** @description API contract version used for the response */
-                    "Lbb-Version"?: string;
-                    /** @description Request correlation id */
-                    "X-Request-Id"?: string;
-                    [name: string]: unknown;
-                };
-                content: {
-                    "application/json": components["schemas"]["LbbErrorEnvelope"];
-                };
-            };
-            /** @description Service unavailable */
-            503: {
-                headers: {
-                    /** @description API contract version used for the response */
-                    "Lbb-Version"?: string;
-                    /** @description Request correlation id */
-                    "X-Request-Id"?: string;
-                    [name: string]: unknown;
-                };
-                content: {
-                    "application/json": components["schemas"]["LbbErrorEnvelope"];
-                };
-            };
-        };
-    };
-    post_v1_graph_traverse: {
-        parameters: {
-            query?: {
-                /** @description Graph name (default `main`) */
-                graph?: string;
-                /** @description Branch name (default `main`) */
-                branch?: string;
-            };
-            header?: {
-                /** @description API contract version to pin. Use `2026-07-23` for this beta-breaking shape. */
-                "Lbb-Version"?: string;
-                /** @description Stable client-generated key for safely retrying mutations and supervision writes. */
-                "Idempotency-Key"?: string;
-            };
-            path?: never;
-            cookie?: never;
-        };
-        requestBody: {
-            content: {
-                "application/json": components["schemas"]["TraverseRequest"];
-            };
-        };
-        responses: {
-            /** @description OK */
-            200: {
-                headers: {
-                    /** @description API contract version used for the response */
-                    "Lbb-Version"?: string;
-                    /** @description Request correlation id */
-                    "X-Request-Id"?: string;
-                    [name: string]: unknown;
-                };
-                content: {
-                    "application/json": components["schemas"]["TraverseResponse"];
-                };
-            };
-            /** @description Bad request */
-            400: {
-                headers: {
-                    /** @description API contract version used for the response */
-                    "Lbb-Version"?: string;
-                    /** @description Request correlation id */
-                    "X-Request-Id"?: string;
-                    [name: string]: unknown;
-                };
-                content: {
-                    "application/json": components["schemas"]["LbbErrorEnvelope"];
-                };
-            };
-            /** @description Unauthorized */
-            401: {
-                headers: {
-                    /** @description API contract version used for the response */
-                    "Lbb-Version"?: string;
-                    /** @description Request correlation id */
-                    "X-Request-Id"?: string;
-                    [name: string]: unknown;
-                };
-                content: {
-                    "application/json": components["schemas"]["LbbErrorEnvelope"];
-                };
-            };
-            /** @description Forbidden */
-            403: {
-                headers: {
-                    /** @description API contract version used for the response */
-                    "Lbb-Version"?: string;
-                    /** @description Request correlation id */
-                    "X-Request-Id"?: string;
-                    [name: string]: unknown;
-                };
-                content: {
-                    "application/json": components["schemas"]["LbbErrorEnvelope"];
-                };
-            };
-            /** @description Not found */
-            404: {
-                headers: {
-                    /** @description API contract version used for the response */
-                    "Lbb-Version"?: string;
-                    /** @description Request correlation id */
-                    "X-Request-Id"?: string;
-                    [name: string]: unknown;
-                };
-                content: {
-                    "application/json": components["schemas"]["LbbErrorEnvelope"];
-                };
-            };
-            /** @description Conflict */
-            409: {
-                headers: {
-                    /** @description API contract version used for the response */
-                    "Lbb-Version"?: string;
-                    /** @description Request correlation id */
-                    "X-Request-Id"?: string;
-                    [name: string]: unknown;
-                };
-                content: {
-                    "application/json": components["schemas"]["LbbErrorEnvelope"];
-                };
-            };
-            /** @description Rate limit exceeded */
-            429: {
-                headers: {
-                    /** @description API contract version used for the response */
-                    "Lbb-Version"?: string;
-                    /** @description Request correlation id */
-                    "X-Request-Id"?: string;
-                    [name: string]: unknown;
-                };
-                content: {
-                    "application/json": components["schemas"]["LbbErrorEnvelope"];
-                };
-            };
-            /** @description Internal server error */
-            500: {
-                headers: {
-                    /** @description API contract version used for the response */
-                    "Lbb-Version"?: string;
-                    /** @description Request correlation id */
-                    "X-Request-Id"?: string;
-                    [name: string]: unknown;
-                };
-                content: {
-                    "application/json": components["schemas"]["LbbErrorEnvelope"];
-                };
-            };
-            /** @description Service unavailable */
-            503: {
-                headers: {
-                    /** @description API contract version used for the response */
-                    "Lbb-Version"?: string;
-                    /** @description Request correlation id */
-                    "X-Request-Id"?: string;
-                    [name: string]: unknown;
-                };
-                content: {
-                    "application/json": components["schemas"]["LbbErrorEnvelope"];
-                };
-            };
-        };
-    };
     get_v1_graphs: {
         parameters: {
             query?: {

package/dist/types.d.ts

@@ -55,6 +55,12 @@ export interface RdfImportOptions {
     observedAt?: string;
     resourceType?: string;
     edgeIdempotency?: "append" | "skip_unchanged";
+    /**
+     * Set `false` to defer the published-generation enqueue. Send `build: false`
+     * on every chunk except the last of a chunked bulk stream, so derived
+     * families build once at the final head. Defaults to `true`.
+     */
+    build?: boolean;
     idempotencyKey?: string;
 }
 export type AttributeFilterOp = "eq" | "ne" | "lt" | "le" | "gt" | "ge";

package/package.json

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