@littlebigbrain/client 0.1.0 → 0.3.0

package/src/client.ts

@@ -1,1428 +0,0 @@
-import type { components } from "./schema.js";
-
-/** Request/response types, generated from the committed OpenAPI spec. */
-export type Schemas = components["schemas"];
-
-/**
- * The unified list-response envelope returned by every collection read
- * (`/v1/graph/entities`, `/v1/graph/edges`, `/v1/graph/observations`): the rows
- * in `data`, plus `next_cursor` (echo back as `cursor` for the next page) and
- * the pre-page `total_count`. Walk pages with {@link LbbClient.listAll}.
- */
-export interface ListResponse<T> {
-  object: "list";
-  data: T[];
-  has_more: boolean;
-  next_cursor: string | null;
-  snapshot: Schemas["SnapshotView"];
-  total_count: number;
-}
-
-/**
- * A flat `{ field: value }` property map. Values are coerced to each field's
- * declared type server-side, so a string like `"2026-06-26"` lands in a
- * `date_time` field and `"52"` in an `i64` field. The verbose
- * `Schemas["PropertyInput"][]` form is also accepted.
- */
-export type FlatProperties = Record<string, string | number | boolean>;
-
-/** A single entity-properties record for commit/import, with flat or verbose properties. */
-export type EntityPropertiesLine = {
-  type: string;
-  name: string;
-  /** Optional stable external key; identity becomes `(type, key)`. */
-  key?: string;
-  properties: FlatProperties | Schemas["PropertyInput"][];
-};
-
-/** One bulk-import line: a triplet, or an entity-properties record. */
-export type ImportLine = Schemas["TripletInput"] | EntityPropertiesLine;
-
-export type AttributeFilterOp = "eq" | "ne" | "lt" | "le" | "gt" | "ge";
-
-export type AttributeFilterValue =
-  | string
-  | number
-  | boolean
-  | { dateTime: string }
-  | { entity: Schemas["EntitySelector"] };
-
-export interface AttributeFilter {
-  /** Query variable whose typed property should be compared. Defaults to the first bound pattern variable. */
-  var?: string;
-  /** Ontology property field name, e.g. `status`, `score`, or `committed_at`. */
-  field: string;
-  /** Comparison operator. Defaults to `eq`. */
-  op?: AttributeFilterOp;
-  value: AttributeFilterValue;
-}
-
-export interface EntityAttributeFilterOptions {
-  /** Relation patterns that bind the entity variable(s) before attribute filters run. */
-  patterns: Schemas["AnalyticTriplePattern"][];
-  /** One or more typed-property comparisons. */
-  where: AttributeFilter | AttributeFilter[];
-  /** Additional raw structured-SPARQL filters to AND with `where`. */
-  filters?: Schemas["SparqlFilter"][];
-  select?: string[];
-  limit?: number;
-  offset?: number;
-  asOfValidTime?: string;
-  asOfCommitSeq?: number;
-  orderBy?: Schemas["SparqlOrderBy"][];
-  reason?: boolean;
-  maxSolutions?: number;
-  maxObjectReads?: number;
-  maxFetchedBytes?: number;
-}
-
-/**
- * Minimal structural shape of `fetch`, so the client depends on neither the DOM
- * lib nor a specific runtime. Native `fetch` (Node 18+, browsers, workers)
- * satisfies it; tests can pass a fake.
- */
-export type FetchLike = (
-  input: string,
-  init?: { method?: string; headers?: Record<string, string>; body?: string },
-) => Promise<{
-  ok: boolean;
-  status: number;
-  headers?: { get(name: string): string | null };
-  text(): Promise<string>;
-}>;
-
-/** One term in a SPARQL result binding (the standard results-JSON term object). */
-export interface SparqlTerm {
-  type: "uri" | "literal" | "bnode" | "typed-literal";
-  value: string;
-  datatype?: string;
-  "xml:lang"?: string;
-}
-
-/** The standard SPARQL 1.1 Query Results JSON document. */
-export interface SparqlResultsJson {
-  head: { vars?: string[]; link?: string[] };
-  results?: { bindings: Record<string, SparqlTerm>[] };
-  boolean?: boolean;
-}
-
-/** Parsed SPARQL results: the head vars, the ASK boolean (or null), the raw
- * typed bindings, and the bindings flattened to `{ variable: lexicalValue }`. */
-export interface SparqlResults {
-  vars: string[];
-  boolean: boolean | null;
-  bindings: Record<string, SparqlTerm>[];
-  rows: Record<string, string>[];
-}
-
-/**
- * Parse a {@link Schemas.SparqlTextResponse} (whose `results` field carries the
- * SPARQL Results document as a JSON *string*) into typed bindings plus flat
- * `{ variable: lexicalValue }` rows — the form most callers want, so they never
- * have to `JSON.parse` and zip `head.vars` with binding values by hand.
- */
-export function parseSparqlResults(response: Schemas["SparqlTextResponse"]): SparqlResults {
-  const doc = JSON.parse(response.results) as SparqlResultsJson;
-  const vars = doc.head?.vars ?? [];
-  if (typeof doc.boolean === "boolean") {
-    return { vars, boolean: doc.boolean, bindings: [], rows: [] };
-  }
-  const bindings = doc.results?.bindings ?? [];
-  const rows = bindings.map((binding) =>
-    Object.fromEntries(Object.entries(binding).map(([name, term]) => [name, term.value])),
-  );
-  return { vars, boolean: null, bindings, rows };
-}
-
-function firstPatternVariable(patterns: Schemas["AnalyticTriplePattern"][]): string {
-  for (const pattern of patterns) {
-    if ("var" in pattern.subject) return pattern.subject.var;
-    if ("var" in pattern.object) return pattern.object.var;
-  }
-  return "entity";
-}
-
-function attributeFilterValue(value: AttributeFilterValue): Schemas["SparqlValue"] {
-  if (typeof value === "boolean") return { bool: value };
-  if (typeof value === "number") return Number.isInteger(value) ? { i64: value } : { f64: value };
-  if (typeof value === "string") return { str: value };
-  if ("dateTime" in value) return { date_time: value.dateTime };
-  return { entity: value.entity };
-}
-
-function attributeFilter(filter: AttributeFilter, defaultVar: string): Schemas["SparqlFilter"] {
-  return {
-    compare: {
-      op: filter.op ?? "eq",
-      left: { property: { var: filter.var ?? defaultVar, field: filter.field } },
-      right: { value: attributeFilterValue(filter.value) },
-    },
-  };
-}
-
-export interface LbbClientOptions {
-  /** Base URL of the Little Big Brain server, e.g. `https://db.eu.littlebigbrain.com`. */
-  baseUrl: string;
-  /** Stack API key (`lbb_sk_test_…` / `lbb_sk_live_…`) or single-mode token. */
-  apiKey?: string;
-  /** Graph name (sent as `?graph=`; server default is `main`). */
-  graph?: string;
-  /** Branch name (sent as `?branch=`; server default is `main`). */
-  branch?: string;
-  /**
-   * Stack slug (sent as `?stack=`). Needed only with a session-token `apiKey`
-   * (`lbb_ses_…`), which authorizes an account rather than a single stack; a
-   * stack API key (`lbb_sk_test_…` / `lbb_sk_live_…`) already fixes the stack and ignores this.
-   */
-  stack?: string;
-  /** Override the fetch implementation (defaults to the global `fetch`). */
-  fetch?: FetchLike;
-  /** API version header sent on every request. Defaults to the beta reset contract. */
-  apiVersion?: string;
-  /** Retry count for 429/5xx responses and network failures. Defaults to 2. */
-  maxRetries?: number;
-  /** Base delay between retries. Defaults to 100ms. Tests can set 0. */
-  retryDelayMs?: number;
-}
-
-export interface LbbStackView {
-  stack_id: string;
-  owner_id?: string;
-  name: string;
-  slug: string;
-  tenant_id: string;
-  default_graph: string;
-  default_branch: string;
-  created_at_micros: number;
-  api_key_hint: string;
-  api_key_rotated_at_micros: number;
-}
-
-export interface LbbAdminStackCreateRequest {
-  owner_id: string;
-  name: string;
-  slug?: string;
-}
-
-export interface LbbAdminStackResponse {
-  ok: true;
-  stack: LbbStackView;
-  api_key?: string;
-  active_api_key_count?: number;
-}
-
-export type LbbStackActivityWindow = "1h" | "4h" | "12h" | "24h";
-
-export interface LbbStackActivityResponse {
-  ok: true;
-  stack: {
-    slug: string;
-    name?: string;
-  };
-  window: {
-    range: LbbStackActivityWindow;
-    from_micros: number;
-    to_micros: number;
-    bucket_seconds: number;
-    freshness_seconds: number;
-  };
-  totals: {
-    requests: number;
-    errors: number;
-    p50_latency_ms: number;
-    p95_latency_ms: number;
-    p99_latency_ms: number;
-    storage_read_ops: number;
-    storage_read_bytes: number;
-    storage_write_ops: number;
-    storage_write_bytes: number;
-    index_read_ops: number;
-    index_read_bytes: number;
-  };
-  details: {
-    total_bucket_count: number;
-    active_bucket_count: number;
-    error_rate: number;
-    storage_total_ops: number;
-    storage_total_bytes: number;
-    non_index_storage_read_ops: number;
-    non_index_storage_read_bytes: number;
-    index_read_share: number;
-    first_activity_bucket_start_micros?: number;
-    last_activity_bucket_start_micros?: number;
-  };
-  series: Array<{
-    bucket_start_micros: number;
-    requests: number;
-    errors: number;
-    p50_latency_ms: number;
-    p95_latency_ms: number;
-    p99_latency_ms: number;
-    storage_read_ops: number;
-    storage_read_bytes: number;
-    storage_write_ops: number;
-    storage_write_bytes: number;
-    index_read_ops: number;
-    index_read_bytes: number;
-  }>;
-  routes: Array<{
-    family: string;
-    requests: number;
-    errors: number;
-    error_rate: number;
-    request_share: number;
-    p50_latency_ms: number;
-    p95_latency_ms: number;
-    p99_latency_ms: number;
-  }>;
-  storage: Array<{
-    family: string;
-    read_ops: number;
-    read_bytes: number;
-    write_ops: number;
-    write_bytes: number;
-    total_ops: number;
-    total_bytes: number;
-    op_share: number;
-    byte_share: number;
-  }>;
-  partial: boolean;
-}
-
-export interface LbbAdminSessionResponse {
-  ok: true;
-  /** A `lbb_ses_…` session token scoped to the account. */
-  token: string;
-  expires_at_micros: number;
-}
-
-export interface LbbAdminStackDeleteResponse {
-  ok: true;
-  deleted_stack: LbbStackView;
-  tenant_prefix: string;
-  objects_deleted: number;
-  bytes_deleted: number;
-}
-
-export interface LbbErrorPayload {
-  type?: string;
-  code?: string;
-  message?: string;
-  param?: string | null;
-  request_id?: string | null;
-  doc_url?: string | null;
-}
-
-export interface RawLbbResponse<T> {
-  data: T;
-  status: number;
-  requestId?: string;
-  version?: string;
-  headers?: { get(name: string): string | null };
-}
-
-export interface RequestOptions {
-  query?: Query;
-  body?: unknown;
-  /** Pre-serialized request body (e.g. NDJSON). Takes precedence over `body`. */
-  rawBody?: string;
-  /** Overrides the default `application/json` content type (used with `rawBody`). */
-  contentType?: string;
-  idempotencyKey?: string;
-}
-
-/** Thrown when the server responds with a non-2xx status. */
-export class LbbError extends Error {
-  readonly type?: string;
-  readonly code?: string;
-  readonly param?: string | null;
-  readonly requestId?: string | null;
-  readonly docUrl?: string | null;
-
-  constructor(
-    readonly status: number,
-    readonly body: string,
-    readonly error?: LbbErrorPayload,
-  ) {
-    super(error?.message ?? `Little Big Brain ${status}: ${body}`);
-    this.name = "LbbError";
-    this.type = error?.type;
-    this.code = error?.code;
-    this.param = error?.param;
-    this.requestId = error?.request_id;
-    this.docUrl = error?.doc_url;
-  }
-}
-
-type QueryValue = string | number | boolean | undefined;
-type Query = Record<string, QueryValue>;
-
-function sleep(ms: number): Promise<void> {
-  if (ms <= 0) return Promise.resolve();
-  const timer = (globalThis as { setTimeout?: (callback: () => void, ms: number) => unknown })
-    .setTimeout;
-  return new Promise((resolve) => {
-    if (timer) {
-      timer(resolve, ms);
-    } else {
-      resolve();
-    }
-  });
-}
-
-function retryableStatus(status: number): boolean {
-  return status === 429 || status >= 500;
-}
-
-function retryAllowed(method: string, idempotencyKey?: string): boolean {
-  const upper = method.toUpperCase();
-  return upper === "GET" || upper === "HEAD" || upper === "OPTIONS" || idempotencyKey !== undefined;
-}
-
-function parseLbbError(status: number, body: string, fallbackRequestId?: string): LbbError {
-  try {
-    const parsed = JSON.parse(body) as { error?: LbbErrorPayload };
-    if (parsed.error) {
-      return new LbbError(status, body, {
-        ...parsed.error,
-        request_id: parsed.error.request_id ?? fallbackRequestId ?? null,
-      });
-    }
-  } catch {
-    // Fall through to an unstructured error.
-  }
-  return new LbbError(status, body, {
-    type: "api_error",
-    code: "unstructured_error",
-    message: body || `Little Big Brain ${status}`,
-    request_id: fallbackRequestId ?? null,
-  });
-}
-
-/**
- * A typed HTTP client for a Little Big Brain graph server. One instance is scoped to a
- * single graph/branch; construct another for a different scope. All methods
- * return the parsed JSON response and throw {@link LbbError} on failure.
- */
-export class LbbClient {
-  private readonly baseUrl: string;
-  private readonly apiKey?: string;
-  private readonly graphName?: string;
-  private readonly branchName?: string;
-  private readonly stack?: string;
-  private readonly fetchImpl: FetchLike;
-  private readonly apiVersion: string;
-  private readonly maxRetries: number;
-  private readonly retryDelayMs: number;
-
-  readonly search: SearchNamespace;
-  readonly indexes: IndexNamespace;
-  readonly entities: EntityNamespace;
-  readonly schema: SchemaNamespace;
-
-  constructor(options: LbbClientOptions) {
-    this.baseUrl = options.baseUrl.replace(/\/+$/, "");
-    this.apiKey = options.apiKey;
-    this.graphName = options.graph;
-    this.branchName = options.branch;
-    this.stack = options.stack;
-    this.apiVersion = options.apiVersion ?? "2026-06-22";
-    this.maxRetries = options.maxRetries ?? 2;
-    this.retryDelayMs = options.retryDelayMs ?? 100;
-    const fallback = (globalThis as { fetch?: FetchLike }).fetch;
-    const chosen = options.fetch ?? (fallback ? fallback.bind(globalThis) : undefined);
-    if (!chosen) {
-      throw new Error("no fetch implementation available; pass options.fetch");
-    }
-    this.fetchImpl = chosen;
-    this.search = new SearchNamespace(this);
-    this.indexes = new IndexNamespace(this);
-    this.entities = new EntityNamespace(this);
-    this.schema = new SchemaNamespace(this);
-  }
-
-  graph(name: string, opts: { branch?: string; stack?: string } = {}): GraphNamespace {
-    return new GraphNamespace(
-      this.withScope({
-        graph: name,
-        branch: opts.branch ?? this.branchName,
-        stack: opts.stack ?? this.stack,
-      }),
-    );
-  }
-
-  /**
-   * A new client for a different graph/branch on the same server and credential.
-   * Each instance is scoped to one graph/branch, so use this to target another
-   * scope (e.g. creating a fresh graph) without mutating the current client.
-   */
-  withScope(scope: { graph?: string; branch?: string; stack?: string }): LbbClient {
-    return new LbbClient({
-      baseUrl: this.baseUrl,
-      apiKey: this.apiKey,
-      graph: scope.graph ?? this.graphName,
-      branch: scope.branch ?? this.branchName,
-      stack: scope.stack ?? this.stack,
-      fetch: this.fetchImpl,
-      apiVersion: this.apiVersion,
-      maxRetries: this.maxRetries,
-      retryDelayMs: this.retryDelayMs,
-    });
-  }
-
-  private buildUrl(path: string, query?: Query): string {
-    const params: string[] = [];
-    const push = (key: string, value: string | number | boolean) =>
-      params.push(`${encodeURIComponent(key)}=${encodeURIComponent(String(value))}`);
-    if (this.graphName !== undefined) push("graph", this.graphName);
-    if (this.branchName !== undefined) push("branch", this.branchName);
-    if (this.stack !== undefined) push("stack", this.stack);
-    for (const [key, value] of Object.entries(query ?? {})) {
-      if (value !== undefined) push(key, value);
-    }
-    const qs = params.length > 0 ? `?${params.join("&")}` : "";
-    return `${this.baseUrl}${path}${qs}`;
-  }
-
-  async rawRequest<T>(
-    method: string,
-    path: string,
-    opts: RequestOptions = {},
-  ): Promise<RawLbbResponse<T>> {
-    const headers: Record<string, string> = {
-      "content-type": opts.contentType ?? "application/json",
-      "lbb-version": this.apiVersion,
-    };
-    if (this.apiKey !== undefined) headers["authorization"] = `Bearer ${this.apiKey}`;
-    if (opts.idempotencyKey !== undefined) headers["idempotency-key"] = opts.idempotencyKey;
-    const canRetry = retryAllowed(method, opts.idempotencyKey);
-    const body =
-      opts.rawBody !== undefined
-        ? opts.rawBody
-        : opts.body !== undefined
-          ? JSON.stringify(opts.body)
-          : undefined;
-    const init = {
-      method,
-      headers,
-      body,
-    };
-    let response: Awaited<ReturnType<FetchLike>> | undefined;
-    let text = "";
-    for (let attempt = 0; attempt <= this.maxRetries; attempt += 1) {
-      try {
-        response = await this.fetchImpl(this.buildUrl(path, opts.query), init);
-        text = await response.text();
-      } catch (error) {
-        if (canRetry && attempt < this.maxRetries) {
-          await sleep(this.retryDelayMs * (attempt + 1));
-          continue;
-        }
-        throw error;
-      }
-      if (response.ok || !retryableStatus(response.status) || attempt === this.maxRetries) {
-        break;
-      }
-      if (!canRetry) {
-        break;
-      }
-      await sleep(this.retryDelayMs * (attempt + 1));
-    }
-    if (response === undefined) throw new Error("request did not produce a response");
-    const requestId = response.headers?.get("x-request-id") ?? undefined;
-    const version = response.headers?.get("lbb-version") ?? undefined;
-    if (!response.ok) throw parseLbbError(response.status, text.trim(), requestId);
-    return {
-      data: (text ? JSON.parse(text) : undefined) as T,
-      status: response.status,
-      requestId,
-      version,
-      headers: response.headers,
-    };
-  }
-
-  async request<T>(
-    method: string,
-    path: string,
-    opts: RequestOptions = {},
-  ): Promise<T> {
-    const response = await this.rawRequest<T>(method, path, opts);
-    return response.data;
-  }
-
-  private mutationKey(prefix: string): string {
-    const random = Math.random().toString(36).slice(2);
-    return `${prefix}:${Date.now()}:${random}`;
-  }
-
-  idempotencyKey(prefix = "request"): string {
-    return this.mutationKey(prefix);
-  }
-
-  // --- writes ---
-
-  /** Commit triplets and optional entity embeddings. Prefer `client.graph("main").facts.create(...)`. */
-  commit(
-    body: Schemas["TripletCommitFile"],
-    opts: { idempotencyKey?: string } = {},
-  ): Promise<Schemas["GraphCommitResponse"]> {
-    return this.request("POST", "/v1/graph/commit", {
-      body,
-      idempotencyKey: opts.idempotencyKey ?? this.idempotencyKey("facts.create"),
-    });
-  }
-
-  /**
-   * Validate-only preflight: run the same ontology/schema validation a real
-   * commit would and report the would-be effect (`op_count`, `written_properties`,
-   * `schema_validation`) without writing. A rejected request fails exactly as a
-   * real commit would, so this is a safe check before mutating. No idempotency
-   * key needed — nothing is persisted.
-   */
-  commitDryRun(
-    body: Schemas["TripletCommitFile"],
-  ): Promise<Schemas["GraphCommitDryRunResponse"]> {
-    return this.request("POST", "/v1/graph/commit", {
-      body,
-      query: { dry_run: true },
-    });
-  }
-
-  /**
-   * Bulk-ingest a dataset as NDJSON. Each line is either a triplet or an
-   * `{type,name,properties}` entity-properties record; lines are batched into
-   * bounded internal commits server-side, so a whole dataset loads in one
-   * streamed request without a single oversized commit. Pass `lines` as an array
-   * (serialized to NDJSON here) or a pre-built NDJSON string.
-   */
-  import(
-    lines: ImportLine[] | string,
-    opts: {
-      batch?: number;
-      strict?: boolean;
-      observedAt?: string;
-      idempotencyKey?: string;
-    } = {},
-  ): Promise<Schemas["GraphImportResponse"]> {
-    const ndjson =
-      typeof lines === "string"
-        ? lines
-        : lines.map((line) => JSON.stringify(line)).join("\n");
-    return this.request("POST", "/v1/graph/import", {
-      rawBody: ndjson,
-      contentType: "application/x-ndjson",
-      query: { batch: opts.batch, strict: opts.strict, observed_at: opts.observedAt },
-      idempotencyKey: opts.idempotencyKey,
-    });
-  }
-
-  /**
-   * Bulk-ingest N-Triples without client-side conversion. Resource-object
-   * triples become keyed Resource edges; literal-object triples become text
-   * properties on the subject Resource.
-   */
-  importRdf(
-    ntriples: string,
-    opts: {
-      batch?: number;
-      strict?: boolean;
-      observedAt?: string;
-      resourceType?: string;
-      edgeIdempotency?: "append" | "skip_unchanged";
-      idempotencyKey?: string;
-    } = {},
-  ): Promise<Schemas["GraphRdfImportResponse"]> {
-    return this.request("POST", "/v1/graph/import/rdf", {
-      rawBody: ntriples,
-      contentType: "application/n-triples",
-      query: {
-        batch: opts.batch,
-        strict: opts.strict,
-        observed_at: opts.observedAt,
-        format: "ntriples",
-        resource_type: opts.resourceType,
-        edge_idempotency: opts.edgeIdempotency,
-      },
-      idempotencyKey: opts.idempotencyKey,
-    });
-  }
-
-  /**
-   * Retract specific edges and/or every edge touching given entities. Appends
-   * superseding retract events rather than deleting — history stays visible in an
-   * `as_of` read before the retraction, but the edges drop out of current state.
-   * The surgical alternative to {@link deleteGraph}.
-   */
-  retract(
-    body: Schemas["GraphRetractRequest"],
-    opts: { idempotencyKey?: string } = {},
-  ): Promise<Schemas["GraphRetractResponse"]> {
-    return this.request("POST", "/v1/graph/retract", {
-      body,
-      idempotencyKey: opts.idempotencyKey ?? this.idempotencyKey("retract"),
-    });
-  }
-
-  /** Create the scoped graph/branch. Construct the client with the desired graph/branch first. */
-  createGraph(): Promise<Schemas["CreateGraphResponse"]> {
-    return this.request("POST", "/v1/graph/create");
-  }
-
-  /** Fork the scoped branch from an existing branch in the same graph. */
-  createBranch(
-    body: Schemas["GraphBranchCreateRequest"],
-  ): Promise<Schemas["GraphBranchCreateResponse"]> {
-    return this.request("POST", "/v1/graph/branch", { body });
-  }
-
-  /**
-   * Delete every object under the scoped graph/branch — a destructive reset.
-   * `confirm` must equal the scoped graph id; the next commit re-initializes the
-   * graph. Branch-scoped: sibling branches are untouched.
-   */
-  deleteGraph(opts: { confirm: string }): Promise<unknown> {
-    return this.request("POST", "/v1/graph/delete", { query: { confirm: opts.confirm } });
-  }
-
-  // --- search ---
-
-  /** Full semantic hybrid search from a request body (`POST /v1/graph/search`). */
-  graphSearch(
-    body: Schemas["SemanticGraphSearchRequest"],
-  ): Promise<Schemas["SemanticGraphSearchResponse"]> {
-    return this.request("POST", "/v1/graph/search", { body });
-  }
-
-  /** Reciprocal-rank-fusion across sub-queries. */
-  multiSearch(
-    body: Schemas["HybridMultiSearchRequest"],
-  ): Promise<Schemas["HybridMultiSearchResponse"]> {
-    return this.request("POST", "/v1/search/multi", { body });
-  }
-
-  /**
-   * Append relevance labels for a set of search results — how Little Big Brain
-   * gathers customer-specific qrels. Grade results (3 ideal/good, 1 partial,
-   * 0 bad), referencing the search response's `search_id` so labels tie back to
-   * that ranking. Stored apart from customer facts and exported via
-   * {@link searchFeedbackExport} as training/eval data for embedding fine-tuning.
-   */
-  searchFeedback(
-    body: Schemas["SearchFeedbackRequest"],
-    opts: { idempotencyKey?: string } = {},
-  ): Promise<Schemas["SearchFeedbackResponse"]> {
-    return this.request("POST", "/v1/search/feedback", {
-      body,
-      idempotencyKey: opts.idempotencyKey,
-    });
-  }
-
-  /** Export the stored relevance labels as qrels-style rows for training. */
-  searchFeedbackExport(): Promise<Schemas["SearchFeedbackExportResponse"]> {
-    return this.request("GET", "/v1/search/feedback/export");
-  }
-
-  /** BM25 search. */
-  fullTextSearch(
-    body: Schemas["FullTextSearchRequest"],
-  ): Promise<Schemas["FullTextSearchResponse"]> {
-    return this.request("POST", "/v1/search/full-text", { body });
-  }
-
-  /** ANN/vector search. */
-  embeddingSearch(
-    body: Schemas["EmbeddingSearchRequest"],
-  ): Promise<Schemas["EmbeddingSearchResponse"]> {
-    return this.request("POST", "/v1/search/embedding", { body });
-  }
-
-  // --- traversal ---
-
-  /** Bounded k-hop graph traversal. */
-  traverse(body: Schemas["TraverseRequest"]): Promise<Schemas["TraverseResponse"]> {
-    return this.request("POST", "/v1/graph/traverse", { body });
-  }
-
-  /** Resolve a query to seed entities, then return bounded paths. */
-  semanticTraverse(
-    body: Schemas["SemanticTraverseRequest"],
-  ): Promise<Schemas["SemanticTraverseResponse"]> {
-    return this.request("POST", "/v1/graph/semantic-traverse", { body });
-  }
-
-  /** Ranked incoming/outgoing neighborhood for a graph entity. */
-  entityNeighborhood(opts: {
-    id?: string;
-    type?: string;
-    name?: string;
-    relations?: string[];
-    asOf?: string;
-  }): Promise<Schemas["EntityNeighborhoodResponse"]> {
-    return this.request("GET", "/v1/graph/entity/neighborhood", {
-      query: {
-        id: opts.id,
-        type: opts.type,
-        name: opts.name,
-        relations: opts.relations?.join(","),
-        as_of: opts.asOf,
-      },
-    });
-  }
-
-  /** Stored entity object-ref status and index-coverage metadata (no
-   * attributes — read those from `entityDetail`'s top-level `attributes`). */
-  entityMetadata(opts: {
-    id?: string;
-    type?: string;
-    name?: string;
-    asOf?: string;
-  }): Promise<Schemas["EntityMetadataResponse"]> {
-    return this.request("GET", "/v1/graph/entity/metadata", {
-      query: {
-        id: opts.id,
-        type: opts.type,
-        name: opts.name,
-        as_of: opts.asOf,
-      },
-    });
-  }
-
-  /**
-   * Entity detail: metadata, attributes, current state, edge history, and
-   * observations. Pass `asOf` / `asOfCommitSeq` to reproduce the node as of a
-   * past instant / commit (the state, edges, and history are pinned to it).
-   */
-  entityDetail(opts: {
-    id?: string;
-    type?: string;
-    name?: string;
-    asOf?: string;
-    asOfCommitSeq?: number;
-  }): Promise<Schemas["EntityDetailResponse"]> {
-    return this.request("GET", "/v1/graph/entity", {
-      query: {
-        id: opts.id,
-        type: opts.type,
-        name: opts.name,
-        as_of: opts.asOf,
-        as_of_commit_seq: opts.asOfCommitSeq,
-      },
-    });
-  }
-
-  /**
-   * 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"]>> {
-    return this.request("GET", "/v1/graph/edges", {
-      query: {
-        id: opts.id,
-        type: opts.type,
-        name: opts.name,
-        direction: opts.direction,
-        relation: opts.relation,
-        q: opts.q,
-        limit: opts.limit,
-        cursor: opts.cursor,
-        offset: opts.offset,
-        as_of: opts.asOf,
-        as_of_commit_seq: opts.asOfCommitSeq,
-      },
-    });
-  }
-
-  /**
-   * 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" }))) { … }
-   * ```
-   */
-  async *listAll<T>(
-    fetchPage: (cursor?: string) => Promise<ListResponse<T>>,
-  ): AsyncGenerator<T, void, unknown> {
-    let cursor: string | undefined;
-    for (;;) {
-      const page = await fetchPage(cursor);
-      for (const row of page.data) yield row;
-      if (!page.has_more || page.next_cursor == null) return;
-      cursor = page.next_cursor;
-    }
-  }
-
-  // --- temporal / lineage / shapes ---
-
-  /** Current state of an entity's relations, optionally as-of a timestamp. */
-  currentState(body: Schemas["CurrentStateRequest"]): Promise<Schemas["CurrentStateResponse"]> {
-    return this.request("POST", "/v1/query/state", { body });
-  }
-
-  /** Full edge-event history for a relationship. */
-  history(
-    body: Schemas["RelationshipHistoryRequest"],
-  ): Promise<Schemas["RelationshipHistoryResponse"]> {
-    return this.request("POST", "/v1/query/history", { body });
-  }
-
-  /** Ordered state-transition log for an entity's relation, with dwell time. */
-  transitions(
-    body: Schemas["EntityTransitionsRequest"],
-  ): Promise<Schemas["EntityTransitionsResponse"]> {
-    return this.request("POST", "/v1/query/transitions", { body });
-  }
-
-  /** Lineage and evidence for a single edge. */
-  why(body: Schemas["WhyRequest"]): Promise<Schemas["WhyResponse"]> {
-    return this.request("POST", "/v1/query/why", { body });
-  }
-
-  /** SHACL-style shape/pattern query. */
-  shacl(body: Schemas["ShaclQueryRequest"]): Promise<Schemas["ShaclQueryResponse"]> {
-    return this.request("POST", "/v1/query/shacl", { body });
-  }
-
-  /**
-   * SPARQL-subset SELECT/ASK/aggregate query (FILTER, HAVING, ORDER BY, ASK,
-   * COUNT/SUM/AVG/MIN/MAX). GROUP BY is not limited to entity identity:
-   * `group_by` keys on a variable's entity, and `group_keys` adds typed scalar
-   * keys — a `property` value, or a `date_bucket` calendar truncation
-   * (`year`/`month`/`week`/`day`/`hour`) of a datetime property — so a
-   * per-category breakdown or a time series is one server-side query. Scalar
-   * keys come back per group in `groups[].value_keys[<as>]`, entity keys in
-   * `groups[].keys`.
-   */
-  sparql(body: Schemas["SparqlSelectRequest"]): Promise<Schemas["SparqlSelectResponse"]> {
-    return this.request("POST", "/v1/query/sparql", { body });
-  }
-
-  /** 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"]> {
-    return this.request("POST", "/v1/query/sparql-text", { body });
-  }
-
-  /**
-   * Run a SPARQL 1.1 text query and return parsed results — the ergonomic
-   * complement to {@link sparqlText} (which hands back the raw results string).
-   * Returns `{ vars, boolean, bindings, rows }` via {@link parseSparqlResults}:
-   * `rows` is the bindings flattened to `{ variable: lexicalValue }`, `boolean`
-   * is the ASK answer (or `null` for a SELECT).
-   */
-  async sparqlRows(body: Schemas["SparqlTextRequest"]): Promise<SparqlResults> {
-    return parseSparqlResults(await this.sparqlText(body));
-  }
-
-  /**
-   * Basic-graph-pattern query with group-graph-pattern combinators
-   * (UNION / OPTIONAL / MINUS / EXISTS / NOT EXISTS) folded over the base
-   * patterns. The complement to {@link sparql}: this route carries the
-   * combinators (but not FILTER/aggregation), so use it when a query needs an
-   * optional/union/negated leg rather than a grouped aggregate.
-   */
-  analytics(body: Schemas["AnalyticQueryRequest"]): Promise<Schemas["AnalyticQueryResponse"]> {
-    return this.request("POST", "/v1/query/analytics", { body });
-  }
-
-  /**
-   * 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"]> {
-    return this.request("POST", "/v1/inference/run", { body });
-  }
-
-  /**
-   * 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"]> {
-    return this.request("POST", "/v1/inference/rules", { body });
-  }
-
-  /** The rule set stored on the scoped graph branch (version + rules). */
-  graphRules(): Promise<Schemas["RuleSet"]> {
-    return this.request("GET", "/v1/inference/rules");
-  }
-
-  /**
-   * Stage G — 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"]> {
-    return this.request("POST", "/v1/inference/retrieval-premises", { body });
-  }
-
-  // --- ontology ---
-
-  /**
-   * The active ontology (entity types and relations) for the scoped graph.
-   * Pass `{ counts: true }` to include a per-relation current-edge count
-   * (`OntologyRelationView.edge_count`) so a caller can see which declared
-   * relations are actually populated — at the cost of a snapshot load.
-   */
-  ontologyView(opts: { counts?: boolean } = {}): Promise<Schemas["OntologyView"]> {
-    return this.request("GET", "/v1/ontology", {
-      query: opts.counts ? { counts: true } : undefined,
-    });
-  }
-
-  /**
-   * 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.
-   */
-  ontologyConformance(): Promise<Schemas["SchemaAuditReport"]> {
-    return this.request("GET", "/v1/ontology/conformance");
-  }
-
-  /** Discover ontology concepts, terms, and relations. */
-  ontologySearch(
-    body: Schemas["OntologySearchRequest"],
-  ): Promise<Schemas["OntologySearchResponse"]> {
-    return this.request("POST", "/v1/ontology/search", { body });
-  }
-
-  /** Resolve mentions to concepts/entities. */
-  ontologyResolve(
-    body: Schemas["OntologyResolveRequest"],
-  ): Promise<Schemas["OntologyResolveResponse"]> {
-    return this.request("POST", "/v1/ontology/resolve", { body });
-  }
-
-  /** Define the active ontology before the scoped graph's first commit. */
-  ontologyDefine(
-    body: Schemas["OntologyDefineRequest"],
-  ): Promise<Schemas["OntologyDefineResponse"]> {
-    return this.request("POST", "/v1/ontology/define", { body });
-  }
-
-  /**
-   * Additively evolve the active ontology of an existing graph: widen relation
-   * domains/ranges and declare new entity types (all by name), bumping the
-   * ontology version. Additive-only — every existing record stays valid, so no
-   * migration is needed — and a request that changes nothing is a no-op.
-   */
-  evolveOntology(
-    body: Schemas["OntologyEvolveRequest"],
-  ): Promise<Schemas["OntologyEvolveResponse"]> {
-    return this.request("POST", "/v1/ontology/evolve", { body });
-  }
-
-  // --- index lifecycle ---
-
-  /**
-   * 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> {
-    return this.request("POST", "/v1/index/build", { query: { background: opts.background || undefined } });
-  }
-
-  /**
-   * 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> {
-    return this.request("POST", "/v1/index/run", { query: { background: opts.background || undefined } });
-  }
-
-  /** Append a BM25 delta segment for the unindexed WAL tail. */
-  indexDelta(): Promise<Schemas["IndexDeltaResponse"]> {
-    return this.request("POST", "/v1/index/delta");
-  }
-
-  /** Preview or delete superseded persisted index runs. */
-  indexGc(opts: { keepRuns?: number; dryRun?: boolean } = {}): Promise<Schemas["IndexGcResponse"]> {
-    return this.request("POST", "/v1/index/gc", {
-      query: { keep_runs: opts.keepRuns, dry_run: opts.dryRun },
-    });
-  }
-
-  /** Fold the WAL tail into snapshot segments. */
-  compact(
-    opts: { minTailCommits?: number; maxSegments?: number } = {},
-  ): Promise<Schemas["WalCompactResponse"]> {
-    return this.request("POST", "/v1/graph/compact", {
-      query: { min_tail_commits: opts.minTailCommits, max_segments: opts.maxSegments },
-    });
-  }
-
-  // --- inspection ---
-
-  /** Server, graph, and persisted-index status. */
-  status(): Promise<unknown> {
-    return this.request("GET", "/v1/status");
-  }
-
-  /** Graph footprint, WAL tail, and index coverage. */
-  metadata(): Promise<Schemas["GraphMetadataResponse"]> {
-    return this.request("GET", "/v1/graph/metadata");
-  }
-
-  /** Graph counts and type/relation buckets. */
-  summary(): Promise<Schemas["GraphSummaryResponse"]> {
-    return this.request("GET", "/v1/graph/summary");
-  }
-
-  /** List the graphs (and branches) under the scoped tenant. */
-  listGraphs(): Promise<Schemas["GraphListResponse"]> {
-    return this.request("GET", "/v1/graphs");
-  }
-
-  // --- database admin ---
-
-  /** Create a database stack and return its one-time stack API key. */
-  adminCreateStack(body: LbbAdminStackCreateRequest): Promise<LbbAdminStackResponse> {
-    return this.request("POST", "/api/admin/stacks", { body });
-  }
-
-  /** Inspect a database stack without returning secret key material. */
-  adminStack(slug: string): Promise<LbbAdminStackResponse> {
-    return this.request("GET", "/api/admin/stacks", { query: { stack: slug } });
-  }
-
-  /** Rotate a database stack key and return the new one-time API key. */
-  adminRotateStackKey(slug: string): Promise<LbbAdminStackResponse> {
-    return this.request("POST", "/api/admin/stacks/rotate-key", { query: { stack: slug } });
-  }
-
-  /** Delete a database stack after confirming the slug. */
-  adminDeleteStack(slug: string): Promise<LbbAdminStackDeleteResponse> {
-    return this.request("DELETE", "/api/admin/stacks", { query: { stack: slug, confirm: slug } });
-  }
-
-  /**
-   * Mint a short-lived `lbb_ses_…` session token for an account. A trusted
-   * co-located service uses it (with `?stack=<slug>`) to call the data plane on
-   * the account's behalf without handling the stack's mode-bearing stack key.
-   */
-  adminMintSession(accountId: string): Promise<LbbAdminSessionResponse> {
-    return this.request("POST", "/api/admin/sessions", { body: { account_id: accountId } });
-  }
-
-  /** Customer-visible activity for one database stack. */
-  adminStackActivity(slug: string, window: LbbStackActivityWindow = "24h"): Promise<LbbStackActivityResponse> {
-    return this.request("GET", "/api/admin/stacks/activity", { query: { stack: slug, window } });
-  }
-
-  /** Activity for the stack selected by the bearer stack key or session. */
-  stackActivity(window: LbbStackActivityWindow = "24h"): Promise<LbbStackActivityResponse> {
-    return this.request("GET", "/v1/stack/activity", { query: { window } });
-  }
-}
-
-export class GraphNamespace {
-  readonly facts: FactsNamespace;
-
-  constructor(private readonly client: LbbClient) {
-    this.facts = new FactsNamespace(client);
-  }
-
-  branch(name: string): GraphNamespace {
-    return new GraphNamespace(this.client.withScope({ branch: name }));
-  }
-
-  create(): Promise<Schemas["CreateGraphResponse"]> {
-    return this.client.createGraph();
-  }
-
-  delete(opts: { confirm: string }): Promise<unknown> {
-    return this.client.deleteGraph(opts);
-  }
-
-  /** Retract edges/entities from the scoped graph. See {@link LbbClient.retract}. */
-  retract(
-    body: Schemas["GraphRetractRequest"],
-    opts: { idempotencyKey?: string } = {},
-  ): Promise<Schemas["GraphRetractResponse"]> {
-    return this.client.retract(body, opts);
-  }
-}
-
-export class FactsNamespace {
-  constructor(private readonly client: LbbClient) {}
-
-  create(
-    body: Schemas["TripletCommitFile"],
-    opts: { idempotencyKey?: string } = {},
-  ): Promise<Schemas["GraphCommitResponse"]> {
-    return this.client.request("POST", "/v1/graph/commit", {
-      body,
-      idempotencyKey: opts.idempotencyKey ?? this.client.idempotencyKey("facts.create"),
-    });
-  }
-
-  /** Bulk-load a dataset as NDJSON. See {@link LbbClient.import}. */
-  import(
-    lines: ImportLine[] | string,
-    opts: {
-      batch?: number;
-      strict?: boolean;
-      observedAt?: string;
-      idempotencyKey?: string;
-    } = {},
-  ): Promise<Schemas["GraphImportResponse"]> {
-    return this.client.import(lines, opts);
-  }
-
-  /**
-   * Bulk-load N-Triples through the native RDF import endpoint.
-   *
-   * Statements are committed through the fixed RDF_TRIPLE relation; source RDF
-   * predicates and literal term details are preserved as edge metadata.
-   */
-  importRdf(
-    ntriples: string,
-    opts: {
-      batch?: number;
-      strict?: boolean;
-      observedAt?: string;
-      resourceType?: string;
-      edgeIdempotency?: "append" | "skip_unchanged";
-      idempotencyKey?: string;
-    } = {},
-  ): Promise<Schemas["GraphRdfImportResponse"]> {
-    return this.client.importRdf(ntriples, opts);
-  }
-}
-
-export class SearchNamespace {
-  constructor(private readonly client: LbbClient) {}
-
-  hybrid(
-    query: string,
-    opts?: {
-      topK?: number;
-      source?: string;
-      consistency?: string;
-      lexical?: boolean;
-      bm25?: boolean;
-      vector?: boolean;
-      targets?: string[];
-      profile?: string;
-      /** Opt-in impression logging (L1): durably record this search's full
-       * ranking context, keyed by `search_id`, so a later feedback label on it
-       * carries the ranking it was judged against. Off by default. */
-      logImpression?: boolean;
-    },
-  ): Promise<Schemas["SemanticGraphSearchResponse"]>;
-  hybrid(
-    body: Schemas["SemanticGraphSearchRequest"],
-  ): Promise<Schemas["SemanticGraphSearchResponse"]>;
-  hybrid(
-    input: string | Schemas["SemanticGraphSearchRequest"],
-    opts: {
-      topK?: number;
-      source?: string;
-      consistency?: string;
-      lexical?: boolean;
-      bm25?: boolean;
-      vector?: boolean;
-      targets?: string[];
-      profile?: string;
-      logImpression?: boolean;
-    } = {},
-  ): Promise<Schemas["SemanticGraphSearchResponse"]> {
-    if (typeof input !== "string") {
-      return this.client.request("POST", "/v1/graph/search", { body: input });
-    }
-    return this.client.request("GET", "/v1/search", {
-      query: {
-        query: input,
-        top_k: opts.topK,
-        source: opts.source,
-        consistency: opts.consistency,
-        lexical: opts.lexical,
-        bm25: opts.bm25,
-        vector: opts.vector,
-        targets: opts.targets?.join(","),
-        profile: opts.profile,
-        log_impression: opts.logImpression,
-      },
-    });
-  }
-
-  multi(body: Schemas["HybridMultiSearchRequest"]): Promise<Schemas["HybridMultiSearchResponse"]> {
-    return this.client.multiSearch(body);
-  }
-
-  feedback(
-    body: Schemas["SearchFeedbackRequest"],
-    opts: { idempotencyKey?: string } = {},
-  ): Promise<Schemas["SearchFeedbackResponse"]> {
-    return this.client.searchFeedback(body, opts);
-  }
-
-  feedbackExport(): Promise<Schemas["SearchFeedbackExportResponse"]> {
-    return this.client.searchFeedbackExport();
-  }
-
-  fullText(body: Schemas["FullTextSearchRequest"]): Promise<Schemas["FullTextSearchResponse"]> {
-    return this.client.fullTextSearch(body);
-  }
-
-  vector(body: Schemas["EmbeddingSearchRequest"]): Promise<Schemas["EmbeddingSearchResponse"]> {
-    return this.client.embeddingSearch(body);
-  }
-}
-
-export class SchemaNamespace {
-  constructor(private readonly client: LbbClient) {}
-
-  /** Active graph schema bundle: ontology plus activated SHACL shapes. */
-  view(opts: { audit?: boolean } = {}): Promise<Schemas["SchemaBundleView"]> {
-    return this.client.request("GET", "/v1/schema", {
-      query: { audit: opts.audit || undefined },
-    });
-  }
-
-  /** Preview a proposed RDF/SHACL schema bundle and audit current data. */
-  preview(body: Schemas["SchemaPreviewRequest"]): Promise<Schemas["SchemaPreviewResponse"]> {
-    return this.client.request("POST", "/v1/schema/preview", { body });
-  }
-
-  /** Activate a previewed SHACL schema bundle for this graph branch. */
-  publish(body: Schemas["SchemaPublishRequest"]): Promise<Schemas["SchemaPublishResponse"]> {
-    return this.client.request("POST", "/v1/schema/publish", { body });
-  }
-
-  /** Audit current data against the active SHACL schema bundle. */
-  audit(): Promise<Schemas["SchemaAuditReport"]> {
-    return this.client.request("POST", "/v1/schema/audit");
-  }
-}
-
-export class IndexNamespace {
-  constructor(private readonly client: LbbClient) {}
-
-  run(opts: { wait?: boolean; background?: boolean; body?: unknown } = {}): Promise<unknown> {
-    const background = opts.background ?? (opts.wait === false ? true : undefined);
-    return this.client.request("POST", "/v1/index/run", {
-      query: { background },
-      body: opts.body,
-    });
-  }
-
-  build(): Promise<unknown> {
-    return this.client.indexBuild();
-  }
-
-  delta(): Promise<Schemas["IndexDeltaResponse"]> {
-    return this.client.indexDelta();
-  }
-
-  gc(opts: { keepRuns?: number; dryRun?: boolean } = {}): Promise<Schemas["IndexGcResponse"]> {
-    return this.client.indexGc(opts);
-  }
-}
-
-export class EntityNamespace {
-  constructor(private readonly client: LbbClient) {}
-
-  /**
-   * Browse entities as the unified list envelope. Pass `fields` (names or `*`)
-   * to inline each row's typed attributes as native JSON (under `attributes`) —
-   * "list entities and their titles" in one call instead of a list plus N point
-   * lookups — or `ids`
-   * to fetch a specific set. Page with `cursor` from the previous `next_cursor`.
-   */
-  list(
-    opts: {
-      type?: string;
-      limit?: number;
-      cursor?: string | number;
-      /** @deprecated Legacy alias for `cursor`. */
-      offset?: number;
-      query?: string;
-      /** Property names to inline per row (or `"*"` / `["*"]` for all). */
-      fields?: string | string[];
-      /** Specific entity ids to fetch in one call (bulk lookup). */
-      ids?: string | string[];
-    } = {},
-  ): Promise<ListResponse<Schemas["EntityExplorerRow"]>> {
-    const csv = (v: string | string[] | undefined) =>
-      Array.isArray(v) ? v.join(",") : v;
-    return this.client.request("GET", "/v1/graph/entities", {
-      query: {
-        type: opts.type,
-        limit: opts.limit,
-        cursor: opts.cursor,
-        offset: opts.offset,
-        q: opts.query,
-        fields: csv(opts.fields),
-        ids: csv(opts.ids),
-      },
-    });
-  }
-
-  get(opts: { id?: string; type?: string; name?: string; asOf?: string }): Promise<Schemas["EntityMetadataResponse"]> {
-    return this.client.entityMetadata(opts);
-  }
-
-  detail(opts: { id?: string; type?: string; name?: string }): Promise<Schemas["EntityDetailResponse"]> {
-    return this.client.entityDetail(opts);
-  }
-
-  /**
-   * Filter entities already bound by relation patterns using typed attributes,
-   * without writing RDF property IRIs by hand. This is a convenience wrapper over
-   * the structured SPARQL route: relation `patterns` bind variables, and `where`
-   * compares ontology property fields on those bound variables.
-   */
-  filterByAttributes(opts: EntityAttributeFilterOptions): Promise<Schemas["SparqlSelectResponse"]> {
-    const defaultVar = firstPatternVariable(opts.patterns);
-    const where = Array.isArray(opts.where) ? opts.where : [opts.where];
-    return this.client.sparql({
-      patterns: opts.patterns,
-      filters: [...(opts.filters ?? []), ...where.map((filter) => attributeFilter(filter, defaultVar))],
-      select: opts.select,
-      limit: opts.limit,
-      offset: opts.offset,
-      as_of_valid_time: opts.asOfValidTime,
-      as_of_commit_seq: opts.asOfCommitSeq,
-      order_by: opts.orderBy,
-      reason: opts.reason,
-      max_solutions: opts.maxSolutions,
-      max_object_reads: opts.maxObjectReads,
-      max_fetched_bytes: opts.maxFetchedBytes,
-    });
-  }
-}