@syncular/client 0.22.0 → 0.23.0

package/dist/previous-version.js

@@ -0,0 +1,732 @@
+import { ClientSyncError } from './errors.js';
+import { INVALID_HOST_RESPONSE_CODE } from './local-rebootstrap.js';
+import { fromSqlValue, jsonToRowValue, localColumnType, quoteIdent, rowValueToJson, } from './schema.js';
+import { getMeta, setMeta } from './state.js';
+/** `_syncular_meta` key holding the persisted {@link LocalSchemaDescriptor}. */
+const LOCAL_SCHEMA_DESCRIPTOR_KEY = 'localSchemaDescriptor';
+/**
+ * `_syncular_meta` key holding only a capture REFUSAL. The successful record
+ * lives inside the container file, so this key is absent whenever a container
+ * is present. It stays in the replica because it is small, typed, and useful
+ * even when nothing was captured.
+ */
+const PREVIOUS_VERSION_CONTEXT_KEY = 'previousVersionContext';
+/** `_syncular_meta` key holding the pre-reset compatibility audit (D6). */
+const PREVIOUS_VERSION_AUDIT_KEY = 'previousVersionAudit';
+/**
+ * RFC 0005: the code-derived sibling database filename. Kept out of the replica
+ * as data minimisation, not as a security control.
+ */
+export const PREVIOUS_VERSION_CONTAINER_NAME = 'prev-context';
+/** The one non-reserved row table INSIDE the container file (D3). */
+const CONTAINER_TABLE = 'syncular_prev_context';
+/** Container-local metadata table holding {@link PreviousVersionRecord}. */
+const CONTAINER_META_TABLE = '_syncular_prev_context_meta';
+const DESCRIPTOR_VERSION = 1;
+const AUDIT_VERSION = 1;
+/** Rows copied per `INSERT` batch (A4 step 5). */
+const COPY_BATCH_ROWS = 500;
+/** Incompatible commits recorded at most (D6); the rest flag `truncated`. */
+const MAX_AUDIT_INCOMPATIBLE = 200;
+/** Read spec `limit` ceiling (D7). */
+export const PREVIOUS_VERSION_MAX_LIMIT = 200;
+function isCount(value) {
+    return typeof value === 'number' && Number.isSafeInteger(value) && value >= 0;
+}
+function invalidHostResponse(method) {
+    throw new ClientSyncError(INVALID_HOST_RESPONSE_CODE, `${method} returned an invalid host response`);
+}
+function isSqlValue(value) {
+    return (value === null ||
+        typeof value === 'string' ||
+        typeof value === 'boolean' ||
+        typeof value === 'bigint' ||
+        (typeof value === 'number' && Number.isFinite(value)) ||
+        value instanceof Uint8Array);
+}
+function isSqlRow(value) {
+    if (value === null || typeof value !== 'object' || Array.isArray(value)) {
+        return false;
+    }
+    return Object.values(value).every(isSqlValue);
+}
+const PREVIOUS_VERSION_REASONS = [
+    'not-configured',
+    'no-previous-descriptor',
+    'capture-exceeded-budget',
+    'coverage-complete',
+    'expired',
+    'lease-inactive',
+    'scope-revoked',
+];
+const SNAPSHOT_REQUIRED_KEYS = [
+    'available',
+    'currentVersion',
+    'rows',
+    'state',
+    'truncated',
+];
+const SNAPSHOT_OPTIONAL_KEYS = ['previousVersion', 'reason'];
+const DISCARD_KEYS = ['discarded', 'present'];
+const AUDIT_KEYS = [
+    'atMs',
+    'encodable',
+    'fromVersion',
+    'incompatible',
+    'pending',
+    'toVersion',
+    'truncated',
+    'v',
+];
+const AUDIT_ENTRY_KEYS = ['column', 'commitId', 'reason', 'table'];
+/** Parse a persisted JSON object; anything else is `undefined`, never a guess. */
+function parseJsonObject(raw) {
+    try {
+        const parsed = JSON.parse(raw);
+        return parsed !== null &&
+            typeof parsed === 'object' &&
+            !Array.isArray(parsed)
+            ? parsed
+            : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+function localCorrupt(what) {
+    throw new ClientSyncError('sync.local_corrupt', `persisted ${what} is invalid`);
+}
+// ---------------------------------------------------------------------------
+// Descriptor (D1)
+// ---------------------------------------------------------------------------
+const COLUMN_TYPES = new Set([
+    'string',
+    'integer',
+    'float',
+    'boolean',
+    'bytes',
+    'json',
+    'blob_ref',
+    'crdt',
+]);
+function decodeColumns(value) {
+    if (!Array.isArray(value))
+        return localCorrupt('schema descriptor');
+    return value.map((entry) => {
+        if (entry === null || typeof entry !== 'object' || Array.isArray(entry)) {
+            return localCorrupt('schema descriptor');
+        }
+        const column = entry;
+        const keys = Object.keys(column).sort();
+        if (keys.length !== 2 ||
+            keys[0] !== 'name' ||
+            keys[1] !== 'type' ||
+            typeof column.name !== 'string' ||
+            typeof column.type !== 'string' ||
+            !COLUMN_TYPES.has(column.type)) {
+            return localCorrupt('schema descriptor');
+        }
+        return { name: column.name, type: column.type };
+    });
+}
+function decodeTable(value) {
+    if (value === null || typeof value !== 'object' || Array.isArray(value)) {
+        return localCorrupt('schema descriptor');
+    }
+    const table = value;
+    const keys = Object.keys(table).sort();
+    if (keys.length !== 3 ||
+        keys[0] !== 'columns' ||
+        keys[1] !== 'name' ||
+        keys[2] !== 'primaryKey' ||
+        typeof table.name !== 'string' ||
+        typeof table.primaryKey !== 'string') {
+        return localCorrupt('schema descriptor');
+    }
+    return {
+        name: table.name,
+        primaryKey: table.primaryKey,
+        columns: decodeColumns(table.columns),
+    };
+}
+/**
+ * D1: the semantic local types of every table in the running generated schema,
+ * built from {@link localColumnType} — never from SQLite affinity.
+ */
+function buildLocalSchemaDescriptor(schema) {
+    return {
+        v: DESCRIPTOR_VERSION,
+        version: schema.version,
+        tables: [...schema.tables.values()].map((table) => ({
+            name: table.name,
+            primaryKey: table.primaryKey,
+            columns: table.columns.map((column) => ({
+                name: column.name,
+                type: localColumnType(column),
+            })),
+        })),
+    };
+}
+/** Strict decode: an unknown shape is corruption, never a best guess. */
+function decodeLocalSchemaDescriptor(value) {
+    const record = parseJsonObject(value);
+    if (record === undefined)
+        return localCorrupt('schema descriptor');
+    const keys = Object.keys(record).sort();
+    if (keys.length !== 3 ||
+        keys[0] !== 'tables' ||
+        keys[1] !== 'v' ||
+        keys[2] !== 'version' ||
+        record.v !== DESCRIPTOR_VERSION ||
+        !isCount(record.version) ||
+        !Array.isArray(record.tables)) {
+        return localCorrupt('schema descriptor');
+    }
+    return {
+        v: 1,
+        version: record.version,
+        tables: record.tables.map(decodeTable),
+    };
+}
+/**
+ * D1: persist the descriptor. Callers MUST write this in the same transaction
+ * as {@link LOCAL_SCHEMA_VERSION_KEY}; a descriptor without a matching marker
+ * is treated as absent at reset time.
+ */
+export function setLocalSchemaDescriptor(db, schema) {
+    setMeta(db, LOCAL_SCHEMA_DESCRIPTOR_KEY, JSON.stringify(buildLocalSchemaDescriptor(schema)));
+}
+/** Load and strictly decode the stored descriptor; `undefined` when absent or corrupt. */
+export function loadLocalSchemaDescriptor(db) {
+    const raw = getMeta(db, LOCAL_SCHEMA_DESCRIPTOR_KEY);
+    if (raw === undefined)
+        return undefined;
+    try {
+        return decodeLocalSchemaDescriptor(raw);
+    }
+    catch {
+        return undefined;
+    }
+}
+// ---------------------------------------------------------------------------
+// Container file (D3, moved off the replica connection)
+// ---------------------------------------------------------------------------
+/** Drop both container tables. Also the unconditional orphan sweep (D5). */
+export function dropPreviousVersionContainer(db) {
+    db.exec(`DROP TABLE IF EXISTS ${quoteIdent(CONTAINER_TABLE)}`);
+    db.exec(`DROP TABLE IF EXISTS ${quoteIdent(CONTAINER_META_TABLE)}`);
+}
+/**
+ * Run `fn` against the container file for exactly one open window, closing the
+ * handle afterwards. The container is only opened where `siblingExists` already
+ * reports it — probing never creates the file. `removeFile` deletes the file
+ * once the handle is closed (a sweep or a discard must leave none). Returns
+ * `undefined` when the file or the host's sibling capability is absent.
+ */
+export function withPreviousVersionContainer(db, fn, removeFile = false) {
+    if (db.siblingExists?.(PREVIOUS_VERSION_CONTAINER_NAME) !== true) {
+        return undefined;
+    }
+    const handle = db.openSibling?.(PREVIOUS_VERSION_CONTAINER_NAME);
+    if (handle === undefined)
+        return undefined;
+    try {
+        return fn(handle.database);
+    }
+    finally {
+        handle.close();
+        if (removeFile)
+            handle.removeFile();
+    }
+}
+/** Read the container's own metadata record; `undefined` when absent/corrupt. */
+export function readPreviousVersionContainer(db) {
+    const meta = db.query("SELECT 1 AS present FROM sqlite_master WHERE type = 'table' AND name = ?", [CONTAINER_META_TABLE]);
+    if (meta.length === 0)
+        return undefined;
+    const raw = db.query(`SELECT record FROM ${quoteIdent(CONTAINER_META_TABLE)} WHERE id = 1`)[0]?.record;
+    if (raw === undefined)
+        return undefined;
+    try {
+        return decodeRecord(String(raw));
+    }
+    catch {
+        return undefined;
+    }
+}
+function decodeRecord(value) {
+    const record = parseJsonObject(value);
+    if (record === undefined)
+        return localCorrupt('previous-version context');
+    const keys = Object.keys(record).sort();
+    if (keys.length !== 7 ||
+        keys[0] !== 'bytes' ||
+        keys[1] !== 'createdAtMs' ||
+        keys[2] !== 'currentVersion' ||
+        keys[3] !== 'previousVersion' ||
+        keys[4] !== 'rows' ||
+        keys[5] !== 'tables' ||
+        keys[6] !== 'v' ||
+        record.v !== 1 ||
+        !isCount(record.bytes) ||
+        !isCount(record.createdAtMs) ||
+        !isCount(record.currentVersion) ||
+        !isCount(record.previousVersion) ||
+        !isCount(record.rows) ||
+        !Array.isArray(record.tables)) {
+        return localCorrupt('previous-version context');
+    }
+    return {
+        v: 1,
+        previousVersion: record.previousVersion,
+        currentVersion: record.currentVersion,
+        tables: record.tables.map(decodeTable),
+        rows: record.rows,
+        bytes: record.bytes,
+        createdAtMs: record.createdAtMs,
+    };
+}
+function writeRecord(db, record) {
+    db.exec(`CREATE TABLE IF NOT EXISTS ${quoteIdent(CONTAINER_META_TABLE)} (
+       id INTEGER PRIMARY KEY CHECK (id = 1),
+       record TEXT NOT NULL)`);
+    db.exec(`DELETE FROM ${quoteIdent(CONTAINER_META_TABLE)}`);
+    db.exec(`INSERT INTO ${quoteIdent(CONTAINER_META_TABLE)}(id, record) VALUES (1, ?)`, [JSON.stringify(record)]);
+}
+// ---------------------------------------------------------------------------
+// Bounded capture (D2 / A4)
+// ---------------------------------------------------------------------------
+/**
+ * D2/A4: measure the capture BEFORE materializing anything. Ordered probes,
+ * aborting on the first violation:
+ *
+ * 1. table count from `sqlite_master`;
+ * 2. per-table row count with a `LIMIT maxRows + 1` early-abort probe;
+ * 3. a single-row probe for rows larger than `maxRowBytes`;
+ * 4. a bounded `SUM` over a `LIMIT`ed subquery;
+ * 5. the copy itself into the CONTAINER file, in {@link COPY_BATCH_ROWS}
+ *    batches and one container transaction.
+ */
+export function capturePreviousVersion(replica, container, oldDescriptor, newSchema, config, nowMs) {
+    const discovered = new Set(replica
+        .query(`SELECT name FROM sqlite_master WHERE type = 'table'
+           AND name NOT LIKE '_syncular_%'
+           AND name NOT LIKE 'sqlite_%'`)
+        .map((row) => String(row.name)));
+    // Only descriptor-known tables carry semantic types; those are the tables the
+    // copy would hold, and the count the table budget bounds.
+    const tables = oldDescriptor.tables.filter((table) => discovered.has(table.name));
+    const over = (rows, bytes) => ({
+        ok: false,
+        reason: 'capture-exceeded-budget',
+        measurement: { tables: tables.length, rows, bytes },
+    });
+    if (tables.length > config.maxTables)
+        return over(0, 0);
+    let measuredRows = 0;
+    const perTableRows = [];
+    for (const table of tables) {
+        const probeRows = Number(replica.query(`SELECT COUNT(*) AS count FROM (SELECT 1 FROM ${quoteIdent(table.name)} LIMIT ?)`, [config.maxRows + 1])[0]?.count ?? 0);
+        measuredRows += probeRows;
+        perTableRows.push(probeRows);
+        if (measuredRows > config.maxRows)
+            return over(measuredRows, 0);
+    }
+    let measuredBytes = 0;
+    for (let index = 0; index < tables.length; index++) {
+        const table = tables[index];
+        const byteSum = table.columns
+            .map((c) => `COALESCE(LENGTH(CAST(${quoteIdent(c.name)} AS BLOB)), 0)`)
+            .join(' + ');
+        if (table.columns.length === 0)
+            continue;
+        const oversized = replica.query(`SELECT 1 AS hit FROM ${quoteIdent(table.name)}
+         WHERE (${byteSum}) > ? LIMIT 1`, [config.maxRowBytes]);
+        if (oversized.length > 0)
+            return over(measuredRows, measuredBytes);
+        const total = replica.query(`SELECT COALESCE(SUM(bytes), 0) AS total FROM (
+         SELECT (${byteSum}) AS bytes FROM ${quoteIdent(table.name)} LIMIT ?
+       )`, [perTableRows[index] ?? 0])[0]?.total;
+        measuredBytes += Number(total ?? 0);
+        if (measuredBytes > config.maxBytes)
+            return over(measuredRows, measuredBytes);
+    }
+    let copiedRows = 0;
+    container.transaction(() => {
+        dropPreviousVersionContainer(container);
+        container.exec(`CREATE TABLE ${quoteIdent(CONTAINER_TABLE)} (
+         tbl TEXT NOT NULL,
+         row_id TEXT NOT NULL,
+         payload TEXT NOT NULL,
+         PRIMARY KEY (tbl, row_id))`);
+        for (const table of tables) {
+            const selectColumns = table.columns
+                .map((column) => quoteIdent(column.name))
+                .join(', ');
+            let lastRowId = -1;
+            for (;;) {
+                const rows = replica.query(`SELECT rowid AS _rid, ${selectColumns} FROM ${quoteIdent(table.name)}
+             WHERE rowid > ? ORDER BY rowid ASC LIMIT ?`, [lastRowId, COPY_BATCH_ROWS]);
+                if (rows.length === 0)
+                    break;
+                for (const row of rows) {
+                    const payload = {};
+                    for (const column of table.columns) {
+                        const value = fromSqlValue({ name: column.name, type: column.type, nullable: true }, (row[column.name] ?? null));
+                        payload[column.name] = rowValueToJson(value);
+                    }
+                    container.exec(`INSERT INTO ${quoteIdent(CONTAINER_TABLE)}(tbl, row_id, payload)
+               VALUES (?, ?, ?)`, [table.name, rowIdText(table, row), JSON.stringify(payload)]);
+                }
+                lastRowId = Number(rows[rows.length - 1]?._rid ?? lastRowId);
+                copiedRows += rows.length;
+            }
+        }
+        writeRecord(container, {
+            v: 1,
+            previousVersion: oldDescriptor.version,
+            currentVersion: newSchema.version,
+            tables: tables.map((table) => ({
+                name: table.name,
+                primaryKey: table.primaryKey,
+                columns: table.columns,
+            })),
+            rows: copiedRows,
+            bytes: measuredBytes,
+            createdAtMs: nowMs,
+        });
+    });
+    return {
+        ok: true,
+        measurement: {
+            tables: tables.length,
+            rows: copiedRows,
+            bytes: measuredBytes,
+        },
+    };
+}
+function rowIdText(table, row) {
+    const value = row[table.primaryKey] ?? null;
+    if (value === null)
+        return '';
+    if (value instanceof Uint8Array) {
+        return [...value]
+            .map((byte) => byte.toString(16).padStart(2, '0'))
+            .join('');
+    }
+    return String(value);
+}
+function decodePreviousVersionPayload(table, payload) {
+    const record = parseJsonObject(payload);
+    if (record === undefined)
+        return localCorrupt('previous-version payload');
+    const row = {};
+    for (const column of table.columns) {
+        row[column.name] = jsonToRowValue((record[column.name] ?? null));
+    }
+    return row;
+}
+/** D7: read one previous table from the container, `limit + 1` rows for truncation. */
+export function readPreviousVersionRows(db, table, rowIds, limit) {
+    const where = rowIds.length === 0
+        ? ''
+        : ` AND row_id IN (${rowIds.map(() => '?').join(', ')})`;
+    const rows = db.query(`SELECT row_id, payload FROM ${quoteIdent(CONTAINER_TABLE)}
+       WHERE tbl = ?${where} ORDER BY row_id ASC LIMIT ?`, [table.name, ...rowIds, limit + 1]);
+    const truncated = rows.length > limit;
+    const visible = truncated ? rows.slice(0, limit) : rows;
+    return {
+        rows: visible.map((row) => decodePreviousVersionPayload(table, String(row.payload))),
+        truncated,
+    };
+}
+// ---------------------------------------------------------------------------
+// Durable refusal (read surface for a capture that stored nothing)
+// ---------------------------------------------------------------------------
+export function writePreviousVersionRefusal(db, reason, measurement) {
+    const refusal = {
+        v: 1,
+        reason,
+        tables: measurement.tables,
+        rows: measurement.rows,
+        bytes: measurement.bytes,
+    };
+    setMeta(db, PREVIOUS_VERSION_CONTEXT_KEY, JSON.stringify(refusal));
+}
+/** Delete the durable refusal. Part of the orphan sweep and of a successful capture. */
+export function clearPreviousVersionRefusal(db) {
+    db.exec('DELETE FROM _syncular_meta WHERE key = ?', [
+        PREVIOUS_VERSION_CONTEXT_KEY,
+    ]);
+}
+/** Decode the durable refusal; `undefined` when absent or corrupt. */
+export function storedPreviousVersionRefusal(db) {
+    const raw = getMeta(db, PREVIOUS_VERSION_CONTEXT_KEY);
+    if (raw === undefined)
+        return undefined;
+    const record = parseJsonObject(raw);
+    if (record === undefined)
+        return undefined;
+    if (record.v !== 1 ||
+        (record.reason !== 'no-previous-descriptor' &&
+            record.reason !== 'capture-exceeded-budget')) {
+        return undefined;
+    }
+    return {
+        v: 1,
+        reason: record.reason,
+        ...(isCount(record.tables) ? { tables: record.tables } : {}),
+        ...(isCount(record.rows) ? { rows: record.rows } : {}),
+        ...(isCount(record.bytes) ? { bytes: record.bytes } : {}),
+    };
+}
+/**
+ * D6: classify pending outbox commits against the NEW compiled schema, before
+ * the wipe. It records the commit id, table, typed reason and offending column
+ * ONLY — never an operation, row value or envelope field. The envelope stays in
+ * the outbox (and, on a terminal drop, in the §7.2.1 journal).
+ */
+export function buildPreviousVersionAudit(schema, pending, fromVersion, toVersion, atMs) {
+    const incompatible = [];
+    let incompatibleTotal = 0;
+    let encodable = 0;
+    for (const commit of pending) {
+        const entry = firstIncompatibility(schema, commit);
+        if (entry === undefined) {
+            encodable += 1;
+            continue;
+        }
+        incompatibleTotal += 1;
+        if (incompatible.length < MAX_AUDIT_INCOMPATIBLE)
+            incompatible.push(entry);
+    }
+    return {
+        v: AUDIT_VERSION,
+        atMs,
+        fromVersion,
+        toVersion,
+        pending: pending.length,
+        encodable,
+        truncated: incompatibleTotal > MAX_AUDIT_INCOMPATIBLE,
+        incompatible,
+    };
+}
+function firstIncompatibility(schema, commit) {
+    for (const operation of commit.operations) {
+        const table = schema.tables.get(operation.table);
+        if (table === undefined) {
+            return {
+                commitId: commit.clientCommitId,
+                table: operation.table,
+                reason: 'unknown-table',
+            };
+        }
+        if (operation.values === undefined)
+            continue;
+        for (const key of Object.keys(operation.values)) {
+            if (!table.columnIndex.has(key)) {
+                return {
+                    commitId: commit.clientCommitId,
+                    table: operation.table,
+                    reason: 'unknown-column',
+                    column: key,
+                };
+            }
+        }
+    }
+    return undefined;
+}
+/** Strict decode; `undefined` when absent or malformed. */
+export function storedPreviousVersionAudit(db) {
+    const raw = getMeta(db, PREVIOUS_VERSION_AUDIT_KEY);
+    if (raw === undefined)
+        return undefined;
+    const record = parseJsonObject(raw);
+    if (record === undefined)
+        return undefined;
+    if (record.v !== AUDIT_VERSION ||
+        !isCount(record.atMs) ||
+        !isCount(record.fromVersion) ||
+        !isCount(record.toVersion) ||
+        !isCount(record.pending) ||
+        !isCount(record.encodable) ||
+        typeof record.truncated !== 'boolean' ||
+        !Array.isArray(record.incompatible)) {
+        return undefined;
+    }
+    const incompatible = [];
+    for (const entry of record.incompatible) {
+        if (entry === null || typeof entry !== 'object' || Array.isArray(entry)) {
+            return undefined;
+        }
+        const item = entry;
+        if (typeof item.commitId !== 'string' ||
+            typeof item.table !== 'string' ||
+            (item.reason !== 'unknown-table' && item.reason !== 'unknown-column') ||
+            (item.column !== undefined && typeof item.column !== 'string')) {
+            return undefined;
+        }
+        incompatible.push({
+            commitId: item.commitId,
+            table: item.table,
+            reason: item.reason,
+            ...(typeof item.column === 'string' ? { column: item.column } : {}),
+        });
+    }
+    return {
+        v: 1,
+        atMs: record.atMs,
+        fromVersion: record.fromVersion,
+        toVersion: record.toVersion,
+        pending: record.pending,
+        encodable: record.encodable,
+        truncated: record.truncated,
+        incompatible,
+    };
+}
+export function writePreviousVersionAudit(db, audit) {
+    setMeta(db, PREVIOUS_VERSION_AUDIT_KEY, JSON.stringify(audit));
+}
+/** Delete the advisory audit. Part of a discard, never of a normal bump. */
+export function clearPreviousVersionAudit(db) {
+    db.exec('DELETE FROM _syncular_meta WHERE key = ?', [
+        PREVIOUS_VERSION_AUDIT_KEY,
+    ]);
+}
+// ---------------------------------------------------------------------------
+// Strict bridge decoders (RFC 0005 D10)
+//
+// Compile-time host types are not runtime proof. A version-drifted Worker or
+// native bridge could answer a read command with a forged `available: true`
+// and a peer's protected rows, so every reply is validated against the closed
+// public shape before an application can observe it.
+// ---------------------------------------------------------------------------
+/** Strictly decode a Worker/native `previousVersionSnapshot` reply. */
+export function decodePreviousVersionSnapshot(value) {
+    const method = 'previousVersionSnapshot';
+    if (value === null || typeof value !== 'object' || Array.isArray(value)) {
+        return invalidHostResponse(method);
+    }
+    const source = value;
+    const allowed = new Set([
+        ...SNAPSHOT_REQUIRED_KEYS,
+        ...SNAPSHOT_OPTIONAL_KEYS,
+    ]);
+    const keys = Object.keys(source);
+    if (!keys.every((key) => allowed.has(key)) ||
+        SNAPSHOT_REQUIRED_KEYS.some((key) => !(key in source)) ||
+        source.state !== 'previousVersion' ||
+        typeof source.available !== 'boolean' ||
+        !isCount(source.currentVersion) ||
+        typeof source.truncated !== 'boolean' ||
+        !Array.isArray(source.rows) ||
+        !source.rows.every(isSqlRow)) {
+        return invalidHostResponse(method);
+    }
+    const reason = source.reason;
+    const previousVersion = source.previousVersion;
+    const rows = source.rows;
+    if (source.available) {
+        // An available read names the previous version and never a refusal.
+        if (!isCount(previousVersion) || reason !== undefined) {
+            return invalidHostResponse(method);
+        }
+        return {
+            state: 'previousVersion',
+            available: true,
+            previousVersion,
+            currentVersion: source.currentVersion,
+            rows,
+            truncated: source.truncated,
+        };
+    }
+    if (previousVersion !== undefined ||
+        reason === undefined ||
+        !PREVIOUS_VERSION_REASONS.includes(reason)) {
+        return invalidHostResponse(method);
+    }
+    return {
+        state: 'previousVersion',
+        available: false,
+        currentVersion: source.currentVersion,
+        reason: reason,
+        rows,
+        truncated: source.truncated,
+    };
+}
+/**
+ * Strictly decode a Worker/native `previousVersionAudit` reply. `undefined` is
+ * the legitimate "no audit recorded" answer; anything else malformed throws.
+ */
+export function decodePreviousVersionAuditResult(value) {
+    const method = 'previousVersionAudit';
+    if (value === undefined)
+        return undefined;
+    if (value === null || typeof value !== 'object' || Array.isArray(value)) {
+        return invalidHostResponse(method);
+    }
+    const source = value;
+    const keys = Object.keys(source).sort();
+    if (keys.length !== AUDIT_KEYS.length)
+        return invalidHostResponse(method);
+    if (keys.some((key, index) => key !== AUDIT_KEYS[index])) {
+        return invalidHostResponse(method);
+    }
+    if (source.v !== AUDIT_VERSION ||
+        !isCount(source.atMs) ||
+        !isCount(source.fromVersion) ||
+        !isCount(source.toVersion) ||
+        !isCount(source.pending) ||
+        !isCount(source.encodable) ||
+        typeof source.truncated !== 'boolean' ||
+        !Array.isArray(source.incompatible) ||
+        source.incompatible.length > MAX_AUDIT_INCOMPATIBLE) {
+        return invalidHostResponse(method);
+    }
+    const incompatible = [];
+    for (const entry of source.incompatible) {
+        if (entry === null || typeof entry !== 'object' || Array.isArray(entry)) {
+            return invalidHostResponse(method);
+        }
+        const item = entry;
+        if (!Object.keys(item).every((key) => AUDIT_ENTRY_KEYS.includes(key)) ||
+            typeof item.commitId !== 'string' ||
+            typeof item.table !== 'string' ||
+            (item.reason !== 'unknown-table' && item.reason !== 'unknown-column') ||
+            (item.column !== undefined && typeof item.column !== 'string')) {
+            return invalidHostResponse(method);
+        }
+        incompatible.push({
+            commitId: item.commitId,
+            table: item.table,
+            reason: item.reason,
+            ...(typeof item.column === 'string' ? { column: item.column } : {}),
+        });
+    }
+    return {
+        v: 1,
+        atMs: source.atMs,
+        fromVersion: source.fromVersion,
+        toVersion: source.toVersion,
+        pending: source.pending,
+        encodable: source.encodable,
+        truncated: source.truncated,
+        incompatible,
+    };
+}
+/** Strictly decode a Worker/native `previousVersionDiscard` reply. */
+export function decodePreviousVersionDiscardResult(value) {
+    const method = 'previousVersionDiscard';
+    if (value === null || typeof value !== 'object' || Array.isArray(value)) {
+        return invalidHostResponse(method);
+    }
+    const source = value;
+    const keys = Object.keys(source).sort();
+    if (keys.length !== DISCARD_KEYS.length ||
+        keys.some((key, index) => key !== DISCARD_KEYS[index]) ||
+        typeof source.present !== 'boolean' ||
+        typeof source.discarded !== 'boolean') {
+        return invalidHostResponse(method);
+    }
+    return { present: source.present, discarded: source.discarded };
+}