@zvndev/powdb-client 0.7.2 → 0.8.1

package/CHANGELOG.md

@@ -1,5 +1,16 @@
 # Changelog
 
+## 0.8.0 - 2026-07-02
+
+- Released in lockstep with PowDB workspace v0.8.0 (Embedded Sync Milestone 0).
+- Added **experimental** low-level authenticated embedded-sync protocol helpers:
+  `client.syncStatus`, `client.syncPull`, and `client.syncAck`.
+- Added TypeScript wire support for the private sync status/pull/ack frames
+  (`0x20`-`0x25`), retained-unit payloads, sync repair actions, and the
+  `sync` observability event.
+- These sync helpers are experimental and beta-gated: pin matching client/server
+  versions. Plain `query(powql)` / `querySql(sql)` frames are unchanged.
+
 ## 0.5.1 - 2026-06-17
 
 - Kept the npm client release in lockstep with PowDB workspace v0.5.1.
@@ -12,6 +23,7 @@ All notable changes to `@zvndev/powdb-client`.
 
 | Client version | Compatible PowDB server | Notes |
 |---|---|---|
+| 0.8.x | Matching sync-enabled 0.8.x server | Adds experimental private authenticated embedded-sync helpers (`syncStatus`, `syncPull`, `syncAck`) over wire frames `0x20`-`0x25`. Pin matching client/server versions for these helpers until the stable `@zvndev/powdb-sync` package boundary exists; plain `query(powql)` and `querySql(sql)` frames remain unchanged. |
 | 0.5.x | 0.4.7+ | Adds `client.query(powql, params)` for `$N` parameter binding. The `QueryWithParams` (`0x04`) wire message is only understood by server ≥0.4.7; parameterized queries against an older server error out. Plain `query(powql)` calls remain compatible with 0.3.x–0.4.x. |
 | 0.4.x | 0.3.x – 0.4.x | Wire protocol v1 plus the optional Connect `username` field. **Multi-user mode requires client ≥0.4.0 AND server ≥0.4.6** (the server enforces roles as of 0.4.6; 0.4.5 accepted the username but did not enforce `readonly`). When `user` is omitted the Connect frame is byte-identical to the 0.3.x shape, so legacy shared-password and no-auth servers work unchanged. |
 | 0.3.x | 0.3.x – 0.4.x | Wire protocol v1. The client warns only on a major-version mismatch, so any `0.x` server connects. Minor server bumps may add new opcodes; the client tolerates unknown response codes by surfacing `PowDBError`. Pin both ends. **Caveat:** the 0.3.x client has no `user` option, so it cannot authenticate to a 0.4.5+ server running in **multi-user mode** (the server requires a username once any named user is defined). Shared-password mode works fine. |

package/README.md

@@ -81,6 +81,54 @@ await client.query("insert User { name := $1, age := $2 }", ["Dana", null]);
 
 `QueryParam` is `string | number | bigint | boolean | null`. The params form sends the `QueryWithParams` (0x04) wire message and **requires powdb-server >= 0.4.7**. The plain `query(q)` and `query(q, { signal })` forms are unchanged.
 
+## Experimental embedded sync protocol helpers
+
+The client exposes experimental low-level helpers for the private authenticated
+embedded-sync frames used by the in-progress replica product:
+
+```typescript
+client.on("sync", ({ operation, durationMs, ok, stale, repairAction }) => {
+  metrics.histogram("powdb_sync_ms", durationMs, {
+    operation,
+    ok: String(ok),
+    repairAction: repairAction ?? "error",
+  });
+});
+
+const status = await client.syncStatus("replica-a");
+
+if (status.repairAction === "pull" && status.lastAppliedLsn !== null) {
+  const pull = await client.syncPull({
+    replicaId: "replica-a",
+    sinceLsn: status.lastAppliedLsn,
+    maxUnits: 4096,
+    maxBytes: 16n * 1024n * 1024n,
+    databaseId: "0123456789abcdeffedcba9876543210",
+    primaryGeneration: 1n,
+    walFormatVersion: 1,
+    catalogVersion: 1,
+    segmentFormatVersion: 1,
+  });
+
+  // Apply `pull.units` with the embedded replica layer, then acknowledge.
+  const lastUnit = pull.units.at(-1);
+  if (lastUnit) {
+    await client.syncAck({
+      replicaId: "replica-a",
+      appliedLsn: lastUnit.lsn,
+      remoteLsn: pull.status.remoteLsn,
+    });
+  }
+}
+```
+
+These methods are intentionally not a complete or stable
+`@zvndev/powdb-sync` package. They expose the authenticated server
+pull/status/ack protocol so the embedded replica layer can be built and tested
+without hand-rolled frame code. Pin matching client/server versions while using
+them; the stable product boundary will be the sync package. Servers must have
+sync enabled and reject unauthenticated or `readonly` users.
+
 ## Authentication
 
 For servers using the legacy shared password (`POWDB_PASSWORD`), pass
@@ -254,6 +302,7 @@ Events:
 | Event | Payload | Fires when |
 |---|---|---|
 | `query` | `{ query, durationMs, ok, kind?, error? }` | After every query completes (success or failure) |
+| `sync` | `{ operation, replicaId, durationMs, ok, status?, stale?, repairAction?, units?, advanced?, error? }` | After every sync status/pull/ack request completes |
 | `close` | `{ error: Error \| null }` | Exactly once per socket, on normal or error close |
 
 ## Cancellation
@@ -273,11 +322,12 @@ try {
 }
 ```
 
-If you abort with a custom reason (`ctrl.abort(myError)`) and that reason is
-an `Error`, it is thrown as-is instead. Otherwise the client throws a
-`PowDBError` with `code === "aborted"`.
+A plain `ctrl.abort()` throws a `PowDBError` with `code === "aborted"`. If you
+abort with a custom `Error` reason (`ctrl.abort(myError)`), that error is thrown
+as-is; any non-`Error` reason is wrapped in a `PowDBError` (`code === "aborted"`).
 
-The socket stays open — the server's reply is silently discarded so other in-flight queries keep working.
+The socket stays open — the aborted query's reply is silently discarded when it
+arrives, and every other in-flight query still receives its own result.
 
 ## API
 
@@ -312,6 +362,19 @@ Sends a PowQL query and returns a `Promise<QueryResult>`:
 
 Throws a `PowDBError` (see Structured errors above) on any failure.
 
+### `client.querySql(query, opts?)`
+
+Runs a statement through the server's **SQL frontend** and returns a
+`Promise<QueryResult>` — the same result shape as `query()`. The plain
+`query()` method stays PowQL for wire compatibility; `querySql()` sends the
+dedicated `QuerySql` wire message. Requires server ≥0.5.0 (the SQL frontend was
+added in 0.5.0); see `docs/SQL.md` for the supported subset. `opts.signal?:
+AbortSignal` cancels the query (see Cancellation above).
+
+```typescript
+const result = await client.querySql("SELECT name, age FROM User WHERE age > 27");
+```
+
 ### `client.queryTyped(query, schema, opts?)`
 
 Like `query()`, but coerces each row's string values to JS types using the

package/dist/index.d.ts

@@ -16,9 +16,10 @@
  */
 import * as tls from "node:tls";
 import { EventEmitter } from "node:events";
+import { type SyncRepairAction, type WireRetainedUnit, type WireSyncStatus } from "./protocol.js";
 import { type TypedRow, type TypedSchema } from "./typed.js";
 /** Client library version. Compared to the server's reported version. */
-export declare const CLIENT_VERSION = "0.7.2";
+export declare const CLIENT_VERSION = "0.8.1";
 export type QueryResult = {
     kind: "rows";
     columns: string[];
@@ -42,6 +43,41 @@ export type QueryResult = {
  * binds as an int; `null` binds PowQL `null`.
  */
 export type QueryParam = string | number | bigint | boolean | null;
+/** Unsigned 64-bit sync protocol value. Numbers must be safe non-negative integers. */
+export type SyncU64 = bigint | number;
+/**
+ * Database identity carried by the sync protocol. Strings are the 32-hex-char
+ * form stored in `.powdb-sync/identity.json`; byte arrays must be exactly 16B.
+ */
+export type SyncDatabaseId = string | Uint8Array;
+export interface SyncPullRequest {
+    replicaId: string;
+    sinceLsn: SyncU64;
+    maxUnits: number;
+    maxBytes: SyncU64;
+    databaseId: SyncDatabaseId;
+    primaryGeneration: SyncU64;
+    walFormatVersion: number;
+    catalogVersion: number;
+    segmentFormatVersion: number;
+}
+export interface SyncAckRequest {
+    replicaId: string;
+    appliedLsn: SyncU64;
+    remoteLsn: SyncU64;
+}
+export interface SyncPullResult {
+    status: WireSyncStatus;
+    units: WireRetainedUnit[];
+    hasMore: boolean;
+}
+export interface SyncAckResult {
+    previousAppliedLsn: bigint;
+    appliedLsn: bigint;
+    remoteLsn: bigint;
+    advanced: boolean;
+    status: WireSyncStatus;
+}
 export interface ClientOptions {
     /** TCP host. Required unless `path` (a Unix domain socket) is given. */
     host?: string;
@@ -93,6 +129,20 @@ export interface ClientEvents {
             error?: Error;
         }
     ];
+    sync: [
+        {
+            operation: "status" | "pull" | "ack";
+            replicaId: string;
+            durationMs: number;
+            ok: boolean;
+            status?: WireSyncStatus;
+            stale?: boolean;
+            repairAction?: SyncRepairAction;
+            units?: number;
+            advanced?: boolean;
+            error?: Error;
+        }
+    ];
     close: [{
         error: Error | null;
     }];
@@ -130,6 +180,30 @@ export declare class Client extends EventEmitter<ClientEvents> {
     querySql(query: string, opts?: {
         signal?: AbortSignal;
     }): Promise<QueryResult>;
+    /**
+     * Fetch primary-side sync status for one embedded replica cursor.
+     *
+     * This speaks the private authenticated sync frame added for the embedded
+     * replica product. Servers without sync support return a protocol/query
+     * error; unauthenticated or readonly users are rejected server-side.
+     */
+    syncStatus(replicaId: string, opts?: {
+        signal?: AbortSignal;
+    }): Promise<WireSyncStatus>;
+    /**
+     * Pull a bounded retained-unit chunk after this replica's primary-side cursor.
+     *
+     * The caller supplies the database identity and format versions from the
+     * sync bootstrap metadata. The server rejects mismatches and non-applyable
+     * transaction cuts instead of returning ambiguous history.
+     */
+    syncPull(request: SyncPullRequest, opts?: {
+        signal?: AbortSignal;
+    }): Promise<SyncPullResult>;
+    /** Acknowledge that the replica applied retained history through `appliedLsn`. */
+    syncAck(request: SyncAckRequest, opts?: {
+        signal?: AbortSignal;
+    }): Promise<SyncAckResult>;
     /**
      * Like {@link query}, but coerces string result columns to typed JS values
      * using the caller-supplied schema. See `./typed.ts` for the coercion
@@ -175,8 +249,8 @@ export declare class Client extends EventEmitter<ClientEvents> {
     private onClose;
 }
 export { encode, tryDecode } from "./protocol.js";
-export type { Message, WireParam } from "./protocol.js";
-export { MAX_PAYLOAD_SIZE, MAX_ROWS, MAX_COLUMNS, MAX_PARAMS, } from "./protocol.js";
+export type { Message, SyncRepairAction, WireParam, WireRetainedUnit, WireSyncStatus, } from "./protocol.js";
+export { MAX_PAYLOAD_SIZE, MAX_ROWS, MAX_COLUMNS, MAX_PARAMS, MAX_SYNC_UNITS, MAX_SYNC_PULL_UNITS, MAX_SYNC_PULL_BYTES, } from "./protocol.js";
 export { escapeLiteral, escapeIdent, ident, powql, PowqlIdent, } from "./escape.js";
 export { Pool } from "./pool.js";
 export type { PoolOptions } from "./pool.js";

package/dist/index.js

@@ -17,11 +17,11 @@
 import * as net from "node:net";
 import * as tls from "node:tls";
 import { EventEmitter } from "node:events";
-import { encode, tryDecode, } from "./protocol.js";
+import { encode, tryDecode, MAX_SYNC_PULL_BYTES, MAX_SYNC_PULL_UNITS, } from "./protocol.js";
 import { PowDBError } from "./errors.js";
 import { coerceRows, } from "./typed.js";
 /** Client library version. Compared to the server's reported version. */
-export const CLIENT_VERSION = "0.7.2";
+export const CLIENT_VERSION = "0.8.1";
 function socketChunkToBuffer(chunk) {
     return typeof chunk === "string" ? Buffer.from(chunk) : chunk;
 }
@@ -44,6 +44,52 @@ function toWireParam(p) {
             throw new PowDBError(`unsupported query parameter type: ${typeof p}`, "protocol_error");
     }
 }
+function toU64(value, label) {
+    if (typeof value === "bigint") {
+        if (value < 0n || value > 0xffffffffffffffffn) {
+            throw new PowDBError(`${label} must fit in u64`, "protocol_error");
+        }
+        return value;
+    }
+    if (!Number.isSafeInteger(value) || value < 0) {
+        throw new PowDBError(`${label} must be a safe non-negative integer or bigint`, "protocol_error");
+    }
+    return BigInt(value);
+}
+function toU16(value, label) {
+    if (!Number.isInteger(value) || value < 0 || value > 0xffff) {
+        throw new PowDBError(`${label} must fit in u16`, "protocol_error");
+    }
+    return value;
+}
+function toSyncMaxUnits(value) {
+    if (!Number.isInteger(value) ||
+        value < 1 ||
+        value > MAX_SYNC_PULL_UNITS) {
+        throw new PowDBError(`maxUnits must be between 1 and ${MAX_SYNC_PULL_UNITS}`, "protocol_error");
+    }
+    return value;
+}
+function toSyncMaxBytes(value) {
+    const bytes = toU64(value, "maxBytes");
+    if (bytes < 1n || bytes > BigInt(MAX_SYNC_PULL_BYTES)) {
+        throw new PowDBError(`maxBytes must be between 1 and ${MAX_SYNC_PULL_BYTES}`, "protocol_error");
+    }
+    return bytes;
+}
+function toDatabaseId(value) {
+    if (typeof value === "string") {
+        if (!/^[0-9a-fA-F]{32}$/.test(value)) {
+            throw new PowDBError("databaseId string must be exactly 32 hex characters", "protocol_error");
+        }
+        return Buffer.from(value, "hex");
+    }
+    const bytes = Buffer.from(value);
+    if (bytes.length !== 16) {
+        throw new PowDBError(`databaseId must be exactly 16 bytes, got ${bytes.length}`, "protocol_error");
+    }
+    return bytes;
+}
 /** Module-level set of host:port pairs we've already warned about. */
 const versionWarnings = new Set();
 /** Extract the major component of a dotted version string, e.g. "0.2.0" → "0". */
@@ -52,16 +98,19 @@ function majorOf(version) {
     return dot === -1 ? version : version.slice(0, dot);
 }
 /**
- * Build an AbortError. Prefers the caller-supplied `signal.reason` if it is
- * itself an `Error` (matches DOM semantics); otherwise wraps it in a
- * `PowDBError` with code `"aborted"` so catch-blocks can branch uniformly.
+ * Build an AbortError. A caller-supplied custom `Error` reason
+ * (`ctrl.abort(myError)`) passes through as-is to match DOM semantics. The
+ * default abort reason — Node's `DOMException` named `"AbortError"` — and any
+ * non-Error reason are wrapped in a `PowDBError` with code `"aborted"` so the
+ * common `ctrl.abort()` case branches uniformly on `err.code === "aborted"`.
  */
 function abortError(signal) {
     if (signal && signal.reason !== undefined) {
         const r = signal.reason;
-        if (r instanceof Error)
+        const isDefaultAbort = r instanceof DOMException && r.name === "AbortError";
+        if (r instanceof Error && !isDefaultAbort)
             return r;
-        return new PowDBError(String(r), "aborted");
+        return new PowDBError(isDefaultAbort ? "query was aborted" : String(r), "aborted");
     }
     return new PowDBError("query was aborted", "aborted");
 }
@@ -267,6 +316,145 @@ export class Client extends EventEmitter {
             throw err;
         }
     }
+    /**
+     * Fetch primary-side sync status for one embedded replica cursor.
+     *
+     * This speaks the private authenticated sync frame added for the embedded
+     * replica product. Servers without sync support return a protocol/query
+     * error; unauthenticated or readonly users are rejected server-side.
+     */
+    async syncStatus(replicaId, opts) {
+        const start = Date.now();
+        try {
+            const reply = await this.send({ type: "SyncStatus", replicaId }, opts);
+            if (reply.type === "Error") {
+                throw new PowDBError(`sync status failed: ${reply.message}`, "query_failed");
+            }
+            if (reply.type !== "SyncStatusResult") {
+                throw new PowDBError(`unexpected reply: ${reply.type}`, "protocol_error");
+            }
+            this.emit("sync", {
+                operation: "status",
+                replicaId,
+                durationMs: Date.now() - start,
+                ok: true,
+                status: reply.status,
+                stale: reply.status.stale,
+                repairAction: reply.status.repairAction,
+            });
+            return reply.status;
+        }
+        catch (err) {
+            this.emit("sync", {
+                operation: "status",
+                replicaId,
+                durationMs: Date.now() - start,
+                ok: false,
+                error: err,
+            });
+            throw err;
+        }
+    }
+    /**
+     * Pull a bounded retained-unit chunk after this replica's primary-side cursor.
+     *
+     * The caller supplies the database identity and format versions from the
+     * sync bootstrap metadata. The server rejects mismatches and non-applyable
+     * transaction cuts instead of returning ambiguous history.
+     */
+    async syncPull(request, opts) {
+        const start = Date.now();
+        try {
+            const reply = await this.send({
+                type: "SyncPull",
+                replicaId: request.replicaId,
+                sinceLsn: toU64(request.sinceLsn, "sinceLsn"),
+                maxUnits: toSyncMaxUnits(request.maxUnits),
+                maxBytes: toSyncMaxBytes(request.maxBytes),
+                databaseId: toDatabaseId(request.databaseId),
+                primaryGeneration: toU64(request.primaryGeneration, "primaryGeneration"),
+                walFormatVersion: toU16(request.walFormatVersion, "walFormatVersion"),
+                catalogVersion: toU16(request.catalogVersion, "catalogVersion"),
+                segmentFormatVersion: toU16(request.segmentFormatVersion, "segmentFormatVersion"),
+            }, opts);
+            if (reply.type === "Error") {
+                throw new PowDBError(`sync pull failed: ${reply.message}`, "query_failed");
+            }
+            if (reply.type !== "SyncPullResult") {
+                throw new PowDBError(`unexpected reply: ${reply.type}`, "protocol_error");
+            }
+            this.emit("sync", {
+                operation: "pull",
+                replicaId: request.replicaId,
+                durationMs: Date.now() - start,
+                ok: true,
+                status: reply.status,
+                stale: reply.status.stale,
+                repairAction: reply.status.repairAction,
+                units: reply.units.length,
+            });
+            return {
+                status: reply.status,
+                units: reply.units,
+                hasMore: reply.hasMore,
+            };
+        }
+        catch (err) {
+            this.emit("sync", {
+                operation: "pull",
+                replicaId: request.replicaId,
+                durationMs: Date.now() - start,
+                ok: false,
+                error: err,
+            });
+            throw err;
+        }
+    }
+    /** Acknowledge that the replica applied retained history through `appliedLsn`. */
+    async syncAck(request, opts) {
+        const start = Date.now();
+        try {
+            const reply = await this.send({
+                type: "SyncAck",
+                replicaId: request.replicaId,
+                appliedLsn: toU64(request.appliedLsn, "appliedLsn"),
+                remoteLsn: toU64(request.remoteLsn, "remoteLsn"),
+            }, opts);
+            if (reply.type === "Error") {
+                throw new PowDBError(`sync ack failed: ${reply.message}`, "query_failed");
+            }
+            if (reply.type !== "SyncAckResult") {
+                throw new PowDBError(`unexpected reply: ${reply.type}`, "protocol_error");
+            }
+            this.emit("sync", {
+                operation: "ack",
+                replicaId: request.replicaId,
+                durationMs: Date.now() - start,
+                ok: true,
+                status: reply.status,
+                stale: reply.status.stale,
+                repairAction: reply.status.repairAction,
+                advanced: reply.advanced,
+            });
+            return {
+                previousAppliedLsn: reply.previousAppliedLsn,
+                appliedLsn: reply.appliedLsn,
+                remoteLsn: reply.remoteLsn,
+                advanced: reply.advanced,
+                status: reply.status,
+            };
+        }
+        catch (err) {
+            this.emit("sync", {
+                operation: "ack",
+                replicaId: request.replicaId,
+                durationMs: Date.now() - start,
+                ok: false,
+                error: err,
+            });
+            throw err;
+        }
+    }
     /**
      * Like {@link query}, but coerces string result columns to typed JS values
      * using the caller-supplied schema. See `./typed.ts` for the coercion
@@ -342,8 +530,17 @@ export class Client extends EventEmitter {
      * timeout so an unresponsive peer cannot make `close()` hang forever.
      */
     async close() {
-        if (this.closed)
+        if (this.closed) {
+            // Already torn down (e.g. an error in onData/onClose closed the client
+            // without destroying the socket). Ensure the socket is released so a
+            // post-teardown close() resolves instead of keeping the event loop
+            // alive. `writableEnded` distinguishes that case from a concurrent
+            // close() mid-graceful-shutdown, which must not be force-destroyed.
+            if (!this.socket.destroyed && !this.socket.writableEnded) {
+                this.socket.destroy();
+            }
             return;
+        }
         try {
             this.socket.write(encode({ type: "Disconnect" }));
         }
@@ -497,19 +694,18 @@ export class Client extends EventEmitter {
                 this.socket.write(encode({ type: "Pong" }));
                 continue;
             }
-            // Find the next non-settled pending entry and hand it the reply.
-            // Settled entries at the head were aborted by the caller but their
-            // reply is arriving now — drop it silently.
-            let entry = this.pending.shift();
-            while (entry && entry.settled) {
-                entry = this.pending.shift();
-            }
-            if (!entry) {
-                // Server sent an unsolicited frame (or we got extra after aborts
-                // with no replacement). Treat as protocol error.
+            // Replies are strictly FIFO: this frame belongs to exactly one pending
+            // entry — the head. Consume one entry per frame. If it was aborted
+            // (settled), its reply is arriving now; drop the frame and keep decoding
+            // rather than delivering it to a later, live query.
+            const entry = this.pending.shift();
+            if (entry === undefined) {
+                // No pending entry at all — the server sent an unsolicited frame.
                 this.onClose(new PowDBError("received unexpected frame from server", "protocol_error"));
                 return;
             }
+            if (entry.settled)
+                continue;
             entry.resolve(decoded.msg);
         }
     }
@@ -605,7 +801,7 @@ function openSocket(target, timeoutMs, tlsOpt) {
     });
 }
 export { encode, tryDecode } from "./protocol.js";
-export { MAX_PAYLOAD_SIZE, MAX_ROWS, MAX_COLUMNS, MAX_PARAMS, } from "./protocol.js";
+export { MAX_PAYLOAD_SIZE, MAX_ROWS, MAX_COLUMNS, MAX_PARAMS, MAX_SYNC_UNITS, MAX_SYNC_PULL_UNITS, MAX_SYNC_PULL_BYTES, } from "./protocol.js";
 export { escapeLiteral, escapeIdent, ident, powql, PowqlIdent, } from "./escape.js";
 export { Pool } from "./pool.js";
 export { PowDBError, isPowDBError } from "./errors.js";

package/dist/protocol.d.ts

@@ -17,6 +17,13 @@ export declare const MSG_QUERY = 3;
 export declare const MSG_QUERY_PARAMS = 4;
 /** SQL query frame. Plain Query remains PowQL for backward compatibility. */
 export declare const MSG_QUERY_SQL = 5;
+/** Private embedded-sync control frames. Requires authenticated server support. */
+export declare const MSG_SYNC_STATUS = 32;
+export declare const MSG_SYNC_PULL = 33;
+export declare const MSG_SYNC_ACK = 34;
+export declare const MSG_SYNC_STATUS_RESULT = 35;
+export declare const MSG_SYNC_PULL_RESULT = 36;
+export declare const MSG_SYNC_ACK_RESULT = 37;
 export declare const MSG_RESULT_ROWS = 7;
 export declare const MSG_RESULT_SCALAR = 8;
 export declare const MSG_RESULT_OK = 9;
@@ -33,6 +40,12 @@ export declare const MAX_ROWS = 10000000;
 export declare const MAX_COLUMNS = 4096;
 /** Maximum number of bound parameters in a QueryWithParams message. */
 export declare const MAX_PARAMS = 4096;
+/** Maximum retained units accepted in one sync pull result. */
+export declare const MAX_SYNC_UNITS = 4096;
+/** Maximum retained units accepted by the server for one sync pull request. */
+export declare const MAX_SYNC_PULL_UNITS = 4096;
+/** Maximum retained-unit payload budget accepted by the server for one sync pull. */
+export declare const MAX_SYNC_PULL_BYTES: number;
 /**
  * A positional parameter value for {@link MSG_QUERY_PARAMS}. Wire encoding
  * per param: a 1-byte tag followed by the body —
@@ -57,6 +70,27 @@ export type WireParam = {
     tag: "str";
     value: string;
 };
+export type SyncRepairAction = "none" | "pull" | "awaitArchive" | "rebootstrap";
+export interface WireSyncStatus {
+    replicaId: string;
+    active: boolean;
+    lastAppliedLsn: bigint | null;
+    remoteLsn: bigint;
+    servableLsn: bigint | null;
+    unarchivedLsn: bigint | null;
+    lagLsn: bigint | null;
+    lagBytes: bigint | null;
+    lagMs: bigint | null;
+    stale: boolean;
+    repairAction: SyncRepairAction;
+    lastSyncError: string | null;
+}
+export interface WireRetainedUnit {
+    txId: bigint;
+    recordType: number;
+    lsn: bigint;
+    data: Buffer;
+}
 export type Message = {
     type: "Connect";
     dbName: string;
@@ -82,6 +116,40 @@ export type Message = {
     type: "QueryWithParams";
     query: string;
     params: WireParam[];
+} | {
+    type: "SyncStatus";
+    replicaId: string;
+} | {
+    type: "SyncPull";
+    replicaId: string;
+    sinceLsn: bigint;
+    maxUnits: number;
+    maxBytes: bigint;
+    databaseId: Buffer;
+    primaryGeneration: bigint;
+    walFormatVersion: number;
+    catalogVersion: number;
+    segmentFormatVersion: number;
+} | {
+    type: "SyncAck";
+    replicaId: string;
+    appliedLsn: bigint;
+    remoteLsn: bigint;
+} | {
+    type: "SyncStatusResult";
+    status: WireSyncStatus;
+} | {
+    type: "SyncPullResult";
+    status: WireSyncStatus;
+    units: WireRetainedUnit[];
+    hasMore: boolean;
+} | {
+    type: "SyncAckResult";
+    previousAppliedLsn: bigint;
+    appliedLsn: bigint;
+    remoteLsn: bigint;
+    advanced: boolean;
+    status: WireSyncStatus;
 } | {
     type: "ResultRows";
     columns: string[];

package/dist/protocol.js

@@ -17,6 +17,13 @@ export const MSG_QUERY = 0x03;
 export const MSG_QUERY_PARAMS = 0x04;
 /** SQL query frame. Plain Query remains PowQL for backward compatibility. */
 export const MSG_QUERY_SQL = 0x05;
+/** Private embedded-sync control frames. Requires authenticated server support. */
+export const MSG_SYNC_STATUS = 0x20;
+export const MSG_SYNC_PULL = 0x21;
+export const MSG_SYNC_ACK = 0x22;
+export const MSG_SYNC_STATUS_RESULT = 0x23;
+export const MSG_SYNC_PULL_RESULT = 0x24;
+export const MSG_SYNC_ACK_RESULT = 0x25;
 export const MSG_RESULT_ROWS = 0x07;
 export const MSG_RESULT_SCALAR = 0x08;
 export const MSG_RESULT_OK = 0x09;
@@ -34,6 +41,12 @@ export const MAX_ROWS = 10_000_000;
 export const MAX_COLUMNS = 4096;
 /** Maximum number of bound parameters in a QueryWithParams message. */
 export const MAX_PARAMS = 4096;
+/** Maximum retained units accepted in one sync pull result. */
+export const MAX_SYNC_UNITS = 4096;
+/** Maximum retained units accepted by the server for one sync pull request. */
+export const MAX_SYNC_PULL_UNITS = 4096;
+/** Maximum retained-unit payload budget accepted by the server for one sync pull. */
+export const MAX_SYNC_PULL_BYTES = 16 * 1024 * 1024;
 // ───── Encoding ────────────────────────────────────────────────────────────
 export function encode(msg) {
     let msgType;
@@ -102,6 +115,63 @@ export function encode(msg) {
             msgType = MSG_QUERY_PARAMS;
             break;
         }
+        case "SyncStatus":
+            payload = encodeString(msg.replicaId);
+            msgType = MSG_SYNC_STATUS;
+            break;
+        case "SyncPull": {
+            if (msg.databaseId.length !== 16) {
+                throw new Error(`sync databaseId must be exactly 16 bytes, got ${msg.databaseId.length}`);
+            }
+            payload = Buffer.concat([
+                encodeString(msg.replicaId),
+                u64LE(msg.sinceLsn),
+                u32LE(msg.maxUnits),
+                u64LE(msg.maxBytes),
+                msg.databaseId,
+                u64LE(msg.primaryGeneration),
+                u16LE(msg.walFormatVersion),
+                u16LE(msg.catalogVersion),
+                u16LE(msg.segmentFormatVersion),
+            ]);
+            msgType = MSG_SYNC_PULL;
+            break;
+        }
+        case "SyncAck":
+            payload = Buffer.concat([
+                encodeString(msg.replicaId),
+                u64LE(msg.appliedLsn),
+                u64LE(msg.remoteLsn),
+            ]);
+            msgType = MSG_SYNC_ACK;
+            break;
+        case "SyncStatusResult":
+            payload = encodeSyncStatus(msg.status);
+            msgType = MSG_SYNC_STATUS_RESULT;
+            break;
+        case "SyncPullResult": {
+            const parts = [
+                encodeSyncStatus(msg.status),
+                u32LE(msg.units.length),
+            ];
+            for (const unit of msg.units) {
+                parts.push(encodeRetainedUnit(unit));
+            }
+            parts.push(Buffer.from([msg.hasMore ? 1 : 0]));
+            payload = Buffer.concat(parts);
+            msgType = MSG_SYNC_PULL_RESULT;
+            break;
+        }
+        case "SyncAckResult":
+            payload = Buffer.concat([
+                u64LE(msg.previousAppliedLsn),
+                u64LE(msg.appliedLsn),
+                u64LE(msg.remoteLsn),
+                Buffer.from([msg.advanced ? 1 : 0]),
+                encodeSyncStatus(msg.status),
+            ]);
+            msgType = MSG_SYNC_ACK_RESULT;
+            break;
         case "ResultRows": {
             const parts = [];
             const colCount = Buffer.alloc(2);
@@ -235,6 +305,70 @@ function decodePayload(msgType, payload) {
             }
             return { type: "QueryWithParams", query, params };
         }
+        case MSG_SYNC_STATUS:
+            return { type: "SyncStatus", replicaId: decodeString(payload, cursor) };
+        case MSG_SYNC_PULL: {
+            const replicaId = decodeString(payload, cursor);
+            const sinceLsn = readU64(payload, cursor, "sync pull since LSN");
+            const maxUnits = readU32(payload, cursor, "sync pull max units");
+            const maxBytes = readU64(payload, cursor, "sync pull max bytes");
+            const databaseId = readFixedBytes(payload, cursor, 16, "sync database id");
+            const primaryGeneration = readU64(payload, cursor, "sync primary generation");
+            const walFormatVersion = readU16(payload, cursor, "sync WAL format version");
+            const catalogVersion = readU16(payload, cursor, "sync catalog version");
+            const segmentFormatVersion = readU16(payload, cursor, "sync segment format version");
+            return {
+                type: "SyncPull",
+                replicaId,
+                sinceLsn,
+                maxUnits,
+                maxBytes,
+                databaseId,
+                primaryGeneration,
+                walFormatVersion,
+                catalogVersion,
+                segmentFormatVersion,
+            };
+        }
+        case MSG_SYNC_ACK: {
+            const replicaId = decodeString(payload, cursor);
+            const appliedLsn = readU64(payload, cursor, "sync ack applied LSN");
+            const remoteLsn = readU64(payload, cursor, "sync ack remote LSN");
+            return { type: "SyncAck", replicaId, appliedLsn, remoteLsn };
+        }
+        case MSG_SYNC_STATUS_RESULT:
+            return {
+                type: "SyncStatusResult",
+                status: decodeSyncStatus(payload, cursor),
+            };
+        case MSG_SYNC_PULL_RESULT: {
+            const status = decodeSyncStatus(payload, cursor);
+            const count = readU32(payload, cursor, "sync retained unit count");
+            if (count > MAX_SYNC_UNITS) {
+                throw new Error(`too many retained units: ${count} (max ${MAX_SYNC_UNITS})`);
+            }
+            const units = [];
+            for (let i = 0; i < count; i++) {
+                units.push(decodeRetainedUnit(payload, cursor));
+            }
+            const hasMore = readBool(payload, cursor, "sync has_more");
+            return { type: "SyncPullResult", status, units, hasMore };
+        }
+        case MSG_SYNC_ACK_RESULT: {
+            const previousAppliedLsn = readU64(payload, cursor, "previous applied LSN");
+            const appliedLsn = readU64(payload, cursor, "applied LSN");
+            const remoteLsn = readU64(payload, cursor, "remote LSN");
+            const advanced = readBool(payload, cursor, "sync ack advanced");
+            const status = decodeSyncStatus(payload, cursor);
+            return {
+                type: "SyncAckResult",
+                previousAppliedLsn,
+                appliedLsn,
+                remoteLsn,
+                advanced,
+                status,
+            };
+        }
         case MSG_RESULT_ROWS: {
             const colCount = readU16(payload, cursor, "column count");
             if (colCount > MAX_COLUMNS) {
@@ -248,6 +382,14 @@ function decodePayload(msgType, payload) {
             if (rowCount > MAX_ROWS) {
                 throw new Error(`too many rows: ${rowCount} (max ${MAX_ROWS})`);
             }
+            if (colCount === 0 && rowCount > 0) {
+                throw new Error("nonzero row count with zero columns");
+            }
+            const remaining = BigInt(payload.length - cursor.pos);
+            const minRowBytes = BigInt(rowCount) * BigInt(colCount) * 4n;
+            if (remaining < minRowBytes) {
+                throw new Error(`row data too short for declared shape: ${rowCount} rows x ${colCount} columns`);
+            }
             const rows = [];
             for (let r = 0; r < rowCount; r++) {
                 const row = [];
@@ -278,6 +420,112 @@ function decodePayload(msgType, payload) {
             throw new Error(`unknown message type: 0x${msgType.toString(16)}`);
     }
 }
+function encodeSyncStatus(status) {
+    return Buffer.concat([
+        encodeString(status.replicaId),
+        Buffer.from([status.active ? 1 : 0]),
+        encodeOptionalU64(status.lastAppliedLsn),
+        u64LE(status.remoteLsn),
+        encodeOptionalU64(status.servableLsn),
+        encodeOptionalU64(status.unarchivedLsn),
+        encodeOptionalU64(status.lagLsn),
+        encodeOptionalU64(status.lagBytes),
+        encodeOptionalU64(status.lagMs),
+        Buffer.from([
+            status.stale ? 1 : 0,
+            encodeRepairAction(status.repairAction),
+        ]),
+        encodeOptionalString(status.lastSyncError),
+    ]);
+}
+function decodeSyncStatus(buf, cursor) {
+    const replicaId = decodeString(buf, cursor);
+    const active = readBool(buf, cursor, "sync status active");
+    const lastAppliedLsn = readOptionalU64(buf, cursor, "sync status last applied LSN");
+    const remoteLsn = readU64(buf, cursor, "sync status remote LSN");
+    const servableLsn = readOptionalU64(buf, cursor, "sync status servable LSN");
+    const unarchivedLsn = readOptionalU64(buf, cursor, "sync status unarchived LSN");
+    const lagLsn = readOptionalU64(buf, cursor, "sync status lag LSN");
+    const lagBytes = readOptionalU64(buf, cursor, "sync status lag bytes");
+    const lagMs = readOptionalU64(buf, cursor, "sync status lag milliseconds");
+    const stale = readBool(buf, cursor, "sync status stale");
+    const repairAction = decodeRepairAction(readU8(buf, cursor, "sync repair action"));
+    const lastSyncError = readOptionalString(buf, cursor, "sync status last error");
+    return {
+        replicaId,
+        active,
+        lastAppliedLsn,
+        remoteLsn,
+        servableLsn,
+        unarchivedLsn,
+        lagLsn,
+        lagBytes,
+        lagMs,
+        stale,
+        repairAction,
+        lastSyncError,
+    };
+}
+function encodeRetainedUnit(unit) {
+    return Buffer.concat([
+        u64LE(unit.txId),
+        Buffer.from([u8(unit.recordType, "sync retained unit record type")]),
+        u64LE(unit.lsn),
+        encodeBytes(unit.data),
+    ]);
+}
+function decodeRetainedUnit(buf, cursor) {
+    const txId = readU64(buf, cursor, "sync retained unit tx id");
+    const recordType = readU8(buf, cursor, "sync retained unit record type");
+    const lsn = readU64(buf, cursor, "sync retained unit LSN");
+    const data = readBytes(buf, cursor, "sync retained unit payload");
+    return { txId, recordType, lsn, data };
+}
+function encodeRepairAction(action) {
+    switch (action) {
+        case "none":
+            return 0;
+        case "pull":
+            return 1;
+        case "awaitArchive":
+            return 2;
+        case "rebootstrap":
+            return 3;
+    }
+}
+function decodeRepairAction(raw) {
+    switch (raw) {
+        case 0:
+            return "none";
+        case 1:
+            return "pull";
+        case 2:
+            return "awaitArchive";
+        case 3:
+            return "rebootstrap";
+        default:
+            throw new Error(`unknown sync repair action: ${raw}`);
+    }
+}
+function encodeOptionalU64(value) {
+    return value === null
+        ? Buffer.from([0])
+        : Buffer.concat([Buffer.from([1]), u64LE(value)]);
+}
+function readOptionalU64(buf, cursor, label) {
+    return readBool(buf, cursor, label) ? readU64(buf, cursor, label) : null;
+}
+function encodeOptionalString(value) {
+    return value === null
+        ? Buffer.from([0])
+        : Buffer.concat([Buffer.from([1]), encodeString(value)]);
+}
+function readOptionalString(buf, cursor, label) {
+    return readBool(buf, cursor, label) ? decodeString(buf, cursor) : null;
+}
+function encodeBytes(bytes) {
+    return Buffer.concat([u32LE(bytes.length), bytes]);
+}
 // ───── String helpers ──────────────────────────────────────────────────────
 function encodeString(s) {
     const bytes = Buffer.from(s, "utf8");
@@ -306,6 +554,14 @@ function readU8(buf, cursor, label) {
     cursor.pos += 1;
     return value;
 }
+function readBool(buf, cursor, label) {
+    const raw = readU8(buf, cursor, label);
+    if (raw === 0)
+        return false;
+    if (raw === 1)
+        return true;
+    throw new Error(`invalid boolean for ${label}: ${raw}`);
+}
 function readI64(buf, cursor, label) {
     if (cursor.pos + 8 > buf.length) {
         throw new Error(`truncated ${label}`);
@@ -346,8 +602,39 @@ function readU64(buf, cursor, label) {
     cursor.pos += 8;
     return value;
 }
+function readFixedBytes(buf, cursor, len, label) {
+    if (cursor.pos + len > buf.length) {
+        throw new Error(`truncated ${label}`);
+    }
+    const value = Buffer.from(buf.subarray(cursor.pos, cursor.pos + len));
+    cursor.pos += len;
+    return value;
+}
+function readBytes(buf, cursor, label) {
+    const len = readU32(buf, cursor, label);
+    return readFixedBytes(buf, cursor, len, label);
+}
+function u16LE(n) {
+    const b = Buffer.alloc(2);
+    b.writeUInt16LE(n, 0);
+    return b;
+}
+function u8(n, label) {
+    if (!Number.isInteger(n) || n < 0 || n > 0xff) {
+        throw new Error(`${label} must fit in u8`);
+    }
+    return n;
+}
 function u32LE(n) {
     const b = Buffer.alloc(4);
     b.writeUInt32LE(n, 0);
     return b;
 }
+function u64LE(n) {
+    if (n < 0n || n > 0xffffffffffffffffn) {
+        throw new Error(`u64 value out of range: ${n}`);
+    }
+    const b = Buffer.alloc(8);
+    b.writeBigUInt64LE(n, 0);
+    return b;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zvndev/powdb-client",
-  "version": "0.7.2",
+  "version": "0.8.1",
   "description": "TypeScript client for PowDB (PowQL wire protocol)",
   "type": "module",
   "packageManager": "pnpm@10.29.3",
@@ -51,6 +51,7 @@
     "test": "tsx test/run-with-server.ts test/client.test.ts",
     "test:escape": "tsx test/escape.test.ts",
     "test:protocol": "tsx test/protocol.test.ts",
+    "test:sync-live": "tsx test/sync-live.test.ts",
     "test:auth": "tsx test/auth.test.ts",
     "test:pool": "tsx test/run-with-server.ts test/pool.test.ts",
     "test:typed": "tsx test/typed.test.ts",
@@ -60,7 +61,7 @@
     "prepublishOnly": "npm run build"
   },
   "devDependencies": {
-    "@types/node": "^25",
+    "@types/node": "^26",
     "tsx": "^4",
     "typescript": "^6.0"
   }