@syncular/client 0.22.0 → 0.23.0

package/dist/node-database.js

@@ -3,7 +3,7 @@
  * adapter: synchronous queries, nested transactions, and SQLite image attach.
  */
 import { DatabaseSync } from 'node:sqlite';
-import { mkdtempSync, rmSync, writeFileSync } from 'node:fs';
+import { existsSync, mkdtempSync, rmSync, writeFileSync } from 'node:fs';
 import { tmpdir } from 'node:os';
 import { join } from 'node:path';
 import { assertImageAlias, runTransaction, } from './database.js';
@@ -29,8 +29,10 @@ function normalizeRow(row) {
 }
 export class NodeClientDatabase {
     db;
+    #path;
     #tx = { depth: 0 };
     constructor(path = ':memory:') {
+        this.#path = path;
         this.db = new DatabaseSync(path);
         try {
             this.db.exec('PRAGMA journal_mode = WAL');
@@ -48,6 +50,27 @@ export class NodeClientDatabase {
         const rows = this.db.prepare(sql).all(...coerceParams(params));
         return rows.map(normalizeRow);
     }
+    /** RFC 0005: a sibling file beside the replica, e.g. `<path>.prev-context`. */
+    openSibling(name) {
+        const siblingPath = this.#path === ':memory:' ? ':memory:' : `${this.#path}.${name}`;
+        const database = new NodeClientDatabase(siblingPath);
+        return {
+            database,
+            close: () => database.close(),
+            removeFile: () => {
+                if (siblingPath === ':memory:')
+                    return;
+                rmSync(siblingPath, { force: true });
+                rmSync(`${siblingPath}-wal`, { force: true });
+                rmSync(`${siblingPath}-shm`, { force: true });
+            },
+        };
+    }
+    siblingExists(name) {
+        if (this.#path === ':memory:')
+            return false;
+        return existsSync(`${this.#path}.${name}`);
+    }
     transaction(fn) {
         return runTransaction(this.#tx, (sql) => this.db.exec(sql), fn);
     }

package/dist/previous-version.d.ts

@@ -0,0 +1,207 @@
+/**
+ * RFC 0005 previous-version context.
+ *
+ * A schema bump wipes the local replica (§7.4.3), so the rows the app could
+ * see a moment ago are gone before the server can re-bootstrap them. This
+ * module captures a bounded, typed, read-only copy of the pre-reset rows so
+ * the app can answer "what did this look like before the upgrade" while the
+ * replacement bootstrap is in flight.
+ *
+ * Storage (controller storage move, 2026-09-19): the captured rows live in a
+ * SECOND database file in the replica's own pool directory, opened through
+ * `ClientDatabase.openSibling`, never in the replica database. The guarantee
+ * this buys is stated narrowly: an older client's ordinary query connection
+ * does not attach this file, so no SQL it runs can reach the container. It is
+ * NOT protection against arbitrary same-origin access and NOT protection
+ * against native filesystem access. The filename is a code constant derived at
+ * runtime and is not persisted in the replica database. That is data
+ * minimisation hygiene, NOT a control: same-origin storage access and native
+ * filesystem access can enumerate names regardless, so nothing is claimed on
+ * its strength.
+ *
+ * Two further rules shape the implementation:
+ *
+ * - The capture is typed by the OLD schema's {@link LocalSchemaDescriptor},
+ *   persisted in `_syncular_meta` beside the schema-version marker. SQLite
+ *   column affinity cannot recover a semantic type (`boolean` and `integer`
+ *   are both `INTEGER`; `string`, `json` and `blob_ref` are all `TEXT`), so a
+ *   descriptor-free capture would be undecodable. It is NEVER inferred.
+ * - Every budget is measured before any row is materialized. An over-budget
+ *   capture stores nothing.
+ */
+import type { RowColumn } from '@syncular/core';
+import type { ClientDatabase, SqlRow } from './database.js';
+import { type CompiledClientSchema, type JsonRowValue } from './schema.js';
+/**
+ * RFC 0005: the code-derived sibling database filename. Kept out of the replica
+ * as data minimisation, not as a security control.
+ */
+export declare const PREVIOUS_VERSION_CONTAINER_NAME = "prev-context";
+/** Read spec `limit` ceiling (D7). */
+export declare const PREVIOUS_VERSION_MAX_LIMIT = 200;
+/**
+ * Every reason the read surface can name. `security-inactive` is absent because
+ * `#requireActive()` throws before a read; `purged` and post-TTL are absent
+ * because a discard removes the records, so no durable state can name them;
+ * `namespace-collision` is absent because the container is a separate file and
+ * cannot collide with a replica table.
+ */
+export type PreviousVersionReason = 'not-configured' | 'no-previous-descriptor' | 'capture-exceeded-budget' | 'coverage-complete' | 'expired' | 'lease-inactive' | 'scope-revoked';
+/** Refusals that ARE durable, because no container is written for them. */
+type PreviousVersionRefusalReason = 'no-previous-descriptor' | 'capture-exceeded-budget';
+interface LocalSchemaDescriptorColumn {
+    readonly name: string;
+    readonly type: RowColumn['type'];
+}
+interface LocalSchemaDescriptorTable {
+    readonly name: string;
+    readonly primaryKey: string;
+    readonly columns: readonly LocalSchemaDescriptorColumn[];
+}
+interface LocalSchemaDescriptor {
+    readonly v: 1;
+    readonly version: number;
+    readonly tables: readonly LocalSchemaDescriptorTable[];
+}
+/** Successful capture record, stored INSIDE the container file. */
+export interface PreviousVersionRecord {
+    readonly v: 1;
+    readonly previousVersion: number;
+    readonly currentVersion: number;
+    readonly tables: readonly LocalSchemaDescriptorTable[];
+    readonly rows: number;
+    readonly bytes: number;
+    readonly createdAtMs: number;
+}
+/** Durable refusal stored in `_syncular_meta` when no container is written. */
+interface PreviousVersionRefusal {
+    readonly v: 1;
+    readonly reason: PreviousVersionRefusalReason;
+    readonly tables?: number;
+    readonly rows?: number;
+    readonly bytes?: number;
+}
+export interface PreviousVersionCaptureConfig {
+    readonly maxBytes: number;
+    readonly maxRows: number;
+    readonly maxTables: number;
+    readonly maxRowBytes: number;
+}
+interface PreviousVersionCaptureMeasurement {
+    readonly tables: number;
+    readonly rows: number;
+    readonly bytes: number;
+}
+type PreviousVersionCaptureOutcome = {
+    readonly ok: true;
+    readonly measurement: PreviousVersionCaptureMeasurement;
+} | {
+    readonly ok: false;
+    readonly reason: 'capture-exceeded-budget';
+    readonly measurement: PreviousVersionCaptureMeasurement;
+};
+interface PreviousVersionAuditEntry {
+    readonly commitId: string;
+    readonly table: string;
+    readonly reason: 'unknown-table' | 'unknown-column';
+    /** The offending column; present for every reason except `unknown-table`. */
+    readonly column?: string;
+}
+export interface PreviousVersionAudit {
+    readonly v: 1;
+    readonly atMs: number;
+    readonly fromVersion: number;
+    readonly toVersion: number;
+    readonly pending: number;
+    readonly encodable: number;
+    readonly truncated: boolean;
+    readonly incompatible: readonly PreviousVersionAuditEntry[];
+}
+export interface PreviousVersionReadSpec {
+    readonly table: string;
+    readonly rowIds?: readonly string[];
+    readonly limit?: number;
+}
+export interface PreviousVersionSnapshot {
+    readonly state: 'previousVersion';
+    readonly available: boolean;
+    readonly previousVersion?: number;
+    readonly currentVersion: number;
+    readonly reason?: PreviousVersionReason;
+    readonly rows: readonly SqlRow[];
+    readonly truncated: boolean;
+}
+/**
+ * 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 declare function setLocalSchemaDescriptor(db: ClientDatabase, schema: CompiledClientSchema): void;
+/** Load and strictly decode the stored descriptor; `undefined` when absent or corrupt. */
+export declare function loadLocalSchemaDescriptor(db: ClientDatabase): LocalSchemaDescriptor | undefined;
+/** Drop both container tables. Also the unconditional orphan sweep (D5). */
+export declare function dropPreviousVersionContainer(db: ClientDatabase): void;
+/**
+ * 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 declare function withPreviousVersionContainer<T>(db: ClientDatabase, fn: (container: ClientDatabase) => T, removeFile?: boolean): T | undefined;
+/** Read the container's own metadata record; `undefined` when absent/corrupt. */
+export declare function readPreviousVersionContainer(db: ClientDatabase): PreviousVersionRecord | undefined;
+/**
+ * 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 declare function capturePreviousVersion(replica: ClientDatabase, container: ClientDatabase, oldDescriptor: LocalSchemaDescriptor, newSchema: CompiledClientSchema, config: PreviousVersionCaptureConfig, nowMs: number): PreviousVersionCaptureOutcome;
+/** D7: read one previous table from the container, `limit + 1` rows for truncation. */
+export declare function readPreviousVersionRows(db: ClientDatabase, table: LocalSchemaDescriptorTable, rowIds: readonly string[], limit: number): {
+    rows: SqlRow[];
+    truncated: boolean;
+};
+export declare function writePreviousVersionRefusal(db: ClientDatabase, reason: PreviousVersionRefusalReason, measurement: PreviousVersionCaptureMeasurement): void;
+/** Delete the durable refusal. Part of the orphan sweep and of a successful capture. */
+export declare function clearPreviousVersionRefusal(db: ClientDatabase): void;
+/** Decode the durable refusal; `undefined` when absent or corrupt. */
+export declare function storedPreviousVersionRefusal(db: ClientDatabase): PreviousVersionRefusal | undefined;
+interface PendingCommitLike {
+    readonly clientCommitId: string;
+    readonly operations: readonly {
+        readonly table: string;
+        readonly values?: Readonly<Record<string, JsonRowValue>>;
+    }[];
+}
+/**
+ * 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 declare function buildPreviousVersionAudit(schema: CompiledClientSchema, pending: readonly PendingCommitLike[], fromVersion: number, toVersion: number, atMs: number): PreviousVersionAudit;
+/** Strict decode; `undefined` when absent or malformed. */
+export declare function storedPreviousVersionAudit(db: ClientDatabase): PreviousVersionAudit | undefined;
+export declare function writePreviousVersionAudit(db: ClientDatabase, audit: PreviousVersionAudit): void;
+/** Delete the advisory audit. Part of a discard, never of a normal bump. */
+export declare function clearPreviousVersionAudit(db: ClientDatabase): void;
+/** Strictly decode a Worker/native `previousVersionSnapshot` reply. */
+export declare function decodePreviousVersionSnapshot(value: unknown): PreviousVersionSnapshot;
+/**
+ * Strictly decode a Worker/native `previousVersionAudit` reply. `undefined` is
+ * the legitimate "no audit recorded" answer; anything else malformed throws.
+ */
+export declare function decodePreviousVersionAuditResult(value: unknown): PreviousVersionAudit | undefined;
+/** Strictly decode a Worker/native `previousVersionDiscard` reply. */
+export declare function decodePreviousVersionDiscardResult(value: unknown): {
+    readonly present: boolean;
+    readonly discarded: boolean;
+};
+export {};