@zvndev/powdb-client 0.12.0 → 0.14.0

package/dist/cjs/protocol.js

@@ -8,7 +8,7 @@
  * This mirrors crates/server/src/protocol.rs — keep them in sync.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.MAX_SYNC_PULL_BYTES = exports.MAX_SYNC_PULL_UNITS = exports.MAX_SYNC_UNITS = exports.MAX_PARAMS = exports.MAX_COLUMNS = exports.MAX_ROWS = exports.MAX_PAYLOAD_SIZE = exports.MSG_PONG = exports.MSG_PING = exports.MSG_DISCONNECT = exports.MSG_RESULT_MSG = exports.MSG_ERROR = exports.MSG_RESULT_OK = exports.MSG_RESULT_SCALAR = exports.MSG_RESULT_ROWS = exports.MSG_SYNC_ACK_RESULT = exports.MSG_SYNC_PULL_RESULT = exports.MSG_SYNC_STATUS_RESULT = exports.MSG_SYNC_ACK = exports.MSG_SYNC_PULL = exports.MSG_SYNC_STATUS = exports.MSG_QUERY_SQL = exports.MSG_QUERY_PARAMS = exports.MSG_QUERY = exports.MSG_CONNECT_OK = exports.MSG_CONNECT = void 0;
+exports.MAX_SYNC_PULL_BYTES = exports.MAX_SYNC_PULL_UNITS = exports.MAX_SYNC_UNITS = exports.MAX_PARAMS = exports.MAX_COLUMNS = exports.MAX_ROWS = exports.MAX_PAYLOAD_SIZE = exports.MSG_RESULT_SCALAR_NATIVE = exports.MSG_RESULT_ROWS_NATIVE = exports.MSG_QUERY_SQL_NATIVE = exports.MSG_QUERY_PARAMS_NATIVE = exports.MSG_QUERY_NATIVE = exports.MSG_PONG = exports.MSG_PING = exports.MSG_DISCONNECT = exports.MSG_RESULT_MSG = exports.MSG_ERROR = exports.MSG_RESULT_OK = exports.MSG_RESULT_SCALAR = exports.MSG_RESULT_ROWS = exports.MSG_SYNC_ACK_RESULT = exports.MSG_SYNC_PULL_RESULT = exports.MSG_SYNC_STATUS_RESULT = exports.MSG_SYNC_ACK = exports.MSG_SYNC_PULL = exports.MSG_SYNC_STATUS = exports.MSG_QUERY_SQL = exports.MSG_QUERY_PARAMS = exports.MSG_QUERY = exports.MSG_CONNECT_OK = exports.MSG_CONNECT = void 0;
 exports.encode = encode;
 exports.tryDecode = tryDecode;
 exports.MSG_CONNECT = 0x01;
@@ -37,6 +37,11 @@ exports.MSG_RESULT_MSG = 0x0b;
 exports.MSG_DISCONNECT = 0x10;
 exports.MSG_PING = 0x11;
 exports.MSG_PONG = 0x12;
+exports.MSG_QUERY_NATIVE = 0x13;
+exports.MSG_QUERY_PARAMS_NATIVE = 0x14;
+exports.MSG_QUERY_SQL_NATIVE = 0x15;
+exports.MSG_RESULT_ROWS_NATIVE = 0x16;
+exports.MSG_RESULT_SCALAR_NATIVE = 0x17;
 // ───── Size limits (mirror crates/server/src/protocol.rs) ──────────────────
 /** Maximum payload size accepted from the wire (64 MB). */
 exports.MAX_PAYLOAD_SIZE = 64 * 1024 * 1024;
@@ -85,41 +90,22 @@ function encode(msg) {
             msgType = exports.MSG_QUERY_SQL;
             break;
         case "QueryWithParams": {
-            const parts = [encodeString(msg.query)];
-            const count = Buffer.alloc(2);
-            count.writeUInt16LE(msg.params.length, 0);
-            parts.push(count);
-            for (const p of msg.params) {
-                switch (p.tag) {
-                    case "null":
-                        parts.push(Buffer.from([0]));
-                        break;
-                    case "int": {
-                        const b = Buffer.alloc(9);
-                        b.writeUInt8(1, 0);
-                        b.writeBigInt64LE(p.value, 1);
-                        parts.push(b);
-                        break;
-                    }
-                    case "float": {
-                        const b = Buffer.alloc(9);
-                        b.writeUInt8(2, 0);
-                        b.writeDoubleLE(p.value, 1);
-                        parts.push(b);
-                        break;
-                    }
-                    case "bool":
-                        parts.push(Buffer.from([3, p.value ? 1 : 0]));
-                        break;
-                    case "str":
-                        parts.push(Buffer.from([4]), encodeString(p.value));
-                        break;
-                }
-            }
-            payload = Buffer.concat(parts);
+            payload = encodeQueryWithParams(msg.query, msg.params);
             msgType = exports.MSG_QUERY_PARAMS;
             break;
         }
+        case "QueryNative":
+            payload = encodeString(msg.query);
+            msgType = exports.MSG_QUERY_NATIVE;
+            break;
+        case "QueryWithParamsNative":
+            payload = encodeQueryWithParams(msg.query, msg.params);
+            msgType = exports.MSG_QUERY_PARAMS_NATIVE;
+            break;
+        case "QuerySqlNative":
+            payload = encodeString(msg.query);
+            msgType = exports.MSG_QUERY_SQL_NATIVE;
+            break;
         case "SyncStatus":
             payload = encodeString(msg.replicaId);
             msgType = exports.MSG_SYNC_STATUS;
@@ -197,6 +183,23 @@ function encode(msg) {
             payload = encodeString(msg.value);
             msgType = exports.MSG_RESULT_SCALAR;
             break;
+        case "ResultRowsNative": {
+            const parts = [u16LE(msg.columns.length)];
+            for (const column of msg.columns)
+                parts.push(encodeString(column));
+            parts.push(u32LE(msg.rows.length));
+            for (const row of msg.rows) {
+                for (const value of row)
+                    parts.push(encodeWireValue(value));
+            }
+            payload = Buffer.concat(parts);
+            msgType = exports.MSG_RESULT_ROWS_NATIVE;
+            break;
+        }
+        case "ResultScalarNative":
+            payload = encodeWireValue(msg.value);
+            msgType = exports.MSG_RESULT_SCALAR_NATIVE;
+            break;
         case "ResultOk": {
             payload = Buffer.alloc(8);
             payload.writeBigUInt64LE(msg.affected, 0);
@@ -231,6 +234,83 @@ function encode(msg) {
     payload.copy(frame, 6);
     return frame;
 }
+function encodeQueryWithParams(query, params) {
+    const parts = [encodeString(query), u16LE(params.length)];
+    for (const param of params) {
+        switch (param.tag) {
+            case "null":
+                parts.push(Buffer.from([0]));
+                break;
+            case "int": {
+                const body = Buffer.alloc(9);
+                body.writeUInt8(1, 0);
+                body.writeBigInt64LE(param.value, 1);
+                parts.push(body);
+                break;
+            }
+            case "float": {
+                const body = Buffer.alloc(9);
+                body.writeUInt8(2, 0);
+                body.writeDoubleLE(param.value, 1);
+                parts.push(body);
+                break;
+            }
+            case "bool":
+                parts.push(Buffer.from([3, param.value ? 1 : 0]));
+                break;
+            case "str":
+                parts.push(Buffer.from([4]), encodeString(param.value));
+                break;
+        }
+    }
+    return Buffer.concat(parts);
+}
+function encodeWireValue(value) {
+    let tag;
+    let body;
+    switch (value.type) {
+        case "empty":
+            tag = 0;
+            body = Buffer.alloc(0);
+            break;
+        case "int":
+        case "datetime":
+            tag = value.type === "int" ? 1 : 5;
+            body = Buffer.alloc(8);
+            body.writeBigInt64LE(value.value, 0);
+            break;
+        case "float":
+            tag = 2;
+            body = Buffer.alloc(8);
+            body.writeDoubleLE(value.value, 0);
+            break;
+        case "bool":
+            tag = 3;
+            body = Buffer.from([value.value ? 1 : 0]);
+            break;
+        case "str":
+            tag = 4;
+            body = Buffer.from(value.value, "utf8");
+            break;
+        case "uuid":
+            if (value.value.length !== 16) {
+                throw new Error(`native UUID must be exactly 16 bytes, got ${value.value.length}`);
+            }
+            tag = 6;
+            body = Buffer.from(value.value);
+            break;
+        case "bytes":
+            tag = 7;
+            body = Buffer.from(value.value);
+            break;
+        case "json":
+            tag = 8;
+            body = Buffer.from(value.pj1);
+            decodePj1(body);
+            break;
+    }
+    return Buffer.concat([Buffer.from([tag]), u32LE(body.length), body]);
+}
 // ───── Decoding ────────────────────────────────────────────────────────────
 /**
  * Attempts to parse a single frame from the start of `buf`. Returns the parsed
@@ -310,6 +390,21 @@ function decodePayload(msgType, payload) {
             }
             return { type: "QueryWithParams", query, params };
         }
+        case exports.MSG_QUERY_NATIVE: {
+            const query = decodeStringStrict(payload, cursor, "native PowQL query");
+            requirePayloadEnd(payload, cursor, "native PowQL query");
+            return { type: "QueryNative", query };
+        }
+        case exports.MSG_QUERY_PARAMS_NATIVE: {
+            const { query, params } = decodeNativeQueryWithParams(payload, cursor);
+            requirePayloadEnd(payload, cursor, "native parameterized query");
+            return { type: "QueryWithParamsNative", query, params };
+        }
+        case exports.MSG_QUERY_SQL_NATIVE: {
+            const query = decodeStringStrict(payload, cursor, "native SQL query");
+            requirePayloadEnd(payload, cursor, "native SQL query");
+            return { type: "QuerySqlNative", query };
+        }
         case exports.MSG_SYNC_STATUS:
             return { type: "SyncStatus", replicaId: decodeString(payload, cursor) };
         case exports.MSG_SYNC_PULL: {
@@ -407,6 +502,42 @@ function decodePayload(msgType, payload) {
         }
         case exports.MSG_RESULT_SCALAR:
             return { type: "ResultScalar", value: decodeString(payload, cursor) };
+        case exports.MSG_RESULT_ROWS_NATIVE: {
+            const colCount = readU16(payload, cursor, "native column count");
+            if (colCount > exports.MAX_COLUMNS) {
+                throw new Error(`too many columns: ${colCount} (max ${exports.MAX_COLUMNS})`);
+            }
+            const columns = [];
+            for (let i = 0; i < colCount; i++) {
+                columns.push(decodeStringStrict(payload, cursor, "native column name"));
+            }
+            const rowCount = readU32(payload, cursor, "native row count");
+            if (rowCount > exports.MAX_ROWS) {
+                throw new Error(`too many rows: ${rowCount} (max ${exports.MAX_ROWS})`);
+            }
+            if (colCount === 0 && rowCount > 0) {
+                throw new Error("nonzero native row count with zero columns");
+            }
+            const minimumBytes = BigInt(rowCount) * BigInt(colCount) * 5n;
+            if (BigInt(payload.length - cursor.pos) < minimumBytes) {
+                throw new Error(`native row data too short for declared shape: ${rowCount} rows x ${colCount} columns`);
+            }
+            const rows = [];
+            for (let rowIndex = 0; rowIndex < rowCount; rowIndex++) {
+                const row = [];
+                for (let columnIndex = 0; columnIndex < colCount; columnIndex++) {
+                    row.push(decodeWireValue(payload, cursor));
+                }
+                rows.push(row);
+            }
+            requirePayloadEnd(payload, cursor, "native rows");
+            return { type: "ResultRowsNative", columns, rows };
+        }
+        case exports.MSG_RESULT_SCALAR_NATIVE: {
+            const value = decodeWireValue(payload, cursor);
+            requirePayloadEnd(payload, cursor, "native scalar");
+            return { type: "ResultScalarNative", value };
+        }
         case exports.MSG_RESULT_OK: {
             const affected = readU64(payload, cursor, "affected count");
             return { type: "ResultOk", affected };
@@ -425,6 +556,94 @@ function decodePayload(msgType, payload) {
             throw new Error(`unknown message type: 0x${msgType.toString(16)}`);
     }
 }
+function decodeNativeQueryWithParams(payload, cursor) {
+    const query = decodeStringStrict(payload, cursor, "native query");
+    const count = readU16(payload, cursor, "native param count");
+    if (count > exports.MAX_PARAMS) {
+        throw new Error(`too many parameters: ${count} (max ${exports.MAX_PARAMS})`);
+    }
+    if (count > payload.length - cursor.pos) {
+        throw new Error("parameter count exceeds payload size");
+    }
+    const params = [];
+    for (let index = 0; index < count; index++) {
+        const tag = readU8(payload, cursor, "param tag");
+        switch (tag) {
+            case 0:
+                params.push({ tag: "null" });
+                break;
+            case 1:
+                params.push({ tag: "int", value: readI64(payload, cursor, "int param") });
+                break;
+            case 2:
+                params.push({ tag: "float", value: readF64(payload, cursor, "float param") });
+                break;
+            case 3:
+                params.push({ tag: "bool", value: readBool(payload, cursor, "bool param") });
+                break;
+            case 4:
+                params.push({
+                    tag: "str",
+                    value: decodeStringStrict(payload, cursor, "string param"),
+                });
+                break;
+            default:
+                throw new Error(`unknown param tag: ${tag}`);
+        }
+    }
+    return { query, params };
+}
+function decodeWireValue(buf, cursor) {
+    const tag = readU8(buf, cursor, "typed value tag");
+    const bodyLength = readU32(buf, cursor, "typed value body length");
+    const body = readFixedBytes(buf, cursor, bodyLength, "typed value body");
+    const requireLength = (expected, label) => {
+        if (body.length !== expected) {
+            throw new Error(`invalid ${label} typed value length: expected ${expected}, got ${body.length}`);
+        }
+    };
+    switch (tag) {
+        case 0:
+            requireLength(0, "Empty");
+            return { type: "empty" };
+        case 1:
+            requireLength(8, "Int");
+            return { type: "int", value: body.readBigInt64LE(0) };
+        case 2: {
+            requireLength(8, "Float");
+            return { type: "float", value: body.readDoubleLE(0) };
+        }
+        case 3:
+            requireLength(1, "Bool");
+            if (body[0] !== 0 && body[0] !== 1) {
+                throw new Error(`invalid typed boolean: ${body[0]}`);
+            }
+            return { type: "bool", value: body[0] === 1 };
+        case 4:
+            return { type: "str", value: decodeUtf8Strict(body, "typed string") };
+        case 5:
+            requireLength(8, "DateTime");
+            return { type: "datetime", value: body.readBigInt64LE(0) };
+        case 6:
+            requireLength(16, "UUID");
+            return { type: "uuid", value: new Uint8Array(body) };
+        case 7:
+            return { type: "bytes", value: new Uint8Array(body) };
+        case 8:
+            return {
+                type: "json",
+                value: decodePj1(body),
+                pj1: new Uint8Array(body),
+            };
+        default:
+            throw new Error(`unknown typed value tag: ${tag}`);
+    }
+}
+function requirePayloadEnd(payload, cursor, label) {
+    if (cursor.pos !== payload.length) {
+        throw new Error(`trailing bytes in ${label} payload`);
+    }
+}
 function encodeSyncStatus(status) {
     return Buffer.concat([
         encodeString(status.replicaId),
@@ -551,6 +770,159 @@ function decodeString(buf, cursor) {
     cursor.pos += len;
     return s;
 }
+const strictUtf8 = new TextDecoder("utf-8", { fatal: true });
+function decodeUtf8Strict(bytes, label) {
+    try {
+        return strictUtf8.decode(bytes);
+    }
+    catch {
+        throw new Error(`invalid UTF-8 in ${label}`);
+    }
+}
+function decodeStringStrict(buf, cursor, label) {
+    const len = readU32(buf, cursor, `${label} length`);
+    const bytes = readFixedBytes(buf, cursor, len, label);
+    return decodeUtf8Strict(bytes, label);
+}
+function decodePj1(doc) {
+    const [value, end] = decodePj1Node(doc, 0, 0);
+    if (end !== doc.length)
+        throw new Error("invalid typed PJ1 JSON: trailing bytes");
+    return value;
+}
+function decodePj1Node(doc, start, depth) {
+    if (depth > 128)
+        throw new Error("invalid typed PJ1 JSON: nesting too deep");
+    if (start >= doc.length)
+        throw new Error("invalid typed PJ1 JSON: truncated node");
+    const tag = doc[start];
+    switch (tag) {
+        case 0:
+            return [null, start + 1];
+        case 1:
+            return [false, start + 1];
+        case 2:
+            return [true, start + 1];
+        case 3: {
+            ensurePj1Range(doc, start + 1, 8);
+            const integer = doc.readBigInt64LE(start + 1);
+            const value = integer >= BigInt(Number.MIN_SAFE_INTEGER) &&
+                integer <= BigInt(Number.MAX_SAFE_INTEGER)
+                ? Number(integer)
+                : integer;
+            return [value, start + 9];
+        }
+        case 4: {
+            ensurePj1Range(doc, start + 1, 8);
+            const value = doc.readDoubleLE(start + 1);
+            if (!Number.isFinite(value)) {
+                throw new Error("invalid typed PJ1 JSON: non-finite float");
+            }
+            return [value, start + 9];
+        }
+        case 5: {
+            const [value, end] = decodePj1String(doc, start + 1);
+            return [value, end];
+        }
+        case 6:
+            return decodePj1Array(doc, start, depth);
+        case 7:
+            return decodePj1Object(doc, start, depth);
+        default:
+            throw new Error(`invalid typed PJ1 JSON: reserved/invalid tag ${tag}`);
+    }
+}
+function decodePj1Array(doc, start, depth) {
+    const count = pj1U32(doc, start + 1);
+    const headerSize = 5 + 4 * (count + 1);
+    ensurePj1Range(doc, start, headerSize);
+    let expectedOffset = headerSize;
+    const values = [];
+    for (let index = 0; index < count; index++) {
+        const offset = pj1U32(doc, start + 5 + index * 4);
+        const nextOffset = pj1U32(doc, start + 5 + (index + 1) * 4);
+        if (offset !== expectedOffset || nextOffset < offset) {
+            throw new Error("invalid typed PJ1 JSON: array offsets not canonical");
+        }
+        const [value, end] = decodePj1Node(doc, start + offset, depth + 1);
+        if (end !== start + nextOffset) {
+            throw new Error("invalid typed PJ1 JSON: array element length mismatch");
+        }
+        values.push(value);
+        expectedOffset = nextOffset;
+    }
+    const total = pj1U32(doc, start + 5 + count * 4);
+    if (total !== expectedOffset) {
+        throw new Error("invalid typed PJ1 JSON: array end offset mismatch");
+    }
+    ensurePj1Range(doc, start, total);
+    return [values, start + total];
+}
+function decodePj1Object(doc, start, depth) {
+    const count = pj1U32(doc, start + 1);
+    const headerSize = 5 + count * 8 + 4;
+    ensurePj1Range(doc, start, headerSize);
+    const keys = [];
+    let expectedKeyOffset = headerSize;
+    for (let index = 0; index < count; index++) {
+        const keyOffset = pj1U32(doc, start + 5 + index * 8);
+        if (keyOffset !== expectedKeyOffset) {
+            throw new Error("invalid typed PJ1 JSON: object key offset mismatch");
+        }
+        const [text, end, bytes] = decodePj1String(doc, start + keyOffset);
+        const previous = keys[keys.length - 1];
+        if (previous && Buffer.compare(previous.bytes, bytes) >= 0) {
+            throw new Error("invalid typed PJ1 JSON: object keys not strictly sorted");
+        }
+        keys.push({ text, bytes });
+        expectedKeyOffset = end - start;
+    }
+    const result = {};
+    let expectedValueOffset = expectedKeyOffset;
+    for (let index = 0; index < count; index++) {
+        const valueOffset = pj1U32(doc, start + 5 + index * 8 + 4);
+        if (valueOffset !== expectedValueOffset) {
+            throw new Error("invalid typed PJ1 JSON: object value offset mismatch");
+        }
+        const [value, end] = decodePj1Node(doc, start + valueOffset, depth + 1);
+        const key = keys[index];
+        if (!key)
+            throw new Error("invalid typed PJ1 JSON: missing object key");
+        Object.defineProperty(result, key.text, {
+            value,
+            enumerable: true,
+            configurable: true,
+            writable: true,
+        });
+        expectedValueOffset = end - start;
+    }
+    const total = pj1U32(doc, start + 5 + count * 8);
+    if (total !== expectedValueOffset) {
+        throw new Error("invalid typed PJ1 JSON: object end offset mismatch");
+    }
+    ensurePj1Range(doc, start, total);
+    return [result, start + total];
+}
+function decodePj1String(doc, lengthOffset) {
+    const len = pj1U32(doc, lengthOffset);
+    const dataStart = lengthOffset + 4;
+    ensurePj1Range(doc, dataStart, len);
+    const bytes = doc.subarray(dataStart, dataStart + len);
+    return [decodeUtf8Strict(bytes, "PJ1 string"), dataStart + len, bytes];
+}
+function pj1U32(doc, offset) {
+    ensurePj1Range(doc, offset, 4);
+    return doc.readUInt32LE(offset);
+}
+function ensurePj1Range(doc, offset, len) {
+    if (!Number.isSafeInteger(offset) ||
+        !Number.isSafeInteger(len) ||
+        offset < 0 ||
+        len < 0 ||
+        offset + len > doc.length) {
+        throw new Error("invalid typed PJ1 JSON: truncated or overflowing range");
+    }
+}
 function readU8(buf, cursor, label) {
     if (cursor.pos + 1 > buf.length) {
         throw new Error(`truncated ${label}`);

package/dist/index.d.ts

@@ -16,10 +16,24 @@
  */
 import * as tls from "node:tls";
 import { EventEmitter } from "node:events";
-import { type SyncRepairAction, type WireRetainedUnit, type WireSyncStatus } from "./protocol.js";
+import { type NativeJson, type SyncRepairAction, type WireRetainedUnit, type WireSyncStatus, type WireValue } 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.12.0";
+export declare const CLIENT_VERSION = "0.14.0";
+/**
+ * The maximum catalog format version this client can read. State this as the
+ * `catalogVersion` in sync pull requests: the server accepts any replica whose
+ * maximum is at least its active catalog format and rejects an older replica.
+ * When validating a server-reported catalog version, accept anything at or
+ * below this and reject anything newer (the client cannot read it).
+ */
+export declare const SUPPORTED_CATALOG_VERSION = 6;
+/**
+ * Throw when a server-reported catalog format is newer than this client can
+ * read. Accepts `serverCatalogVersion <= SUPPORTED_CATALOG_VERSION`; rejects a
+ * newer server, which requires upgrading the client.
+ */
+export declare function assertServerCatalogVersionSupported(serverCatalogVersion: number, clientMax?: number): void;
 export type QueryResult = {
     kind: "rows";
     columns: string[];
@@ -34,6 +48,46 @@ export type QueryResult = {
     kind: "message";
     message: string;
 };
+export type { NativeJson } from "./protocol.js";
+/** A value returned by the lossless native wire surface. */
+export type NativeValue = null | number | bigint | boolean | string | Uint8Array | NativeJson;
+export type NativeQueryResult = {
+    kind: "rows";
+    columns: string[];
+    rows: NativeValue[][];
+} | {
+    kind: "scalar";
+    value: NativeValue;
+} | {
+    kind: "ok";
+    affected: bigint;
+} | {
+    kind: "message";
+    message: string;
+};
+/**
+ * The fully lossless result of {@link Client.queryNativeRaw}: every cell is the
+ * raw {@link WireValue} tagged union straight off the wire, with no conversion
+ * to {@link NativeValue}. Use this when you need storage-level identity that the
+ * convenience conversion erases: the raw PJ1 bytes of a JSON cell (`pj1`), or
+ * telling an absent value (`{ type: "empty" }`) apart from the string `"null"`
+ * (`{ type: "str", value: "null" }`) or a JSON null (`{ type: "json", value:
+ * null }`), all of which {@link queryNative} collapses to `null`.
+ */
+export type RawNativeQueryResult = {
+    kind: "rows";
+    columns: string[];
+    rows: WireValue[][];
+} | {
+    kind: "scalar";
+    value: WireValue;
+} | {
+    kind: "ok";
+    affected: bigint;
+} | {
+    kind: "message";
+    message: string;
+};
 /**
  * A value bound to a positional `$N` placeholder in {@link Client.query}.
  *
@@ -256,6 +310,32 @@ export declare class Client extends EventEmitter<ClientEvents> {
     }, maybeOpts?: {
         signal?: AbortSignal;
     }): Promise<QueryResult>;
+    /**
+     * Run PowQL over the lossless typed wire surface. Unlike {@link query},
+     * cells are not stringified: bytes remain bytes, JSON is recursive data,
+     * and unsafe integers remain bigint. This method never retries as a legacy
+     * query, because replaying a mutation after an ambiguous response is unsafe.
+     */
+    queryNative(query: string, paramsOrOpts?: QueryParam[] | {
+        signal?: AbortSignal;
+    }, maybeOpts?: {
+        signal?: AbortSignal;
+    }): Promise<NativeQueryResult>;
+    /**
+     * Like {@link queryNative}, but returns every cell as the raw
+     * {@link WireValue} tagged union with no conversion to {@link NativeValue}.
+     *
+     * Reach for this only when the convenience conversion would erase something
+     * you need: the raw PJ1 bytes of a JSON cell (`pj1`), or the distinction
+     * between an absent value (`{ type: "empty" }`), the string `"null"`, and a
+     * JSON null (all three of which {@link queryNative} maps to `null`). For
+     * ordinary reads, {@link queryNative} is friendlier.
+     */
+    queryNativeRaw(query: string, paramsOrOpts?: QueryParam[] | {
+        signal?: AbortSignal;
+    }, maybeOpts?: {
+        signal?: AbortSignal;
+    }): Promise<RawNativeQueryResult>;
     /**
      * Run a SQL statement through the server-side SQL frontend. The plain
      * {@link query} method remains PowQL for wire compatibility.
@@ -263,6 +343,10 @@ export declare class Client extends EventEmitter<ClientEvents> {
     querySql(query: string, opts?: {
         signal?: AbortSignal;
     }): Promise<QueryResult>;
+    /** Run SQL through the lossless typed wire surface without legacy replay. */
+    querySqlNative(query: string, opts?: {
+        signal?: AbortSignal;
+    }): Promise<NativeQueryResult>;
     /**
      * Fetch primary-side sync status for one embedded replica cursor.
      *
@@ -381,7 +465,7 @@ export declare class Client extends EventEmitter<ClientEvents> {
     private onClose;
 }
 export { encode, tryDecode } from "./protocol.js";
-export type { Message, SyncRepairAction, WireParam, WireRetainedUnit, WireSyncStatus, } from "./protocol.js";
+export type { Message, SyncRepairAction, WireValue, 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";