@littlebigbrain/client 0.8.0 → 0.8.1

package/README.md

@@ -1,6 +1,6 @@
 # @littlebigbrain/client
 
-The typed TypeScript client for [Little Big Brain](https://littlebigbrain.com) — write graph facts, build indexes, and run hybrid search over one snapshot. Request and response types are generated from the API contract, so every call is fully typed. Runs anywhere there's a global `fetch`: Node 18+, browsers, and edge workers.
+The typed TypeScript client for [Little Big Brain](https://littlebigbrain.com) — write graph facts and query one immutable published snapshot. Request and response types are generated from the API contract, so every call is fully typed. Runs anywhere there's a global `fetch`: Node 18+, browsers, and edge workers.
 
 ```sh
 npm install @littlebigbrain/client
@@ -32,13 +32,14 @@ await graph.facts.create(
   { idempotencyKey: "policy-42-v1" },
 );
 
-// 2. Build persisted BM25 + vector + adjacency indexes and wait.
-await graph.indexes.run({ wait: true });
+// 2. Publication is automatic. Inspect one coherent watermark when needed.
+const published = await lbb.readSnapshot();
+console.log(published.snapshot.served_at_seq, published.query_lag_commits);
 
 // 3. Hybrid search over the snapshot.
 const results = await graph.search.hybrid(
   "How long are customer records retained?",
-  { topK: 10, source: "persisted", consistency: "strong" },
+  { topK: 10, consistency: "eventual" },
 );
 ```
 
@@ -97,7 +98,12 @@ Methods return parsed JSON and throw `LbbError` (with `status`, `code`, `message
 
 ## More
 
-The `graph(...)` scope exposes `facts`, `search`, `entities`, `indexes`, `ontology`, `query`, `schema`, and `context` namespaces — covering managed embeddings, multi-query fusion, traversal, temporal state and history, SHACL, ontology evolution, and durable index jobs. Every generated shape is available as `Schemas["TypeName"]`.
+The `graph(...)` scope exposes `facts`, `search`, `entities`, `ontology`,
+`query`, `schema`, and `context` namespaces. `context` includes vocabulary
+suggestion, term resolution, relation decoding, and groundability inspection; `schema`
+reads or atomically publishes the active ontology/shapes bundle. Writes enqueue
+published-generation maintenance automatically. Every generated shape is
+available as `Schemas["TypeName"]`.
 
 Full reference and guides: [docs.littlebigbrain.com/sdks/typescript](https://docs.littlebigbrain.com/sdks/typescript/).
 

package/dist/client.d.ts

@@ -1,12 +1,12 @@
-import type { ImportLine, LbbClientOptions, ListResponse, RawLbbResponse, ReadConsistencyOptions, RdfExportOptions, RdfImportOptions, Schemas, SearchConsistency, SparqlResults } from "./types.js";
+import type { ImportLine, LbbClientOptions, ListResponse, RawLbbResponse, ReadConsistencyOptions, 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";
+import { ContextNamespace, EntityNamespace, GraphNamespace, 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, 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 type { AttributeFilter, AttributeFilterOp, AttributeFilterValue, EntityAttributeFilterOptions, EntityPropertiesLine, FetchLike, FlatProperties, ImportLine, LbbClientOptions, LbbRequestEvent, LbbResponseEvent, LbbRetryEvent, LbbErrorPayload, ListResponse, RawLbbResponse, ReadConsistencyOptions, RdfImportOptions, Schemas, SearchConsistency, SparqlResults, SparqlResultsJson, SparqlTerm, CommitRequest, CommitResponse, Entity, EntitySelector, GraphMetadata, GraphSummary, SchemaView, SearchRequest, SearchResponse, SearchResult, Snapshot, } from "./types.js";
 export { LbbError } from "./transport.js";
 export type { CallOptions, Query, QueryValue, RequestOptions, } from "./transport.js";
-export type { EntityListOptions, HybridSearchOptions } from "./namespaces.js";
-export { ContextNamespace, EntityNamespace, FactsNamespace, GraphNamespace, IndexNamespace, OntologyNamespace, QueryNamespace, SchemaNamespace, SearchNamespace, } from "./namespaces.js";
+export type { HybridSearchOptions } from "./namespaces.js";
+export { ContextNamespace, EntityNamespace, FactsNamespace, GraphNamespace, OntologyNamespace, QueryNamespace, SchemaNamespace, SearchNamespace, } from "./namespaces.js";
 export interface IndexLineageObservation {
     metadata: Schemas["GraphMetadataResponse"];
     lineage: Schemas["IndexLineage"];
@@ -40,7 +40,6 @@ export declare class LbbClient {
     readonly defaultConsistency?: SearchConsistency;
     readonly context: ContextNamespace;
     readonly search: SearchNamespace;
-    readonly indexes: IndexNamespace;
     readonly entities: EntityNamespace;
     readonly schema: SchemaNamespace;
     readonly ontology: OntologyNamespace;
@@ -97,18 +96,15 @@ export declare class LbbClient {
      * streamed request without a single oversized commit. Pass `lines` as an array
      * (serialized to NDJSON here) or a pre-built NDJSON string.
      *
-     * Set `index: true` to run one full index build after the last batch, so the
-     * data is served from the persisted runs (not just the ephemeral snapshot
-     * fallback) by the time the call returns — the "bulk load, queryable on return"
-     * path. Prefer this over indexing per batch (which serializes builds and races
-     * the throttle): import the whole dataset, index once. The response's `index`
-     * object reports whether the build ran or was skipped.
+     * A successful import durably enqueues one complete published-generation
+     * build after the final batch. It does not build index families or wait for
+     * visibility; the response's `published_generation` object carries the
+     * durable job and due sequence to observe.
      */
     import(lines: ImportLine[] | string, opts?: {
         batch?: number;
         strict?: boolean;
         observedAt?: string;
-        index?: boolean;
         idempotencyKey?: string;
     }): Promise<Schemas["GraphImportResponse"] & {
         commitSeq: number | null;
@@ -119,8 +115,6 @@ export declare class LbbClient {
      * properties on the subject Resource.
      */
     importRdf(rdf: string, opts?: RdfImportOptions): Promise<Schemas["GraphRdfImportResponse"]>;
-    /** Export the snapshot-visible RDF projection as Turtle, N-Triples, TriG, or N-Quads. */
-    exportRdf(opts?: RdfExportOptions): Promise<string>;
     /**
      * Retract specific edges and/or every edge touching given entities. Appends
      * superseding retract events rather than deleting — history stays visible in an
@@ -273,19 +267,15 @@ export declare class LbbClient {
         kind: string;
         run: number;
     }): Promise<Schemas["ModelSplitAudit"]>;
-    /**
-     * Champion vs challenger retrieval over one pinned snapshot. Returns
-     * promotion evidence (hit-rate@k, latency, overlap); never promotes.
-     */
-    shadowEval(body: Schemas["ShadowEvalRequest"]): Promise<Schemas["ShadowEvalResponse"]>;
-    /**
-     * Execution-verified QA probes generated from the graph's current edges —
-     * labels are the executed projections, so they are verified by construction.
-     * Feeds `shadowEval` directly.
-     */
+    /** Execution-verified QA probes generated from the graph's current edges. */
     syntheticEval(opts?: {
         limit?: number;
     }): Promise<Schemas["SyntheticEvalResponse"]>;
+    /**
+     * Compare champion and challenger retrieval over one pinned published
+     * snapshot. The endpoint returns promotion evidence but never promotes.
+     */
+    shadowEval(body: Schemas["ShadowEvalRequest"]): Promise<Schemas["ShadowEvalResponse"]>;
     /** The doubling retrain policy: is a retrain due for this model kind? */
     modelCadence(opts: {
         kind: string;
@@ -303,15 +293,6 @@ export declare class LbbClient {
     trainingConfig(): Promise<Schemas["ModelTrainingConfig"]>;
     /** Set the automatic-training configuration (`auto_train` toggle + kinds). */
     setTrainingConfig(body: Schemas["ModelTrainingConfig"]): Promise<Schemas["ModelTrainingConfig"]>;
-    /**
-     * Verdict on an ask (`accepted` | `rejected` | `corrected` + the right
-     * plan), joined to the ask's trace by `ask_id` — the planner fine-tune's
-     * explicit feedback capture. `accepted: false` in the response means
-     * signal capture is off on this deployment (the contract is identical).
-     */
-    askFeedback(body: Schemas["AskFeedbackRequest"], opts?: {
-        idempotencyKey?: string;
-    }): Promise<Schemas["AskFeedbackResponse"]>;
     ingestSignals(body: Schemas["SignalIngestRequest"], opts?: {
         idempotencyKey?: string;
     }): Promise<Schemas["SignalIngestResponse"]>;
@@ -324,36 +305,22 @@ export declare class LbbClient {
     externalPlannerTrace(payload: Schemas["ExternalPlannerTraceV1"], opts?: {
         idempotencyKey?: string;
     }): Promise<Schemas["SignalIngestResponse"]>;
-    /**
-     * The planner fine-tune's training feed: accepted/corrected feedback
-     * joined to its traces (signals ≤ the split pin), topped up with
-     * execution-verified synthetic plans.
-     */
+    /** Planner training examples at or before an optional signal split. */
     plannerDataset(opts?: {
         limit?: number;
         splitSeq?: number;
     }): Promise<Schemas["PlannerDatasetResponse"]>;
-    /**
-     * The DPO pass's training feed: preference pairs from corrected verdicts,
-     * paired rejections, and synthetic corrupted-slot pairs.
-     */
+    /** Planner preference pairs at or before an optional signal split. */
     plannerPreferenceDataset(opts?: {
         limit?: number;
         splitSeq?: number;
     }): Promise<Schemas["PlannerPreferenceDatasetResponse"]>;
-    /**
-     * The suggest-ranker trainer's probe feed: `suggestion_adopted` signals
-     * (typed prefix + adopted text) ≤ the split pin, topped up with
-     * execution-verified synthetic vocabulary pairs.
-     */
+    /** Suggest-ranker examples at or before an optional signal split. */
     suggestDataset(opts?: {
         limit?: number;
         splitSeq?: number;
     }): Promise<Schemas["SuggestDatasetResponse"]>;
-    /**
-     * The extractor fine-tune's training feed: EPISODE transcripts joined to
-     * the facts the observe pipeline committed from them.
-     */
+    /** Extractor examples at or before an optional signal split. */
     extractorDataset(opts?: {
         limit?: number;
         splitSeq?: number;
@@ -369,8 +336,7 @@ export declare class LbbClient {
     }): Promise<unknown>;
     /**
      * Promote a finished `planner_lora` training run: gated on held-out slot
-     * exactness, recorded as a `kind=planner` training run whose adapter `/v1/ask`
-     * then serves.
+     * exactness and recorded as a `kind=planner` training run.
      */
     promotePlanner(opts: {
         runId: string;
@@ -386,28 +352,11 @@ export declare class LbbClient {
      * pair that admits a single relation flags `signature_forced`.
      */
     suggest(body: Schemas["SearchSuggestRequest"]): Promise<Schemas["SearchSuggestResponse"]>;
-    /**
-     * Snap free text to the nearest real vocabulary item. Embedding cosine
-     * on a managed graph, else lexical; never fabricates a term.
-     */
+    /** Snap free text to the nearest term in the pinned published vocabulary. */
     resolveTerm(body: Schemas["ResolveTermRequest"]): Promise<Schemas["ResolveTermResponse"]>;
-    /**
-     * Ground a natural-language question to the graph's real vocabulary, retrieve
-     * against the pinned snapshot, and answer with citations (`/v1/ask`).
-     */
-    ask(body: Schemas["AskRequest"]): Promise<Schemas["AskResponse"]>;
-    /**
-     * Name the relation between two entities (`/v1/decode`): the DB narrows the
-     * candidates to the type pair's admissible relations, answers alone
-     * when the pair forces a single relation, and otherwise decodes it with the
-     * graph-native fine-tuned model — the "DB narrows, cheap model decodes" call.
-     */
+    /** Decode a relation from the graph's admissible published vocabulary. */
     decode(body: Schemas["DecodeRequest"]): Promise<Schemas["DecodeResponse"]>;
-    /**
-     * Report which completion mechanisms will carry on this graph:
-     * signature sparsity, name semantics, sampled narrowing recall, and a
-     * narrow / narrow+finetune / lexical-first recommendation.
-     */
+    /** Report completion strategy fitness for the pinned published graph. */
     groundability(opts?: {
         sample?: number;
     }): Promise<Schemas["GroundabilityReport"]>;
@@ -438,8 +387,6 @@ export declare class LbbClient {
         name?: string;
         relations?: string[];
         asOf?: string;
-        /** Require the bounded ranged-adjacency path; returns `index_busy` while unavailable. */
-        indexed?: boolean;
     }): Promise<Schemas["EntityNeighborhoodResponse"]>;
     /** Exact type cardinality plus a bounded deterministic sample from ranged adjacency. */
     entityTypeSample(opts: {
@@ -466,37 +413,11 @@ export declare class LbbClient {
         asOf?: string;
         asOfCommitSeq?: number;
     }): Promise<Schemas["EntityDetailResponse"]>;
-    /**
-     * Paged edge listing. Scope to one node with `id` (or `type`+`name`) and a
-     * `direction` (`out`/`in`/`both`) to walk **every** edge of a high-degree node
-     * — `entityDetail` returns the full set but is awkward to page; this carries
-     * `offset`/`limit` and reports `total_count`. Optional `relation`/`q` filters
-     * and an `asOf`/`asOfCommitSeq` snapshot pin. Each row carries `valid_time`, so
-     * the page is enough to reconstruct a per-edge timeline.
-     */
-    graphEdges(opts?: {
-        id?: string;
-        type?: string;
-        name?: string;
-        direction?: "out" | "in" | "both";
-        relation?: string;
-        q?: string;
-        limit?: number;
-        /** Opaque cursor from a previous page's `next_cursor`. */
-        cursor?: string | number;
-        /** @deprecated Legacy alias for `cursor` (still accepted by the server). */
-        offset?: number;
-        asOf?: string;
-        asOfCommitSeq?: number;
-    }): Promise<ListResponse<Schemas["GraphEdgeRow"]>>;
     /**
      * Page through every row of a list endpoint, following `next_cursor` until
      * exhausted. Pass a fetcher that takes a cursor and returns a
      * {@link ListResponse}:
-     * ```ts
-     * for await (const e of client.listAll((cursor) =>
-     *   client.entities.list({ cursor, fields: "title" }))) { … }
-     * ```
+     * The caller supplies a bounded collection endpoint and its cursor.
      */
     listAll<T>(fetchPage: (cursor?: string) => Promise<ListResponse<T>>): AsyncGenerator<T, void, unknown>;
     /** Current state of an entity's relations, optionally as-of a timestamp. */
@@ -507,8 +428,6 @@ export declare class LbbClient {
     transitions(body: Schemas["EntityTransitionsRequest"]): Promise<Schemas["EntityTransitionsResponse"]>;
     /** Lineage and evidence for a single edge. */
     why(body: Schemas["WhyRequest"]): Promise<Schemas["WhyResponse"]>;
-    /** SHACL-style shape/pattern query. */
-    shacl(body: Schemas["ShaclQueryRequest"]): Promise<Schemas["ShaclQueryResponse"]>;
     /**
      * SPARQL-subset SELECT/ASK/aggregate query (FILTER, HAVING, ORDER BY, ASK,
      * COUNT/SUM/AVG/MIN/MAX). GROUP BY is not limited to entity identity:
@@ -538,28 +457,6 @@ export declare class LbbClient {
      * optional/union/negated leg rather than a grouped aggregate.
      */
     analytics(body: Schemas["AnalyticQueryRequest"]): Promise<Schemas["AnalyticQueryResponse"]>;
-    /**
-     * Run inference rules (SHACL-AF `sh:TripleRule` shape) to a bounded fixpoint
-     * and return the derived edges as a **preview** — derived facts are never
-     * written to the asserted graph. Each rule is a BGP `body`/`where` plus a
-     * `head` triple template instantiated per binding.
-     */
-    infer(body: Schemas["InferenceRunRequest"]): Promise<Schemas["InferenceRunResponse"]>;
-    /**
-     * Define (replace) the versioned rule set stored on the scoped graph branch.
-     * The stored set is what SHACL `include_derived` and `infer` use when a
-     * request carries no inline rules. Returns the new `rules_version`.
-     */
-    defineRules(body: Schemas["RuleSetDefineRequest"]): Promise<Schemas["RuleSetDefineResponse"]>;
-    /** The rule set stored on the scoped graph branch (version + rules). */
-    graphRules(): Promise<Schemas["RuleSet"]>;
-    /**
-     * Derive edges from calibrated retrieval matches (preview): each
-     * candidate scored `P >= threshold` becomes a derived edge `(anchor, relation,
-     * matched)` with a typed `Retrieval` provenance leaf. Pass either explicit
-     * `candidates` or a `query` the server runs as BM25 entity retrieval.
-     */
-    retrievalPremises(body: Schemas["RetrievalPremiseRequest"]): Promise<Schemas["RetrievalPremiseResponse"]>;
     /**
      * The active ontology (entity types and relations) for the scoped graph.
      * Pass `{ counts: true }` to include a per-relation current-edge count
@@ -573,11 +470,10 @@ export declare class LbbClient {
      * Audit the current snapshot against the ontology's *implied* constraints —
      * capped `cardinality` derived as `sh:maxCount` — returning a SHACL-shaped
      * report. Whole-snapshot and never blocks a write. Unlike
-     * {@link SchemaNamespace.audit}, this needs no published shape bundle: the
-     * shapes come from the ontology itself. See the `decoration_status` catalog on
-     * {@link ontologyView} for which decorations are enforced.
+     * The report is referenced by the pinned published read root and carries its
+     * own validation watermark and ontology/shapes provenance.
      */
-    ontologyConformance(): Promise<Schemas["SchemaAuditReport"]>;
+    ontologyConformance(opts?: Pick<ReadConsistencyOptions, "consistency">): Promise<Schemas["SchemaAuditReport"]>;
     /** Discover ontology concepts, terms, and relations. */
     ontologySearch(body: Schemas["OntologySearchRequest"]): Promise<Schemas["OntologySearchResponse"]>;
     /** Resolve mentions to concepts/entities. */
@@ -593,47 +489,6 @@ export declare class LbbClient {
     evolveOntology(body: Schemas["OntologyEvolveRequest"]): Promise<Schemas["OntologyEvolveResponse"]>;
     /** Suggest ontology additions from the current graph without mutating it. */
     induceOntology(body: Schemas["OntologyInduceRequest"]): Promise<Schemas["OntologyInduceResponse"]>;
-    /**
-     * Build default ANN + BM25 indexes. With `{ background: true }` the build
-     * runs detached on the server and the call returns immediately — use it for
-     * large corpora whose synchronous build would exceed a fronting gateway's
-     * timeout (a 504), then poll `metadata()` for completion.
-     */
-    indexBuild(opts?: {
-        background?: boolean;
-    }): Promise<unknown>;
-    /**
-     * Build BM25, ANN/vector, and adjacency index families. With
-     * `{ background: true }` the build runs detached on the server and the call
-     * returns immediately — use it for large corpora whose synchronous build would
-     * exceed a fronting gateway's timeout, then poll `metadata()` for completion.
-     */
-    indexRun(opts?: {
-        background?: boolean;
-    }): Promise<unknown>;
-    /** Submit a durable full-index build. Requires a reconnect-safe idempotency key. */
-    indexSubmit(body: Partial<Schemas["IndexBuildOptions"]> | undefined, opts: {
-        idempotencyKey: string;
-    }): Promise<Schemas["SearchIndexJobStatusResponse"]>;
-    /** Poll a durable full-index build. */
-    indexJob(jobId: string): Promise<Schemas["SearchIndexJobStatusResponse"]>;
-    /** Cancel a durable full-index build. Repeated cancellation returns its current terminal status. */
-    cancelIndexJob(jobId: string): Promise<Schemas["SearchIndexJobStatusResponse"]>;
-    /** Append a BM25 delta segment for the unindexed WAL tail. */
-    indexDelta(): Promise<Schemas["IndexDeltaResponse"]>;
-    /** Preview or delete superseded persisted index runs. */
-    indexGc(opts?: {
-        keepRuns?: number;
-        dryRun?: boolean;
-    }): Promise<Schemas["IndexGcResponse"]>;
-    /** Submit durable, cancellable index garbage collection. */
-    indexGcSubmit(body: Schemas["IndexGcRequest"] | undefined, opts: {
-        idempotencyKey: string;
-    }): Promise<Schemas["IndexGcJobStatusResponse"]>;
-    /** Poll exact planning/deletion progress for durable index garbage collection. */
-    indexGcJob(jobId: string): Promise<Schemas["IndexGcJobStatusResponse"]>;
-    /** Cancel durable index garbage collection. */
-    cancelIndexGcJob(jobId: string): Promise<Schemas["IndexGcJobStatusResponse"]>;
     /** Fold the WAL tail into snapshot segments. */
     compact(opts?: {
         minTailCommits?: number;
@@ -641,11 +496,9 @@ export declare class LbbClient {
     }): Promise<Schemas["WalCompactResponse"]>;
     /** Server, graph, and persisted-index status. */
     status(): Promise<unknown>;
-    /** Graph footprint, WAL tail, and index coverage. Exact object inventory is opt-in. */
+    /** Graph footprint, WAL tail, and published-index coverage. */
     metadata(opts?: {
-        includeObjects?: boolean;
         includeIndexes?: boolean;
-        includeTemporalCoverage?: boolean;
     }): Promise<Schemas["GraphMetadataResponse"]>;
     waitForIndexLineage(targetSeq: number, opts?: {
         timeoutMs?: number;
@@ -653,6 +506,8 @@ export declare class LbbClient {
     }): Promise<IndexLineageObservation>;
     /** Graph counts and type/relation buckets. Carries `consistency`/`min_indexed_seq` on the URL. */
     summary(opts?: ReadConsistencyOptions): Promise<Schemas["GraphSummaryResponse"]>;
+    /** Pinned published read root and its query/conformance lag against one coherent head. */
+    readSnapshot(): Promise<Schemas["PublishedReadStatusResponse"]>;
     /** List the graphs (and branches) under the scoped tenant. */
     listGraphs(): Promise<Schemas["GraphListResponse"]>;
 }