@ultimat3/realtime 7.0.0 → 9.0.0

package/CLAUDE.md

@@ -13,6 +13,35 @@ Tier 3 package. Channels, live queries, local-first sync. One protocol for all t
 
 ## Rules
 
+- **Two entries, and a name lives in exactly ONE of them (2026-08-22, BREAKING).** `.` is the
+  client half — `hooks`, `client*`, `identity-map`, `live-rows`, `apply-patches`, `offline-queue`,
+  `rebase`, `local-store`, `sync-protocol`, `json`, `cursor`, `errors`, and the client's half of
+  `thundering-herd`. `./server` (`src/server.ts`) is everything that touches `nats`, Postgres, the
+  sync node, the channel hub, the live-query registry or the fanout. The reason is measured, not
+  aesthetic: `nats` `require()`s `stream/web`, so one barrel carrying `openNatsClient` beside
+  `useLive` failed `bun build --target=browser` with
+  `Browser build cannot require() Node.js builtin: "stream/web"` — the island `wiki/Realtime.md`
+  promises could not be built at all. Two build errors hold it: `packages/cli/src/realtime-browser-barrel.test.ts`
+  bundles a `useLive`-only entry for the browser, and `barrel-split.test.ts` refuses a name
+  exported from both (values through the namespace objects, types off the source text, because a
+  type-only export leaves no runtime entry). `errors.ts` is deliberately whole on `.`: every code
+  reaches the wire through `toWireError`, so a client must be able to name any of them, and the
+  module is already in the client graph via `sync-protocol`.
+- **`sideEffects` is the ARRAY `["./src/errors.ts"]`, never `false` and never absent.** Absent was
+  what made the failure above unrecoverable — with no field a bundler must assume every module has
+  effects, so nothing was tree-shaken and `nats` came along with `useLive`. Measured, not guessed:
+  `bun run side-effects --explain --json` prints what the tree actually does at import time.
+  `false` would drop `registerErrorCodes()` and every `REALTIME_ERROR_TITLES` entry with it.
+  **The array alone would have fixed the build** and is not why the split exists: tree-shaking is
+  a bundler's discretion, `export * from` or a namespace import defeats it, and "the client entry
+  cannot reach the bus" is a contract rather than an optimisation.
+- **`@ultimat3/realtime/server` needs its own `paths` entry in `tsconfig.base.json`**, beside
+  `@ultimat3/admin/dev`'s. `@ultimat3/*` maps `realtime/server` to `packages/realtime/server/src`,
+  which does not exist, and the root program has no `node_modules/@ultimat3` symlink to fall back
+  through — so `scripts/**` (which the root `tsc -b` compiles) reports `TS2307` without it. The
+  workspace packages resolve through their own `node_modules` and never needed it, which is what
+  makes the failure look local to `scripts/`.
+
 - Policy is evaluated **once per subscriber**, never once per query. `live-query.test.ts` proves it
   for a hand-written definition and `live-definition.test.ts` proves it for a real declared
   `query({ live: true })` — the second one matters, because a rule that only holds for test fakes
@@ -640,6 +669,8 @@ Tier 3 package. Channels, live queries, local-first sync. One protocol for all t
 
 | File | Owns |
 |---|---|
+| `index.ts` | the `.` barrel: the client half, and the only thing a browser island may import |
+| `server.ts` | the `./server` barrel: the bus, the WAL path, the node. Disjoint from `index.ts` by test |
 | `sync-protocol.ts` | the wire: 10 frame kinds, `encode`/`decode`, `PROTOCOL_VERSION` |
 | `channel.ts` / `presence.ts` / `socket.ts` | tier 1 |
 | `live-query.ts` / `live-definition.ts` / `changefeed.ts` / `changefeed-env.ts` / `replicator.ts` / `pg-advisory-lock.ts` / `fanout.ts` / `transport-env.ts` / `matcher-bridge.ts` | tier 2 |

package/README.md

@@ -44,23 +44,45 @@ frame handler is unchanged between rungs.
 
 `local` must be pure — no I/O, no `Date.now()`, no `Math.random()` — because rebase replays it.
 
+## Two entries, and which one an island may import
+
+`As of 2026-08`, `@ultimat3/realtime` is the **client** half — the hooks, the identity map, the offline queue, the
+wire and the reconnect vocabulary. `@ultimat3/realtime/server` is the bus, the Postgres replication
+path and the sync node. A name lives in exactly one of them; the `Entry` column below says which.
+
+The split is not cosmetic. `nats` `require()`s `stream/web`, so one barrel carrying `openNatsClient`
+beside `useLive` made the browser island this package promises **unbuildable** —
+`Browser build cannot require() Node.js builtin: "stream/web"`. `packages/cli/src/realtime-browser-barrel.test.ts`
+bundles an entry importing only `useLive` for `target: 'browser'` and fails the build if either
+half reaches the other; `barrel-split.test.ts` fails if one name is exported from both.
+
+Migrating from 7.x: an import of a **server** name changes its specifier and nothing else.
+
+```
+- import { ChannelHub, createSyncNode, LiveQueryRegistry } from '@ultimat3/realtime';
++ import { ChannelHub, createSyncNode, LiveQueryRegistry } from '@ultimat3/realtime/server';
+```
+
+Client names — `useLive`, `liveHookFor`, `LiveClient`, `OfflineQueue`, `RebaseLog`, `IdentityMap`,
+`encode`/`decode`, every `X_*` error class — are unchanged.
+
 ## Public API
 
-| Concern | Export |
-|---|---|
-| tier 1 | `topic`, `ChannelHub`, `PresenceRegistry`, `SyncSocket`, `SocketRegistry` |
-| tier 2 | `LiveQueryRegistry`, `InMemoryChangeFeed`, `PgLogicalReplicationFeed`, `selectChangeFeed`, `createReplicator`, `PgAdvisoryLock`, `matcherFor` |
-| replication | `parsePgUrl`, `bunPgStream`, `PgOutputDecoder`, `entityRow`, `changeLsn`, `commitPositionOf` |
-| fanout | `Transport`, `InProcessTransport`, `NatsTransport`, `selectTransport`, `subjectMatches` |
-| the bus, behind `NatsTransport` | the port — `NatsClient`, `NatsMessage`, `NatsSubscription`, `NatsConnect`, `NatsTarget`, `parseNatsUrl` — plus `openNatsClient` (the `nats` adapter), `NatsKvSet`, `ensureKvBucket`, `kvGet`/`kvLast`/`kvWrite`, `assertBucket`, `encodeToken`/`decodeToken`, and `FakeNatsBroker`/`fakeNatsConnect` for tests |
-| reconnect | `LiveCursor`, `resumeFrom`, `shouldResnapshot`, `defaultReconnectBudget`, `RingChangeBuffer`, `backoffDelay`, `Scheduler`, `timeoutScheduler`, `drainPlan`, `AcceptBudget` |
-| the client store | `IdentityMap` — one row value per `(entity, id)` — plus `RowWindows`, `rowKey`, `privateScope`, `applyPatches`/`orderAfterPatches` |
-| tier 3 | `MemoryLocalStore`, `createOpfsLocalStore`, `OfflineQueue`, `RebaseLog`, `reconcile`, `custom` |
-| wire | `PROTOCOL_VERSION`, `encode`, `decode`, `Frame` |
-| halves | `LiveClient` (client), `createSyncNode` / `listenSyncNode` (`sync` role) |
-| a socket's identity | `SyncAuthenticator`, `SyncGrant`, `GrantBook`, `sweepGrants`, `DEFAULT_REAUTH_INTERVAL_MS` |
-| hooks | `setLiveClient`, `useLive`, `useConnection`, `useMutation`, `useMutationQueue` |
-| the typed projection | `liveHookFor` — one query bound to one named hook |
+| Concern | Entry | Export |
+|---|---|---|
+| tier 1 | `./server` | `topic`, `ChannelHub`, `PresenceRegistry`, `SyncSocket`, `SocketRegistry` |
+| tier 2 | `./server` | `LiveQueryRegistry`, `InMemoryChangeFeed`, `PgLogicalReplicationFeed`, `selectChangeFeed`, `createReplicator`, `PgAdvisoryLock`, `matcherFor` |
+| replication | `./server` | `parsePgUrl`, `bunPgStream`, `PgOutputDecoder`, `entityRow`, `changeLsn`, `commitPositionOf` |
+| fanout | `./server` | `Transport`, `InProcessTransport`, `NatsTransport`, `selectTransport`, `subjectMatches` |
+| the bus, behind `NatsTransport` | `./server` | the port — `NatsClient`, `NatsMessage`, `NatsSubscription`, `NatsConnect`, `NatsTarget`, `parseNatsUrl` — plus `openNatsClient` (the `nats` adapter), `NatsKvSet`, `ensureKvBucket`, `kvGet`/`kvLast`/`kvWrite`, `assertBucket`, `encodeToken`/`decodeToken`, and `FakeNatsBroker`/`fakeNatsConnect` for tests |
+| reconnect | both | `LiveCursor`, `resumeFrom`, `shouldResnapshot`, `defaultReconnectBudget`, `backoffDelay`, `Scheduler`, `timeoutScheduler` on `.`; `RingChangeBuffer`, `drainPlan`, `AcceptBudget`, `reconnectFrame` on `./server` — the node's half of the reconnect is the node's |
+| the client store | `.` | `IdentityMap` — one row value per `(entity, id)` — plus `RowWindows`, `rowKey`, `privateScope`, `applyPatches`/`orderAfterPatches` |
+| tier 3 | `.` | `MemoryLocalStore`, `createOpfsLocalStore`, `OfflineQueue`, `RebaseLog`, `reconcile`, `custom` |
+| wire | `.` | `PROTOCOL_VERSION`, `encode`, `decode`, `Frame` |
+| halves | both | `LiveClient` on `.`; `createSyncNode` / `listenSyncNode` (`sync` role) on `./server` |
+| a socket's identity | `./server` | `SyncAuthenticator`, `SyncGrant`, `GrantBook`, `sweepGrants`, `DEFAULT_REAUTH_INTERVAL_MS` |
+| hooks | `.` | `setLiveClient`, `useLive`, `useConnection`, `useMutation`, `useMutationQueue` |
+| the typed projection | `.` | `liveHookFor` — one query bound to one named hook |
 
 ## The four hooks
 

package/package.json

@@ -1,9 +1,12 @@
 {
   "name": "@ultimat3/realtime",
-  "version": "7.0.0",
+  "version": "9.0.0",
   "description": "Three-tier realtime: channels, live queries, local-first sync — one protocol, one mutator shape",
   "license": "MIT",
   "type": "module",
+  "sideEffects": [
+    "./src/errors.ts"
+  ],
   "repository": {
     "type": "git",
     "url": "git+https://github.com/developerz-ai/ultimate.git",
@@ -14,7 +17,8 @@
     "provenance": true
   },
   "exports": {
-    ".": "./src/index.ts"
+    ".": "./src/index.ts",
+    "./server": "./src/server.ts"
   },
   "files": [
     "src",
@@ -32,8 +36,8 @@
     "test": "bun test"
   },
   "dependencies": {
-    "@ultimat3/core": "7.0.0",
-    "@ultimat3/query": "7.0.0",
+    "@ultimat3/core": "9.0.0",
+    "@ultimat3/query": "9.0.0",
     "nats": "2.29.3"
   }
 }

package/src/index.ts

@@ -1,49 +1,10 @@
-// Public API. Explicit, tier by tier: channels, live queries, local-first sync, plus the wire and
-// the server/client halves that carry all three.
+// The CLIENT half of the public API — everything a browser island may bundle. Explicit, tier by
+// tier: the wire, the hooks, the identity map, the offline queue and the reconnect vocabulary.
+// Nothing here reaches `nats`, a Postgres socket or the sync node; those are `./server`, and
+// `packages/cli/src/realtime-browser-barrel.test.ts` is the build error that keeps them apart.
 
 // ---- the client's one stateless piece, reusable against an app's own store ----------------------
 export { applyPatches, orderAfterPatches } from './apply-patches';
-export {
-  type ChangeBufferOptions,
-  DEFAULT_MAX_BUFFER_BYTES,
-  DEFAULT_MAX_BUFFER_BYTES_PER_QUERY,
-  RingChangeBuffer,
-} from './change-buffer';
-// ---- tier 2: live queries ----------------------------------------------------------------------
-export {
-  type ChangeEvent,
-  type ChangeFeed,
-  type ChangeFeedStartOptions,
-  type ChangeOp,
-  formatLsn,
-  InMemoryChangeFeed,
-  type InMemoryChangeFeedOptions,
-  PgLogicalReplicationFeed,
-  type PgLogicalReplicationOptions,
-  parseLsn,
-} from './changefeed';
-export {
-  type ChangeFeedSelection,
-  DEFAULT_REPLICATION_PUBLICATION,
-  DEFAULT_REPLICATION_SLOT,
-  REPLICATION_ENV_KEYS,
-  type ReplicationEnvironment,
-  replicatorLockKey,
-  type SelectChangeFeedOptions,
-  selectChangeFeed,
-} from './changefeed-env';
-// ---- tier 1: channels + presence ---------------------------------------------------------------
-export {
-  ChannelHub,
-  type ChannelHubOptions,
-  channelFrame,
-  DEFAULT_MAX_TOPICS_PER_NODE,
-  type Topic,
-  type TopicGuard,
-  type TopicGuardArgs,
-  type TopicGuardResult,
-  topic,
-} from './channel';
 // ---- server + client halves -------------------------------------------------------------------
 export {
   type ClientSocket,
@@ -75,7 +36,7 @@ export {
   shouldResnapshot,
   verifyDigest,
 } from './cursor';
-// ---- errors ----------------------------------------------------------------------------------
+// ---- errors: one vocabulary for both halves, because every code reaches the wire ---------------
 export {
   CursorStaleError,
   FrameRateLimitError,
@@ -99,16 +60,6 @@ export {
   TransportProtocolError,
   TransportUnavailableError,
 } from './errors';
-export {
-  InProcessTransport,
-  type InProcessTransportOptions,
-  subjectMatches,
-  type Transport,
-  type TransportHandler,
-  type TransportSet,
-  type TransportSetEntry,
-  type TransportSubscription,
-} from './fanout';
 // ---- the client hooks --------------------------------------------------------------------------
 export {
   type ConflictLike,
@@ -147,17 +98,6 @@ export {
   type RowOp,
   type RowPatch,
 } from './json';
-export type {
-  LiveQueryDefinition,
-  LiveSubscription,
-  SnapshotResult,
-} from './live-contract';
-export { type LiveDefinitionOptions, liveQueryDefinition } from './live-definition';
-export {
-  DEFAULT_MAX_ENTRIES,
-  LiveQueryRegistry,
-  type LiveQueryRegistryOptions,
-} from './live-query';
 export { type Registration, RowWindows } from './live-rows';
 // ---- tier 3: local-first ------------------------------------------------------------------------
 export {
@@ -169,51 +109,6 @@ export {
   type OpfsLocalStoreOptions,
   type TableMap,
 } from './local-store';
-export {
-  applyToWindow,
-  type BridgeResult,
-  bridgeChange,
-  canAffect,
-  type IncrementalMatcher,
-  matcherFor,
-  NO_CHANGE,
-  normalizePatch,
-  patchFromChange,
-  type SubscriptionShape,
-  toBridgeResult,
-} from './matcher-bridge';
-// ---- the production bus -------------------------------------------------------------------------
-export {
-  DEFAULT_NATS_PORT,
-  DEFAULT_REQUEST_TIMEOUT_MS,
-  type NatsClient,
-  type NatsClientOptions,
-  type NatsConnect,
-  type NatsHeaders,
-  type NatsMessage,
-  type NatsMessageHandler,
-  type NatsRequestManyOptions,
-  type NatsRequestOptions,
-  type NatsSubscription,
-  type NatsTarget,
-  parseNatsUrl,
-} from './nats-client';
-export { FakeNatsBroker, type FakeNatsOptions, fakeNatsConnect } from './nats-fake';
-export {
-  assertBucket,
-  assertServerVersion,
-  ensureKvBucket,
-  type JsError,
-  type KvRecord,
-  kvGet,
-  kvLast,
-  kvStream,
-  kvSubject,
-  kvWrite,
-} from './nats-jetstream';
-export { decodeToken, encodeToken, NatsKvSet, type NatsKvSetOptions } from './nats-kv';
-export { openNatsClient } from './nats-lib-client';
-export { NatsTransport, type NatsTransportOptions } from './nats-transport';
 export {
   type DrainReport,
   MemoryQueueStore,
@@ -225,47 +120,12 @@ export {
   type QueueState,
   type QueueStore,
 } from './offline-queue';
-export { PgAdvisoryLock, type PgAdvisoryLockOptions } from './pg-advisory-lock';
-// ---- the postgres replication path ------------------------------------------------------------
-export { camel, entityRow } from './pg-entity-row';
-export {
-  changeLsn,
-  commitPositionOf,
-  type ReplicationStreamStats,
-} from './pg-replication';
-export { bunPgStream, type PgTarget, parsePgUrl, type SslMode } from './pg-socket';
-export type { PgStream } from './pg-wire';
-export {
-  type PgColumn,
-  PgOutputDecoder,
-  type PgOutputMessage,
-  type PgRelation,
-} from './pgoutput';
-export { authorizeWithPolicy, type GateOptions, visibleWithPolicy } from './policy-gate';
-export {
-  DEFAULT_MAX_PRESENCE_MEMBERS,
-  PRESENCE_KEY_PREFIX,
-  PRESENCE_SWEEP_PREFIX,
-  type PresenceInput,
-  type PresenceOptions,
-  PresenceRegistry,
-  type PresenceRoster,
-  presenceFrame,
-} from './presence';
 /** The typed projection: one query bound to one named hook, `useLiveFeed({ orgId })`. */
 export {
   type LiveQueryHook,
   type LiveQuerySource,
   liveHookFor,
 } from './query-hook';
-export {
-  createEntry,
-  fillWindow,
-  orgIdOf,
-  type PendingRead,
-  type QueryEntry,
-  refillWindowInLane,
-} from './query-window';
 export {
   type ConflictStrategy,
   type CustomMerge,
@@ -280,72 +140,6 @@ export {
   type ServerAck,
   strategyName,
 } from './rebase';
-export {
-  type AdvisoryLock,
-  CHANGE_SUBJECT_PREFIX,
-  type ChangeEnvelope,
-  changeSubject,
-  createReplicator,
-  InMemoryAdvisoryLock,
-  normalize,
-  parseChange,
-  parseEnvelope,
-  type Replicator,
-  type ReplicatorOptions,
-  type ReplicatorStats,
-  SeqGapDetector,
-} from './replicator';
-export {
-  actorIdOf,
-  CLOSE,
-  DEFAULT_FRAME_BURST,
-  DEFAULT_IDLE_TIMEOUT_MS,
-  DEFAULT_MAX_BUFFERED_BYTES,
-  DEFAULT_MAX_FRAMES_PER_SECOND,
-  idleSweepPeriodMs,
-  SocketRegistry,
-  type SocketRegistryOptions,
-  SyncSocket,
-  type SyncSocketOptions,
-  type WsLike,
-} from './socket';
-export type {
-  GateFailed,
-  GateStage,
-  RowDenied,
-  Subscriber,
-  SubscriberGateOptions,
-} from './subscriber-gate';
-export {
-  GrantBook,
-  type GrantSweepDeps,
-  type GrantSweepResult,
-  type SyncAuthenticator,
-  type SyncGrant,
-  sweepGrants,
-} from './sync-auth';
-export {
-  createFrameRouter,
-  type FrameRouter,
-  type FrameRouterOptions,
-  type MutationHandler,
-} from './sync-frames';
-export {
-  type ListenOptions,
-  listenSyncNode,
-  type SyncListener,
-} from './sync-listen';
-export {
-  createSyncNode,
-  DEFAULT_MAX_CONNECTIONS,
-  DEFAULT_MAX_FRAME_BYTES,
-  DEFAULT_REAUTH_INTERVAL_MS,
-  type SyncNode,
-  type SyncNodeOptions,
-  type SyncWs,
-  type UpgradeTarget,
-  type WsData,
-} from './sync-node';
 // ---- the wire -------------------------------------------------------------------------------------
 export {
   type AckFrame,
@@ -371,29 +165,14 @@ export {
   type UpdateAvailableFrame,
   type WireError,
 } from './sync-protocol';
+// ---- the client's own reconnect: the backoff it computes and the timer it arms -----------------
 export {
-  AcceptBudget,
-  type AcceptBudgetOptions,
   type BackoffPolicy,
   backoffDelay,
-  type DrainedSocket,
-  type DrainPlanEntry,
-  type DrainPlanOptions,
   defaultBackoff,
-  drainPlan,
   type JitterMode,
   type ReconnectReason,
   type Rng,
-  reconnectFrame,
   type Scheduler,
   timeoutScheduler,
 } from './thundering-herd';
-export {
-  DEFAULT_PRESENCE_BUCKET,
-  DEFAULT_PRESENCE_TTL_MS,
-  type SelectTransportOptions,
-  selectTransport,
-  TRANSPORT_ENV_KEYS,
-  type TransportEnvironment,
-  type TransportSelection,
-} from './transport-env';

package/src/offline-queue.ts

@@ -217,6 +217,23 @@ export class OfflineQueue {
     await this.#persist();
   }
 
+  /**
+   * Re-asked at the top of every iteration, because `#sendable()` is a SNAPSHOT and the loop awaits
+   * a network `send` inside it. An `ack` landing mid-pass removes its entry from the queue, a
+   * `fail` marks it terminal and a `clear` drops all of them — and the pass, holding the snapshot,
+   * re-sent an intent the server had already settled AND counted it in `DrainReport.sent`, so the
+   * number a UI renders as "synced" was larger than the frames that left the tab.
+   *
+   * Deliberately NOT an `#epoch` bump in `ack`/`fail`: an ack arriving during a drain is the
+   * ordinary case — the server answers frame 1 while the pass is on frame 2 — and invalidating the
+   * pass would stop every drain against a server that answers promptly. The epoch means "the
+   * connection this pass was draining into is gone", which is one mutation's settlement away from
+   * nothing at all.
+   */
+  #stillSendable(mutation: QueuedMutation): boolean {
+    return mutation.status === 'pending' && this.#mutations.includes(mutation);
+  }
+
   /** Never sent on this connection. `inflight` is excluded: it is already on a socket. */
   #sendable(): readonly QueuedMutation[] {
     return this.#mutations
@@ -246,6 +263,9 @@ export class OfflineQueue {
           stoppedAt: mutation.key,
         };
       }
+      // Settled by the server, or dropped by `clear()`, since the snapshot was taken. Skipped
+      // rather than stopping the pass: nothing behind it moved, so the order invariant holds.
+      if (!this.#stillSendable(mutation)) continue;
       mutation.status = 'inflight';
       mutation.attempts += 1;
       try {

package/src/pgoutput.ts

@@ -1,3 +1,4 @@
+import { renderThrowable } from '@ultimat3/core';
 // Decodes pgoutput logical-replication messages (protocol version 1, Postgres >= 12) into typed
 // PgOutputMessage values, and the postgres text-format values inside each tuple into JsonValue.
 // Pure byte decoding: no sockets, no I/O. A decoder instance owns the per-connection relation
@@ -92,7 +93,7 @@ function decodeValue(typeOid: number, text: string): JsonValue {
       } catch (cause) {
         throw new ReplicationProtocolError({
           stage: 'value',
-          detail: `type oid ${typeOid} carried invalid json: ${String(cause)}`,
+          detail: `type oid ${typeOid} carried invalid json: ${renderThrowable(cause)}`,
         });
       }
       return parsed as JsonValue;

package/src/server.ts

@@ -0,0 +1,234 @@
+// The SERVER half of the public API: the bus, the Postgres replication path, the sync node and the
+// live-query registry it fans out through. Split from `index.ts` because `nats` require()s
+// `stream/web` and the WAL decoder is a Postgres client — one barrel carrying both made the browser
+// island `useLive` promises unbuildable. Every name here has exactly one home; the shared
+// vocabulary (the wire, the errors, `Row`, the backoff) stays on `@ultimat3/realtime`.
+
+// ---- the retained change window one node fans out from ------------------------------------------
+export {
+  type ChangeBufferOptions,
+  DEFAULT_MAX_BUFFER_BYTES,
+  DEFAULT_MAX_BUFFER_BYTES_PER_QUERY,
+  RingChangeBuffer,
+} from './change-buffer';
+// ---- tier 2: live queries ----------------------------------------------------------------------
+export {
+  type ChangeEvent,
+  type ChangeFeed,
+  type ChangeFeedStartOptions,
+  type ChangeOp,
+  formatLsn,
+  InMemoryChangeFeed,
+  type InMemoryChangeFeedOptions,
+  PgLogicalReplicationFeed,
+  type PgLogicalReplicationOptions,
+  parseLsn,
+} from './changefeed';
+export {
+  type ChangeFeedSelection,
+  DEFAULT_REPLICATION_PUBLICATION,
+  DEFAULT_REPLICATION_SLOT,
+  REPLICATION_ENV_KEYS,
+  type ReplicationEnvironment,
+  replicatorLockKey,
+  type SelectChangeFeedOptions,
+  selectChangeFeed,
+} from './changefeed-env';
+// ---- tier 1: channels + presence ---------------------------------------------------------------
+export {
+  ChannelHub,
+  type ChannelHubOptions,
+  channelFrame,
+  DEFAULT_MAX_TOPICS_PER_NODE,
+  type Topic,
+  type TopicGuard,
+  type TopicGuardArgs,
+  type TopicGuardResult,
+  topic,
+} from './channel';
+export {
+  InProcessTransport,
+  type InProcessTransportOptions,
+  subjectMatches,
+  type Transport,
+  type TransportHandler,
+  type TransportSet,
+  type TransportSetEntry,
+  type TransportSubscription,
+} from './fanout';
+export type {
+  LiveQueryDefinition,
+  LiveSubscription,
+  SnapshotResult,
+} from './live-contract';
+export { type LiveDefinitionOptions, liveQueryDefinition } from './live-definition';
+export {
+  DEFAULT_MAX_ENTRIES,
+  LiveQueryRegistry,
+  type LiveQueryRegistryOptions,
+} from './live-query';
+export {
+  applyToWindow,
+  type BridgeResult,
+  bridgeChange,
+  canAffect,
+  type IncrementalMatcher,
+  matcherFor,
+  NO_CHANGE,
+  normalizePatch,
+  patchFromChange,
+  type SubscriptionShape,
+  toBridgeResult,
+} from './matcher-bridge';
+// ---- the production bus -------------------------------------------------------------------------
+export {
+  DEFAULT_NATS_PORT,
+  DEFAULT_REQUEST_TIMEOUT_MS,
+  type NatsClient,
+  type NatsClientOptions,
+  type NatsConnect,
+  type NatsHeaders,
+  type NatsMessage,
+  type NatsMessageHandler,
+  type NatsRequestManyOptions,
+  type NatsRequestOptions,
+  type NatsSubscription,
+  type NatsTarget,
+  parseNatsUrl,
+} from './nats-client';
+export { FakeNatsBroker, type FakeNatsOptions, fakeNatsConnect } from './nats-fake';
+export {
+  assertBucket,
+  assertServerVersion,
+  ensureKvBucket,
+  type JsError,
+  type KvRecord,
+  kvGet,
+  kvLast,
+  kvStream,
+  kvSubject,
+  kvWrite,
+} from './nats-jetstream';
+export { decodeToken, encodeToken, NatsKvSet, type NatsKvSetOptions } from './nats-kv';
+export { openNatsClient } from './nats-lib-client';
+export { NatsTransport, type NatsTransportOptions } from './nats-transport';
+export { PgAdvisoryLock, type PgAdvisoryLockOptions } from './pg-advisory-lock';
+// ---- the postgres replication path ------------------------------------------------------------
+export { camel, entityRow } from './pg-entity-row';
+export {
+  changeLsn,
+  commitPositionOf,
+  type ReplicationStreamStats,
+} from './pg-replication';
+export { bunPgStream, type PgTarget, parsePgUrl, type SslMode } from './pg-socket';
+export type { PgStream } from './pg-wire';
+export {
+  type PgColumn,
+  PgOutputDecoder,
+  type PgOutputMessage,
+  type PgRelation,
+} from './pgoutput';
+export { authorizeWithPolicy, type GateOptions, visibleWithPolicy } from './policy-gate';
+export {
+  DEFAULT_MAX_PRESENCE_MEMBERS,
+  PRESENCE_KEY_PREFIX,
+  PRESENCE_SWEEP_PREFIX,
+  type PresenceInput,
+  type PresenceOptions,
+  PresenceRegistry,
+  type PresenceRoster,
+  presenceFrame,
+} from './presence';
+export {
+  createEntry,
+  fillWindow,
+  orgIdOf,
+  type PendingRead,
+  type QueryEntry,
+  refillWindowInLane,
+} from './query-window';
+export {
+  type AdvisoryLock,
+  CHANGE_SUBJECT_PREFIX,
+  type ChangeEnvelope,
+  changeSubject,
+  createReplicator,
+  InMemoryAdvisoryLock,
+  normalize,
+  parseChange,
+  parseEnvelope,
+  type Replicator,
+  type ReplicatorOptions,
+  type ReplicatorStats,
+  SeqGapDetector,
+} from './replicator';
+export {
+  actorIdOf,
+  CLOSE,
+  DEFAULT_FRAME_BURST,
+  DEFAULT_IDLE_TIMEOUT_MS,
+  DEFAULT_MAX_BUFFERED_BYTES,
+  DEFAULT_MAX_FRAMES_PER_SECOND,
+  idleSweepPeriodMs,
+  SocketRegistry,
+  type SocketRegistryOptions,
+  SyncSocket,
+  type SyncSocketOptions,
+  type WsLike,
+} from './socket';
+export type {
+  GateFailed,
+  GateStage,
+  RowDenied,
+  Subscriber,
+  SubscriberGateOptions,
+} from './subscriber-gate';
+export {
+  GrantBook,
+  type GrantSweepDeps,
+  type GrantSweepResult,
+  type SyncAuthenticator,
+  type SyncGrant,
+  sweepGrants,
+} from './sync-auth';
+export {
+  createFrameRouter,
+  type FrameRouter,
+  type FrameRouterOptions,
+  type MutationHandler,
+} from './sync-frames';
+export {
+  type ListenOptions,
+  listenSyncNode,
+  type SyncListener,
+} from './sync-listen';
+export {
+  createSyncNode,
+  DEFAULT_MAX_CONNECTIONS,
+  DEFAULT_MAX_FRAME_BYTES,
+  DEFAULT_REAUTH_INTERVAL_MS,
+  type SyncNode,
+  type SyncNodeOptions,
+  type SyncWs,
+  type UpgradeTarget,
+  type WsData,
+} from './sync-node';
+// ---- admission and drain: the node's half of the reconnect vocabulary ---------------------------
+export {
+  AcceptBudget,
+  type AcceptBudgetOptions,
+  type DrainedSocket,
+  type DrainPlanEntry,
+  type DrainPlanOptions,
+  drainPlan,
+  reconnectFrame,
+} from './thundering-herd';
+export {
+  DEFAULT_PRESENCE_BUCKET,
+  DEFAULT_PRESENCE_TTL_MS,
+  type SelectTransportOptions,
+  selectTransport,
+  TRANSPORT_ENV_KEYS,
+  type TransportEnvironment,
+  type TransportSelection,
+} from './transport-env';