npm - @visorcraft/mongreldb-kit - Versions diffs - 0.55.0 → 0.57.0 - Mend

@visorcraft/mongreldb-kit 0.55.0 → 0.57.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (14) hide show

package/dist/remote.js CHANGED Viewed

@@ -1,10 +1,1126 @@
 import { RemoteDatabase as NativeRemoteDatabase } from '@visorcraft/mongreldb/native.js';
 import { tableFromIPC, tableFromJSON } from 'apache-arrow';
 import { randomBytes } from 'node:crypto';
-import { KitError, KitUnsupportedError, QueryCancelledError, QueryIdConflictError, QueryTimeoutError, TransactionAbortedError } from './errors.js';
+import { CommitOutcomeError, CapabilityUnsupportedError, KitError, QueryCancelledError, QueryIdConflictError, QueryExecutionError, QueryOutcomeUnknownError, RemoteProtocolError, ResultLimitExceededError, SerializationError, QueryTimeoutError, TransactionAbortedError } from './errors.js';
 import { procedureJson } from './procedure.js';
 import { triggerJson } from './trigger.js';
 import { createVirtualTableSql, dropVirtualTableSql } from './external.js';
+const SQL_RECOVERY_WINDOW_MS = 2_000;
+const SQL_RECOVERY_REQUEST_TIMEOUT_MS = 250;
+const SQL_RECOVERY_POLL_INTERVAL_MS = 25;
+const MAX_U64 = 18446744073709551615n;
+const MAX_CONTROL_JSON_RESPONSE_BYTES = 1024 * 1024;
+const MAX_PAGE_JSON_RESPONSE_BYTES = 64 * 1024 * 1024;
+const TERMINAL_SQL_STATES = new Set(['completed', 'failed', 'cancelled', 'pre_cancelled']);
+function containsHttpHeaderControl(value) {
+    return /[\u0000-\u001f\u007f]/u.test(value);
+}
+function parseJsonStrict(text) {
+    let offset = 0;
+    const fail = (message) => {
+        throw new SyntaxError(`${message} at JSON offset ${offset}`);
+    };
+    const whitespace = () => {
+        while (offset < text.length
+            && [' ', '\t', '\r', '\n'].includes(text[offset]))
+            offset += 1;
+    };
+    const string = () => {
+        if (text[offset] !== '"')
+            fail('expected string');
+        const start = offset++;
+        while (offset < text.length) {
+            const char = text[offset++];
+            if (char === '"')
+                return JSON.parse(text.slice(start, offset));
+            if (char.charCodeAt(0) < 0x20)
+                fail('unescaped control character');
+            if (char !== '\\')
+                continue;
+            if (offset >= text.length)
+                fail('unterminated escape');
+            const escape = text[offset++];
+            if (escape === 'u') {
+                if (!/^[0-9a-fA-F]{4}$/.test(text.slice(offset, offset + 4))) {
+                    fail('invalid unicode escape');
+                }
+                offset += 4;
+            }
+            else if (!'"\\/bfnrt'.includes(escape)) {
+                fail('invalid string escape');
+            }
+        }
+        return fail('unterminated string');
+    };
+    const value = () => {
+        whitespace();
+        const char = text[offset];
+        if (char === '"')
+            return string();
+        if (char === '{') {
+            offset += 1;
+            const object = Object.create(null);
+            const keys = new Set();
+            whitespace();
+            if (text[offset] === '}') {
+                offset += 1;
+                return object;
+            }
+            while (true) {
+                whitespace();
+                const key = string();
+                if (keys.has(key))
+                    fail(`duplicate JSON object key ${JSON.stringify(key)}`);
+                keys.add(key);
+                whitespace();
+                if (text[offset++] !== ':')
+                    fail('expected colon');
+                object[key] = value();
+                whitespace();
+                const separator = text[offset++];
+                if (separator === '}')
+                    return object;
+                if (separator !== ',')
+                    fail('expected comma or object end');
+            }
+        }
+        if (char === '[') {
+            offset += 1;
+            const array = [];
+            whitespace();
+            if (text[offset] === ']') {
+                offset += 1;
+                return array;
+            }
+            while (true) {
+                array.push(value());
+                whitespace();
+                const separator = text[offset++];
+                if (separator === ']')
+                    return array;
+                if (separator !== ',')
+                    fail('expected comma or array end');
+            }
+        }
+        for (const [literal, parsed] of [['true', true], ['false', false], ['null', null]]) {
+            if (text.startsWith(literal, offset)) {
+                offset += literal.length;
+                return parsed;
+            }
+        }
+        const number = text.slice(offset).match(/^-?(?:0|[1-9]\d*)(?:\.\d+)?(?:[eE][+-]?\d+)?/u)?.[0];
+        if (!number)
+            return fail('expected JSON value');
+        offset += number.length;
+        const parsed = Number(number);
+        if (!Number.isFinite(parsed))
+            return fail('non-finite JSON number');
+        return parsed;
+    };
+    const parsed = value();
+    whitespace();
+    if (offset !== text.length)
+        fail('trailing JSON data');
+    return parsed;
+}
+async function responseBytesBounded(response, limit) {
+    const declared = response.headers.get('content-length');
+    if (declared !== null) {
+        if (!/^\d+$/u.test(declared) || Number(declared) > limit) {
+            throw new SyntaxError(`HTTP response exceeded ${limit} bytes`);
+        }
+    }
+    if (!response.body)
+        return new Uint8Array();
+    const reader = response.body.getReader();
+    const chunks = [];
+    let length = 0;
+    try {
+        while (true) {
+            const { done, value } = await reader.read();
+            if (done)
+                break;
+            length += value.byteLength;
+            if (length > limit) {
+                await reader.cancel().catch(() => undefined);
+                throw new SyntaxError(`HTTP response exceeded ${limit} bytes`);
+            }
+            chunks.push(value);
+        }
+    }
+    finally {
+        reader.releaseLock();
+    }
+    const bytes = new Uint8Array(length);
+    let offset = 0;
+    for (const chunk of chunks) {
+        bytes.set(chunk, offset);
+        offset += chunk.byteLength;
+    }
+    return bytes;
+}
+async function responseTextBounded(response, limit) {
+    try {
+        return new TextDecoder('utf-8', { fatal: true }).decode(await responseBytesBounded(response, limit));
+    }
+    catch {
+        throw new SyntaxError('HTTP response was not valid UTF-8');
+    }
+}
+async function responseJsonStrict(response, limit = MAX_CONTROL_JSON_RESPONSE_BYTES) {
+    return parseJsonStrict(await responseTextBounded(response, limit));
+}
+function preExecutionCancellationError(queryId, outcome) {
+    const metadata = {
+        cancelOutcome: outcome,
+        cancellationReason: 'client_request',
+        retryable: false,
+        serverState: 'pre_cancelled'
+    };
+    if (outcome === 'not_found') {
+        return new KitError('SQL pre-registration cancellation was not found by the server', 'QUERY_NOT_FOUND');
+    }
+    if (outcome === 'too_late') {
+        return new KitError('SQL cancellation arrived after the commit fence', 'CANCEL_TOO_LATE');
+    }
+    if (outcome === 'already_finished') {
+        return new KitError('SQL query ID already belongs to a finished query', 'QUERY_ALREADY_FINISHED');
+    }
+    return new QueryCancelledError(queryId, 'SQL query cancelled before execution', { committed: false, committedStatements: 0, completedStatements: 0, statementIndex: 0 }, metadata);
+}
+function isNonNegativeInteger(value) {
+    return Number.isSafeInteger(value) && value >= 0;
+}
+function isOptionalNonNegativeInteger(value) {
+    return value === undefined || value === null || isNonNegativeInteger(value);
+}
+function hasOnlyKeys(value, allowed) {
+    return Object.keys(value).every((key) => allowed.includes(key));
+}
+function hasAllKeys(value, required) {
+    return required.every((key) => Object.prototype.hasOwnProperty.call(value, key));
+}
+function normalizeQueryId(value) {
+    if (typeof value !== 'string' || !/^[0-9a-f]{32}$/i.test(value)) {
+        throw new TypeError('queryId must be exactly 32 hexadecimal characters');
+    }
+    return value.toLowerCase();
+}
+function isOptionalEpoch(value, exactText) {
+    if (exactText !== undefined && exactText !== null
+        && (typeof exactText !== 'string' || !/^\d+$/.test(exactText)))
+        return false;
+    if (typeof exactText === 'string'
+        && (BigInt(exactText).toString() !== exactText || BigInt(exactText) > MAX_U64))
+        return false;
+    if (value === undefined || value === null)
+        return true;
+    if (!Number.isSafeInteger(value) || value < 0)
+        return false;
+    if (typeof exactText === 'string')
+        return BigInt(value) === BigInt(exactText);
+    return true;
+}
+function receiptEpoch(value, exactText) {
+    if (typeof exactText === 'string')
+        return BigInt(exactText);
+    return typeof value === 'number' ? BigInt(value) : undefined;
+}
+function isQueryNotFoundResponse(value, queryId) {
+    if (value === null || typeof value !== 'object')
+        return false;
+    const body = value;
+    const outcome = body.outcome;
+    const error = body.error;
+    const nullable = [
+        'committed', 'committed_statements', 'last_commit_epoch', 'last_commit_epoch_text',
+        'first_commit_statement_index', 'last_commit_statement_index', 'completed_statements',
+        'statement_index'
+    ];
+    return hasOnlyKeys(body, [
+        'query_id', 'status', 'terminal_state', ...nullable, 'cancel_outcome',
+        'cancellation_reason', 'retryable', 'server_state', 'outcome', 'error'
+    ]) && hasAllKeys(body, [
+        'query_id', 'status', 'terminal_state', ...nullable, 'cancel_outcome',
+        'cancellation_reason', 'retryable', 'server_state', 'outcome', 'error'
+    ])
+        && outcome !== null && typeof outcome === 'object'
+        && hasOnlyKeys(outcome, [...nullable, 'serialization'])
+        && hasAllKeys(outcome, [...nullable, 'serialization'])
+        && error !== null && typeof error === 'object'
+        && hasOnlyKeys(error, ['code', 'message', 'query_id', 'committed', 'retryable'])
+        && hasAllKeys(error, ['code', 'message', 'query_id', 'committed', 'retryable'])
+        && body.query_id === queryId && body.status === 'unknown'
+        && body.terminal_state === null && body.cancel_outcome === 'not_found'
+        && body.cancellation_reason === null && body.retryable === false
+        && body.server_state === 'not_found'
+        && nullable.every((field) => body[field] === null && outcome[field] === null)
+        && outcome.serialization === 'unknown'
+        && error.code === 'QUERY_NOT_FOUND'
+        && typeof error.message === 'string' && error.message.length > 0
+        && error.query_id === queryId && error.committed === null && error.retryable === false;
+}
+function isRemoteSqlWriteReceipt(value, queryId, expectedOriginalQueryId) {
+    if (value === null || typeof value !== 'object')
+        return false;
+    const body = value;
+    const outcome = body.outcome;
+    if (outcome === null || typeof outcome !== 'object')
+        return false;
+    const durable = outcome;
+    const terminal = body.terminal_error;
+    if (!hasOnlyKeys(body, [
+        'query_id', 'original_query_id', 'status', 'terminal_state', 'server_state',
+        'cancel_outcome', 'cancellation_reason', 'committed', 'committed_statements',
+        'last_commit_epoch', 'last_commit_epoch_text', 'first_commit_statement_index',
+        'last_commit_statement_index', 'completed_statements', 'statement_index', 'retryable',
+        'idempotency_replayed', 'idempotency_persisted', 'idempotency_expires_at_ms',
+        'outcome', 'terminal_error'
+    ]) || !hasOnlyKeys(durable, [
+        'committed', 'committed_statements', 'last_commit_epoch', 'last_commit_epoch_text',
+        'first_commit_statement_index', 'last_commit_statement_index', 'completed_statements',
+        'statement_index', 'serialization'
+    ]) || !hasAllKeys(durable, [
+        'committed', 'committed_statements', 'last_commit_epoch', 'last_commit_epoch_text',
+        'first_commit_statement_index', 'last_commit_statement_index', 'completed_statements',
+        'statement_index', 'serialization'
+    ]))
+        return false;
+    if (terminal !== undefined && terminal !== null
+        && (typeof terminal !== 'object'
+            || !hasOnlyKeys(terminal, ['code', 'category'])))
+        return false;
+    const statusCommitted = body.status === 'completed'
+        ? false
+        : ['committed', 'committed_with_error', 'partially_committed',
+            'cancelled_after_commit', 'deadline_after_commit'].includes(body.status)
+            ? true
+            : undefined;
+    const shapeValid = body.query_id === queryId
+        && typeof body.original_query_id === 'string'
+        && /^[0-9a-f]{32}$/i.test(body.original_query_id)
+        && typeof body.status === 'string'
+        && body.status.trim().length > 0
+        && (body.terminal_state === undefined || body.terminal_state === null
+            || body.terminal_state === body.status)
+        && (body.server_state === undefined || body.server_state === null
+            || ['completed', 'failed', 'cancelled'].includes(body.server_state))
+        && (body.cancel_outcome === undefined || body.cancel_outcome === null
+            || body.cancel_outcome === 'already_finished')
+        && (body.cancellation_reason === undefined || body.cancellation_reason === null
+            || ['none', 'client_request', 'deadline', 'client_disconnected',
+                'session_closed', 'server_shutdown'].includes(body.cancellation_reason))
+        && typeof body.committed === 'boolean'
+        && isNonNegativeInteger(body.committed_statements)
+        && body.committed === durable.committed
+        && body.committed_statements === durable.committed_statements
+        && typeof body.retryable === 'boolean'
+        && typeof body.idempotency_replayed === 'boolean'
+        && typeof body.idempotency_persisted === 'boolean'
+        && isNonNegativeInteger(body.idempotency_expires_at_ms)
+        && typeof durable.committed === 'boolean'
+        && isNonNegativeInteger(durable.committed_statements)
+        && ['not_started', 'in_progress', 'succeeded', 'failed', 'unknown']
+            .includes(durable.serialization)
+        && isOptionalEpoch(body.last_commit_epoch, body.last_commit_epoch_text)
+        && isOptionalNonNegativeInteger(body.first_commit_statement_index)
+        && isOptionalNonNegativeInteger(body.last_commit_statement_index)
+        && isNonNegativeInteger(body.completed_statements)
+        && isNonNegativeInteger(body.statement_index)
+        && isOptionalEpoch(durable.last_commit_epoch, durable.last_commit_epoch_text)
+        && isOptionalNonNegativeInteger(durable.first_commit_statement_index)
+        && isOptionalNonNegativeInteger(durable.last_commit_statement_index)
+        && (terminal === undefined || terminal === null
+            || typeof terminal === 'object'
+                && typeof terminal.code === 'string'
+                && terminal.code.trim().length > 0
+                && ['cancellation', 'deadline', 'result_limit', 'serialization', 'execution']
+                    .includes(terminal.category));
+    if (!shapeValid)
+        return false;
+    if (statusCommitted === undefined || body.committed !== statusCommitted)
+        return false;
+    if (body.server_state != null) {
+        const expectedState = ['completed', 'committed'].includes(body.status)
+            ? 'completed'
+            : ['committed_with_error', 'partially_committed'].includes(body.status)
+                ? 'failed' : 'cancelled';
+        if (body.server_state !== expectedState)
+            return false;
+    }
+    if (body.cancellation_reason != null) {
+        const reasonMatches = body.status === 'cancelled_after_commit'
+            ? !['none', 'deadline'].includes(body.cancellation_reason)
+            : body.status === 'deadline_after_commit'
+                ? body.cancellation_reason === 'deadline'
+                : body.cancellation_reason === 'none';
+        if (!reasonMatches)
+            return false;
+    }
+    const terminalRecord = terminal;
+    if (terminalRecord != null
+        && (((terminalRecord.category === 'cancellation')
+            !== ['QUERY_CANCELLED', 'QUERY_CANCELLED_AFTER_COMMIT'].includes(terminalRecord.code))
+            || ((terminalRecord.category === 'deadline')
+                !== ['DEADLINE_EXCEEDED', 'DEADLINE_AFTER_COMMIT'].includes(terminalRecord.code))
+            || ((terminalRecord.category === 'result_limit')
+                !== (terminalRecord.code === 'RESULT_LIMIT_EXCEEDED'))
+            || ((terminalRecord.category === 'serialization')
+                !== ['SERIALIZATION_FAILED', 'SERIALIZATION_FAILED_AFTER_COMMIT']
+                    .includes(terminalRecord.code))))
+        return false;
+    const terminalMatches = body.status === 'completed' || body.status === 'committed'
+        ? terminal == null
+        : body.status === 'cancelled_after_commit'
+            ? terminalRecord?.code === 'QUERY_CANCELLED_AFTER_COMMIT'
+                && terminalRecord.category === 'cancellation'
+            : body.status === 'deadline_after_commit'
+                ? terminalRecord?.code === 'DEADLINE_AFTER_COMMIT'
+                    && terminalRecord.category === 'deadline'
+                : ['committed_with_error', 'partially_committed'].includes(body.status)
+                    && terminal != null;
+    if (!terminalMatches)
+        return false;
+    const topEpoch = receiptEpoch(body.last_commit_epoch, body.last_commit_epoch_text);
+    const outcomeEpoch = receiptEpoch(durable.last_commit_epoch, durable.last_commit_epoch_text);
+    if (topEpoch !== outcomeEpoch)
+        return false;
+    const topFirst = body.first_commit_statement_index;
+    const outcomeFirst = durable.first_commit_statement_index;
+    const topLast = body.last_commit_statement_index;
+    const outcomeLast = durable.last_commit_statement_index;
+    if ((topFirst ?? null) !== (outcomeFirst ?? null) || (topLast ?? null) !== (outcomeLast ?? null)) {
+        return false;
+    }
+    if (body.completed_statements !== durable.completed_statements
+        || body.statement_index !== durable.statement_index)
+        return false;
+    if (topFirst != null && topLast != null && topFirst > topLast)
+        return false;
+    if (body.committed) {
+        if (body.committed_statements === 0 || topEpoch === undefined
+            || body.last_commit_epoch_text == null || durable.last_commit_epoch_text == null
+            || topFirst == null || topLast == null)
+            return false;
+    }
+    else if (body.committed_statements !== 0 || topEpoch !== undefined
+        || topFirst != null || topLast != null)
+        return false;
+    if (topFirst != null && topLast != null
+        && (body.committed_statements > topLast - topFirst + 1
+            || topLast > body.statement_index))
+        return false;
+    if (body.statement_index > body.completed_statements
+        || body.completed_statements > body.statement_index + 1)
+        return false;
+    const originalQueryIdMatches = expectedOriginalQueryId === undefined
+        ? body.idempotency_replayed === true || body.original_query_id === queryId
+        : body.idempotency_replayed === true
+            ? body.original_query_id === expectedOriginalQueryId
+            : body.original_query_id === queryId;
+    return body.idempotency_persisted === true
+        && body.idempotency_expires_at_ms > 0
+        && body.retryable === false
+        && originalQueryIdMatches;
+}
+const QUERY_STATES = new Set([
+    'queued', 'planning', 'executing', 'streaming', 'serializing', 'commit_critical',
+    'cancelling', 'completed', 'failed', 'cancelled', 'pre_cancelled', 'finished'
+]);
+const QUERY_STATUSES = new Set([
+    'running', 'outcome_unknown', 'completed', 'failed_before_commit',
+    'cancelled_before_commit', 'deadline_before_commit', 'cancelled_before_start',
+    'committed', 'committed_with_error', 'partially_committed',
+    'cancelled_after_commit', 'deadline_after_commit', 'finished'
+]);
+const COMMITTED_QUERY_STATUSES = new Set([
+    'committed', 'committed_with_error', 'partially_committed',
+    'cancelled_after_commit', 'deadline_after_commit'
+]);
+function sameOptional(left, right) {
+    return (left ?? null) === (right ?? null);
+}
+function isRemoteQueryStatus(value, queryId) {
+    if (value === null || typeof value !== 'object')
+        return false;
+    const body = value;
+    const outcome = body.outcome !== null && typeof body.outcome === 'object'
+        ? body.outcome
+        : undefined;
+    if (outcome === undefined)
+        return false;
+    const serverState = body.server_state ?? '';
+    const terminal = body.terminal_error;
+    if (!hasOnlyKeys(body, [
+        'query_id', 'status', 'state', 'server_state', 'terminal_state', 'operation',
+        'started_ms_ago', 'deadline_ms_remaining', 'session_id',
+        'committed', 'committed_statements', 'last_commit_epoch', 'last_commit_epoch_text',
+        'first_commit_statement_index', 'last_commit_statement_index', 'completed_statements',
+        'statement_index', 'cancel_outcome', 'retryable', 'terminal_error',
+        'cancellation_reason', 'outcome', 'trace'
+    ]) || !hasOnlyKeys(outcome, [
+        'committed', 'committed_statements', 'last_commit_epoch', 'last_commit_epoch_text',
+        'first_commit_statement_index', 'last_commit_statement_index', 'completed_statements',
+        'statement_index', 'serialization'
+    ]) || !hasAllKeys(outcome, [
+        'committed', 'committed_statements', 'last_commit_epoch', 'last_commit_epoch_text',
+        'first_commit_statement_index', 'last_commit_statement_index', 'completed_statements',
+        'statement_index', 'serialization'
+    ]))
+        return false;
+    if (terminal !== undefined && terminal !== null
+        && (typeof terminal !== 'object'
+            || !hasOnlyKeys(terminal, ['code', 'category'])))
+        return false;
+    const trace = body.trace;
+    if (trace !== undefined && (trace === null || typeof trace !== 'object'
+        || !hasOnlyKeys(trace, [
+            'queue_duration_us', 'planning_duration_us', 'execution_duration_us',
+            'serialization_duration_us', 'cancel_requested_phase', 'cancel_observed_phase',
+            'commit_fence_outcome'
+        ])))
+        return false;
+    const traceRecord = trace;
+    const tracePhaseValid = (phase) => phase === undefined || phase === null
+        || typeof phase === 'string' && QUERY_STATES.has(phase);
+    if (traceRecord !== undefined
+        && (traceRecord.queue_duration_us !== undefined
+            && !isNonNegativeInteger(traceRecord.queue_duration_us)
+            || traceRecord.planning_duration_us !== undefined
+                && !isNonNegativeInteger(traceRecord.planning_duration_us)
+            || traceRecord.execution_duration_us !== undefined
+                && !isNonNegativeInteger(traceRecord.execution_duration_us)
+            || traceRecord.serialization_duration_us !== undefined
+                && !isNonNegativeInteger(traceRecord.serialization_duration_us)
+            || !tracePhaseValid(traceRecord.cancel_requested_phase)
+            || !tracePhaseValid(traceRecord.cancel_observed_phase)
+            || traceRecord.commit_fence_outcome !== undefined
+                && !['not_reached', 'cancel_won', 'commit_won']
+                    .includes(traceRecord.commit_fence_outcome)))
+        return false;
+    if (body.query_id !== queryId
+        || typeof body.status !== 'string' || !QUERY_STATUSES.has(body.status)
+        || typeof body.state !== 'string' || !QUERY_STATES.has(body.state)
+        || typeof serverState !== 'string'
+        || serverState !== '' && (!QUERY_STATES.has(serverState) || serverState !== body.state)
+        || body.terminal_state != null && body.terminal_state !== body.status
+        || body.started_ms_ago !== undefined && !isNonNegativeInteger(body.started_ms_ago)
+        || body.deadline_ms_remaining !== undefined && body.deadline_ms_remaining !== null
+            && !isNonNegativeInteger(body.deadline_ms_remaining)
+        || body.session_id !== undefined && body.session_id !== null
+            && (typeof body.session_id !== 'string' || body.session_id.length > 256)
+        || ![undefined, null, true, false].includes(body.committed)
+        || ![undefined, null, true, false].includes(outcome.committed)
+        || typeof body.retryable !== 'boolean'
+        || typeof body.cancellation_reason !== 'string'
+        || !['not_started', 'in_progress', 'succeeded', 'failed', 'unknown']
+            .includes(outcome.serialization)
+        || !isOptionalNonNegativeInteger(body.committed_statements)
+        || !isOptionalNonNegativeInteger(body.first_commit_statement_index)
+        || !isOptionalNonNegativeInteger(body.last_commit_statement_index)
+        || !isOptionalNonNegativeInteger(body.completed_statements)
+        || !isOptionalNonNegativeInteger(body.statement_index)
+        || !isOptionalNonNegativeInteger(outcome.committed_statements)
+        || !isOptionalNonNegativeInteger(outcome.first_commit_statement_index)
+        || !isOptionalNonNegativeInteger(outcome.last_commit_statement_index)
+        || !isOptionalNonNegativeInteger(outcome.completed_statements)
+        || !isOptionalNonNegativeInteger(outcome.statement_index)
+        || !isOptionalEpoch(body.last_commit_epoch, body.last_commit_epoch_text)
+        || !isOptionalEpoch(outcome.last_commit_epoch, outcome.last_commit_epoch_text)
+        || terminal != null && (typeof terminal !== 'object'
+            || typeof terminal.code !== 'string'
+            || terminal.code.trim().length === 0
+            || !['cancellation', 'deadline', 'result_limit', 'serialization', 'execution']
+                .includes(terminal.category))) {
+        return false;
+    }
+    const topEpoch = receiptEpoch(body.last_commit_epoch, body.last_commit_epoch_text);
+    const outcomeEpoch = receiptEpoch(outcome.last_commit_epoch, outcome.last_commit_epoch_text);
+    if (topEpoch !== outcomeEpoch
+        || !sameOptional(body.committed, outcome.committed)
+        || !sameOptional(body.committed_statements, outcome.committed_statements)
+        || !sameOptional(body.first_commit_statement_index, outcome.first_commit_statement_index)
+        || !sameOptional(body.last_commit_statement_index, outcome.last_commit_statement_index)
+        || !sameOptional(body.completed_statements, outcome.completed_statements)
+        || !sameOptional(body.statement_index, outcome.statement_index))
+        return false;
+    const committed = body.committed ?? null;
+    const committedStatements = body.committed_statements;
+    const first = body.first_commit_statement_index;
+    const last = body.last_commit_statement_index;
+    const completed = body.completed_statements;
+    const statement = body.statement_index;
+    const stateMatchesStatus = body.status === 'running'
+        ? ['queued', 'planning', 'executing', 'streaming', 'serializing',
+            'commit_critical', 'cancelling'].includes(body.state)
+        : body.status === 'committed'
+            ? ['planning', 'executing', 'streaming', 'serializing',
+                'commit_critical', 'cancelling', 'completed'].includes(body.state)
+            : body.status === 'completed' ? body.state === 'completed'
+                : ['failed_before_commit', 'committed_with_error', 'partially_committed',
+                    'outcome_unknown'].includes(body.status) ? body.state === 'failed'
+                    : ['cancelled_before_commit', 'deadline_before_commit',
+                        'cancelled_after_commit', 'deadline_after_commit'].includes(body.status)
+                        ? body.state === 'cancelled'
+                        : body.status === 'cancelled_before_start' ? body.state === 'pre_cancelled'
+                            : body.status === 'finished' && body.state === 'finished';
+    if (!stateMatchesStatus)
+        return false;
+    const expectedTerminal = body.status === 'running' || body.status === 'finished'
+        || body.status === 'committed' && body.state !== 'completed'
+        ? null : body.status;
+    if ((body.terminal_state ?? null) !== expectedTerminal)
+        return false;
+    if (committed === true) {
+        if (!COMMITTED_QUERY_STATUSES.has(body.status)
+            || committedStatements == null || committedStatements === 0
+            || topEpoch === undefined || body.last_commit_epoch_text == null
+            || outcome.last_commit_epoch_text == null || first == null || last == null
+            || completed == null || statement == null)
+            return false;
+    }
+    else if (committed === false) {
+        if (COMMITTED_QUERY_STATUSES.has(body.status)
+            || body.status === 'outcome_unknown' || body.status === 'finished'
+            || committedStatements !== 0 || topEpoch !== undefined
+            || first != null || last != null || completed == null || statement == null)
+            return false;
+    }
+    else if (body.status !== 'outcome_unknown' && body.status !== 'finished'
+        || committedStatements != null || topEpoch !== undefined
+        || first != null || last != null || completed != null || statement != null)
+        return false;
+    if (first != null && last != null && committedStatements != null && statement != null
+        && (first > last || committedStatements > last - first + 1 || last > statement))
+        return false;
+    if (completed != null && statement != null
+        && (statement > completed || completed > statement + 1))
+        return false;
+    const expectedCancel = body.state === 'cancelling' ? 'accepted'
+        : body.state === 'commit_critical' ? 'too_late'
+            : ['completed', 'failed', 'cancelled', 'finished'].includes(body.state)
+                ? 'already_finished'
+                : body.state === 'pre_cancelled' ? 'pre_cancelled' : null;
+    if ((body.cancel_outcome ?? null) !== expectedCancel)
+        return false;
+    const terminalError = terminal;
+    const terminalCode = terminalError?.code;
+    const terminalCategory = terminalError?.category;
+    const terminalMatches = ['running', 'completed', 'committed', 'finished']
+        .includes(body.status) ? terminal == null
+        : body.status === 'outcome_unknown'
+            ? terminalCode === 'QUERY_OUTCOME_UNKNOWN' && terminalCategory === 'execution'
+            : ['cancelled_before_commit', 'cancelled_before_start'].includes(body.status)
+                ? terminalCode === 'QUERY_CANCELLED' && terminalCategory === 'cancellation'
+                : body.status === 'cancelled_after_commit'
+                    ? terminalCode === 'QUERY_CANCELLED_AFTER_COMMIT'
+                        && terminalCategory === 'cancellation'
+                    : body.status === 'deadline_before_commit'
+                        ? terminalCode === 'DEADLINE_EXCEEDED' && terminalCategory === 'deadline'
+                        : body.status === 'deadline_after_commit'
+                            ? terminalCode === 'DEADLINE_AFTER_COMMIT'
+                                && terminalCategory === 'deadline'
+                            : terminal != null;
+    if (!terminalMatches)
+        return false;
+    if (terminalError != null
+        && ((terminalCategory === 'cancellation')
+            !== ['QUERY_CANCELLED', 'QUERY_CANCELLED_AFTER_COMMIT'].includes(terminalCode)
+            || (terminalCategory === 'deadline')
+                !== ['DEADLINE_EXCEEDED', 'DEADLINE_AFTER_COMMIT'].includes(terminalCode))) {
+        return false;
+    }
+    const retryable = ['IDEMPOTENCY_STORE_FULL', 'IDEMPOTENCY_STORE_UNAVAILABLE']
+        .includes(terminalCode);
+    if (body.retryable !== retryable)
+        return false;
+    const reason = body.cancellation_reason;
+    if (!['none', 'client_request', 'deadline', 'client_disconnected',
+        'session_closed', 'server_shutdown'].includes(reason))
+        return false;
+    if (['deadline_before_commit', 'deadline_after_commit'].includes(body.status)) {
+        return reason === 'deadline';
+    }
+    if (['cancelled_before_commit', 'cancelled_before_start', 'cancelled_after_commit']
+        .includes(body.status)
+        || ['running', 'committed'].includes(body.status) && body.state === 'cancelling') {
+        return reason !== 'none';
+    }
+    return reason === 'none' || body.state === 'commit_critical';
+}
+function isRemoteSqlPage(value, initialOptions) {
+    if (value === null || typeof value !== 'object')
+        return false;
+    const body = value;
+    if (body.page === null || typeof body.page !== 'object' || !Array.isArray(body.rows))
+        return false;
+    const page = body.page;
+    if (page.limits === null || typeof page.limits !== 'object')
+        return false;
+    const limits = page.limits;
+    if (!hasOnlyKeys(body, ['status', 'rows', 'next_cursor', 'page'])
+        || !hasOnlyKeys(page, [
+            'offset', 'row_count', 'total_rows', 'byte_count', 'estimated_tokens', 'limits',
+            'projection', 'expires_at_ms', 'snapshot', 'token_estimate'
+        ])
+        || !hasOnlyKeys(limits, ['rows', 'bytes', 'tokens']))
+        return false;
+    const shapeValid = body.status === 'completed'
+        && body.rows.every((row) => row !== null && typeof row === 'object' && !Array.isArray(row))
+        && (body.next_cursor === undefined || body.next_cursor === null
+            || typeof body.next_cursor === 'string' && body.next_cursor.length > 0)
+        && isNonNegativeInteger(page.offset)
+        && isNonNegativeInteger(page.row_count)
+        && page.row_count === body.rows.length
+        && isNonNegativeInteger(page.total_rows)
+        && page.offset <= page.total_rows
+        && page.row_count <= page.total_rows - page.offset
+        && isNonNegativeInteger(page.byte_count)
+        && isNonNegativeInteger(page.estimated_tokens)
+        && isNonNegativeInteger(limits.rows)
+        && isNonNegativeInteger(limits.bytes)
+        && isNonNegativeInteger(limits.tokens)
+        && Array.isArray(page.projection)
+        && page.projection.length > 0 && page.projection.length <= 128
+        && page.projection.every((column) => typeof column === 'string'
+            && column.length > 0 && column !== '*'
+            && Buffer.byteLength(column, 'utf8') <= 256)
+        && page.projection.reduce((bytes, column) => bytes + Buffer.byteLength(column, 'utf8'), 0) <= 16 * 1024
+        && isNonNegativeInteger(page.expires_at_ms)
+        && page.snapshot === 'retained_result'
+        && page.token_estimate === 'ceil(projected_json_bytes/4)';
+    if (!shapeValid)
+        return false;
+    const projection = page.projection;
+    if (new Set(projection).size !== projection.length
+        || body.rows.some((row) => {
+            const keys = Object.keys(row);
+            return keys.length !== projection.length
+                || projection.some((column) => !Object.prototype.hasOwnProperty.call(row, column));
+        }))
+        return false;
+    const byteCount = body.rows.reduce((bytes, row, index) => bytes + (index === 0 ? 0 : 1)
+        + Buffer.byteLength(JSON.stringify(row), 'utf8'), 2);
+    if (page.byte_count !== byteCount
+        || page.estimated_tokens !== Math.ceil(byteCount / 4))
+        return false;
+    if (limits.rows === 0 || limits.bytes === 0
+        || limits.tokens === 0
+        || limits.bytes > MAX_PAGE_JSON_RESPONSE_BYTES
+        || page.row_count > limits.rows
+        || page.byte_count > limits.bytes
+        || page.estimated_tokens > limits.tokens)
+        return false;
+    const hasMore = page.offset + page.row_count < page.total_rows;
+    if (hasMore && page.row_count === 0
+        || hasMore !== (typeof body.next_cursor === 'string'))
+        return false;
+    if (typeof body.next_cursor === 'string'
+        && Buffer.byteLength(body.next_cursor, 'utf8') > 2_048)
+        return false;
+    if (page.expires_at_ms === 0)
+        return false;
+    if (initialOptions === undefined)
+        return true;
+    return page.offset === 0
+        && JSON.stringify(page.projection) === JSON.stringify(initialOptions.projection)
+        && limits.rows <= initialOptions.pageSizeRows
+        && (initialOptions.maxPageBytes === undefined
+            || limits.bytes <= initialOptions.maxPageBytes)
+        && (initialOptions.maxPageTokens === undefined
+            || limits.tokens <= initialOptions.maxPageTokens)
+        && (initialOptions.maxOutputRows === undefined
+            || page.total_rows <= initialOptions.maxOutputRows)
+        && (initialOptions.maxOutputBytes === undefined
+            || page.byte_count <= initialOptions.maxOutputBytes);
+}
+function remoteSqlPage(page) {
+    return {
+        status: page.status,
+        rows: page.rows,
+        nextCursor: page.next_cursor ?? undefined,
+        page: {
+            offset: page.page.offset,
+            rowCount: page.page.row_count,
+            totalRows: page.page.total_rows,
+            byteCount: page.page.byte_count,
+            estimatedTokens: page.page.estimated_tokens,
+            limits: page.page.limits,
+            projection: page.page.projection,
+            expiresAtMs: page.page.expires_at_ms,
+            snapshot: page.page.snapshot,
+            tokenEstimate: page.page.token_estimate
+        }
+    };
+}
+class RetryIdempotentSqlError extends Error {
+    outcome;
+    constructor(outcome) {
+        super(outcome.message);
+        this.outcome = outcome;
+    }
+}
+class QueryNotRetainedError extends QueryOutcomeUnknownError {
+    constructor(queryId, message) {
+        super(queryId, message, { retryable: false, serverState: 'not_found' });
+    }
+}
+class InvalidQueryStatusError extends QueryOutcomeUnknownError {
+    constructor(queryId, message) {
+        super(queryId, `invalid query status response: ${message}`, {
+            retryable: false,
+            serverState: 'invalid_status'
+        });
+    }
+}
+function remoteEpoch(text, value) {
+    if (text !== undefined && text !== null) {
+        if (!/^\d+$/.test(text) || BigInt(text) > MAX_U64) {
+            throw new KitError('invalid last_commit_epoch_text from server');
+        }
+        return BigInt(text);
+    }
+    if (value === undefined || value === null)
+        return undefined;
+    if (!Number.isSafeInteger(value) || value < 0) {
+        throw new KitError('server returned an unsafe numeric commit epoch', 'QUERY_OUTCOME_UNKNOWN');
+    }
+    return BigInt(value);
+}
+function mergedCommitState(nested, top) {
+    if (nested === true || top === true)
+        return true;
+    return nested ?? top ?? null;
+}
+function recoveryStatusIsDecisive(status) {
+    return TERMINAL_SQL_STATES.has(status.state)
+        || mergedCommitState(status.outcome?.committed, status.committed) === true;
+}
+function maxKnown(left, right) {
+    if (left === undefined || left === null)
+        return right ?? undefined;
+    if (right === undefined || right === null)
+        return left;
+    return Math.max(left, right);
+}
+function cancelOutcome(value) {
+    return {
+        accepted: 'accepted',
+        cancellation_requested: 'accepted',
+        already_cancelling: 'already_cancelling',
+        cancelling: 'already_cancelling',
+        too_late: 'too_late',
+        commit_critical: 'too_late',
+        already_finished: 'already_finished',
+        finished: 'already_finished',
+        not_found: 'not_found',
+        pre_cancelled: 'pre_cancelled'
+    }[String(value)];
+}
+function validateCancelResponse(value, queryId, httpStatus) {
+    if (value === null || typeof value !== 'object') {
+        throw new KitError('SQL cancellation response was not an object', 'REMOTE_PROTOCOL');
+    }
+    const body = value;
+    if (!hasOnlyKeys(body, [
+        'query_id', 'state', 'cancel_outcome', 'status', 'terminal_state', 'code',
+        'committed', 'committed_statements', 'last_commit_epoch', 'last_commit_epoch_text',
+        'first_commit_statement_index', 'last_commit_statement_index', 'completed_statements',
+        'statement_index', 'cancellation_reason', 'retryable', 'server_state', 'outcome', 'error',
+        'terminal_error'
+    ])) {
+        throw new KitError('SQL cancellation response has unknown fields', 'REMOTE_PROTOCOL');
+    }
+    if (body.outcome !== undefined && body.outcome !== null
+        && (typeof body.outcome !== 'object'
+            || !hasOnlyKeys(body.outcome, [
+                'committed', 'committed_statements', 'last_commit_epoch', 'last_commit_epoch_text',
+                'first_commit_statement_index', 'last_commit_statement_index', 'completed_statements',
+                'statement_index', 'serialization'
+            ]))) {
+        throw new KitError('SQL cancellation outcome has unknown fields', 'REMOTE_PROTOCOL');
+    }
+    if (body.error !== undefined && body.error !== null
+        && (typeof body.error !== 'object'
+            || !hasOnlyKeys(body.error, [
+                'code', 'message', 'query_id', 'committed', 'retryable'
+            ]))) {
+        throw new KitError('SQL cancellation error has unknown fields', 'REMOTE_PROTOCOL');
+    }
+    if (body.terminal_error !== undefined && body.terminal_error !== null
+        && (typeof body.terminal_error !== 'object'
+            || !hasOnlyKeys(body.terminal_error, [
+                'code', 'category'
+            ])
+            || typeof body.terminal_error.code !== 'string'
+            || body.terminal_error.code.length === 0
+            || typeof body.terminal_error.category !== 'string'
+            || body.terminal_error.category.length === 0)) {
+        throw new KitError('SQL cancellation terminal error has invalid fields', 'REMOTE_PROTOCOL');
+    }
+    const durable = body.outcome;
+    if (durable != null) {
+        const required = [
+            'committed', 'committed_statements', 'last_commit_epoch', 'last_commit_epoch_text',
+            'first_commit_statement_index', 'last_commit_statement_index', 'completed_statements',
+            'statement_index', 'serialization'
+        ];
+        if (!required.every((field) => Object.prototype.hasOwnProperty.call(durable, field))
+            || ![null, true, false].includes(durable.committed)
+            || ['committed_statements', 'first_commit_statement_index',
+                'last_commit_statement_index', 'completed_statements', 'statement_index']
+                .some((field) => !isOptionalNonNegativeInteger(durable[field]))
+            || !isOptionalEpoch(durable.last_commit_epoch, durable.last_commit_epoch_text)
+            || !['not_started', 'in_progress', 'succeeded', 'failed', 'unknown']
+                .includes(durable.serialization)) {
+            throw new KitError('SQL cancellation outcome fields are invalid', 'REMOTE_PROTOCOL');
+        }
+    }
+    if (body.committed !== undefined && ![null, true, false]
+        .includes(body.committed)) {
+        throw new KitError('SQL cancellation committed field is invalid', 'REMOTE_PROTOCOL');
+    }
+    for (const field of ['committed_statements', 'first_commit_statement_index',
+        'last_commit_statement_index', 'completed_statements', 'statement_index']) {
+        if (body[field] !== undefined && !isOptionalNonNegativeInteger(body[field])) {
+            throw new KitError(`SQL cancellation ${field} is invalid`, 'REMOTE_PROTOCOL');
+        }
+        if (durable != null && body[field] !== undefined
+            && !sameOptional(body[field], durable[field])) {
+            throw new KitError(`SQL cancellation ${field} disagrees with outcome`, 'REMOTE_PROTOCOL');
+        }
+    }
+    if ((body.last_commit_epoch !== undefined || body.last_commit_epoch_text !== undefined)
+        && !isOptionalEpoch(body.last_commit_epoch, body.last_commit_epoch_text)) {
+        throw new KitError('SQL cancellation commit epoch is invalid', 'REMOTE_PROTOCOL');
+    }
+    if (durable != null
+        && (body.committed !== undefined && !sameOptional(body.committed, durable.committed)
+            || (body.last_commit_epoch !== undefined || body.last_commit_epoch_text !== undefined)
+                && receiptEpoch(body.last_commit_epoch, body.last_commit_epoch_text)
+                    !== receiptEpoch(durable.last_commit_epoch, durable.last_commit_epoch_text))) {
+        throw new KitError('SQL cancellation outcome metadata disagrees', 'REMOTE_PROTOCOL');
+    }
+    if (body.status !== undefined && (typeof body.status !== 'string'
+        || !QUERY_STATUSES.has(body.status) && body.status !== 'unknown')) {
+        throw new KitError('SQL cancellation status is invalid', 'REMOTE_PROTOCOL');
+    }
+    if (body.terminal_state !== undefined && body.terminal_state !== null
+        && (typeof body.terminal_state !== 'string'
+            || body.terminal_state !== body.status)) {
+        throw new KitError('SQL cancellation terminal state is invalid', 'REMOTE_PROTOCOL');
+    }
+    if (body.retryable !== undefined && typeof body.retryable !== 'boolean') {
+        throw new KitError('SQL cancellation retryable field is invalid', 'REMOTE_PROTOCOL');
+    }
+    if (body.server_state !== undefined && (typeof body.server_state !== 'string'
+        || !QUERY_STATES.has(body.server_state) && body.server_state !== 'not_found')) {
+        throw new KitError('SQL cancellation server state is invalid', 'REMOTE_PROTOCOL');
+    }
+    if (body.cancellation_reason !== undefined && body.cancellation_reason !== null
+        && (typeof body.cancellation_reason !== 'string'
+            || !['none', 'client_request', 'deadline', 'client_disconnected',
+                'session_closed', 'server_shutdown'].includes(body.cancellation_reason))) {
+        throw new KitError('SQL cancellation reason is invalid', 'REMOTE_PROTOCOL');
+    }
+    const detail = body.error;
+    if (detail != null
+        && (typeof detail.code !== 'string' || detail.code.length === 0
+            || typeof detail.message !== 'string' || detail.message.length === 0
+            || detail.query_id !== undefined && detail.query_id !== null
+                && typeof detail.query_id !== 'string'
+            || detail.committed !== undefined
+                && ![null, true, false].includes(detail.committed)
+            || detail.retryable !== undefined && typeof detail.retryable !== 'boolean')) {
+        throw new KitError('SQL cancellation error fields are invalid', 'REMOTE_PROTOCOL');
+    }
+    if (body.query_id !== queryId) {
+        throw new KitError('SQL cancellation query ID does not match the request', 'REMOTE_PROTOCOL');
+    }
+    const decodeField = (name) => {
+        const raw = body[name];
+        if (raw === undefined || raw === null)
+            return undefined;
+        const decoded = cancelOutcome(raw);
+        if (decoded === undefined) {
+            throw new KitError(`SQL cancellation ${name} is invalid`, 'REMOTE_PROTOCOL');
+        }
+        return decoded;
+    };
+    const outcome = decodeField('cancel_outcome');
+    let state = decodeField('state');
+    if (outcome === 'not_found' && state === undefined && body.server_state === 'not_found') {
+        state = 'not_found';
+    }
+    if (outcome === undefined || state === undefined) {
+        throw new KitError('SQL cancellation state and outcome are required', 'REMOTE_PROTOCOL');
+    }
+    if (outcome !== state) {
+        throw new KitError('SQL cancellation state and outcome disagree', 'REMOTE_PROTOCOL');
+    }
+    const result = outcome;
+    const compatible = httpStatus === 202 && ['accepted', 'pre_cancelled'].includes(result ?? '')
+        || httpStatus === 200 && ['already_cancelling', 'already_finished'].includes(result ?? '')
+        || httpStatus === 409 && result === 'too_late'
+        || httpStatus === 404 && result === 'not_found';
+    if (!compatible) {
+        throw new KitError('SQL cancellation HTTP status and outcome disagree', 'REMOTE_PROTOCOL');
+    }
+    const terminal = body.terminal_error;
+    if (result === 'pre_cancelled') {
+        if (terminal != null
+            && (terminal.code !== 'QUERY_CANCELLED' || terminal.category !== 'cancellation')) {
+            throw new KitError('SQL cancellation terminal error disagrees with outcome', 'REMOTE_PROTOCOL');
+        }
+    }
+    else if (terminal != null) {
+        throw new KitError('SQL cancellation terminal error disagrees with outcome', 'REMOTE_PROTOCOL');
+    }
+    return result;
+}
+function exactNativeValue(values, valid) {
+    let exact = undefined;
+    for (const value of values) {
+        if (value === undefined)
+            continue;
+        if (!valid(value) || exact !== undefined && !Object.is(exact, value)) {
+            throw new Error('conflicting native response fields');
+        }
+        exact = value;
+    }
+    return exact;
+}
+function nativeRemoteWriteEpoch(...sources) {
+    let exact;
+    const merge = (value, text) => {
+        if (value === undefined || value === null)
+            return;
+        let parsed;
+        if (text) {
+            if (typeof value !== 'string' || !/^\d+$/u.test(value)
+                || BigInt(value).toString() !== value)
+                throw new Error('invalid exact commit epoch');
+            parsed = BigInt(value);
+        }
+        else if (typeof value === 'bigint')
+            parsed = value;
+        else if (typeof value === 'number' && Number.isSafeInteger(value))
+            parsed = BigInt(value);
+        else if (typeof value === 'string' && /^\d+$/u.test(value)
+            && BigInt(value).toString() === value)
+            parsed = BigInt(value);
+        else
+            throw new Error('invalid commit epoch');
+        if (parsed < 0n || parsed > MAX_U64)
+            throw new Error('commit epoch outside u64 range');
+        if (exact !== undefined && exact !== parsed)
+            throw new Error('conflicting commit epoch fields');
+        exact = parsed;
+    };
+    for (const source of sources) {
+        merge(source.lastCommitEpoch, false);
+        merge(source.epoch, false);
+        merge(source.lastCommitEpochText, true);
+        merge(source.epochText, true);
+    }
+    return exact;
+}
+function nativeRemoteWriteError(error) {
+    const original = error instanceof Error ? error : new Error(String(error));
+    if (error instanceof KitError)
+        return error;
+    if (error === null || typeof error !== 'object')
+        return original;
+    const top = error;
+    const details = top.remoteQueryError !== null && typeof top.remoteQueryError === 'object'
+        ? top.remoteQueryError
+        : top;
+    const candidateCodes = [top.code, details.code].filter((value) => typeof value === 'string');
+    if (!candidateCodes.some((code) => code === 'COMMIT_OUTCOME'
+        || code === 'QUERY_OUTCOME_UNKNOWN'))
+        return original;
+    try {
+        if (details !== top && !hasOnlyKeys(details, [
+            'code', 'message', 'queryId', 'status', 'httpStatus', 'outcomeKnown', 'committed',
+            'epoch', 'epochText', 'committedStatements', 'lastCommitEpoch',
+            'lastCommitEpochText', 'firstCommitStatementIndex', 'lastCommitStatementIndex',
+            'completedStatements', 'statementIndex', 'cancelOutcome', 'cancellationReason',
+            'retryable', 'serverState', 'terminalState'
+        ]))
+            throw new Error('unknown native response field');
+        const code = exactNativeValue([top.code, details.code], (value) => value === 'COMMIT_OUTCOME' || value === 'QUERY_OUTCOME_UNKNOWN');
+        const queryId = exactNativeValue([top.queryId, top.query_id, details.queryId, details.query_id], (value) => typeof value === 'string'
+            && (value === 'unknown' || /^[0-9a-f]{32}$/u.test(value))) ?? 'unknown';
+        const message = exactNativeValue([top.message, details.message], (value) => typeof value === 'string') ?? original.message;
+        const retryable = exactNativeValue([top.retryable, details.retryable], (value) => typeof value === 'boolean');
+        const serverState = exactNativeValue([top.serverState, details.serverState], (value) => typeof value === 'string');
+        const status = exactNativeValue([top.status, details.status], (value) => typeof value === 'string');
+        const committed = exactNativeValue([top.committed, details.committed], (value) => value === null || typeof value === 'boolean');
+        const outcomeKnown = exactNativeValue([top.outcomeKnown, details.outcomeKnown], (value) => typeof value === 'boolean');
+        for (const field of [
+            'committedStatements', 'firstCommitStatementIndex', 'lastCommitStatementIndex',
+            'completedStatements', 'statementIndex'
+        ]) {
+            exactNativeValue([top[field], details[field]], (value) => value === null || isNonNegativeInteger(value));
+        }
+        for (const field of [
+            'cancelOutcome', 'cancellationReason', 'terminalState'
+        ]) {
+            exactNativeValue([top[field], details[field]], (value) => value === null || typeof value === 'string');
+        }
+        const lastCommitEpoch = nativeRemoteWriteEpoch(details, top);
+        const metadata = {
+            retryable,
+            serverState: serverState ?? status
+        };
+        if (code === 'QUERY_OUTCOME_UNKNOWN') {
+            if (committed !== null || outcomeKnown !== false || retryable !== false) {
+                throw new Error('invalid unknown outcome metadata');
+            }
+            return new QueryOutcomeUnknownError(queryId, message, metadata);
+        }
+        if (committed !== true || outcomeKnown !== true || retryable !== false
+            || lastCommitEpoch === undefined) {
+            throw new Error('invalid committed outcome metadata');
+        }
+        return new CommitOutcomeError(queryId, message || 'remote write committed but response failed', { committed: true, lastCommitEpoch }, metadata);
+    }
+    catch {
+        return new QueryOutcomeUnknownError('unknown', 'invalid committed outcome metadata from server', { retryable: false, serverState: 'invalid_outcome' });
+    }
+}
+function parseRemoteWriteJson(response, operation, commitProven = true) {
+    try {
+        return parseJsonStrict(response);
+    }
+    catch {
+        if (!commitProven) {
+            throw new QueryOutcomeUnknownError('unknown', `remote ${operation} finished but its response was invalid`, { retryable: false, serverState: 'invalid_response' });
+        }
+        throw new CommitOutcomeError('unknown', `remote ${operation} committed but its response was invalid`, { committed: true }, { retryable: false, serverState: 'invalid_response' });
+    }
+}
+function parseProcedureCallResponse(response) {
+    const value = parseRemoteWriteJson(response, 'procedure call', false);
+    const invalid = () => {
+        throw new QueryOutcomeUnknownError('unknown', 'remote procedure call returned invalid commit metadata', { retryable: false, serverState: 'invalid_response' });
+    };
+    if (value === null || typeof value !== 'object')
+        return invalid();
+    const body = value;
+    const fields = ['status', 'committed', 'epoch', 'epoch_text', 'result'];
+    if (!hasOnlyKeys(body, fields) || !hasAllKeys(body, fields)
+        || body.status !== 'ok' || typeof body.committed !== 'boolean')
+        return invalid();
+    if (body.committed) {
+        if (!isNonNegativeInteger(body.epoch) || typeof body.epoch_text !== 'string'
+            || !isOptionalEpoch(body.epoch, body.epoch_text))
+            return invalid();
+    }
+    else if (body.epoch !== null || body.epoch_text !== null)
+        return invalid();
+    return value;
+}
 /**
  * A thin Kit client for a running `mongreldb-server` daemon.
  *
@@ -20,11 +1136,70 @@ import { createVirtualTableSql, dropVirtualTableSql } from './external.js';
 export class RemoteDatabase {
     inner;
     url;
+    #authorization;
     capabilities;
     /** Connect (lazily) to a daemon at `url`, e.g. `http://127.0.0.1:8453`. */
-    constructor(url) {
-        this.url = url.replace(/\/$/, '');
-        this.inner = new NativeRemoteDatabase(this.url);
+    constructor(url, options = {}) {
+        let parsed;
+        try {
+            parsed = new URL(url);
+        }
+        catch {
+            throw new TypeError('remote URL must be a valid http:// or https:// URL');
+        }
+        if (!['http:', 'https:'].includes(parsed.protocol) || !parsed.hostname) {
+            throw new TypeError('remote URL must use http:// or https:// and include a host');
+        }
+        if (parsed.username || parsed.password) {
+            throw new TypeError('remote credentials must use the auth option, not the URL');
+        }
+        if (parsed.search || parsed.hash) {
+            throw new TypeError('remote URL must not include a query or fragment');
+        }
+        if (options.auth && 'bearerToken' in options.auth
+            && (typeof options.auth.bearerToken !== 'string'
+                || options.auth.bearerToken.trim().length === 0
+                || containsHttpHeaderControl(options.auth.bearerToken))) {
+            throw new TypeError('bearer token must not be empty');
+        }
+        if (options.auth && !('bearerToken' in options.auth)
+            && (typeof options.auth.username !== 'string'
+                || options.auth.username.length === 0
+                || options.auth.username.includes(':')
+                || containsHttpHeaderControl(options.auth.username)
+                || typeof options.auth.password !== 'string'
+                || containsHttpHeaderControl(options.auth.password))) {
+            throw new TypeError('basic-auth username must be non-empty and contain no colon');
+        }
+        this.url = `${parsed.origin}${parsed.pathname}`.replace(/\/$/, '');
+        const nativeOptions = options.auth && 'bearerToken' in options.auth
+            ? { bearerToken: options.auth.bearerToken }
+            : options.auth
+                ? { username: options.auth.username, password: options.auth.password }
+                : undefined;
+        this.#authorization = options.auth && 'bearerToken' in options.auth
+            ? `Bearer ${options.auth.bearerToken}`
+            : options.auth
+                ? `Basic ${Buffer.from(`${options.auth.username}:${options.auth.password}`, 'utf8').toString('base64')}`
+                : undefined;
+        const NativeRemote = NativeRemoteDatabase;
+        this.inner = new NativeRemote(this.url, nativeOptions);
+    }
+    request(path, init = {}) {
+        const headers = new Headers(init.headers);
+        if (this.#authorization)
+            headers.set('authorization', this.#authorization);
+        return fetch(`${this.url}${path}`, { ...init, headers });
+    }
+    async recoveryRequest(path, init, timeoutMs) {
+        const controller = new AbortController();
+        const timer = setTimeout(() => controller.abort(), timeoutMs);
+        try {
+            return await this.request(path, { ...init, signal: controller.signal });
+        }
+        finally {
+            clearTimeout(timer);
+        }
     }
     /** Liveness check; returns the server's health string (throws if down). */
     health() {
@@ -49,119 +1224,631 @@ export class RemoteDatabase {
     }
     /** Run a SQL query without blocking the Node event loop. */
     async sql(sql, options) {
-        if (options?.timeoutMs !== undefined || options?.signal !== undefined || options?.queryId !== undefined) {
-            return this.startSql(sql, options).result;
-        }
-        return this.executeSql(sql);
+        return this.startSql(sql, options).result;
     }
     async sqlRows(sql, options) {
         return [...(await this.sql(sql, options))].map((row) => ({ ...row }));
     }
     startSql(sql, options = {}) {
-        const queryId = options.queryId ?? randomBytes(16).toString('hex');
+        const queryId = normalizeQueryId(options.queryId ?? randomBytes(16).toString('hex'));
         if (options.timeoutMs !== undefined && (!Number.isSafeInteger(options.timeoutMs) || options.timeoutMs <= 0)) {
             throw new RangeError('timeoutMs must be a positive safe integer');
         }
+        for (const [name, value] of [['maxOutputRows', options.maxOutputRows], ['maxOutputBytes', options.maxOutputBytes]]) {
+            if (value !== undefined && (!Number.isSafeInteger(value) || value <= 0)) {
+                throw new RangeError(`${name} must be a positive safe integer`);
+            }
+        }
         if (options.signal?.aborted) {
             return {
                 id: queryId,
-                result: Promise.reject(new QueryCancelledError(queryId)),
-                cancel: async () => { }
+                result: Promise.reject(preExecutionCancellationError(queryId, 'pre_cancelled')),
+                cancel: async () => 'pre_cancelled',
+                status: async () => ({
+                    queryId,
+                    phase: 'pre_cancelled',
+                    terminalState: 'cancelled_before_start',
+                    serverState: 'pre_cancelled',
+                    operation: 'sql',
+                    committed: false,
+                    durableOutcome: { committed: false, committedStatements: 0 },
+                    terminalErrorCode: 'QUERY_CANCELLED',
+                    completedStatements: 0,
+                    statementIndex: 0,
+                    cancellationReason: 'client_request',
+                    cancelOutcome: 'pre_cancelled',
+                    retryable: false
+                })
             };
         }
         const controller = new AbortController();
-        let cancelled = false;
-        const cancel = async () => {
-            if (cancelled)
-                return;
-            cancelled = true;
-            const request = this.cancelSql(queryId);
-            controller.abort();
-            await request;
+        let executionStarted = false;
+        let cancelPromise;
+        let signalCancelPromise;
+        const applyCancelOutcome = (outcome) => {
+            if (outcome === 'accepted' || outcome === 'already_cancelling' || outcome === 'pre_cancelled') {
+                controller.abort();
+            }
+            return outcome;
+        };
+        const cancel = () => {
+            cancelPromise ??= this.cancelSql(queryId).then(applyCancelOutcome);
+            return cancelPromise;
+        };
+        const cancelForSignal = () => {
+            signalCancelPromise ??= this.cancelSqlForSignal(queryId).then(applyCancelOutcome);
+            return signalCancelPromise;
         };
         const onAbort = () => {
-            void cancel();
+            void cancelForSignal().catch(() => controller.abort());
         };
         options.signal?.addEventListener('abort', onAbort, { once: true });
         const result = this.requireSqlCancellation()
-            .then(() => this.executeSql(sql, queryId, options.timeoutMs, controller.signal))
-            .catch((error) => {
-            if (cancelled || options.signal?.aborted) {
+            .then(async () => {
+            if (options.signal?.aborted) {
+                const outcome = await cancelForSignal();
+                throw preExecutionCancellationError(queryId, outcome);
+            }
+            executionStarted = true;
+            return this.executeSql(sql, queryId, options.timeoutMs, options.maxOutputRows, options.maxOutputBytes, controller.signal);
+        })
+            .catch(async (error) => {
+            const outcome = await (signalCancelPromise ?? cancelPromise)?.catch(() => undefined);
+            if (!executionStarted && options.signal?.aborted) {
+                if (error instanceof CapabilityUnsupportedError)
+                    throw error;
+                if (error instanceof KitError && outcome === undefined)
+                    throw error;
+                throw preExecutionCancellationError(queryId, outcome);
+            }
+            if (outcome === 'pre_cancelled') {
                 throw new QueryCancelledError(queryId);
             }
-            throw error;
+            if (outcome === 'accepted' || outcome === 'already_cancelling'
+                || outcome === 'too_late' || outcome === 'already_finished') {
+                return this.resolveLostQueryOutcome(queryId, error);
+            }
+            if (error instanceof KitError)
+                throw error;
+            return this.resolveLostQueryOutcome(queryId, error);
         })
             .finally(() => options.signal?.removeEventListener('abort', onAbort));
-        return { id: queryId, result, cancel };
+        return { id: queryId, result, cancel, status: () => this.queryStatus(queryId) };
     }
     async cancelSql(queryId) {
+        queryId = normalizeQueryId(queryId);
         await this.requireSqlCancellation();
-        const response = await fetch(`${this.url}/queries/${queryId}/cancel`, { method: 'POST' });
-        if (response.ok || response.status === 409 || response.status === 404)
-            return;
+        return this.sendCancelSql(queryId);
+    }
+    async cancelSqlForSignal(queryId) {
+        await this.requireSqlCancellation();
+        return this.sendCancelSql(queryId, SQL_RECOVERY_REQUEST_TIMEOUT_MS);
+    }
+    async sendCancelSql(queryId, timeoutMs) {
+        const path = `/queries/${queryId}/cancel`;
+        const response = timeoutMs === undefined
+            ? await this.request(path, { method: 'POST' })
+            : await this.recoveryRequest(path, { method: 'POST' }, timeoutMs);
+        if ([200, 202, 404, 409].includes(response.status)) {
+            const body = await responseJsonStrict(response).catch(() => {
+                throw new KitError('SQL cancellation response was not valid JSON', 'REMOTE_PROTOCOL');
+            });
+            return validateCancelResponse(body, queryId, response.status);
+        }
         throw new KitError(`SQL cancellation failed with HTTP ${response.status}`);
     }
-    async executeSql(sql, queryId, timeoutMs, signal) {
-        const response = await fetch(`${this.url}/sql`, {
+    async queryStatus(queryId) {
+        queryId = normalizeQueryId(queryId);
+        const status = await this.rawQueryStatus(queryId);
+        const committed = mergedCommitState(status.outcome?.committed, status.committed);
+        return {
+            queryId: status.query_id,
+            phase: status.server_state || status.state,
+            terminalState: status.terminal_state ?? undefined,
+            serverState: status.server_state || status.state,
+            operation: status.operation ?? 'sql',
+            committed,
+            durableOutcome: {
+                committed,
+                committedStatements: maxKnown(status.outcome?.committed_statements, status.committed_statements) ?? null,
+                lastCommitEpoch: remoteEpoch(status.outcome?.last_commit_epoch_text ?? status.last_commit_epoch_text, status.outcome?.last_commit_epoch ?? status.last_commit_epoch),
+                firstCommitStatementIndex: status.outcome?.first_commit_statement_index
+                    ?? status.first_commit_statement_index ?? undefined,
+                lastCommitStatementIndex: status.outcome?.last_commit_statement_index
+                    ?? status.last_commit_statement_index ?? undefined
+            },
+            terminalErrorCode: status.terminal_error?.code,
+            terminalErrorCategory: status.terminal_error?.category,
+            completedStatements: status.outcome?.completed_statements ?? status.completed_statements ?? null,
+            statementIndex: status.outcome?.statement_index ?? status.statement_index ?? null,
+            cancellationReason: status.cancellation_reason ?? 'none',
+            cancelOutcome: status.cancel_outcome ?? undefined,
+            retryable: status.retryable
+        };
+    }
+    async sqlPage(sql, options) {
+        await this.requireSqlPagination();
+        if (options.projection.length === 0 || options.projection.length > 128
+            || options.projection.some((column) => typeof column !== 'string'
+                || column.length === 0 || column === '*'
+                || Buffer.byteLength(column, 'utf8') > 256)
+            || new Set(options.projection).size !== options.projection.length
+            || options.projection.reduce((bytes, column) => bytes + Buffer.byteLength(column, 'utf8'), 0) > 16 * 1024) {
+            throw new RangeError('projection must contain 1 to 128 unique explicit columns');
+        }
+        for (const [name, value] of [
+            ['pageSizeRows', options.pageSizeRows],
+            ['timeoutMs', options.timeoutMs],
+            ['maxPageBytes', options.maxPageBytes],
+            ['maxPageTokens', options.maxPageTokens],
+            ['maxOutputRows', options.maxOutputRows],
+            ['maxOutputBytes', options.maxOutputBytes]
+        ]) {
+            if (value !== undefined && (!Number.isSafeInteger(value) || value <= 0)) {
+                throw new RangeError(`${name} must be a positive safe integer`);
+            }
+        }
+        const queryId = normalizeQueryId(options.queryId ?? randomBytes(16).toString('hex'));
+        let response;
+        try {
+            response = await this.request('/sql', {
+                method: 'POST',
+                headers: { 'content-type': 'application/json' },
+                body: JSON.stringify({
+                    sql,
+                    format: 'json',
+                    query_id: queryId,
+                    timeout_ms: options.timeoutMs,
+                    max_output_rows: options.maxOutputRows,
+                    max_output_bytes: options.maxOutputBytes,
+                    pagination: {
+                        page_size_rows: options.pageSizeRows,
+                        projection: options.projection,
+                        max_page_bytes: options.maxPageBytes,
+                        max_page_tokens: options.maxPageTokens
+                    }
+                })
+            });
+        }
+        catch (error) {
+            return this.resolveLostQueryOutcome(queryId, error);
+        }
+        if (!response.ok) {
+            const error = await remoteSqlError(response, queryId);
+            if (error instanceof QueryOutcomeUnknownError) {
+                return this.resolveLostQueryOutcome(queryId, error);
+            }
+            throw error;
+        }
+        if (response.headers.get('x-mongreldb-query-id') !== queryId) {
+            return this.resolveLostQueryOutcome(queryId, new Error('SQL response x-mongreldb-query-id does not match the request'));
+        }
+        const body = await responseJsonStrict(response, MAX_PAGE_JSON_RESPONSE_BYTES).catch((error) => this.resolveLostQueryOutcome(queryId, error));
+        if (!isRemoteSqlPage(body, options)) {
+            return this.resolveLostQueryOutcome(queryId, new Error('SQL pagination response was not a valid retained page'));
+        }
+        return remoteSqlPage(body);
+    }
+    async continueSqlPage(cursor) {
+        await this.requireSqlPagination();
+        if (cursor.length === 0 || Buffer.byteLength(cursor, 'utf8') > 2_048) {
+            throw new RangeError('cursor must contain 1 to 2048 UTF-8 bytes');
+        }
+        const response = await this.request('/sql/continue', {
+            method: 'POST',
+            headers: { 'content-type': 'application/json' },
+            body: JSON.stringify({ cursor })
+        });
+        if (!response.ok)
+            throw await remoteSqlError(response, 'unknown');
+        const body = await responseJsonStrict(response, MAX_PAGE_JSON_RESPONSE_BYTES).catch((error) => {
+            throw new SerializationError('unknown', error instanceof Error ? error.message : 'SQL continuation response was not valid JSON', { committed: false });
+        });
+        if (!isRemoteSqlPage(body)) {
+            throw new SerializationError('unknown', 'SQL continuation response was not a valid retained page', { committed: false });
+        }
+        return remoteSqlPage(body);
+    }
+    async executeIdempotentSql(sql, options) {
+        await this.requireSqlIdempotency();
+        if (options.idempotencyKey.length === 0
+            || Buffer.byteLength(options.idempotencyKey, 'utf8') > 256) {
+            throw new RangeError('idempotencyKey must contain 1 to 256 bytes');
+        }
+        for (const [name, value] of [
+            ['timeoutMs', options.timeoutMs],
+            ['maxOutputRows', options.maxOutputRows],
+            ['maxOutputBytes', options.maxOutputBytes]
+        ]) {
+            if (value !== undefined && (!Number.isSafeInteger(value) || value <= 0)) {
+                throw new RangeError(`${name} must be a positive safe integer`);
+            }
+        }
+        const queryId = normalizeQueryId(options.queryId ?? randomBytes(16).toString('hex'));
+        try {
+            return await this.executeIdempotentSqlOnce(sql, options, queryId);
+        }
+        catch (error) {
+            if (!(error instanceof RetryIdempotentSqlError))
+                throw error;
+            await this.requireFreshSqlIdempotency();
+            let replayQueryId = randomBytes(16).toString('hex');
+            while (replayQueryId === queryId)
+                replayQueryId = randomBytes(16).toString('hex');
+            try {
+                return await this.executeIdempotentSqlOnce(sql, options, replayQueryId, queryId);
+            }
+            catch (replayError) {
+                if (replayError instanceof RetryIdempotentSqlError)
+                    throw replayError.outcome;
+                throw replayError;
+            }
+        }
+    }
+    async executeIdempotentSqlOnce(sql, options, queryId, expectedOriginalQueryId) {
+        let response;
+        try {
+            response = await this.request('/sql', {
+                method: 'POST',
+                headers: { 'content-type': 'application/json' },
+                body: JSON.stringify({
+                    sql,
+                    format: 'json',
+                    query_id: queryId,
+                    timeout_ms: options.timeoutMs,
+                    max_output_rows: options.maxOutputRows,
+                    max_output_bytes: options.maxOutputBytes,
+                    idempotency_key: options.idempotencyKey
+                })
+            });
+        }
+        catch (error) {
+            return this.resolveIdempotentSqlLoss(queryId, error);
+        }
+        if (!response.ok) {
+            const error = await remoteSqlError(response, queryId);
+            if (error instanceof QueryOutcomeUnknownError) {
+                return this.resolveIdempotentSqlLoss(queryId, error);
+            }
+            throw error;
+        }
+        const body = await responseJsonStrict(response).catch((error) => this.resolveIdempotentSqlLoss(queryId, error));
+        if (!isRemoteSqlWriteReceipt(body, queryId, expectedOriginalQueryId)) {
+            return this.resolveIdempotentSqlLoss(queryId, new Error('SQL idempotency response was not a valid durable receipt'));
+        }
+        const receipt = {
+            queryId: body.query_id,
+            originalQueryId: body.original_query_id,
+            status: body.status,
+            terminalState: body.terminal_state ?? undefined,
+            serverState: body.server_state ?? undefined,
+            cancelOutcome: body.cancel_outcome ?? undefined,
+            cancellationReason: body.cancellation_reason ?? undefined,
+            committed: body.committed,
+            committedStatements: body.committed_statements,
+            lastCommitEpoch: remoteEpoch(body.outcome.last_commit_epoch_text ?? body.last_commit_epoch_text, body.outcome.last_commit_epoch ?? body.last_commit_epoch),
+            firstCommitStatementIndex: body.first_commit_statement_index
+                ?? body.outcome.first_commit_statement_index
+                ?? undefined,
+            lastCommitStatementIndex: body.last_commit_statement_index
+                ?? body.outcome.last_commit_statement_index
+                ?? undefined,
+            completedStatements: body.completed_statements,
+            statementIndex: body.statement_index,
+            retryable: body.retryable,
+            idempotencyReplayed: body.idempotency_replayed,
+            idempotencyPersisted: body.idempotency_persisted,
+            idempotencyExpiresAtMs: body.idempotency_expires_at_ms,
+            terminalError: body.terminal_error ?? undefined
+        };
+        if (response.headers.get('x-mongreldb-query-id') !== queryId) {
+            if (receipt.committed) {
+                throw new CommitOutcomeError(queryId, 'SQL committed but x-mongreldb-query-id did not match the request', {
+                    committed: true,
+                    committedStatements: receipt.committedStatements,
+                    lastCommitEpoch: receipt.lastCommitEpoch,
+                    firstCommitStatementIndex: receipt.firstCommitStatementIndex,
+                    lastCommitStatementIndex: receipt.lastCommitStatementIndex,
+                    completedStatements: receipt.completedStatements,
+                    statementIndex: receipt.statementIndex
+                }, {
+                    cancelOutcome: receipt.cancelOutcome,
+                    cancellationReason: receipt.cancellationReason,
+                    retryable: false,
+                    serverState: receipt.serverState
+                });
+            }
+            return this.resolveIdempotentSqlLoss(queryId, new Error('SQL response x-mongreldb-query-id does not match the request'));
+        }
+        return receipt;
+    }
+    async resolveIdempotentSqlLoss(queryId, cause) {
+        let status;
+        try {
+            status = await this.rawQueryStatus(queryId, SQL_RECOVERY_REQUEST_TIMEOUT_MS);
+        }
+        catch (error) {
+            if (error instanceof QueryNotRetainedError) {
+                throw new RetryIdempotentSqlError(error);
+            }
+            if (!(error instanceof QueryOutcomeUnknownError)) {
+                return this.resolveLostQueryOutcome(queryId, cause);
+            }
+            throw error;
+        }
+        return this.resolveLostQueryOutcome(queryId, cause, status);
+    }
+    async rawQueryStatus(queryId, recoveryTimeoutMs) {
+        await this.requireSqlCancellation();
+        const path = `/queries/${queryId}`;
+        const response = recoveryTimeoutMs === undefined
+            ? await this.request(path)
+            : await this.recoveryRequest(path, {}, recoveryTimeoutMs);
+        if (response.status === 404) {
+            const body = await responseJsonStrict(response).catch((error) => {
+                throw new InvalidQueryStatusError(queryId, error instanceof Error ? error.message : 'query-not-found response was not valid JSON');
+            });
+            if (!isQueryNotFoundResponse(body, queryId)) {
+                throw new InvalidQueryStatusError(queryId, 'query-not-found response fields were inconsistent');
+            }
+            throw new QueryNotRetainedError(queryId, `query ${queryId} is not retained`);
+        }
+        if (!response.ok)
+            throw new KitError(`query status failed with HTTP ${response.status}`);
+        const body = await responseJsonStrict(response).catch((error) => {
+            throw new InvalidQueryStatusError(queryId, error instanceof Error ? error.message : 'response was not valid JSON');
+        });
+        if (!isRemoteQueryStatus(body, queryId)) {
+            throw new InvalidQueryStatusError(queryId, 'response fields were inconsistent');
+        }
+        return body;
+    }
+    async resolveLostQueryOutcome(queryId, cause, initialStatus) {
+        const deadline = Date.now() + SQL_RECOVERY_WINDOW_MS;
+        let status = initialStatus ?? await this.queryStatusForRecovery(queryId, deadline);
+        if (!status || !recoveryStatusIsDecisive(status)) {
+            await this.cancelSqlForRecovery(queryId, deadline);
+        }
+        while (Date.now() < deadline) {
+            if (status && recoveryStatusIsDecisive(status))
+                break;
+            status = await this.queryStatusForRecovery(queryId, deadline) ?? status;
+            if (status && recoveryStatusIsDecisive(status))
+                break;
+            const remaining = deadline - Date.now();
+            if (remaining > 0) {
+                await new Promise((resolve) => setTimeout(resolve, Math.min(SQL_RECOVERY_POLL_INTERVAL_MS, remaining)));
+            }
+        }
+        if (!status || !recoveryStatusIsDecisive(status)) {
+            throw new QueryOutcomeUnknownError(queryId, cause instanceof Error ? cause.message : 'SQL transport failed before terminal status was retained');
+        }
+        const outcome = status?.outcome;
+        const message = cause instanceof Error ? cause.message : 'SQL response was lost';
+        const committed = mergedCommitState(outcome?.committed, status.committed);
+        const metadata = {
+            cancelOutcome: status.cancel_outcome ?? undefined,
+            cancellationReason: status.cancellation_reason,
+            retryable: status.retryable,
+            serverState: status.server_state || status.state
+        };
+        if (committed === null) {
+            throw new QueryOutcomeUnknownError(queryId, message, metadata);
+        }
+        const durableOutcome = {
+            committed,
+            committedStatements: maxKnown(outcome?.committed_statements, status.committed_statements),
+            lastCommitEpoch: remoteEpoch(outcome?.last_commit_epoch_text ?? status.last_commit_epoch_text, outcome?.last_commit_epoch ?? status.last_commit_epoch),
+            firstCommitStatementIndex: outcome?.first_commit_statement_index
+                ?? status.first_commit_statement_index ?? undefined,
+            lastCommitStatementIndex: outcome?.last_commit_statement_index
+                ?? status.last_commit_statement_index ?? undefined,
+            completedStatements: outcome?.completed_statements ?? status.completed_statements ?? undefined,
+            statementIndex: outcome?.statement_index ?? status.statement_index ?? undefined
+        };
+        switch (status.terminal_error?.code) {
+            case 'QUERY_CANCELLED':
+            case 'QUERY_CANCELLED_AFTER_COMMIT':
+                throw new QueryCancelledError(queryId, message, durableOutcome, metadata);
+            case 'DEADLINE_EXCEEDED':
+            case 'DEADLINE_AFTER_COMMIT':
+                throw new QueryTimeoutError(queryId, message, durableOutcome, metadata);
+            case 'RESULT_LIMIT_EXCEEDED':
+                throw new ResultLimitExceededError(queryId, message, durableOutcome, metadata);
+            case 'SERIALIZATION_FAILED':
+            case 'SERIALIZATION_FAILED_AFTER_COMMIT':
+                throw new SerializationError(queryId, message, durableOutcome, metadata);
+            default:
+                if (durableOutcome.committed) {
+                    throw new CommitOutcomeError(queryId, message, durableOutcome, metadata);
+                }
+                if (status.state === 'completed') {
+                    throw new SerializationError(queryId, message, durableOutcome, metadata);
+                }
+                throw new QueryExecutionError(queryId, status.terminal_error?.code ?? 'QUERY_FAILED', message, durableOutcome, metadata);
+        }
+    }
+    recoveryTimeout(deadline) {
+        const remaining = deadline - Date.now();
+        return remaining > 0
+            ? Math.min(SQL_RECOVERY_REQUEST_TIMEOUT_MS, remaining)
+            : undefined;
+    }
+    async queryStatusForRecovery(queryId, deadline) {
+        const timeout = this.recoveryTimeout(deadline);
+        if (timeout === undefined)
+            return undefined;
+        return this.rawQueryStatus(queryId, timeout).catch(() => undefined);
+    }
+    async cancelSqlForRecovery(queryId, deadline) {
+        const timeout = this.recoveryTimeout(deadline);
+        if (timeout === undefined)
+            return;
+        const response = await this.recoveryRequest(`/queries/${queryId}/cancel`, { method: 'POST' }, timeout).catch(() => undefined);
+        if (response && [200, 202, 404, 409].includes(response.status)) {
+            const body = await responseJsonStrict(response).catch(() => undefined);
+            if (body !== undefined) {
+                try {
+                    validateCancelResponse(body, queryId, response.status);
+                }
+                catch {
+                    // Recovery remains outcome-unknown when control metadata is malformed.
+                }
+            }
+        }
+    }
+    async executeSql(sql, queryId, timeoutMs, maxOutputRows, maxOutputBytes, signal) {
+        const response = await this.request('/sql', {
             method: 'POST',
             headers: { 'content-type': 'application/json' },
-            body: JSON.stringify({ sql, format: 'arrow', query_id: queryId, timeout_ms: timeoutMs }),
+            body: JSON.stringify({
+                sql,
+                format: 'arrow',
+                query_id: queryId,
+                timeout_ms: timeoutMs,
+                max_output_rows: maxOutputRows,
+                max_output_bytes: maxOutputBytes
+            }),
             signal
         });
         if (!response.ok) {
-            throw await remoteSqlError(response, queryId ?? 'unknown');
+            const error = await remoteSqlError(response, queryId);
+            if (error instanceof QueryOutcomeUnknownError) {
+                return this.resolveLostQueryOutcome(queryId, error);
+            }
+            throw error;
+        }
+        if (response.headers.get('x-mongreldb-query-id') !== queryId) {
+            return this.resolveLostQueryOutcome(queryId, new Error('SQL response x-mongreldb-query-id does not match the request'));
         }
-        const bytes = new Uint8Array(await response.arrayBuffer());
+        const bytes = await responseBytesBounded(response, Math.min(maxOutputBytes ?? MAX_PAGE_JSON_RESPONSE_BYTES, MAX_PAGE_JSON_RESPONSE_BYTES));
         if (bytes.length === 0) {
             return tableFromJSON([]);
         }
         return tableFromIPC(bytes);
     }
-    async requireSqlCancellation() {
-        this.capabilities ??= fetch(`${this.url}/capabilities`).then(async (response) => {
-            if (response.status === 404)
-                return null;
-            if (!response.ok)
-                throw new KitError(`capability request failed with HTTP ${response.status}`);
-            const body = await response.json();
-            return body.sql_cancellation ?? null;
+    async loadCapabilities() {
+        const response = await this.request('/capabilities');
+        if (response.status === 404)
+            return null;
+        if (!response.ok)
+            throw new KitError(`capability request failed with HTTP ${response.status}`);
+        const capabilities = await responseJsonStrict(response).catch(() => {
+            throw new KitError('capability response was not valid bounded JSON', 'REMOTE_PROTOCOL');
         });
-        const capability = await this.capabilities;
-        if (capability?.version !== 1 || !capability.client_query_ids || !capability.cancel_endpoint) {
-            throw new KitUnsupportedError('server does not support SQL cancellation capability version 1');
+        if (!isRemoteCapabilities(capabilities)) {
+            throw new KitError('capability response had unknown or invalid fields', 'REMOTE_PROTOCOL');
+        }
+        return capabilities;
+    }
+    validateSqlCancellationCapability(capability) {
+        if (capability?.version !== 2 || !capability.client_query_ids || !capability.cancel_endpoint
+            || !capability.query_status || !capability.pre_registration_cancel) {
+            throw new CapabilityUnsupportedError('server does not support SQL cancellation capability version 2');
+        }
+        return capability;
+    }
+    validateSqlIdempotencyCapability(capability) {
+        if (capability?.version !== 1
+            || !capability.durable_pre_execution_intent
+            || !capability.replay_committed_receipt
+            || !capability.indeterminate_never_reexecutes) {
+            throw new CapabilityUnsupportedError('server does not support durable SQL idempotency capability version 1');
         }
         return capability;
     }
+    async requireSqlCancellation() {
+        this.capabilities ??= this.loadCapabilities();
+        const capability = (await this.capabilities)?.sql_cancellation;
+        return this.validateSqlCancellationCapability(capability);
+    }
+    async requireSqlPagination() {
+        await this.requireSqlCancellation();
+        const capability = (await this.capabilities)?.sql_pagination;
+        if (capability?.version !== 1
+            || capability.continuation_endpoint !== '/sql/continue'
+            || !capability.retained_snapshot
+            || !capability.projection_required
+            || !capability.byte_and_token_hints) {
+            throw new CapabilityUnsupportedError('server does not support SQL pagination capability version 1');
+        }
+        return capability;
+    }
+    async requireSqlIdempotency() {
+        await this.requireSqlCancellation();
+        const capability = (await this.capabilities)?.sql_idempotency;
+        return this.validateSqlIdempotencyCapability(capability);
+    }
+    async requireFreshSqlIdempotency() {
+        const capabilities = await this.loadCapabilities();
+        this.validateSqlCancellationCapability(capabilities?.sql_cancellation);
+        this.validateSqlIdempotencyCapability(capabilities?.sql_idempotency);
+    }
     /** Flush/commit `table` on the server; returns the new epoch. */
     commit(table) {
-        return this.inner.commit(table);
+        try {
+            return this.inner.commit(table);
+        }
+        catch (error) {
+            throw nativeRemoteWriteError(error);
+        }
     }
     createProcedure(spec) {
-        return JSON.parse(this.inner.createProcedure({ json: procedureJson(spec) }));
+        try {
+            return parseRemoteWriteJson(this.inner.createProcedure({ json: procedureJson(spec) }), 'procedure creation');
+        }
+        catch (error) {
+            throw nativeRemoteWriteError(error);
+        }
     }
     dropProcedure(name) {
-        this.inner.dropProcedure(name);
+        try {
+            this.inner.dropProcedure(name);
+        }
+        catch (error) {
+            throw nativeRemoteWriteError(error);
+        }
     }
     callProcedure(name, opts = {}) {
-        return JSON.parse(this.inner.callProcedure(name, {
-            argsJson: JSON.stringify(opts.args ?? {}),
-            idempotencyKey: opts.idempotencyKey
-        }));
+        try {
+            return parseProcedureCallResponse(this.inner.callProcedure(name, {
+                argsJson: JSON.stringify(opts.args ?? {}),
+                idempotencyKey: opts.idempotencyKey
+            }));
+        }
+        catch (error) {
+            throw nativeRemoteWriteError(error);
+        }
     }
     createTrigger(spec) {
-        return JSON.parse(this.inner.createTrigger({ json: triggerJson(spec) }));
+        try {
+            return parseRemoteWriteJson(this.inner.createTrigger({ json: triggerJson(spec) }), 'trigger creation');
+        }
+        catch (error) {
+            throw nativeRemoteWriteError(error);
+        }
     }
     replaceTrigger(name, spec) {
-        return JSON.parse(this.inner.replaceTrigger(name, { json: triggerJson(spec) }));
+        try {
+            return parseRemoteWriteJson(this.inner.replaceTrigger(name, { json: triggerJson(spec) }), 'trigger replacement');
+        }
+        catch (error) {
+            throw nativeRemoteWriteError(error);
+        }
     }
     dropTrigger(name) {
-        this.inner.dropTrigger(name);
+        try {
+            this.inner.dropTrigger(name);
+        }
+        catch (error) {
+            throw nativeRemoteWriteError(error);
+        }
     }
     triggers() {
-        return JSON.parse(this.inner.triggers());
+        return parseJsonStrict(this.inner.triggers());
     }
     trigger(name) {
-        return JSON.parse(this.inner.trigger(name));
+        return parseJsonStrict(this.inner.trigger(name));
     }
     createVirtualTable(spec) {
         return this.sql(createVirtualTableSql(spec));
@@ -180,26 +1867,286 @@ export class RemoteDatabase {
         return this.inner.compactTable(table);
     }
 }
+function isRemoteCapabilities(value) {
+    if (value === null || typeof value !== 'object')
+        return false;
+    const body = value;
+    if (!hasOnlyKeys(body, ['sql_cancellation', 'sql_idempotency', 'sql_pagination']))
+        return false;
+    const cancellation = body.sql_cancellation;
+    if (cancellation !== undefined && (cancellation === null || typeof cancellation !== 'object'
+        || !hasOnlyKeys(cancellation, [
+            'version', 'client_query_ids', 'cancel_endpoint', 'query_status',
+            'stream_disconnect_cancels', 'pre_registration_cancel'
+        ])
+        || !isNonNegativeInteger(cancellation.version) || cancellation.version > 255
+        || ['client_query_ids', 'cancel_endpoint', 'query_status',
+            'stream_disconnect_cancels', 'pre_registration_cancel']
+            .some((field) => typeof cancellation[field] !== 'boolean')))
+        return false;
+    const idempotency = body.sql_idempotency;
+    if (idempotency !== undefined && (idempotency === null || typeof idempotency !== 'object'
+        || !hasOnlyKeys(idempotency, [
+            'version', 'durable_pre_execution_intent', 'replay_committed_receipt',
+            'indeterminate_never_reexecutes'
+        ])
+        || !isNonNegativeInteger(idempotency.version) || idempotency.version > 255
+        || ['durable_pre_execution_intent', 'replay_committed_receipt',
+            'indeterminate_never_reexecutes']
+            .some((field) => typeof idempotency[field] !== 'boolean')))
+        return false;
+    const pagination = body.sql_pagination;
+    return pagination === undefined || pagination !== null && typeof pagination === 'object'
+        && hasOnlyKeys(pagination, [
+            'version', 'continuation_endpoint', 'retained_snapshot', 'projection_required',
+            'byte_and_token_hints'
+        ])
+        && isNonNegativeInteger(pagination.version) && pagination.version <= 255
+        && typeof pagination.continuation_endpoint === 'string'
+        && ['retained_snapshot', 'projection_required', 'byte_and_token_hints']
+            .every((field) => typeof pagination[field] === 'boolean');
+}
+function isRemoteSqlErrorEnvelope(value, queryId) {
+    if (value === null || typeof value !== 'object')
+        return false;
+    const body = value;
+    if (body.outcome === null || typeof body.outcome !== 'object'
+        || body.error === null || typeof body.error !== 'object')
+        return false;
+    const outcome = body.outcome;
+    const error = body.error;
+    if (!hasOnlyKeys(body, [
+        'query_id', 'status', 'terminal_state', 'committed', 'committed_statements',
+        'last_commit_epoch', 'last_commit_epoch_text', 'first_commit_statement_index',
+        'last_commit_statement_index', 'completed_statements', 'statement_index',
+        'cancel_outcome', 'cancellation_reason', 'retryable', 'server_state', 'outcome',
+        'error', 'max_rows', 'max_bytes'
+    ]) || !hasOnlyKeys(outcome, [
+        'committed', 'committed_statements', 'last_commit_epoch', 'last_commit_epoch_text',
+        'first_commit_statement_index', 'last_commit_statement_index', 'completed_statements',
+        'statement_index', 'serialization'
+    ]) || !hasOnlyKeys(error, [
+        'code', 'message', 'query_id', 'committed', 'retryable', 'max_rows', 'max_bytes'
+    ]) || !hasAllKeys(outcome, [
+        'committed', 'committed_statements', 'last_commit_epoch', 'last_commit_epoch_text',
+        'first_commit_statement_index', 'last_commit_statement_index', 'completed_statements',
+        'statement_index', 'serialization'
+    ]))
+        return false;
+    const code = error.code;
+    const status = body.status;
+    if (body.query_id !== queryId || error.query_id !== queryId
+        || typeof code !== 'string' || code.trim().length === 0
+        || typeof error.message !== 'string' || error.message.trim().length === 0
+        || typeof status !== 'string' || body.terminal_state !== status
+        || !['not_started', 'in_progress', 'succeeded', 'failed', 'unknown']
+            .includes(outcome.serialization)
+        || typeof body.retryable !== 'boolean' || error.retryable !== body.retryable
+        || ![null, true, false].includes(body.committed)
+        || body.committed !== outcome.committed || body.committed !== error.committed)
+        return false;
+    const names = ['committed_statements', 'first_commit_statement_index',
+        'last_commit_statement_index', 'completed_statements', 'statement_index'];
+    if (names.some((name) => !isOptionalNonNegativeInteger(body[name])
+        || !sameOptional(body[name], outcome[name])))
+        return false;
+    for (const name of ['max_rows', 'max_bytes']) {
+        const topLimit = body[name];
+        const errorLimit = error[name];
+        if (topLimit != null && (!isNonNegativeInteger(topLimit) || topLimit === 0)
+            || errorLimit != null && (!isNonNegativeInteger(errorLimit) || errorLimit === 0)
+            || topLimit != null && errorLimit != null && topLimit !== errorLimit)
+            return false;
+    }
+    if (!isOptionalEpoch(body.last_commit_epoch, body.last_commit_epoch_text)
+        || !isOptionalEpoch(outcome.last_commit_epoch, outcome.last_commit_epoch_text))
+        return false;
+    const topEpoch = receiptEpoch(body.last_commit_epoch, body.last_commit_epoch_text);
+    const outcomeEpoch = receiptEpoch(outcome.last_commit_epoch, outcome.last_commit_epoch_text);
+    if (topEpoch !== outcomeEpoch)
+        return false;
+    const committed = body.committed;
+    const committedStatements = body.committed_statements;
+    const first = body.first_commit_statement_index;
+    const last = body.last_commit_statement_index;
+    const completed = body.completed_statements;
+    const statement = body.statement_index;
+    const unknown = code === 'QUERY_OUTCOME_UNKNOWN';
+    if (committed === true) {
+        if (unknown || !COMMITTED_QUERY_STATUSES.has(status)
+            || committedStatements == null || committedStatements === 0
+            || topEpoch === undefined || body.last_commit_epoch_text == null
+            || outcome.last_commit_epoch_text == null || first == null || last == null
+            || completed == null || statement == null)
+            return false;
+    }
+    else if (committed === false) {
+        if (unknown || !['failed_before_commit', 'cancelled_before_commit',
+            'deadline_before_commit', 'cancelled_before_start'].includes(status)
+            || committedStatements !== 0 || topEpoch !== undefined
+            || first != null || last != null || completed == null || statement == null)
+            return false;
+    }
+    else if (!unknown || status !== 'outcome_unknown'
+        || names.some((name) => body[name] != null) || topEpoch !== undefined
+        || body.retryable !== false)
+        return false;
+    if (first != null && last != null && committedStatements != null && statement != null
+        && (first > last || committedStatements > last - first + 1 || last > statement))
+        return false;
+    if (completed != null && statement != null
+        && (statement > completed || completed > statement + 1))
+        return false;
+    const expectedRetryable = ['QUERY_REGISTRY_FULL', 'IDEMPOTENCY_STORE_FULL',
+        'IDEMPOTENCY_STORE_UNAVAILABLE'].includes(code);
+    if (body.retryable !== expectedRetryable)
+        return false;
+    const codeMatchesStatus = {
+        QUERY_OUTCOME_UNKNOWN: status === 'outcome_unknown',
+        QUERY_CANCELLED_AFTER_COMMIT: status === 'cancelled_after_commit' && committed,
+        DEADLINE_AFTER_COMMIT: status === 'deadline_after_commit' && committed,
+        QUERY_CANCELLED: ['cancelled_before_commit', 'cancelled_before_start'].includes(status),
+        DEADLINE_EXCEEDED: status === 'deadline_before_commit',
+        COMMIT_OUTCOME: committed === true,
+        SERIALIZATION_FAILED_AFTER_COMMIT: committed === true
+    }[code] ?? true;
+    const statusMatchesCode = {
+        outcome_unknown: code === 'QUERY_OUTCOME_UNKNOWN',
+        cancelled_after_commit: code === 'QUERY_CANCELLED_AFTER_COMMIT',
+        deadline_after_commit: code === 'DEADLINE_AFTER_COMMIT',
+        cancelled_before_commit: code === 'QUERY_CANCELLED',
+        cancelled_before_start: code === 'QUERY_CANCELLED',
+        deadline_before_commit: code === 'DEADLINE_EXCEEDED'
+    }[status] ?? true;
+    return codeMatchesStatus && statusMatchesCode;
+}
+function isSqlCursorErrorEnvelope(value) {
+    if (value === null || typeof value !== 'object')
+        return false;
+    const body = value;
+    const outcome = body.outcome;
+    const error = body.error;
+    const countFields = [
+        'committed_statements', 'first_commit_statement_index',
+        'last_commit_statement_index', 'completed_statements', 'statement_index'
+    ];
+    return hasOnlyKeys(body, [
+        'status', 'terminal_state', 'server_state', 'committed', ...countFields,
+        'last_commit_epoch', 'last_commit_epoch_text', 'cancel_outcome',
+        'cancellation_reason', 'retryable', 'outcome', 'error'
+    ]) && hasAllKeys(body, [
+        'status', 'terminal_state', 'server_state', 'committed', ...countFields,
+        'last_commit_epoch', 'last_commit_epoch_text', 'cancel_outcome',
+        'cancellation_reason', 'retryable', 'outcome', 'error'
+    ])
+        && outcome !== null && typeof outcome === 'object'
+        && hasOnlyKeys(outcome, [
+            'committed', ...countFields, 'last_commit_epoch', 'last_commit_epoch_text',
+            'serialization'
+        ]) && hasAllKeys(outcome, [
+        'committed', ...countFields, 'last_commit_epoch', 'last_commit_epoch_text',
+        'serialization'
+    ])
+        && error !== null && typeof error === 'object'
+        && hasOnlyKeys(error, ['code', 'message', 'committed', 'retryable'])
+        && hasAllKeys(error, ['code', 'message', 'committed', 'retryable'])
+        && body.status === 'failed_before_commit'
+        && body.terminal_state === 'failed_before_commit' && body.server_state === 'failed'
+        && body.committed === false && outcome.committed === false
+        && body.committed_statements === 0 && outcome.committed_statements === 0
+        && body.last_commit_epoch === null && outcome.last_commit_epoch === null
+        && body.last_commit_epoch_text === null && outcome.last_commit_epoch_text === null
+        && body.first_commit_statement_index === null
+        && outcome.first_commit_statement_index === null
+        && body.last_commit_statement_index === null
+        && outcome.last_commit_statement_index === null
+        && body.completed_statements === 0 && outcome.completed_statements === 0
+        && body.statement_index === 0 && outcome.statement_index === 0
+        && body.cancel_outcome === null && body.cancellation_reason === null
+        && body.retryable === false && outcome.serialization === 'not_started'
+        && typeof error.code === 'string' && error.code.length > 0
+        && typeof error.message === 'string' && error.message.length > 0
+        && error.committed === false && error.retryable === false;
+}
 async function remoteSqlError(response, fallbackQueryId) {
     let body = {};
     try {
-        body = await response.json();
+        const value = await responseJsonStrict(response);
+        if (fallbackQueryId === 'unknown' && isSqlCursorErrorEnvelope(value)) {
+            body = value;
+        }
+        else {
+            const candidateQueryId = value !== null && typeof value === 'object'
+                && typeof value.query_id === 'string'
+                && /^[0-9a-f]{32}$/u.test(value.query_id)
+                ? value.query_id
+                : undefined;
+            const expectedQueryId = fallbackQueryId === 'unknown' ? candidateQueryId : fallbackQueryId;
+            if (expectedQueryId === undefined || !isRemoteSqlErrorEnvelope(value, expectedQueryId)) {
+                return fallbackQueryId === 'unknown'
+                    ? new SerializationError('unknown', `SQL error response was malformed (HTTP ${response.status})`, { committed: false })
+                    : new QueryOutcomeUnknownError(fallbackQueryId, `SQL error response was malformed (HTTP ${response.status})`, { retryable: false, serverState: 'invalid_outcome' });
+            }
+            body = value;
+        }
     }
     catch {
-        return new KitError(`SQL request failed with HTTP ${response.status}`);
+        return fallbackQueryId === 'unknown'
+            ? new SerializationError('unknown', `SQL error response was not valid JSON (HTTP ${response.status})`, { committed: false })
+            : new QueryOutcomeUnknownError(fallbackQueryId, `SQL error response was not valid JSON (HTTP ${response.status})`);
     }
     const queryId = body.error?.query_id ?? fallbackQueryId;
     const message = body.error?.message;
-    switch (body.error?.code) {
+    const outcome = {
+        committed: mergedCommitState(body.outcome?.committed, body.committed),
+        committedStatements: maxKnown(body.outcome?.committed_statements, body.committed_statements),
+        lastCommitEpoch: remoteEpoch(body.outcome?.last_commit_epoch_text ?? body.last_commit_epoch_text, body.outcome?.last_commit_epoch ?? body.last_commit_epoch),
+        firstCommitStatementIndex: body.outcome?.first_commit_statement_index
+            ?? body.first_commit_statement_index,
+        lastCommitStatementIndex: body.outcome?.last_commit_statement_index
+            ?? body.last_commit_statement_index,
+        completedStatements: maxKnown(body.outcome?.completed_statements, body.completed_statements),
+        statementIndex: maxKnown(body.outcome?.statement_index, body.statement_index)
+    };
+    const metadata = {
+        cancelOutcome: body.cancel_outcome,
+        cancellationReason: body.cancellation_reason,
+        retryable: body.retryable,
+        serverState: body.server_state
+    };
+    const serverCode = body.error?.code;
+    switch (serverCode) {
         case 'QUERY_CANCELLED':
-            return new QueryCancelledError(queryId, message);
+        case 'QUERY_CANCELLED_AFTER_COMMIT':
+            return new QueryCancelledError(queryId, message, outcome, metadata);
         case 'DEADLINE_EXCEEDED':
-            return new QueryTimeoutError(queryId, message);
+        case 'DEADLINE_AFTER_COMMIT':
+            return new QueryTimeoutError(queryId, message, outcome, metadata);
         case 'QUERY_ID_CONFLICT':
             return new QueryIdConflictError(queryId, message);
         case 'TRANSACTION_ABORTED':
             return new TransactionAbortedError(message);
+        case 'COMMIT_OUTCOME':
+            return new CommitOutcomeError(queryId, message ?? 'SQL committed but response failed', { ...outcome, committed: true }, metadata);
+        case 'SERIALIZATION_FAILED_AFTER_COMMIT':
+            return new SerializationError(queryId, message ?? 'SQL committed but response serialization failed', { ...outcome, committed: true }, metadata);
+        case 'QUERY_OUTCOME_UNKNOWN':
+            return new QueryOutcomeUnknownError(queryId, message, metadata);
+        case 'QUERY_REGISTRY_FULL':
+        case 'CANCEL_TOO_LATE':
+        case 'QUERY_ALREADY_FINISHED':
+        case 'QUERY_NOT_FOUND':
+            return new KitError(message ?? `SQL request failed with HTTP ${response.status}`, serverCode);
+        case 'RESULT_LIMIT_EXCEEDED':
+            return new ResultLimitExceededError(queryId, message ?? 'SQL result limit exceeded', outcome, metadata);
+        case 'SERIALIZATION_FAILED':
+            return new SerializationError(queryId, message ?? 'SQL response serialization failed', outcome, metadata);
+        case 'CAPABILITY_UNSUPPORTED':
+            return new CapabilityUnsupportedError(message ?? 'server capability is unsupported');
         default:
+            if (serverCode) {
+                return new RemoteProtocolError(serverCode, response.status, message ?? `SQL request failed with HTTP ${response.status}`, queryId === 'unknown' ? undefined : queryId, outcome, metadata);
+            }
             return new KitError(message ?? `SQL request failed with HTTP ${response.status}`);
     }
 }