@pylonsync/sync 0.3.292 → 0.3.293

package/dist/room-subscriptions.d.ts

@@ -0,0 +1,113 @@
+export interface RoomMember {
+    user_id: string;
+    joined_at: string;
+    data?: Record<string, unknown>;
+}
+/** Reason codes the SDK exposes on a room subscription error. */
+export type RoomErrorCode = "NOT_IN_ROOM" | "UNKNOWN";
+export interface RoomError {
+    code: RoomErrorCode;
+    message?: string;
+}
+/** Callback fired when a room's membership snapshot OR error state
+ *  changes. The same callback receives every transition for the room —
+ *  snapshots overwrite state, updates mutate it, and errors set the
+ *  `error` slot. Subscribers read the latest values via the getters on
+ *  the entry; this fires purely as a "something changed" pulse so
+ *  React hooks can re-render. */
+export type RoomSubscriber = () => void;
+/** A broadcast message relayed through a room. `from` is the sender's
+ *  user id (the server stamps it — clients can't spoof each other). */
+export interface RoomMessage {
+    topic: string;
+    payload: unknown;
+    from: string;
+}
+export type RoomMessageSubscriber = (message: RoomMessage) => void;
+export declare class RoomSubscriptions {
+    private readonly sendWs;
+    private readonly rooms;
+    /** Caller-supplied uplink to the WS. The engine routes through its
+     *  active transport; this module stays transport-agnostic.
+     *  Returns true when the message reached the wire (transport is open),
+     *  false otherwise — RoomSubscriptions uses this to decide whether
+     *  to surface "not connected yet" to the registry's callers.
+     *  No-op transports (followers, no WS yet) return false; the engine
+     *  hides the broadcast/leader split behind this hook. */
+    constructor(sendWs: (msg: unknown) => boolean);
+    /** Register a subscriber for `roomId`. First add ships the WS
+     *  `room-subscribe`; subsequent adds just bump the refcount and
+     *  deliver the cached snapshot to the new subscriber's callback.
+     *
+     *  Returns an unsubscribe function that decrements the refcount on
+     *  call. The last unsubscribe ships `room-unsubscribe`, clears the
+     *  entry, and the next register() for the same room is a fresh
+     *  start.
+     *
+     *  Idempotent w.r.t. wire frames: a re-subscribe with no intervening
+     *  full unsubscribe doesn't re-send `room-subscribe` to the server. */
+    register(roomId: string, subscriber: RoomSubscriber): () => void;
+    /** Get-or-create the entry for a room. `isFirst` means this call
+     *  created it, i.e. the caller must ship the wire `room-subscribe`. */
+    private ensureEntry;
+    /**
+     * Register a BROADCAST-MESSAGE listener for `roomId`. Counts toward
+     * the same refcount as membership subscribers (a tab that only
+     * listens for broadcasts still needs the wire `room-subscribe`).
+     * The callback receives every `action: "broadcast"` relay for the
+     * room — including the caller's own broadcasts echoed back; filter
+     * on `message.from` if self-echo is unwanted.
+     */
+    registerMessages(roomId: string, subscriber: RoomMessageSubscriber): () => void;
+    /** Decrement the refcount for one subscriber. Internal — the
+     *  `register()` returned unsubscribe routes here. Last out ships
+     *  `room-unsubscribe`. */
+    private unregisterOne;
+    /** Force a full teardown of one room regardless of refcount. Used by
+     *  the engine's leader-handoff and the hook's manual `leave()` path.
+     *  Notifies every remaining subscriber via the standard pulse (so
+     *  they observe `members === null` and re-render as disconnected). */
+    unregisterRoom(roomId: string): void;
+    /** Snapshot push from the server: full membership for the room.
+     *  Overwrites any cached state, clears any prior error, and pulses
+     *  every subscriber callback. */
+    applySnapshot(roomId: string, members: RoomMember[]): void;
+    /** Incremental update from the server. `action` mirrors the server's
+     *  RoomEvent variants — join / leave / presence / broadcast.
+     *  Membership actions mutate the cached `members` snapshot in-place
+     *  and pulse the membership subscribers; `broadcast` actions route
+     *  the relayed payload to the message subscribers instead (and do
+     *  NOT pulse membership — fire-rate broadcasts would otherwise
+     *  re-render every useRoom consumer per message). */
+    applyUpdate(roomId: string, action: "join" | "leave" | "presence" | "broadcast", member: RoomMember | undefined, _data: unknown): void;
+    /** Server pushed `{ type: "error", code, room }` after a subscribe.
+     *  Record the error on the room and pulse subscribers — the React
+     *  hook surfaces it via the `error` return slot. We do NOT
+     *  unregister automatically: the user genuinely isn't in the room
+     *  and the SDK shouldn't retry, but the registry entry stays so
+     *  React unmount still ships a `room-unsubscribe` (server is
+     *  idempotent for unknown subs). */
+    applyError(roomId: string, error: RoomError): void;
+    /** Read the cached snapshot for a room without subscribing. The
+     *  React hook uses this in its initial-state effect so a re-mount
+     *  inside the same registry lifecycle picks up the current members
+     *  on tick zero. Returns `null` when the snapshot hasn't landed
+     *  yet — DISTINCT from `[]` ("empty room"). */
+    members(roomId: string): RoomMember[] | null;
+    /** Latest error for a room (null if none). */
+    error(roomId: string): RoomError | null;
+    /** Is there at least one local subscriber for `roomId`. Used by the
+     *  hook's polling-fallback path to decide whether to keep polling. */
+    has(roomId: string): boolean;
+    /** Every room currently tracked. Used by `replay()` and by the
+     *  multi-tab seed-on-promotion. */
+    roomIds(): string[];
+    /** Resend `room-subscribe` for every active room. Called by the
+     *  engine's `onConnected` hook after the WS reopens — the server
+     *  forgets per-client subs across disconnects, so without this
+     *  resync the first push would never arrive. */
+    replay(): void;
+    /** Test/diagnostics: total active rooms. */
+    size(): number;
+    private notify;
+}

package/dist/server-subscriptions.d.ts

@@ -0,0 +1,26 @@
+export declare class ServerSubscriptions {
+    private readonly sendWs;
+    private specs;
+    constructor(sendWs: (msg: unknown) => void);
+    /** Register a subscription. Sends `subscribeMessage` over WS and
+     *  remembers it so the next reconnect re-sends it.
+     *
+     *  Re-registering the same key with the SAME payload is a no-op
+     *  (the prior subscribe is still live on the server). But a
+     *  re-register with a DIFFERENT payload re-sends — that's the
+     *  intended behavior of `useReactiveQuery(name, args)` when args
+     *  change: same sub_id, new args, server must observe the change
+     *  or the handler keeps running against stale arguments. */
+    register(key: string, subscribeMessage: unknown): void;
+    /** Unregister. Sends `unsubscribeMessage` over WS and forgets the
+     *  replay entry. No-op for unknown keys (matches React's
+     *  StrictMode-friendly double-unmount semantics). */
+    unregister(key: string, unsubscribeMessage: unknown): void;
+    /** Whether `key` is currently registered. */
+    has(key: string): boolean;
+    /** Re-send every registered subscribe message. Called from
+     *  `ws.onopen` after the socket reconnects — the server purges
+     *  per-client subscription state on disconnect, so without this
+     *  resync the subscriber's first event would never arrive. */
+    replay(): void;
+}

package/dist/session-resolver.d.ts

@@ -0,0 +1,68 @@
+import type { ResolvedSession } from "./types";
+/** Verdict returned from `observeSession`. The engine acts on these
+ *  three booleans; the resolver makes no decisions about side effects
+ *  (replica reset, store notify, pull) — those belong upstream. */
+export interface SessionTransition {
+    /** Resolved session differs in any field (userId / tenantId / isAdmin /
+     *  roles). When true, the engine should notify subscribers. */
+    identityChanged: boolean;
+    /** The tenant moved AND it isn't the null→X first-resolution case —
+     *  cached rows belong to a different tenant and the replica should
+     *  be wiped before the next pull. */
+    replicaInvalidated: boolean;
+    /** First time tenant flipped from null to a real value (the engine
+     *  started before /api/auth/select-org landed). The cached rows in
+     *  this case ARE for the new tenant; reset would tombstone valid
+     *  state. Engine should pull but NOT reset. */
+    isFirstResolution: boolean;
+    /** Tenant value moved at all (covers both null→X and X→Y). When
+     *  true, the engine should pull regardless of reset semantics —
+     *  cached rows under the old tenant won't include rows added under
+     *  the new one. */
+    tenantChanged: boolean;
+}
+export interface TokenTransition {
+    /** Token flipped since the last observation. Engine should reset
+     *  the replica because the visible set changed under a new identity. */
+    tokenChanged: boolean;
+}
+export declare class SessionResolver {
+    private _resolved;
+    /** `undefined` until the first observation — distinguishes "we've
+     *  never seen a token" from "the token is null." Same for tenant. */
+    private lastSeenToken;
+    private lastSeenTenant;
+    /** Current resolved session — what `useSession` consumers should see. */
+    resolved(): ResolvedSession;
+    /** Stable string signature of the current session. Captured before
+     *  long-running ops (reconcile, in particular) so the op can detect
+     *  if anything changed during its in-flight period and bail. */
+    signature(): string;
+    /** Compute the verdict for a freshly resolved session WITHOUT
+     *  mutating internal state. The engine inspects the verdict to
+     *  decide whether to reset the replica + pull, then calls
+     *  `commitObservation(next)` once it's safe for `useSession`
+     *  subscribers to see the new tenant.
+     *
+     *  Splitting compute from commit prevents the "useSession reports
+     *  new tenant + useQuery shows old tenant's rows" inconsistency
+     *  window that existed when the resolved session was mutated
+     *  before `resetReplica()` finished. */
+    inspectSession(next: ResolvedSession): SessionTransition;
+    /** Commit a previously-inspected session as the current truth.
+     *  Engine calls this AFTER acting on the verdict (replica reset,
+     *  pull) so subscribers never observe a half-applied transition. */
+    commitObservation(next: ResolvedSession): void;
+    /** Convenience for tests / migration: inspect + commit in one call.
+     *  Production callers should use `inspectSession` + `commitObservation`
+     *  to control the timing of state mutation. */
+    observeSession(next: ResolvedSession): SessionTransition;
+    /** Feed in the current bearer token. Returns whether it flipped
+     *  since the previous observation. The engine uses this in pull()
+     *  to decide whether to reset before reading the cursor. */
+    observeToken(token: string | null): TokenTransition;
+}
+/** Stable signature of a resolved session. Used by reconcile to detect
+ *  mid-fetch session flips. Roles array is sorted+joined so insertion
+ *  order doesn't trip the equality check. */
+export declare function sessionSignature(s: ResolvedSession): string;

package/dist/storage.d.ts

@@ -0,0 +1,30 @@
+export interface Storage {
+    get(key: string): string | null;
+    set(key: string, value: string): void;
+    remove(key: string): void;
+}
+/**
+ * Pick a default storage adapter for the current host. Returns a real
+ * localStorage wrapper in browsers, an in-memory map elsewhere. Apps that
+ * need persistence on non-browser hosts (RN, Tauri, Electron) should pass
+ * their own adapter via `SyncEngineConfig.storage` and skip this default.
+ */
+export declare function defaultStorage(): Storage;
+/**
+ * Build a `Storage` wrapper around an async backend (AsyncStorage,
+ * Tauri-store, etc). The host is responsible for hydrating `seed` from
+ * the async backend at startup and for persisting writes on its own
+ * schedule. The wrapper itself stays synchronous so the engine doesn't
+ * change shape per platform.
+ *
+ * Typical RN wiring:
+ * ```ts
+ * const seed = await AsyncStorage.multiGet(KEYS).then(toRecord);
+ * const storage = createWriteThroughStorage(seed, async (k, v) => {
+ *   if (v === null) await AsyncStorage.removeItem(k);
+ *   else await AsyncStorage.setItem(k, v);
+ * });
+ * init({ baseUrl, storage });
+ * ```
+ */
+export declare function createWriteThroughStorage(seed: Record<string, string> | null, onWrite: (key: string, value: string | null) => void): Storage;

package/dist/subscription-coordinator.d.ts

@@ -0,0 +1,99 @@
+import type { ServerSubscriptions } from "./server-subscriptions";
+import type { ReactiveMessage } from "./types";
+/** Engine-side surface the coordinator depends on. Kept narrow so the
+ *  coordinator's contract with the engine is explicit. */
+export interface SubscriptionCoordinatorContext {
+    isLeader(): boolean;
+    broadcastToTabs(payload: unknown): void;
+}
+export declare class SubscriptionCoordinator {
+    private readonly serverSubs;
+    private readonly ctx;
+    /** Per-row local refcount for CRDT subscriptions — N `useLoroDoc`
+     *  consumers on the same `(entity, rowId)` in THIS tab share a
+     *  single server subscription. Distinct from `reactiveSubOwners`:
+     *  CRDT keys are per-row (many consumers per tab) while reactive
+     *  sub_ids are per-consumer-instance (typically one). StrictMode
+     *  double-subscribe still bumps the count by one each call; the
+     *  matching double-unsubscribe early-returns when the count is
+     *  already zero, so the math balances. */
+    private crdtSubscribers;
+    /** Per-row set of FOLLOWER tabIds that have forwarded a
+     *  `sub-register` for this key. Leader-only. Used to:
+     *    (a) skip the WS unsubscribe until both `crdtSubscribers`
+     *        and this set are empty, and
+     *    (b) skip the cross-tab binary broadcast when no follower
+     *        cares about CRDT (saves bandwidth when the leader is
+     *        the only CRDT consumer). */
+    private crdtForwarders;
+    /** Per-sub_id ownership set for reactive subscriptions on the
+     *  leader: which tabs (self + forwarders) want this sub alive.
+     *  A SET, not a count, so a follower crash + late `sub-unregister`
+     *  storm can't underflow the count, and a remount/StrictMode
+     *  double-subscribe from one tab still counts as one owner. */
+    private reactiveSubOwners;
+    /** Inbound message routing for reactive subscriptions — server pushes
+     *  `reactive-result` / `reactive-error` envelopes keyed by sub_id and
+     *  the hook's handler lives here. */
+    private reactiveHandlers;
+    /** Specs (fn_name + args) for every reactive subscription this tab
+     *  has registered, regardless of role. On promotion the new leader
+     *  uses these to register with serverSubs; on a leader change while
+     *  we stay a follower we use them to re-forward `sub-register` to
+     *  the new leader. */
+    private wantedReactiveSpecs;
+    constructor(serverSubs: ServerSubscriptions, ctx: SubscriptionCoordinatorContext);
+    /** Refcounted CRDT row subscribe. First subscriber for the row sends
+     *  the WS frame (leader) or forwards to the leader (follower).
+     *  Idempotent at the WS level: re-calling with no intervening
+     *  unsubscribe just bumps the count. */
+    subscribeCrdt(entity: string, rowId: string): void;
+    /** Refcount-aware CRDT row unsubscribe. Last unsubscribe ships the
+     *  WS frame; intermediate calls just decrement. Calling more times
+     *  than `subscribeCrdt` is a no-op (StrictMode-safe). */
+    unsubscribeCrdt(entity: string, rowId: string): void;
+    /** Register a reactive query subscription. The caller-minted `sub_id`
+     *  is used by the React hook to dispatch result/error pushes to the
+     *  right component.
+     *
+     *  Idempotent: re-calling with the same `sub_id` replaces the prior
+     *  handler + spec. Useful when args change and the hook re-registers
+     *  — ServerSubscriptions re-sends on payload change, so the WS sees
+     *  the new args. */
+    subscribeReactive(sub_id: string, fn_name: string, args: unknown, handler: (msg: ReactiveMessage) => void): void;
+    /** Tear down a reactive subscription. No-op for unknown sub_ids —
+     *  React StrictMode double-unmount doesn't error. */
+    unsubscribeReactive(sub_id: string): void;
+    /** Follower → leader: register a WS subscription on the follower's
+     *  behalf. Caller (engine) has already gated on `isLeader()`. */
+    handleForwardedRegister(msg: Record<string, unknown>, fromTabId: string): void;
+    /** Follower → leader: unregister a WS subscription on the follower's
+     *  behalf. */
+    handleForwardedUnregister(msg: Record<string, unknown>, fromTabId: string): void;
+    /** Leader → follower: a `reactive-result` / `reactive-error` envelope
+     *  arrived on the leader's WS. Route to the local handler if we
+     *  registered the sub. */
+    handleReactiveMessage(sub_id: string, payload: ReactiveMessage): void;
+    /** Seed serverSubs with every subscription this tab currently wants.
+     *  Called when this tab settles as leader (either at start() or via
+     *  late promotion) so the next WS connect replays the bundle.
+     *  Idempotent: serverSubs.register dedupes by payload equality. */
+    seedFromLocalInterest(): void;
+    /** Re-broadcast every locally-wanted sub to the (new) leader.
+     *  Triggered by `request-sub-replay` after a leader change while we
+     *  stayed a follower. */
+    replayForwardedSubs(): void;
+    /** A peer tab disappeared (broker `bye` fired). Drop it from every
+     *  forwarder/owner set; if a key drops to zero remaining owners
+     *  (no local consumer, no forwarder) we unregister the WS sub so
+     *  the server stops fanning at a tab that no longer exists. */
+    scrubPeer(tabId: string): void;
+    /** True when at least one follower tab has forwarded a CRDT sub.
+     *  The engine gates its binary-broadcast on this so we don't fan
+     *  binary frames to every tab when no follower cares about CRDT. */
+    hasCrdtForwarders(): boolean;
+}
+/** Internal CRDT key format: `${entity}\x00${rowId}`. Centralized so
+ *  the engine's binary-frame parser (and any future routing logic)
+ *  agrees with the coordinator on the wire shape. */
+export declare function crdtKey(entity: string, rowId: string): string;

package/dist/test-harness/env.d.ts

@@ -0,0 +1,56 @@
+import { SyncEngine } from "../index";
+import { TestServer, type VisibilityFilter } from "./server";
+import { type TransportHandle } from "./transport";
+export interface CreateTestEnvOptions {
+    /** Override visibility per-entity (tenant scoping, RLS, etc.). */
+    visible?: VisibilityFilter;
+    /** Override the appName the engine uses for storage keys. */
+    appName?: string;
+    /** Mid-fetch hook fired before /api/entities/<E>/cursor responds.
+     *  Lets a scenario flip server state to drive the reconcile
+     *  session-guard race. */
+    beforeListEntityRows?: import("./server").BeforeListEntityHook;
+    /** Mid-fetch hook fired before /api/sync/pull responds. */
+    beforePull?: import("./server").BeforePullHook;
+    /** Field projector — strips serverOnly-style fields before the
+     *  row leaves the server. */
+    projectRow?: import("./server").FieldProjector;
+    /** Transport mode passed to the engine. Default "websocket". Use
+     *  "poll" to disable the WS-onopen reconcile race in scenarios
+     *  that only want to pin the in-start pipeline. */
+    transport?: "websocket" | "poll" | "sse";
+    /** Base delay (ms) for WS reconnect backoff. The default value used
+     *  inside the harness (`undefined` → 1000) introduces seconds of
+     *  wall-clock waiting on every reconnect scenario; pass a small
+     *  value when the test specifically exercises the reconnect path. */
+    reconnectDelay?: number;
+}
+export interface TestEnv {
+    server: TestServer;
+    engine: SyncEngine;
+    transport: TransportHandle;
+    /** Token of the most recent signIn() call. */
+    token: string | undefined;
+    /** Mint a session on the server AND tell the transport to send it
+     *  as Authorization: Bearer on future requests. Returns the token. */
+    signIn(input: {
+        userId: string | null;
+        tenantId?: string | null;
+        isAdmin?: boolean;
+        roles?: string[];
+    }): string;
+    /** Re-stamp tenant on the active token (mirrors select-org). */
+    selectOrg(tenantId: string | null): void;
+    /** Sign out: drops the active token. The engine still has its
+     *  cached resolved session until something forces a refresh. */
+    signOut(): void;
+    /** Boot the engine and wait for the initial pull + hydration. */
+    start(): Promise<void>;
+    /** Drain pending microtasks + give the engine a moment to react
+     *  to recent events (WS messages, session-changed envelopes, etc.).
+     *  Most scenarios call this between mutations + assertions. */
+    flush(ms?: number): Promise<void>;
+    /** Tear down: stops the engine, restores global fetch/WebSocket. */
+    dispose(): Promise<void>;
+}
+export declare function createTestEnv(opts?: CreateTestEnvOptions): TestEnv;

package/dist/test-harness/index.d.ts

@@ -0,0 +1,5 @@
+export { createTestEnv } from "./env";
+export type { CreateTestEnvOptions, TestEnv } from "./env";
+export { TestServer, defaultVisibilityFilter } from "./server";
+export type { AuthContext, ServerSession, TestServerOptions, VisibilityFilter, } from "./server";
+export type { TransportHandle } from "./transport";

package/dist/test-harness/server.d.ts

@@ -0,0 +1,178 @@
+import type { ChangeEvent, Row, SyncCursor } from "../types";
+export interface ServerSession {
+    token: string;
+    userId: string | null;
+    tenantId: string | null;
+    isAdmin: boolean;
+    roles: string[];
+}
+export interface AuthContext {
+    userId: string | null;
+    tenantId: string | null;
+    isAdmin: boolean;
+    roles: string[];
+}
+export interface VisibilityFilter {
+    /** Return the subset of `rows` the given auth context can see for
+     *  this entity. Default: every row, so tests that don't care about
+     *  policy just pass. Tests that DO care can pass a custom filter to
+     *  exercise the "session changed mid-fetch" path. */
+    (entity: string, rows: Row[], auth: AuthContext): Row[];
+}
+export declare const defaultVisibilityFilter: VisibilityFilter;
+/** Hook fired right before `/api/entities/<E>/cursor` serializes its
+ *  response. Lets a scenario flip server state (e.g., `setTenant`) so
+ *  the engine sees a different session signature on apply than on
+ *  fetch — the canonical race the reconcile session-guard pins.
+ *  Receives the same auth context the visibility filter uses.
+ *  Returning a Promise makes the fetch await — useful for landing a
+ *  session refresh in flight before the response serializes. */
+export type BeforeListEntityHook = (entity: string, auth: AuthContext) => void | Promise<void>;
+/** Hook fired right before `/api/sync/pull` serializes its response.
+ *  Same role as `beforeListEntityRows` but on the pull path. */
+export type BeforePullHook = (auth: AuthContext, since: number) => void | Promise<void>;
+/** Field projector — strips fields from a row before it leaves the
+ *  server. Models the `serverOnly` projection in production: the
+ *  field exists in the canonical row but is never wired to a client. */
+export type FieldProjector = (entity: string, row: Row) => Row;
+export declare const identityProjector: FieldProjector;
+export interface TestServerOptions {
+    /** Override visibility per-entity (tenant scoping, RLS, etc.). */
+    visible?: VisibilityFilter;
+    /** Mid-fetch hook for the entity-cursor path. */
+    beforeListEntityRows?: BeforeListEntityHook;
+    /** Mid-fetch hook for the sync-pull path. */
+    beforePull?: BeforePullHook;
+    /** Strip fields from rows on the way to the wire (mimics serverOnly). */
+    projectRow?: FieldProjector;
+}
+/** Subscribers attached to WS connections — receive every change
+ *  event we append to the log, plus session-changed envelopes. */
+export type ServerSubscriber = (msg: Record<string, unknown>) => void;
+export declare class TestServer {
+    private sessions;
+    private rows;
+    private log;
+    private subscribers;
+    private visible;
+    private beforeListEntityHook?;
+    private beforePullHook?;
+    private project;
+    private nextSeq;
+    /** When set, the next pull() returns this status instead of normal.
+     *  Used to simulate 410 RESYNC_REQUIRED and similar transient errors. */
+    private nextPullStatus;
+    /** When true, every DELTA pull (since > 0) 410s, but a snapshot pull
+     *  (since = 0) succeeds. Simulates a horizontally-scaled deployment
+     *  where a client bounces between instances whose in-memory change
+     *  logs diverge (no shared persistent log) — every cursor is "stale"
+     *  on the instance it lands on. This is the condition that drove the
+     *  280GB egress storm; the test asserts the client backs off instead
+     *  of re-snapshotting forever. */
+    force410OnDelta: boolean;
+    /** Count of snapshot pulls served (since = 0). The egress storm was a
+     *  runaway count here; the regression test bounds it. */
+    snapshotPullCount: number;
+    /** Count of /api/sync/push requests received. Lets a test assert the
+     *  engine actually shipped a batch (e.g. hydrated offline writes that
+     *  must drain once leader-elected), independent of the no-op push
+     *  response the harness returns. */
+    pushRequestCount: number;
+    /** `${entity}/${row_id}` of every op the engine pushed, across all
+     *  push requests. Lets a test assert a SPECIFIC mutation reached the
+     *  server — robust against a stray retry from an unrelated engine
+     *  whose pending timer fires against the globally-installed fetch
+     *  mock (that pushes ITS ops, never this test's row). */
+    readonly receivedPushKeys: string[];
+    /** Captured outbound WS messages from clients — tests assert against
+     *  this to verify `reactive-subscribe`, `crdt-subscribe`, etc., were
+     *  actually sent over the wire. */
+    readonly receivedWsMessages: Array<{
+        userId: string | null;
+        msg: unknown;
+    }>;
+    constructor(opts?: TestServerOptions);
+    /** Mint a session and return its bearer token. */
+    signIn(input: {
+        userId: string | null;
+        tenantId?: string | null;
+        isAdmin?: boolean;
+        roles?: string[];
+    }): string;
+    /** Re-stamp the tenant on an existing token (analogue of
+     *  /api/auth/select-org). Fires session-changed to subscribers so
+     *  the client can refresh its resolved session. */
+    setTenant(token: string, tenantId: string | null): void;
+    /** Mutate fields on an existing session in place. Used by scenarios
+     *  that need to change the sessionSignature without triggering the
+     *  engine's tenant-flip resetReplica (e.g., role changes). */
+    mutateSession(token: string, patch: Partial<Omit<ServerSession, "token">>): void;
+    /** Revoke a session (drop the token from the map). Used by signOut
+     *  scenarios — subsequent /api/auth/me returns anonymous. */
+    revoke(token: string): void;
+    /** What /api/auth/me returns for a given token. */
+    authContextFor(token: string | undefined): AuthContext;
+    /** Inject a 410 into the next pull. Engine should resetReplica and
+     *  re-pull from seq=0; the second pull responds normally. */
+    primeNextPullStatus(status: number): void;
+    consumeNextPullStatus(): number | null;
+    /** Inject a one-shot outcome for the NEXT push: a `network` failure
+     *  (the fetch rejects with no status — simulating offline / connection
+     *  reset) or an HTTP `status` (e.g. 403 permanent rejection, 503
+     *  transient). Lets tests exercise the transient-vs-permanent
+     *  classification in pushInner. */
+    private nextPushOutcome;
+    primeNextPushOutcome(o: {
+        kind: "network";
+    } | {
+        kind: "status";
+        status: number;
+    }): void;
+    consumeNextPushOutcome(): {
+        kind: "network";
+    } | {
+        kind: "status";
+        status: number;
+    } | null;
+    /** Make the NEXT delta pull report `has_more: true` once, exercising
+     *  the change-log tail-pull recursion in pullInner (the path that
+     *  self-deadlocked before the pullInner() fix). */
+    private nextPullHasMore;
+    primeNextPullHasMore(): void;
+    consumeNextPullHasMore(): boolean;
+    /** Bulk-seed rows for an entity AND emit insert events into the
+     *  change log so the engine discovers them via /api/sync/pull at
+     *  since=0 — same shape production clients see when they boot
+     *  against a populated server. Without logging, the rows would only
+     *  be discoverable via reconcile, which doesn't fire on start. */
+    seed(entity: string, rows: Row[]): void;
+    insert(entity: string, row: Row): void;
+    update(entity: string, id: string, patch: Partial<Row>): void;
+    delete(entity: string, id: string): void;
+    /** Raw seq bump for tests that want to inject events directly. */
+    nextSeqValue(): number;
+    /** /api/entities/<entity>/cursor — policy-filtered list.
+     *  Async so the `beforeListEntityRows` hook can await state changes
+     *  (e.g., land a session refresh mid-fetch). Auth is re-read AFTER
+     *  the hook so a hook that flips roles / tenant takes effect on
+     *  the response the engine sees, matching what a real server does
+     *  when the session mutates mid-request. */
+    listEntityRows(entity: string, token: string | undefined): Promise<Row[]>;
+    /** /api/sync/pull — every visible change since `since`. */
+    pull(token: string | undefined, since: number): Promise<{
+        changes: ChangeEvent[];
+        cursor: SyncCursor;
+        has_more: boolean;
+    }>;
+    subscribe(userId: string, sub: ServerSubscriber): () => void;
+    /** Push an arbitrary envelope to every subscriber for a user — used
+     *  for `reactive-result`, `row-revoked`, `session-changed` etc. */
+    pushToUser(userId: string, msg: Record<string, unknown>): void;
+    /** Record an outbound WS message from a client (subscribe / unsub /
+     *  ping). Tests can assert against `receivedWsMessages` to verify
+     *  the engine actually sent something over the wire. */
+    recordClientWsMessage(token: string | undefined, msg: unknown): void;
+    private broadcastToUser;
+    private bumpSeq;
+    private appendLog;
+}

package/dist/test-harness/transport.d.ts

@@ -0,0 +1,19 @@
+import type { TestServer } from "./server";
+export interface TransportHandle {
+    /** Token the engine is currently sending as Authorization: Bearer */
+    currentToken: () => string | undefined;
+    /** Set / clear the active token (mirrors localStorage flips). */
+    setToken: (token: string | undefined) => void;
+    /** Number of `fetch` calls observed — assert against this in
+     *  tests that need to confirm "nothing more was requested." */
+    fetchCount: () => number;
+    /** Number of WS connections opened so far. */
+    wsConnectCount: () => number;
+    /** Close the most-recently-opened mock WS so the engine sees a
+     *  disconnect and schedules reconnect via its backoff. Returns
+     *  true if a socket was actually closed, false otherwise. */
+    closeLatestWs: () => boolean;
+    /** Tear down the global stubs. */
+    restore: () => void;
+}
+export declare function installTransport(server: TestServer): TransportHandle;