@modernrelay/orbit-omnigraph 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 ModernRelay
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,167 @@
+# @modernrelay/orbit-omnigraph
+
+Optional Omnigraph data-source adapter for Orbit (spec Appendix B). Framework-agnostic:
+depends only on the framework-free ingestion/error surface of `@modernrelay/orbit-core`
+and the official TypeScript SDK `@modernrelay/omnigraph` (0.8.x) — never on React, and
+core never depends on it.
+
+## The v1 rule (B.10)
+
+> **v1 loads graphs via `og.export()`; queries only ever resolve ids** (search, overlay
+> selection — search itself arrives with S11). The query path never introduces nodes or
+> edges into the graph.
+
+Export is the only complete-graph read: it streams NDJSON with full identity — physical
+edge ids included — so every v1 edge carries an export id and no synthesized-id scheme ever
+mixes in (B.4/§5). What that buys, and what it defers (server-backed expansion, query-path
+loading, authed blob fetch), is tabulated in spec B.10.
+
+## Quick start
+
+```ts
+// server.ts — the ONLY place authenticated construction lives (B.1)
+import { createOmnigraphServerClient } from '@modernrelay/orbit-omnigraph/server';
+
+const client = createOmnigraphServerClient({
+  baseUrl: 'http://127.0.0.1:8080',
+  token: process.env.OMNIGRAPH_TOKEN!, // secret material — server-side only
+});
+```
+
+```ts
+// anywhere (browser code passes a preconfigured safe client instead — see below)
+import { createOmnigraphSource } from '@modernrelay/orbit-omnigraph';
+import { createGraphInstance } from '@modernrelay/orbit-core';
+
+const source = createOmnigraphSource({
+  client,               // preconfigured SDK client — no token option here
+  graphId: 'demo',
+  branch: 'main',       // default
+  // typeNames: ['Signal', 'Correlates'],   // partial per-type load (wire: type_names)
+  // driftPolicy: 'reject',                 // default; see below
+  // maxPendingBytes: 64 * 1024 * 1024,     // default whole-load atomic budget
+  onProgress: ({ lines, nodes, edges, bytes }) => console.log(lines, nodes, edges, bytes),
+});
+
+const instance = createGraphInstance({ engine });
+const result = await source.load(instance /*, abortSignal */);
+// result: { sourceRevision, dataRef, counts, serverVersion, warnings }
+```
+
+`load()` drives one streamed export pass into a `purpose:'replace'` ingest session
+(`datasetKey` = `og:<graphId>:<branch>`): edge lines arrive first (lexicographic table-key
+order) and pass straight through — core's pending-endpoint index links them as nodes land
+(§7.5). Every append is awaited, and the atomic load has a finite whole-export byte budget
+(`maxPendingBytes`, 64 MiB by default); exceeding it aborts without publishing a partial
+graph. Ids are namespaced through the B.3 codec, and B.6 wire encodings are normalized to
+the query-path string forms. Byte progress and budgets use re-serialized UTF-8 NDJSON size,
+including one line break per export row.
+
+The `target` is structural (`IngestTarget`: `beginIngest` + `getRevisions` +
+optional `getDiagnostics`) — deliberately decoupled from `GraphInstance`, which satisfies
+it structurally; so does any recorder or headless pipeline.
+
+## `sourceRevision` and drift (B.2)
+
+The canonical `sourceRevision` is a hash of
+`{ graphId, branch, headBefore, headAfter, schemaFingerprint }` — but `/export` is
+branch-only (no snapshot isolation), so `headAfter` is only knowable after the stream,
+while core's `beginIngest` requires `sourceRevision` up front for a replace session.
+
+Resolution: under `'reject'` and `'retry-once'`, a session begins under the **provisional**
+revision (the canonical hash with `headAfter := headBefore`), the stream appends into it,
+and the head is re-read **before** `commit()`. `'accept-warn'` buffers the bounded export
+until that second head is known, then opens one session under the canonical final revision:
+
+- **equal heads** — provisional === final; commit cleanly. The steady-state path.
+- **drift** (`driftPolicy`):
+  - `'reject'` (default) — abort the session and throw `OmnigraphDriftError`; the graph is
+    untouched. Right for durable/shareable sessions.
+  - `'accept-warn'` — commit under the canonical final revision; `dataRef` records
+    **both** heads and a warning is added to the result.
+  - `'retry-once'` — abort and restart the whole load once; a second drift rejects.
+
+This is sound because a replace session is atomic and invisible until commit (§7.5):
+nothing publishes under a revision the policy did not explicitly accept, and the decision
+is never hidden — every accepted drift or retry appears in `result.warnings`.
+
+A second identical load of a quiescent branch produces the same
+`{datasetKey, sourceRevision}` and replays idempotently — core publishes nothing (§7.5).
+
+## Search: stored-query `SearchService` (B.7 / §16.5)
+
+`createOmnigraphSearchService` wires a stored server-side search query (BM25 / fuzzy /
+vector / RRF with `order { score desc } limit K`) as a §16.5 `SearchService` — plug it into
+core as `services.search` and the instance owns `RequestContext` creation, revision-keyed
+caching, supersede cancellation, and stale-result admission. The service declares
+`revisionDependencies: ['source']` and passes `ctx.signal` through SDK `CallOptions`, so a
+superseded keystroke cancels the in-flight HTTP call.
+
+```ts
+import { createOmnigraphSearchService } from '@modernrelay/orbit-omnigraph';
+
+const search = createOmnigraphSearchService({
+  client,                      // preconfigured SDK client — same B.1 rule as the loader
+  graphId: 'demo',
+  branch: 'main',              // default
+  queryName: 'search-intel',   // registry name; invoked as POST /queries/search-intel
+  // params: (q, limit) => ({ q, limit }),   // default — reshape for your query's params
+  typeOf: { $s: 'Signal' },    // REQUIRED (B.3): column → node type for the id encoding
+  // labelColumn: '$s.title',  // default: the first string-valued column per row
+});
+
+const instance = createGraphInstance({ engine, services: { search } });
+```
+
+Row mapping (override wholesale with `mapRow: (row) => SearchResult | null`, `null` skips):
+
+- **id** — Omnigraph ids are unique per type only and query rows carry no type
+  discriminator, so the adapter **requires** a caller-supplied column→node-type mapping
+  (`typeOf`): a record keyed by the bare-variable projection columns holding node structs
+  (`return { $s }` → `{ $s: 'Signal' }`; the first listed column present wins), or a
+  per-row function returning the type name (the row's first node-struct column supplies the
+  physical id). Every id is qualified via `encodeSourceId(nodeType, physicalId)` — it
+  round-trips `decodeSourceId` and matches export-loaded node ids exactly.
+- **score** — a finite number in the row's `score` column (the score lane never doubles as
+  a label).
+- **label** — `labelColumn`'s value when configured, else the first string-valued column in
+  row key order.
+
+Trivial calls (empty query, non-positive limit) resolve `[]` without a network call, and
+results are defensively capped at the requested limit. Errors follow B.9: SDK typed errors
+rethrow as plain `omnigraph:`-prefixed `Error`s; aborts surface as `AbortError`.
+
+> **v1 caveat (B.7):** the stored query searches the WHOLE branch server-side, so against a
+> *partial* export load (`typeNames`) it can return ids outside the loaded set.
+> `activateSearchResult` classifies those as `'not-loaded'` (§16.5) — the host may remedy
+> that only by re-running export for the relevant types (query-path single-node fetch is
+> exactly what B.10 defers). Constrain the stored query to the loaded types, or load the
+> full graph, to avoid the mismatch. Discovery via `og.queries.list()` returns only the
+> `mcp.expose == true` registry subset — invoking a known `queryName` works regardless.
+
+## Server-only entry — do not import from the browser
+
+`@modernrelay/orbit-omnigraph/server` (`createOmnigraphServerClient`) is the only
+authenticated SDK construction and must stay server-side: `omnigraph-server` ships no CORS
+configuration and uses static bearer tokens (secret material) (B.9). Browser deployments
+pass a preconfigured safe same-origin/public client to `createOmnigraphSource` — the
+browser entry deliberately has no `baseUrl`/`token` option — and typically route reads
+through a proxy/BFF. A client-bundle exclusion gate (`scripts/pack-smoke.mjs`,
+`treeshake:omnigraph-client`) asserts the server entry never reaches a client bundle.
+
+## Error surface (B.9)
+
+SDK typed errors (`NetworkError`, `ConflictError`, …) never cross this package's public
+surface — failures rethrow as plain `Error`s with a stable `omnigraph:` message prefix.
+Cancellation (`AbortSignal`) surfaces as an `AbortError`; the session is aborted and the
+graph left untouched. SDK/server `major.minor` version mismatches (`og.health()` vs the
+SDK's pinned `SERVER_VERSION`) surface as a result warning, never a hard failure (B.1).
+
+## Also in the box
+
+- `encodeSourceId`/`decodeSourceId`/`encodeSyntheticEdgeId` — the B.3/B.4 identity codec
+  every adapter path must use.
+- `parsePgSchema`/`edgeEndpointTypes`/`schemaFingerprint`/`bigIntKeyWarnings` — the `.pg`
+  schema model (B.6): endpoint-type resolution, wire-type knowledge, revision fingerprint.
+- `classifyExportLine`/`normalizeNode`/`normalizeEdge` — export-line normalization
+  (B.2/B.6).