@modernrelay/orbit-omnigraph 0.13.6 → 0.14.0

package/dist/index.d.ts

@@ -2,7 +2,7 @@ import { GraphEdge, GraphNode, BeginIngestOptions, IngestSession, Revisions, Gra
 import { Omnigraph } from '@modernrelay/omnigraph';
 
 /**
- * Identity codec (spec Appendix B.3 / B.4).
+ * Identity codec.
  *
  * Omnigraph node ids are unique **per type only** (derived from the `@key`
  * tuple within each type's table), so unqualified ids are unsound as orbit
@@ -13,7 +13,7 @@ import { Omnigraph } from '@modernrelay/omnigraph';
  * no `(kind, sourceId)` pair can collide with a different pair.
  *
  * Human-readable labels stay separate from identity; there is deliberately no
- * `namespaceIds:false` escape hatch (B.3).
+ * `namespaceIds:false` escape hatch.
  */
 interface DecodedSourceId {
     /** The namespace component: a node type name or an edge type name. */
@@ -26,7 +26,7 @@ interface DecodedSourceId {
  *
  * - Nodes: `encodeSourceId(NodeType, data.id)`
  * - Edges: `encodeSourceId(EdgeName, data.id)`; endpoints use
- *   `encodeSourceId(endpointType, from|to)` (B.3).
+ * `encodeSourceId(endpointType, from|to)`.
  */
 declare function encodeSourceId(kind: string, sourceId: string): string;
 /**
@@ -38,16 +38,16 @@ declare function encodeSourceId(kind: string, sourceId: string): string;
  */
 declare function decodeSourceId(id: string): DecodedSourceId | null;
 /**
- * Synthetic edge id for **query-derived** subgraphs (spec §5 rule, B.4).
+ * Synthetic edge id for **query-derived** subgraphs.
  *
  * The GQ grammar has no edge variable, so the query path can never surface
  * physical edge ids; query-derived edges are identified by
  * `['synthetic-edge', EdgeName, source, target]` where `source`/`target` are
  * the already-encoded endpoint node ids.
  *
- * Exported for the future query path (B.5 expansion recipe — post-v1).
- * Caveats (B.4): parallel edges collapse under this scheme, and a dataset
- * MUST NOT mix synthetic ids with physical `/export` ids for the same edges —
+ * Exported for the future query path.
+ * Caveats: parallel edges collapse under this scheme, and a dataset
+ * MUST NOT mix synthetic ids with physical `/export` ids for the same edges
  * one scheme per dataset, never both. Because a synthetic id is a 4-tuple,
  * {@link decodeSourceId} rejects it (`null`), keeping the two schemes
  * mechanically un-confusable.
@@ -55,13 +55,13 @@ declare function decodeSourceId(id: string): DecodedSourceId | null;
 declare function encodeSyntheticEdgeId(edgeName: string, source: string, target: string): string;
 
 /**
- * `.pg` schema model + tolerant parser (spec Appendix B.3 / B.6).
+ * `.pg` schema model + tolerant parser.
  *
  * The adapter needs three things from the graph schema, all served here:
- *  1. edge endpoint-type resolution (B.3 — export edge lines carry bare
- *     `from`/`to` ids without endpoint types),
- *  2. per-property wire-type knowledge for temporal/blob normalization (B.6),
- *  3. a stable schema fingerprint for the export revision stamp (B.2).
+ * 1. edge endpoint-type resolution (export edge lines carry bare `from`/`to`
+ * ids without endpoint types),
+ * 2. per-property wire-type knowledge for temporal/blob normalization,
+ * 3. a stable schema fingerprint for the export revision stamp.
  *
  * The parser is deliberately tolerant: it extracts the declarations it
  * understands (interfaces, node blocks, edge declarations, properties,
@@ -141,7 +141,7 @@ interface PgSchema {
  */
 declare function parsePgSchema(source: string): PgSchema;
 /**
- * Resolve an edge type's declared endpoint node types (B.3). Export edge
+ * Resolve an edge type's declared endpoint node types. Export edge
  * lines carry bare `from`/`to` ids, so endpoint types come from here. Edge
  * names match exactly first, then case-insensitively (the server matches edge
  * names case-insensitively). Returns `null` for an unknown edge name.
@@ -151,7 +151,7 @@ declare function edgeEndpointTypes(schema: PgSchema, edgeName: string): {
     to: string;
 } | null;
 /**
- * Stable fingerprint of `.pg` source for the B.2 revision stamp: FNV-1a
+ * Stable fingerprint of `.pg` source for the adapter revision stamp: FNV-1a
  * 64-bit over the UTF-8 bytes of the source, as 16 lowercase hex chars.
  *
  * Pure and browser-safe (no `node:crypto`). Hashes the source **verbatim**:
@@ -166,44 +166,44 @@ interface BigIntKeyWarning {
     property: string;
 }
 /**
- * B.6 hazard scan: `I64`/`U64` properties used as identity (`@key` or named
- * `id`). The HTTP path emits native JSON numbers even past ±2^53 — silently
- * rounded by `JSON.parse`, unrescued by the SDK — so two distinct big-int ids
- * can collapse after rounding, violating §5. Surface these before loading.
+ * Find `I64`/`U64` properties used as identity (`@key` or named `id`). The
+ * HTTP path emits native JSON numbers even past ±2^53, where `JSON.parse`
+ * silently rounds them, so two distinct big-int ids can collapse. Surface
+ * these hazards before loading.
  */
 declare function bigIntKeyWarnings(schema: PgSchema): BigIntKeyWarning[];
 
 /**
- * Export-line classification and normalization (spec Appendix B.2 / B.3 / B.6).
+ * Export-line classification and normalization.
  *
  * `/export` streams NDJSON — one JSON object per line, `data` passed through
  * **verbatim** by the SDK. This module turns those lines into orbit
  * `GraphNode`/`GraphEdge` values:
  *
- *  - ids are namespaced through the B.3 codec (`encodeSourceId`),
- *  - the node/edge KIND is injected as {@link ORBIT_TYPE_KEY} — namespaced so
- *    a schema's own `type` property passes through as ordinary data (B.6),
- *  - edge endpoint types are resolved from the `.pg` schema (edge lines carry
- *    bare `from`/`to` ids — B.3),
- *  - attr values are normalized to the query-path string forms (B.6) so
- *    generated types and §16.6 temporal dimensions see one encoding
- *    regardless of read path:
- *      * `Date`      — export sends **days since Unix epoch** (number) →
- *                      `'YYYY-MM-DD'` (UTC)
- *      * `DateTime`  — export sends **epoch milliseconds** (number) →
- *                      ISO 8601 (`'YYYY-MM-DDTHH:MM:SS.mmmZ'`)
- *      * `Blob`      — inline internal blobs arrive as `'base64:<data>'` →
- *                      `'data:application/octet-stream;base64,<data>'`;
- *                      external-URI refs pass through verbatim (B.10)
- *      * everything else — verbatim.
+ * - ids are namespaced through the adapter identity codec (`encodeSourceId`),
+ * - the node/edge KIND is injected as {@link ORBIT_TYPE_KEY} — namespaced so
+ * a schema's own `type` property passes through as ordinary data,
+ * - edge endpoint types are resolved from the `.pg` schema because edge lines
+ * carry bare `from`/`to` ids,
+ * - attr values are normalized to the query-path string forms so
+ * generated types and temporal dimensions see one encoding
+ * regardless of read path:
+ * * `Date` — export sends **days since Unix epoch** (number) →
+ * `'YYYY-MM-DD'` (UTC)
+ * * `DateTime` — export sends **epoch milliseconds** (number) →
+ * ISO 8601 (`'YYYY-MM-DDTHH:MM:SS.mmmZ'`)
+ * * `Blob` — inline internal blobs arrive as `'base64:<data>'` →
+ * `'data:application/octet-stream;base64,<data>'`;
+ * external-URI refs pass through verbatim
+ * * everything else — verbatim.
  *
  * Non-finite float sentinels (`'NaN'`/`'Infinity'`/`'-Infinity'`) are a
  * **query-path-only** encoding: a non-finite stored float aborts `/export`
- * server-side, so export-loaded data never contains the sentinels (B.6).
+ * server-side, so export-loaded data never contains the sentinels.
  * This module therefore does NOT special-case them.
  */
 
-/** An edge line names an edge type the `.pg` schema does not declare (B.3). */
+/** An edge line names an edge type the `.pg` schema does not declare. */
 declare class UnknownEdgeTypeError extends Error {
     readonly name = "UnknownEdgeTypeError";
     readonly edgeName: string;
@@ -230,14 +230,14 @@ type ClassifiedExportLine = NodeExportLine | EdgeExportLine | {
     kind: 'unknown';
 };
 /**
- * Classify one parsed export line per the B.2 shapes:
- *  - node line: `{"type": "<NodeType>", "data": {"id", …props}}`
- *  - edge line: `{"edge": "<EdgeName>", "from": <src id>, "to": <dst id>, "data": {"id", …props}}`
+ * Classify one parsed export line using the adapter's wire shapes:
+ * - node line: `{"type": "<NodeType>", "data": {"id", …props}}`
+ * - edge line: `{"edge": "<EdgeName>", "from": <src id>, "to": <dst id>, "data": {"id", …props}}`
  * Anything else is `{ kind: 'unknown' }`.
  */
 declare function classifyExportLine(line: unknown): ClassifiedExportLine;
 /**
- * The adapter's node/edge KIND discriminator key (B.3/B.6).
+ * The adapter's node/edge KIND discriminator key.
  *
  * Namespaced on purpose: the adapter injects this field into someone else's
  * data, so it takes the awkward key and leaves the generic word `type` to the
@@ -252,8 +252,8 @@ declare const ORBIT_TYPE_KEY = "orbit:type";
 /**
  * Normalize a node export line to a `GraphNode`:
  * `id = encodeSourceId(type, data.id)`, `attrs = { …data, 'orbit:type' }`
- * with B.6 value normalization driven by the schema's property types. A node
- * type absent from the schema is tolerated — its attrs pass through verbatim
+ * with value normalization driven by the schema's property types. A node type
+ * absent from the schema is tolerated — its attrs pass through verbatim
  * (identity never needs the schema on the node path).
  */
 declare function normalizeNode(line: {
@@ -263,8 +263,8 @@ declare function normalizeNode(line: {
 /**
  * Normalize an edge export line to a `GraphEdge`:
  * `id = encodeSourceId(edge, data.id)`; `source`/`target` namespace the bare
- * `from`/`to` ids with the endpoint node types resolved from the schema
- * (B.3). Throws {@link UnknownEdgeTypeError} when the schema does not declare
+ * `from`/`to` ids with the endpoint node types resolved from the schema.
+ * Throws {@link UnknownEdgeTypeError} when the schema does not declare
  * the edge — endpoint identity cannot be constructed without it.
  */
 declare function normalizeEdge(line: {
@@ -275,14 +275,14 @@ declare function normalizeEdge(line: {
 }, schema: PgSchema): GraphEdge;
 
 /**
- * Public types for the v1 export loader (spec Appendix B.1/B.2/B.8/B.10).
+ * Public types for the v1 export loader.
  *
- * The organizing rule of the v1 adapter (B.10): graphs load via `og.export()`;
- * queries only ever resolve ids. These types describe that one load path —
+ * The organizing rule of the v1 adapter: graphs load via `og.export()`;
+ * queries only ever resolve ids. These types describe that one load path
  * its options, its ingestion target seam, and its revision-stamped result.
  */
 
-/** Cumulative progress, reported after every appended batch (B.2). */
+/** Cumulative progress, reported after every appended batch. */
 interface OmnigraphLoadProgress {
     /** Export lines consumed so far (nodes + edges + skipped unknowns). */
     lines: number;
@@ -294,33 +294,33 @@ interface OmnigraphLoadProgress {
     bytes: number;
 }
 /**
- * B.2 revision-stamp drift policy: what to do when the branch head observed
- * after the export stream differs from the head observed before it.
+ * Revision-stamp drift policy: what to do when the branch head observed after
+ * the export stream differs from the head observed before it.
  *
  * - `'reject'` (default): abort the session and throw — the graph is left
- *   untouched. The right choice for durable/shareable sessions.
+ * untouched. The right choice for durable/shareable sessions.
  * - `'accept-warn'`: buffer the export, then commit under the canonical final
- *   revision once `headAfter` is known; both heads are recorded in `dataRef`
- *   and a warning is added when they differ.
+ * revision once `headAfter` is known; both heads are recorded in `dataRef`
+ * and a warning is added when they differ.
  * - `'retry-once'`: abort, restart the whole load once; a second drift
- *   rejects.
+ * rejects.
  */
 type OmnigraphDriftPolicy = 'reject' | 'accept-warn' | 'retry-once';
 interface OmnigraphSourceOptions {
     /**
      * A **preconfigured** SDK client. In the browser this must be a safe
      * same-origin or public client — this option surface deliberately accepts
-     * no `baseUrl`/`token` pair (B.1): authenticated client construction lives
+     * no `baseUrl`/`token` pair: authenticated client construction lives
      * ONLY in `@modernrelay/orbit-omnigraph/server`
      * (`createOmnigraphServerClient`), which is excluded from client bundles.
      */
     client: Omnigraph;
     /** Cluster graph id; every call is scoped to it via `client.graph(graphId)`. */
     graphId: string;
-    /** Branch to export (B.2 — export is branch-only). Default `'main'`. */
+    /** Branch to export. Default `'main'`. */
     branch?: string;
     /**
-     * Partial per-type load (B.10): forwarded as the SDK `ExportInput.typeNames`
+     * Partial per-type load: forwarded as the SDK `ExportInput.typeNames`
      * field (wire form `type_names`). Omit to export every table.
      */
     typeNames?: readonly string[];
@@ -330,17 +330,17 @@ interface OmnigraphSourceOptions {
      * Whole-load byte budget for the atomic replace. Because atomic staging
      * cannot drain before commit, exceeding this finite cap aborts the load
      * without publishing a partial graph. Must be a positive safe integer.
-     * Default 64 MiB.
+     * Default 512 MiB.
      */
     maxPendingBytes?: number;
-    /** B.2 drift policy. Default `'reject'`. */
+    /** Revision-stamp drift policy. Default `'reject'`. */
     driftPolicy?: OmnigraphDriftPolicy;
     /** Called after every appended batch with cumulative counts. */
     onProgress?: (p: OmnigraphLoadProgress) => void;
 }
 /**
- * B.8 view-state `dataRef` (v1: branch-based). The readable object behind the
- * canonical `sourceRevision` hash; retained so hosts can display/persist the
+ * Branch-based view-state `dataRef`. This is the readable object behind the
+ * canonical `sourceRevision` hash, retained so hosts can display or persist the
  * exact coordinates a session was loaded from. `headBefore !== headAfter`
  * only ever appears under `driftPolicy: 'accept-warn'`.
  */
@@ -355,8 +355,8 @@ interface OmnigraphDataRef {
     schemaFingerprint: string;
     /**
      * Sorted node-type subset of a PARTIAL export; absent = full export.
-     * Part of the identity coordinate (review P1: two partial exports at the
-     * same head differing only by types must never replay as one another).
+     * Part of the identity coordinate: two partial exports at the same head
+     * differing only by types must never replay as one another.
      */
     typeNames?: readonly string[];
 }
@@ -369,9 +369,9 @@ interface OmnigraphLoadCounts {
 }
 interface OmnigraphLoadResult {
     /**
-     * The committed source coordinate: the canonical hash of `dataRef` (B.2).
+     * The committed source coordinate: the canonical hash of `dataRef`.
      * Stable across identical replays — a second load of a quiescent branch
-     * commits idempotently (§5: same `{datasetKey, sourceRevision}` publishes
+     * commits idempotently (the same `{datasetKey, sourceRevision}` publishes
      * nothing).
      */
     sourceRevision: string;
@@ -380,14 +380,14 @@ interface OmnigraphLoadResult {
     /** `og.health().version` — the server build the load ran against. */
     serverVersion: string;
     /**
-     * Non-fatal observations: SDK/server major.minor mismatch (B.1), accepted
-     * drift (B.2), B.6 big-int identity hazards, skipped unknown lines. Never
+     * Non-fatal observations: SDK/server major.minor mismatch, accepted
+     * drift, big-int identity hazards, and skipped unknown lines. Never
      * hides a retry or accepted-drift decision.
      */
     warnings: string[];
 }
 /**
- * Minimal structural ingestion target (§7.5) — deliberately decoupled from
+ * Minimal structural ingestion target — deliberately decoupled from
  * `GraphInstance`. The loader needs exactly the ingest seam and nothing else,
  * so any object with these members works: a real `GraphInstance` (which
  * satisfies this interface structurally), a recorder, or a headless pipeline.
@@ -399,48 +399,47 @@ interface IngestTarget {
 }
 
 /**
- * v1 export loader (spec Appendix B.2 / B.8 / B.10).
+ * v1 export loader.
  *
- * The organizing rule (B.10): graphs load via `og.export()` — one streamed
+ * The organizing rule: graphs load via `og.export` — one streamed
  * NDJSON pass, edge lines first (lexicographic table-key order), driven
  * straight into a `purpose:'replace'` ingest session on the target. Queries
  * never introduce nodes or edges.
  *
- * Revision stamp (B.2): the canonical `sourceRevision` hashes
+ * Revision stamp: the canonical `sourceRevision` hashes
  * `{ graphId, branch, headBefore, headAfter, schemaFingerprint }` (plus the
- * sorted `typeNames` subset when the export is partial — review P1), but
+ * sorted `typeNames` subset when the export is partial), but
  * `headAfter` is only knowable after the stream — while core's
  * `BeginIngestOptions` requires `sourceRevision` up front for a replace
  * session. Resolution: under the rejecting/retrying policies the session
  * begins under the PROVISIONAL revision (the canonical hash with
- * `headAfter := headBefore`), the stream appends into it, and `headAfter` is
- * captured BEFORE `commit()`. `accept-warn` is the exception: normalized
+ * `headAfter:= headBefore`), the stream appends into it, and `headAfter` is
+ * captured BEFORE `commit`. `accept-warn` is the exception: normalized
  * batches are buffered until `headAfter` is known, then appended once into a
  * session opened with the canonical FINAL revision:
  *
- *  - equal heads   → provisional === final; commit cleanly. The session only
- *                    ever commits a revision whose hash is truthful.
- *  - drifted heads → `driftPolicy` decides: `'reject'` aborts the session
- *                    (graph untouched) and throws {@link OmnigraphDriftError};
- *                    `'accept-warn'` commits the buffered export under the
- *                    final revision, records BOTH heads in `dataRef`, and
- *                    adds a warning;
- *                    `'retry-once'` aborts and restarts the whole load once
- *                    (a second drift rejects).
+ * - equal heads → provisional === final; commit cleanly. The session only
+ * ever commits a revision whose hash is truthful.
+ * - drifted heads → `driftPolicy` decides: `'reject'` aborts the session
+ * (graph untouched) and throws {@link OmnigraphDriftError};
+ * `'accept-warn'` commits the buffered export under the
+ * final revision, records BOTH heads in `dataRef`, and
+ * adds a warning;
+ * `'retry-once'` aborts and restarts the whole load once
+ * (a second drift rejects).
  *
  * This is sound because a replace session is atomic and invisible until
- * commit (§7.5): nothing is published under a revision the policy did not
+ * commit: nothing is published under a revision the policy did not
  * explicitly accept.
  *
- * Error surface (B.9): SDK typed errors never cross this package's public
+ * Error surface: SDK typed errors never cross this package's public
  * surface — they are mapped to plain `Error`s with a stable `omnigraph:`
  * message prefix.
  */
 
 /**
- * B.2 drift under `driftPolicy: 'reject'` (or a second drift under
- * `'retry-once'`): the branch head moved while the export streamed, the
- * session was aborted, and the target graph is untouched.
+ * Raised when a branch moves during export and the configured drift policy
+ * rejects the load. The session is aborted and the target graph is untouched.
  */
 declare class OmnigraphDriftError extends Error {
     readonly name = "OmnigraphDriftError";
@@ -450,7 +449,7 @@ declare class OmnigraphDriftError extends Error {
     readonly headAfter: string;
     constructor(graphId: string, branch: string, headBefore: string, headAfter: string);
 }
-/** The one load path a v1 source exposes (B.10). */
+/** The one load path a v1 source exposes. */
 interface OmnigraphSource {
     /**
      * Stream one export of the configured graph/branch into `target` via a
@@ -461,26 +460,26 @@ interface OmnigraphSource {
     load(target: IngestTarget, signal?: AbortSignal): Promise<OmnigraphLoadResult>;
 }
 /**
- * Create a v1 export-backed data source (B.2/B.10). The client must be
- * preconfigured (B.1): in the browser a safe same-origin or public client —
+ * Create a v1 export-backed data source. The client must be
+ * preconfigured. In the browser, use a safe same-origin or public client;
  * there is deliberately no `baseUrl`/`token` option here. Authenticated
  * construction lives only in `@modernrelay/orbit-omnigraph/server`.
  */
 declare function createOmnigraphSource(options: OmnigraphSourceOptions): OmnigraphSource;
 
 /**
- * B.7 stored-query `SearchService` (§16.5).
+ * Stored-query `SearchService` integration.
  *
  * A stored query using `bm25`/`fuzzy`/`nearest`/`rrf` with
  * `order { score desc } limit K` returns entity rows plus a score column; this
- * module wires it as a §16.5 `SearchService` via
+ * module wires it as a `SearchService` via
  * `og.queries.invoke(name, { params, branch })`, passing
  * `RequestContext.signal` through SDK `CallOptions`. Core performs revision
  * admission — the service only declares `revisionDependencies: ['source']`
  * (results come from the server-side branch, so they are invalidated by a
  * source change, never by client-side model/scope drift).
  *
- * Identity (B.3): Omnigraph ids are unique per type only, and a query row
+ * Identity: Omnigraph ids are unique per type only, and a query row
  * carries no type discriminator of its own — so the adapter REQUIRES a
  * caller-supplied column→node-type mapping (`typeOf`), either a
  * `{ column: NodeType }` record keyed by the projection columns that hold
@@ -489,12 +488,13 @@ declare function createOmnigraphSource(options: OmnigraphSourceOptions): Omnigra
  * every other adapter path uses — so results round-trip `decodeSourceId` and
  * match export-loaded node ids exactly.
  *
- * v1 caveat (B.7): search runs server-side over the WHOLE branch, so against
- * a partial export load it can return ids outside the loaded set. §16.5
- * classifies those as `'not-loaded'` at activation; constrain the stored
- * query to the loaded types, or load the full graph, to avoid the mismatch.
+ * Partial-load caveat: search runs server-side over the whole branch, so a
+ * partial export load can return ids outside the loaded set.
+ * `activateSearchResult` classifies those as `'not-loaded'`; constrain the
+ * stored query to the loaded types, or load the full graph, to avoid the
+ * mismatch.
  *
- * Error surface (B.9): SDK typed errors never cross this package's public
+ * Error surface: SDK typed errors never cross this package's public
  * surface — they rethrow as plain `Error`s with the stable `omnigraph:`
  * prefix. Abort rejections pass through unchanged.
  */
@@ -503,44 +503,44 @@ declare function createOmnigraphSource(options: OmnigraphSourceOptions): Omnigra
  * projections (`return { $s }`) hold whole-node structs including `id`. */
 type OmnigraphSearchRow = Record<string, unknown>;
 /**
- * The required B.3 column→node-type mapping:
+ * The required column→node-type mapping:
  *
  * - a record `{ '$s': 'Signal' }` — the FIRST listed column present in a row
- *   with a node struct supplies the physical id, encoded under the mapped
- *   type name;
+ * with a node struct supplies the physical id, encoded under the mapped
+ * type name;
  * - or a per-row function returning the node type name — the row's first
- *   node-struct column (row key order) supplies the physical id.
+ * node-struct column (row key order) supplies the physical id.
  */
 type OmnigraphSearchTypeOf = ((row: OmnigraphSearchRow) => string) | Readonly<Record<string, string>>;
 interface OmnigraphSearchServiceOptions<N = Record<string, unknown>> {
-    /** A **preconfigured** SDK client (B.1) — no `baseUrl`/`token` here. */
+    /** A **preconfigured** SDK client — no `baseUrl`/`token` here. */
     client: Omnigraph;
     /** Cluster graph id; the invoke is scoped via `client.graph(graphId)`. */
     graphId: string;
-    /** Branch the stored query reads (B.7). Default `'main'`. */
+    /** Branch the stored query reads. Default `'main'`. */
     branch?: string;
     /** Registry name of the stored search query (`POST /queries/{name}`).
      * Invoking a known name works whether or not it is `mcp.expose`d. */
     queryName: string;
-    /** Builds the stored query's `params` object from the §16.5 call.
+    /** Builds the stored query's `params` object from the call.
      * Default: `(q, limit) => ({ q, limit })`. */
     params?: (q: string, limit: number) => Record<string, unknown>;
-    /** REQUIRED B.3 mapping from row to node type — see
+    /** REQUIRED mapping from row to node type — see
      * {@link OmnigraphSearchTypeOf}. */
     typeOf: OmnigraphSearchTypeOf;
-    /** Column whose value becomes `label` (String()-coerced when present).
+    /** Column whose value becomes `label` (String-coerced when present).
      * Default: the first string-valued column in row key order. */
     labelColumn?: string;
     /** Full custom row→result escape hatch: overrides the default mapping
      * (including `typeOf`/`labelColumn`); return `null` to skip a row. The
-     * returned `id` MUST already be B.3-encoded via `encodeSourceId`. */
+     * returned `id` MUST already be type-qualified via `encodeSourceId`. */
     mapRow?: (row: OmnigraphSearchRow) => SearchResult<N> | null;
 }
 /**
- * Create the B.7 stored-query search service. Plug it into core as
+ * Create the stored-query search service. Plug it into core as
  * `services.search`; the instance owns `RequestContext` creation,
  * revision-keyed caching, supersede cancellation, and stale-result rejection
- * at admission (§16.5).
+ * at admission.
  */
 declare function createOmnigraphSearchService<N = Record<string, unknown>>(options: OmnigraphSearchServiceOptions<N>): SearchService<N>;
 

package/dist/index.js

@@ -1,5 +1,5 @@
-import { encodeSourceId, parsePgSchema, schemaFingerprint, bigIntKeyWarnings, classifyExportLine, normalizeNode, normalizeEdge } from './chunk-NT5KJVIT.js';
-export { InvalidExportLineError, ORBIT_TYPE_KEY, UnknownEdgeTypeError, bigIntKeyWarnings, classifyExportLine, decodeSourceId, edgeEndpointTypes, encodeSourceId, encodeSyntheticEdgeId, normalizeEdge, normalizeNode, parsePgSchema, schemaFingerprint } from './chunk-NT5KJVIT.js';
+import { encodeSourceId, parsePgSchema, schemaFingerprint, bigIntKeyWarnings, classifyExportLine, normalizeNode, normalizeEdge } from './chunk-YDRPXYQ7.js';
+export { InvalidExportLineError, ORBIT_TYPE_KEY, UnknownEdgeTypeError, bigIntKeyWarnings, classifyExportLine, decodeSourceId, edgeEndpointTypes, encodeSourceId, encodeSyntheticEdgeId, normalizeEdge, normalizeNode, parsePgSchema, schemaFingerprint } from './chunk-YDRPXYQ7.js';
 import { SERVER_VERSION, OmnigraphError } from '@modernrelay/omnigraph';
 import { OrbitOperationError } from '@modernrelay/orbit-core';
 
@@ -14,7 +14,7 @@ var OmnigraphDriftError = class extends Error {
   headAfter;
   constructor(graphId, branch, headBefore, headAfter) {
     super(
-      `omnigraph: branch '${branch}' of graph '${graphId}' changed during export (head ${headBefore} \u2192 ${headAfter}); session aborted per driftPolicy (spec B.2: service:omnigraph-source-changed-during-export)`
+      `omnigraph: branch '${branch}' of graph '${graphId}' changed during export (head ${headBefore} \u2192 ${headAfter}); session aborted per driftPolicy (service:omnigraph-source-changed-during-export)`
     );
     this.graphId = graphId;
     this.branch = branch;
@@ -101,7 +101,7 @@ function createOmnigraphSource(options) {
     for (const hazard of bigIntKeyWarnings(schema)) {
       pushUnique(
         warnings,
-        `omnigraph: ${hazard.type}.${hazard.property} is a 64-bit integer used as identity \u2014 JSON parsing silently rounds values past \xB12^53, which can collapse distinct ids (B.6)`
+        `omnigraph: ${hazard.type}.${hazard.property} is a 64-bit integer used as identity \u2014 JSON parsing silently rounds values past \xB12^53, which can collapse distinct ids`
       );
     }
     const provisionalRef = {
@@ -233,7 +233,7 @@ function createOmnigraphSource(options) {
       }
       await flush();
       if (unknown > 0) {
-        pushUnique(warnings, `omnigraph: skipped ${unknown} unrecognized export line(s) (B.2)`);
+        pushUnique(warnings, `omnigraph: skipped ${unknown} unrecognized export line(s)`);
       }
       throwIfAborted(signal);
       const headAfter = await newestHead(signal);
@@ -244,7 +244,7 @@ function createOmnigraphSource(options) {
         if (headAfter !== headBefore) {
           pushUnique(
             warnings,
-            `omnigraph: branch '${branch}' advanced during export (head ${headBefore} \u2192 ${headAfter}); committed under the canonical final revision per driftPolicy:'accept-warn' \u2014 dataRef records both heads (B.2)`
+            `omnigraph: branch '${branch}' advanced during export (head ${headBefore} \u2192 ${headAfter}); committed under the canonical final revision per driftPolicy:'accept-warn' \u2014 dataRef records both heads`
           );
         }
         await commitBuffered(finalRevision);
@@ -258,11 +258,11 @@ function createOmnigraphSource(options) {
       }
       const activeSession = session;
       if (activeSession === void 0) throw new Error("omnigraph: internal missing ingest session");
-      await activeSession.abort("omnigraph: source changed during export (B.2)");
+      await activeSession.abort("omnigraph: source changed during export");
       if (driftPolicy === "retry-once" && attempt === 1) {
         pushUnique(
           warnings,
-          `omnigraph: branch '${branch}' advanced during export (head ${headBefore} \u2192 ${headAfter}); load restarted once per driftPolicy:'retry-once' (B.2)`
+          `omnigraph: branch '${branch}' advanced during export (head ${headBefore} \u2192 ${headAfter}); load restarted once per driftPolicy:'retry-once'`
         );
         return { kind: "retry" };
       }
@@ -294,7 +294,7 @@ function createOmnigraphSource(options) {
     const sdk = majorMinor(SERVER_VERSION);
     if (server === null || server !== sdk) {
       warnings.push(
-        `omnigraph: server version ${serverVersion} does not match the SDK-pinned server version ${SERVER_VERSION} (major.minor differ) \u2014 SDK behavior is undefined against this server (B.1)`
+        `omnigraph: server version ${serverVersion} does not match the SDK-pinned server version ${SERVER_VERSION} (major.minor differ) \u2014 SDK behavior is undefined against this server`
       );
     }
     for (let attempt = 1; ; attempt += 1) {
@@ -343,7 +343,7 @@ function extractRows(response, queryName) {
   const rows = response.rows;
   if (!Array.isArray(rows)) {
     throw new Error(
-      `omnigraph: stored query '${queryName}' did not return a read envelope with rows \u2014 the B.7 search query must be a stored READ query (not a mutation)`
+      `omnigraph: stored query '${queryName}' did not return a read envelope with rows \u2014 the configured search query must be a stored READ query (not a mutation)`
     );
   }
   for (const row of rows) {
@@ -360,7 +360,7 @@ function resolveIdentity(row, typeOf, queryName) {
     const kind = typeOf(row);
     if (typeof kind !== "string" || kind.length === 0) {
       throw new Error(
-        `omnigraph: typeOf returned ${JSON.stringify(kind)} for a '${queryName}' search row \u2014 it must return a non-empty node type name (B.3)`
+        `omnigraph: typeOf returned ${JSON.stringify(kind)} for a '${queryName}' search row \u2014 typeOf must return a non-empty node type name`
       );
     }
     for (const key of Object.keys(row)) {
@@ -368,7 +368,7 @@ function resolveIdentity(row, typeOf, queryName) {
       if (isNodeStruct(value)) return { kind, sourceId: value.id };
     }
     throw new Error(
-      `omnigraph: '${queryName}' search row has no node-struct column (an object with a string 'id') \u2014 project the matched entity bare (return { $s }) so its physical id is available (B.7)`
+      `omnigraph: '${queryName}' search row has no node-struct column (an object with a string 'id') \u2014 project the matched entity bare (return { $s }) so its physical id is available`
     );
   }
   for (const [column, kind] of Object.entries(typeOf)) {
@@ -376,7 +376,7 @@ function resolveIdentity(row, typeOf, queryName) {
     if (isNodeStruct(value)) return { kind, sourceId: value.id };
   }
   throw new Error(
-    `omnigraph: '${queryName}' search row has no node struct under the mapped column(s) ${JSON.stringify(Object.keys(typeOf))} \u2014 the typeOf record must key the bare-variable projection column(s) (B.3)`
+    `omnigraph: '${queryName}' search row has no node struct under the mapped column(s) ${JSON.stringify(Object.keys(typeOf))} \u2014 the typeOf record must key the columns that contain bare-variable node projections`
   );
 }
 function createOmnigraphSearchService(options) {