@syncular/server 0.1.2 → 0.2.0

package/dist/index.js

@@ -1,35 +1,53 @@
 /**
- * @syncular/server - Server-side sync infrastructure
+ * @syncular/server — framework-free embeddable SSP2 protocol library
+ * (SPEC.md is normative; REVISE.md B2 is the architectural mandate).
  *
- * Commit-log based sync with:
- * - commit log + change log
- * - scopes + subscriptions (partial sync + auth)
- * - commit-level idempotency
- * - blob/media storage
+ * Core surface: `handleSyncRequest(bytes, ctx) → bytes` over host-provided
+ * storage / scope-resolution / segment-store interfaces, plus a
+ * transport-agnostic realtime session (§8), the direct segment download
+ * handler (§5.5), and signed-URL token issuance/verification (§5.4).
  */
-export * from '@syncular/core';
-export * from './auth-leases.js';
-export * from './blobs/index.js';
-export * from './clients.js';
-export * from './commit-integrity.js';
-export * from './compaction.js';
-export * from './dialect/index.js';
-export * from './encrypted-crdt.js';
+export * from './admin.js';
+export * from './blob-handlers.js';
+export * from './blob-store.js';
+export * from './content-encoding.js';
+export * from './context.js';
+export * from './crdt-merger.js';
+export * from './d1-storage.js';
 export * from './errors.js';
-export * from './handlers/index.js';
-export * from './helpers/index.js';
-export * from './migrate.js';
-export * from './notify.js';
-export * from './plugins/index.js';
-export * from './proxy/index.js';
+export * from './events.js';
+export * from './events-ring.js';
+export * from './frame-bytes.js';
+export * from './handler.js';
+export * from './lease-store.js';
+// The `PgExecutor` seam + Postgres storage/fanout are driver-agnostic (zero
+// runtime deps). Concrete driver adapters (pglite for tests; Bun.sql /
+// node-postgres for production, documented in the README) live in separate
+// entry points so the barrel never imports a driver.
+export * from './pg-executor.js';
+export * from './postgres-fanout.js';
+export * from './postgres-storage.js';
 export * from './prune.js';
 export * from './pull.js';
 export * from './push.js';
-export * from './realtime/index.js';
+export * from './realtime.js';
+export * from './relational-rows.js';
+export * from './s3-blob-store.js';
+export * from './s3-segment-store.js';
 export * from './schema.js';
-export * from './snapshot-artifacts.js';
-export * from './snapshot-chunks.js';
-export * from './stats.js';
-export * from './subscriptions/index.js';
-export * from './sync.js';
-//# sourceMappingURL=index.js.map
+export * from './scopes.js';
+export * from './segment-download.js';
+export * from './segment-store.js';
+export * from './signed-url.js';
+// Bun-specific storages (top-level `bun:sqlite`): re-exported for Bun/Node
+// hosts. Workers/edge builds tree-shake them (and their `bun:sqlite` import)
+// away — the runtime-neutral core closure is enforced by
+// `test/runtime-neutrality.test.ts`.
+export * from './sqlite-blob-store.js';
+export * from './sqlite-dialect.js';
+export * from './sqlite-image.js';
+export * from './sqlite-lease-store.js';
+export * from './sqlite-segment-store.js';
+export * from './sqlite-storage.js';
+export * from './storage.js';
+export * from './validate.js';

package/dist/lease-store.d.ts

@@ -0,0 +1,50 @@
+/**
+ * Auth-lease store (SPEC.md §7.3.1).
+ *
+ * A lease is a server-issued, time-bounded grant recording the actor's
+ * resolved allowed scopes at issuance, keyed by `(partition, clientId)`.
+ * It is the authorization the server falls to during a host-authorization
+ * outage (§7.3.3), and the client's offline-trust window (§7.3.5).
+ *
+ * The store is OPTIONAL, wired only when `leases` is configured
+ * (`leases` absent ⇒ the feature is off, zero cost — the blob-store
+ * pattern). Records are host-owned; a production store signs them at rest
+ * and verifies on read (§7.3.1). The reference stores keep them plain in
+ * memory / sqlite — the seam is what matters for conformance.
+ */
+import type { ScopeMap } from '@syncular/core';
+/** The stored lease record (§7.3.1). `revoked` is durable (§7.3.4). */
+export interface LeaseRecord {
+    readonly leaseId: string;
+    readonly actorId: string;
+    /** The actor's resolved allowed scopes at issuance (§3.2 step 3). */
+    readonly allowedScopes: ScopeMap;
+    readonly issuedAtMs: number;
+    readonly expiresAtMs: number;
+    readonly revoked: boolean;
+}
+export interface LeaseStore {
+    /** The lease for `(partition, clientId)`, if any (revoked or not). */
+    get(partition: string, clientId: string): Promise<LeaseRecord | undefined>;
+    /**
+     * Issue or refresh the lease for `(partition, clientId)` (§7.3.3). A
+     * refresh slides the SAME `leaseId` — implementations MUST reuse the
+     * stored id for the pair unless it is revoked (a revoked handle never
+     * silently resurrects: a fresh id is minted only once the host clears
+     * the revocation). Returns the stored record.
+     */
+    issue(partition: string, clientId: string, actorId: string, allowedScopes: ScopeMap, nowMs: number, ttlMs: number): Promise<LeaseRecord>;
+    /** Revoke a lease by `leaseId` (§7.3.4); durable, survives refresh. */
+    revoke(partition: string, leaseId: string): Promise<void>;
+}
+/** Stable-per-pair id generator; overridable for deterministic tests. */
+export type LeaseIdFactory = () => string;
+export declare class MemoryLeaseStore implements LeaseStore {
+    #private;
+    constructor(options?: {
+        readonly leaseId?: LeaseIdFactory;
+    });
+    get(partition: string, clientId: string): Promise<LeaseRecord | undefined>;
+    issue(partition: string, clientId: string, actorId: string, allowedScopes: ScopeMap, nowMs: number, ttlMs: number): Promise<LeaseRecord>;
+    revoke(partition: string, leaseId: string): Promise<void>;
+}

package/dist/pg-executor-pglite.d.ts

@@ -0,0 +1,27 @@
+/**
+ * A `PgExecutor` over @electric-sql/pglite (embedded WASM Postgres).
+ *
+ * This is the **test/dev** driver — hermetic, no docker, runs under bun.
+ * `@electric-sql/pglite` is a devDependency of `@syncular/server`; this
+ * module is exported for tests and local experiments, not the production
+ * path. Production wires Bun.sql or node-postgres against the same
+ * `PgExecutor` interface (see the server README).
+ *
+ * pglite is single-connection, so `transaction` runs `BEGIN`/`COMMIT`/
+ * `ROLLBACK` on the one connection and relies on the caller not interleaving
+ * unrelated queries during a transaction scope (the storage layer holds one
+ * transaction at a time per push).
+ */
+import type { PGlite } from '@electric-sql/pglite';
+import type { PgExecutor } from './pg-executor.js';
+/** Minimal structural type for a pglite instance (avoids a hard type dep). */
+interface PgliteLike {
+    query<Row>(query: string, params?: unknown[]): Promise<{
+        rows: Row[];
+        affectedRows?: number;
+    }>;
+    exec(query: string): Promise<unknown>;
+    close(): Promise<void>;
+}
+export declare function pgliteExecutor(db: PGlite | PgliteLike): PgExecutor;
+export {};

package/dist/pg-executor-pglite.js

@@ -0,0 +1,33 @@
+function queryable(db) {
+    return {
+        async query(text, params) {
+            const result = await db.query(text, params ? [...params] : undefined);
+            return {
+                rows: result.rows,
+                rowCount: result.affectedRows ?? result.rows.length,
+            };
+        },
+    };
+}
+export function pgliteExecutor(db) {
+    const like = db;
+    const q = queryable(like);
+    return {
+        query: q.query,
+        async transaction(fn) {
+            await like.exec('BEGIN');
+            try {
+                const result = await fn(q);
+                await like.exec('COMMIT');
+                return result;
+            }
+            catch (error) {
+                await like.exec('ROLLBACK');
+                throw error;
+            }
+        },
+        async close() {
+            await like.close();
+        },
+    };
+}

package/dist/pg-executor.d.ts

@@ -0,0 +1,67 @@
+/**
+ * The minimal Postgres executor seam (REVISE B2: zero runtime deps).
+ *
+ * `PostgresServerStorage` is written entirely against this interface so the
+ * server library never imports a specific driver. Production wires one of:
+ *
+ *   - **Bun.sql** (built into bun) — see `bunSqlExecutor` in the README;
+ *   - **node-postgres** (`pg`) — a `Pool`/`PoolClient` adapter;
+ *
+ * and the test lane wires **@electric-sql/pglite** (embedded WASM Postgres,
+ * a devDependency) via `pgliteExecutor`. All three speak the same three
+ * primitives below.
+ *
+ * ## Type-parser contract (load-bearing)
+ *
+ * `commitSeq`/`serverVersion` are `int8`/`bigint` columns. Drivers disagree
+ * on how they decode `int8`:
+ *
+ *   - pglite → JS `number`;
+ *   - node-postgres → `string` (its default `int8` parser is off to avoid
+ *     silent precision loss past 2^53);
+ *   - Bun.sql → `bigint`.
+ *
+ * The storage layer therefore coerces every sequence value it reads through
+ * `Number(...)` (see `asNumber`). Sequences here are per-partition commit
+ * counters and server_version counters — both comfortably inside 2^53 for
+ * any realistic deployment, so the coercion is safe; a host that expects to
+ * exceed 2^53 commits in a single partition has bigger problems than this
+ * seam. `bytea` columns MUST decode to `Uint8Array`/`Buffer` (all three
+ * drivers do); `NULL` decodes to JS `null`.
+ */
+/** One database row as a plain object keyed by (lower-cased) column name. */
+export type PgRow = Record<string, unknown>;
+/**
+ * A handle that runs parameterized statements. Both the pool-level executor
+ * and a per-transaction client implement it, so storage code is written once
+ * against `PgQueryable` regardless of transaction scope.
+ *
+ * `params` use Postgres positional placeholders (`$1`, `$2`, ...). `text`
+ * is a single statement (no multi-statement `;`-joined batches — those are
+ * driver-specific and defeat parameterization).
+ */
+export interface PgQueryable {
+    query<Row = PgRow>(text: string, params?: readonly unknown[]): Promise<{
+        rows: Row[];
+        rowCount: number;
+    }>;
+}
+/**
+ * The pool-level executor: `PgQueryable` plus transaction control. A
+ * `transaction` callback receives a client pinned to one connection for the
+ * duration of a real Postgres `BEGIN … COMMIT/ROLLBACK`; throwing rolls back.
+ */
+export interface PgExecutor extends PgQueryable {
+    /**
+     * Run `fn` inside a single Postgres transaction on one pinned connection.
+     * The executor issues `BEGIN` before `fn`, `COMMIT` on resolve, and
+     * `ROLLBACK` on throw (rethrowing the original error).
+     */
+    transaction<T>(fn: (client: PgQueryable) => Promise<T>): Promise<T>;
+    /** Release any pooled resources. Optional (pglite/Bun.sql). */
+    close?(): Promise<void>;
+}
+/** Coerce a driver-decoded sequence value (`number | string | bigint`). */
+export declare function asNumber(value: unknown): number;
+/** Coerce a driver-decoded `bytea` value to a `Uint8Array`. */
+export declare function asBytes(value: unknown): Uint8Array;

package/dist/pg-executor.js

@@ -0,0 +1,56 @@
+/**
+ * The minimal Postgres executor seam (REVISE B2: zero runtime deps).
+ *
+ * `PostgresServerStorage` is written entirely against this interface so the
+ * server library never imports a specific driver. Production wires one of:
+ *
+ *   - **Bun.sql** (built into bun) — see `bunSqlExecutor` in the README;
+ *   - **node-postgres** (`pg`) — a `Pool`/`PoolClient` adapter;
+ *
+ * and the test lane wires **@electric-sql/pglite** (embedded WASM Postgres,
+ * a devDependency) via `pgliteExecutor`. All three speak the same three
+ * primitives below.
+ *
+ * ## Type-parser contract (load-bearing)
+ *
+ * `commitSeq`/`serverVersion` are `int8`/`bigint` columns. Drivers disagree
+ * on how they decode `int8`:
+ *
+ *   - pglite → JS `number`;
+ *   - node-postgres → `string` (its default `int8` parser is off to avoid
+ *     silent precision loss past 2^53);
+ *   - Bun.sql → `bigint`.
+ *
+ * The storage layer therefore coerces every sequence value it reads through
+ * `Number(...)` (see `asNumber`). Sequences here are per-partition commit
+ * counters and server_version counters — both comfortably inside 2^53 for
+ * any realistic deployment, so the coercion is safe; a host that expects to
+ * exceed 2^53 commits in a single partition has bigger problems than this
+ * seam. `bytea` columns MUST decode to `Uint8Array`/`Buffer` (all three
+ * drivers do); `NULL` decodes to JS `null`.
+ */
+/** Coerce a driver-decoded sequence value (`number | string | bigint`). */
+export function asNumber(value) {
+    if (typeof value === 'number')
+        return value;
+    if (typeof value === 'bigint')
+        return Number(value);
+    if (typeof value === 'string')
+        return Number.parseInt(value, 10);
+    if (value === null || value === undefined)
+        return 0;
+    throw new Error(`expected a numeric column, got ${typeof value}`);
+}
+/** Coerce a driver-decoded `bytea` value to a `Uint8Array`. */
+export function asBytes(value) {
+    if (value instanceof Uint8Array)
+        return value;
+    if (value === null || value === undefined) {
+        throw new Error('expected bytea, got null');
+    }
+    // node-postgres/Bun.sql return Buffer (a Uint8Array subclass); this branch
+    // is a defensive copy for any array-like the driver hands back.
+    if (Array.isArray(value))
+        return new Uint8Array(value);
+    throw new Error(`expected bytea, got ${typeof value}`);
+}

package/dist/postgres-fanout.d.ts

@@ -0,0 +1,83 @@
+/**
+ * LISTEN/NOTIFY multi-instance fanout (TODO §4.1) — the primitive that lets
+ * N server instances behind a load balancer wake each other's realtime
+ * sessions when a commit lands on any one of them.
+ *
+ * ## The multi-instance problem
+ *
+ * A commit applied on instance A fans out to A's *local* RealtimeHub
+ * sessions immediately (in-memory `notifyCommit`, full delta, no re-read).
+ * But a client whose socket lives on instance B never saw it. LISTEN/NOTIFY
+ * closes that gap:
+ *
+ *   1. after a commit lands, the originating instance calls `notify(payload)`
+ *      → `NOTIFY syncular_commit, '<partition>:<commitSeq>'`;
+ *   2. every instance runs a `listen()` loop on a dedicated connection;
+ *      on a notification it parses the payload and calls
+ *      `hub.wake(partition, 'sync')`.
+ *
+ * ## Why wake, not re-broadcast the delta
+ *
+ * Postgres NOTIFY payloads are capped (~8000 bytes) and are not an ordered,
+ * lossless delta channel — so we do NOT try to ship commit bytes through
+ * them. Remote sessions receive a `sync` wake and pull the delta from the
+ * shared Postgres storage they already read from (§8.3 wake semantics). The
+ * originating instance keeps the in-memory fast path (its own sessions get
+ * the full delta with no extra read); only *cross-instance* delivery pays
+ * the re-pull. Single-instance deployments never install a fanout at all.
+ *
+ * The payload carries `commitSeq` purely for observability/ordering in logs;
+ * the wake itself is seq-agnostic (a session pulls whatever it is behind).
+ *
+ * pglite cannot exercise cross-connection NOTIFY, so the integration
+ * (`postgres-fanout.integration.test.ts`) is env-gated on `SYNCULAR_PG_URL`
+ * and skips cleanly; the payload encode/parse is unit-tested hermetically.
+ */
+import type { WakeReason } from '@syncular/core';
+/** The channel every syncular instance LISTENs on. */
+export declare const FANOUT_CHANNEL = "syncular_commit";
+export interface FanoutPayload {
+    readonly partition: string;
+    readonly commitSeq: number;
+}
+/**
+ * Encode a fanout payload as `<partition>:<commitSeq>`. The partition is
+ * base64url-encoded so a partition string containing `:` cannot corrupt the
+ * frame; commitSeq is a plain decimal integer.
+ */
+export declare function encodeFanoutPayload(payload: FanoutPayload): string;
+/** Parse a fanout payload; returns `undefined` for a malformed frame. */
+export declare function parseFanoutPayload(text: string): FanoutPayload | undefined;
+/** The hub surface the fanout wakes (a `RealtimeHub` satisfies this). */
+export interface FanoutWakeTarget {
+    wake(partition: string, reason: WakeReason): void;
+}
+/**
+ * A raw notification connection. Production wires a driver's LISTEN support:
+ *   - node-postgres: a dedicated `Client` with `client.on('notification', …)`
+ *     after `LISTEN syncular_commit`;
+ *   - Bun.sql: `sql.listen(channel, handler)`.
+ * The `notify` side can reuse the main pool (`SELECT pg_notify($1,$2)`), but
+ * LISTEN needs its own long-lived connection.
+ */
+export interface PgNotificationConnection {
+    /** Register a payload handler for the channel and begin listening. */
+    listen(channel: string, handler: (payload: string) => void): Promise<void> | void;
+    /** Send a notification on the channel. */
+    notify(channel: string, payload: string): Promise<void>;
+    close?(): Promise<void>;
+}
+/**
+ * The fanout primitive. `install(hub)` starts the LISTEN loop that wakes the
+ * hub on every remote commit; `notifyCommit` is called after a local commit
+ * lands to fan it to the other instances.
+ */
+export declare class PostgresFanout {
+    #private;
+    constructor(conn: PgNotificationConnection);
+    /** Start the LISTEN loop, waking `hub` on every notification received. */
+    install(hub: FanoutWakeTarget): Promise<void>;
+    /** Fan an applied commit out to the other instances. */
+    notifyCommit(partition: string, commitSeq: number): Promise<void>;
+    close(): Promise<void>;
+}

package/dist/postgres-fanout.js

@@ -0,0 +1,71 @@
+/** The channel every syncular instance LISTENs on. */
+export const FANOUT_CHANNEL = 'syncular_commit';
+/**
+ * The wake reason remote instances raise on a fanout notification (§8.3):
+ * `catchup-required` — a commit landed on another instance, so the local
+ * session pulls the delta it is now behind on from shared storage.
+ */
+const FANOUT_WAKE_REASON = 'catchup-required';
+/**
+ * Encode a fanout payload as `<partition>:<commitSeq>`. The partition is
+ * base64url-encoded so a partition string containing `:` cannot corrupt the
+ * frame; commitSeq is a plain decimal integer.
+ */
+export function encodeFanoutPayload(payload) {
+    const partition = Buffer.from(payload.partition, 'utf8').toString('base64url');
+    return `${partition}:${payload.commitSeq}`;
+}
+/** Parse a fanout payload; returns `undefined` for a malformed frame. */
+export function parseFanoutPayload(text) {
+    const sep = text.indexOf(':');
+    if (sep <= 0)
+        return undefined;
+    const partitionB64 = text.slice(0, sep);
+    const seqText = text.slice(sep + 1);
+    const commitSeq = Number.parseInt(seqText, 10);
+    if (!Number.isFinite(commitSeq) || commitSeq < 0)
+        return undefined;
+    if (!/^\d+$/.test(seqText))
+        return undefined;
+    let partition;
+    try {
+        partition = Buffer.from(partitionB64, 'base64url').toString('utf8');
+    }
+    catch {
+        return undefined;
+    }
+    if (partition.length === 0)
+        return undefined;
+    return { partition, commitSeq };
+}
+/**
+ * The fanout primitive. `install(hub)` starts the LISTEN loop that wakes the
+ * hub on every remote commit; `notifyCommit` is called after a local commit
+ * lands to fan it to the other instances.
+ */
+export class PostgresFanout {
+    #conn;
+    #installed = false;
+    constructor(conn) {
+        this.#conn = conn;
+    }
+    /** Start the LISTEN loop, waking `hub` on every notification received. */
+    async install(hub) {
+        if (this.#installed)
+            throw new Error('fanout already installed');
+        this.#installed = true;
+        await this.#conn.listen(FANOUT_CHANNEL, (payload) => {
+            const parsed = parseFanoutPayload(payload);
+            if (parsed === undefined)
+                return; // ignore malformed frames
+            hub.wake(parsed.partition, FANOUT_WAKE_REASON);
+        });
+    }
+    /** Fan an applied commit out to the other instances. */
+    async notifyCommit(partition, commitSeq) {
+        await this.#conn.notify(FANOUT_CHANNEL, encodeFanoutPayload({ partition, commitSeq }));
+    }
+    async close() {
+        await this.#conn.close?.();
+    }
+}

package/dist/postgres-storage.d.ts

@@ -0,0 +1,69 @@
+import { type PgExecutor } from './pg-executor.js';
+import type { CompiledSchema, CompiledTable } from './schema.js';
+import type { ClientCursorInfo, ClientRecord, CommitMetadata, CommitMetadataQuery, CommitWindowQuery, RowScanQuery, ScopeActivityQuery, ScopeCommitActivity, ServerStorage, StorageTransaction, StoredCommit, StoredPushResult, StoredRow } from './storage.js';
+/**
+ * Schema DDL. Applied by `PostgresServerStorage.migrate()` (idempotent).
+ *
+ * Covering index design (the reason this file exists):
+ *   - `sync_change_scopes_pk (partition, tbl, var, value, commit_seq)` — the
+ *     candidate scan for `readCommitWindow` ranges on the (partition, tbl,
+ *     var, value IN …) prefix and returns `commit_seq` already ascending;
+ *   - `sync_row_scopes_pk (partition, tbl, var, value, row_id)` — same shape
+ *     for `scanRows`, ordered by `row_id`.
+ * Both are the PRIMARY KEY, so they are the clustering/covering index for
+ * their table. No secondary index is needed for the hot path.
+ *
+ * Blob reference index (§5.9.4) — parity with the SQLite dialect's
+ * `sync_blob_refs`:
+ *   - PRIMARY KEY `(partition, tbl, row_id, blob_id)` — the by-row prefix
+ *     lets `setBlobRefs` replace a row's set with a single ranged DELETE and
+ *     the delete path clear it by (partition, tbl, row_id);
+ *   - the secondary `sync_blob_refs_by_blob (partition, blob_id)` index
+ *     drives `listRowsReferencingBlob` (the download-authorization candidate
+ *     set, §5.9.5) as an index range, never a scan. `postgres-explain
+ *     .test.ts` asserts an `Index` node here too.
+ */
+export declare const POSTGRES_DDL = "\nCREATE TABLE IF NOT EXISTS sync_partitions(\n  partition TEXT PRIMARY KEY,\n  max_commit_seq BIGINT NOT NULL DEFAULT 0,\n  horizon_seq BIGINT NOT NULL DEFAULT 0\n);\nCREATE TABLE IF NOT EXISTS sync_row_scopes(\n  partition TEXT NOT NULL, tbl TEXT NOT NULL,\n  var TEXT NOT NULL, value TEXT NOT NULL, row_id TEXT NOT NULL,\n  PRIMARY KEY(partition, tbl, var, value, row_id)\n);\nCREATE TABLE IF NOT EXISTS sync_commits(\n  partition TEXT NOT NULL, commit_seq BIGINT NOT NULL,\n  client_id TEXT NOT NULL, client_commit_id TEXT NOT NULL,\n  actor_id TEXT NOT NULL, created_at_ms BIGINT NOT NULL,\n  PRIMARY KEY(partition, commit_seq)\n);\nCREATE INDEX IF NOT EXISTS sync_commits_by_time\n  ON sync_commits(partition, created_at_ms);\nCREATE TABLE IF NOT EXISTS sync_changes(\n  partition TEXT NOT NULL, commit_seq BIGINT NOT NULL, idx INTEGER NOT NULL,\n  tbl TEXT NOT NULL, row_id TEXT NOT NULL, op SMALLINT NOT NULL,\n  row_version BIGINT, scopes JSONB NOT NULL, payload BYTEA,\n  PRIMARY KEY(partition, commit_seq, idx)\n);\nCREATE INDEX IF NOT EXISTS sync_changes_by_table\n  ON sync_changes(partition, commit_seq, tbl, idx);\nCREATE TABLE IF NOT EXISTS sync_change_scopes(\n  partition TEXT NOT NULL, tbl TEXT NOT NULL,\n  var TEXT NOT NULL, value TEXT NOT NULL, commit_seq BIGINT NOT NULL,\n  PRIMARY KEY(partition, tbl, var, value, commit_seq)\n);\nCREATE TABLE IF NOT EXISTS sync_push_results(\n  partition TEXT NOT NULL, client_id TEXT NOT NULL,\n  client_commit_id TEXT NOT NULL, result JSONB NOT NULL,\n  PRIMARY KEY(partition, client_id, client_commit_id)\n);\nCREATE TABLE IF NOT EXISTS sync_clients(\n  partition TEXT NOT NULL, client_id TEXT NOT NULL, actor_id TEXT NOT NULL,\n  cursor BIGINT NOT NULL, subscriptions JSONB NOT NULL,\n  updated_at_ms BIGINT NOT NULL,\n  PRIMARY KEY(partition, client_id)\n);\nCREATE TABLE IF NOT EXISTS sync_blob_refs(\n  partition TEXT NOT NULL, tbl TEXT NOT NULL, row_id TEXT NOT NULL,\n  blob_id TEXT NOT NULL,\n  PRIMARY KEY(partition, tbl, row_id, blob_id)\n);\nCREATE INDEX IF NOT EXISTS sync_blob_refs_by_blob\n  ON sync_blob_refs(partition, blob_id);\n";
+export declare class PostgresServerStorage implements ServerStorage {
+    #private;
+    constructor(exec: PgExecutor);
+    /** Apply the schema DDL (idempotent). Call once before use. */
+    migrate(): Promise<void>;
+    /** Resolve a table's compiled schema; row operations require `ensureSchema`. */
+    table(name: string): CompiledTable;
+    ensureSchema(schema: CompiledSchema): Promise<void>;
+    /**
+     * Open a real Postgres transaction. The push handler drives the returned
+     * `StorageTransaction` imperatively (getRow/upsert/…/commit), but the
+     * driver seam models a transaction as a callback scope. We bridge the two:
+     * `transaction(fn)` blocks inside `fn` on a promise that the imperative
+     * `commit()`/`rollback()` resolves/rejects, so BEGIN…COMMIT wraps exactly
+     * the handler's writes on one pinned connection.
+     */
+    begin(partition: string): Promise<StorageTransaction>;
+    getMaxCommitSeq(partition: string): Promise<number>;
+    getHorizonSeq(partition: string): Promise<number>;
+    setHorizonSeq(partition: string, seq: number): Promise<void>;
+    pruneCommitsThrough(partition: string, seq: number): Promise<number>;
+    getCommitSeqBefore(partition: string, createdBeforeMs: number): Promise<number>;
+    getRow(partition: string, table: string, rowId: string): Promise<StoredRow | undefined>;
+    getPushResult(partition: string, clientId: string, clientCommitId: string): Promise<StoredPushResult | undefined>;
+    readCommitWindow(partition: string, query: CommitWindowQuery): Promise<StoredCommit[]>;
+    scanRows(partition: string, query: RowScanQuery): Promise<StoredRow[]>;
+    getClientRecord(partition: string, clientId: string): Promise<ClientRecord | undefined>;
+    putClientRecord(partition: string, record: ClientRecord): Promise<void>;
+    listClientCursors(partition: string): Promise<ClientCursorInfo[]>;
+    listRowsReferencingBlob(partition: string, blobId: string): Promise<{
+        readonly table: string;
+        readonly rowId: string;
+        readonly scopes: Record<string, string>;
+    }[]>;
+    listReferencedBlobIds(partition: string): Promise<string[]>;
+    listClientRecords(partition: string): Promise<ClientRecord[]>;
+    listCommitMetadata(partition: string, query: CommitMetadataQuery): Promise<CommitMetadata[]>;
+    scopeActivity(partition: string, query: ScopeActivityQuery): Promise<ScopeCommitActivity[]>;
+    getRowScopes(partition: string, table: string, rowId: string): Promise<{
+        serverVersion: number;
+        scopes: Record<string, string>;
+    } | undefined>;
+}