@syncular/client 0.22.0 → 0.23.0

package/dist/bun-database.d.ts

@@ -4,7 +4,7 @@
  * browser entry never touches `bun:sqlite`.
  */
 import { Database } from 'bun:sqlite';
-import { type ClientDatabase, type SqlRow, type SqlValue } from './database.js';
+import { type ClientDatabase, type SiblingDatabase, type SqlRow, type SqlValue } from './database.js';
 declare module 'bun:sqlite' {
     interface Database {
         clearQueryCache(): void;
@@ -16,6 +16,9 @@ export declare class BunClientDatabase implements ClientDatabase {
     constructor(path?: string);
     exec(sql: string, params?: readonly SqlValue[]): void;
     query(sql: string, params?: readonly SqlValue[]): SqlRow[];
+    /** RFC 0005: a sibling file beside the replica, e.g. `<path>.prev-context`. */
+    openSibling(name: string): SiblingDatabase;
+    siblingExists(name: string): boolean;
     transaction<T>(fn: () => T): T;
     /**
      * §5.3 image import: bun:sqlite attaches files, not buffers, so the

package/dist/bun-database.js

@@ -4,7 +4,7 @@
  * browser entry never touches `bun:sqlite`.
  */
 import { Database } from 'bun: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';
@@ -17,8 +17,10 @@ function coerceParams(params) {
 }
 export class BunClientDatabase {
     db;
+    #path;
     #tx = { depth: 0 };
     constructor(path = ':memory:') {
+        this.#path = path;
         this.db = new Database(path);
         // Match native Rust persistence: append durable commits to the WAL
         // instead of creating and syncing a rollback journal per transaction.
@@ -43,6 +45,27 @@ export class BunClientDatabase {
     query(sql, params = []) {
         return this.db.query(sql).all(...coerceParams(params));
     }
+    /** 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 BunClientDatabase(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.run(sql), fn);
     }

package/dist/client.d.ts

@@ -19,6 +19,7 @@ import { type LocalDataPurgeInput, type LocalDataPurgeResult } from './local-pur
 import { type LocalDataRebootstrapInput, type LocalDataRebootstrapResult } from './local-rebootstrap.js';
 import { type OutboxCommit } from './outbox.js';
 import { type CommitOutcome, type CommitOutcomeQuery, type ConflictRecord, type RejectionRecord, type ResolveCommitOutcomeInput } from './outcomes.js';
+import { type PreviousVersionAudit, type PreviousVersionReadSpec, type PreviousVersionSnapshot } from './previous-version.js';
 import { type ClientSchema } from './schema.js';
 import { type SubscriptionRecord } from './state.js';
 import type { RealtimeConnector, SegmentDownloader, SyncTransport } from './transport.js';
@@ -161,6 +162,31 @@ export interface SyncClientConfig {
      * hosts must not materialize key bytes before their preflight has passed.
      */
     readonly securityPreflight?: boolean;
+    /**
+     * RFC 0005 previous-version context. A feature flag, default off: when
+     * absent or `enabled: false`, a schema bump behaves exactly as 0.22.0 did
+     * apart from the schema-descriptor write and the unconditional orphan
+     * sweep. It is not a security control.
+     *
+     * When enabled, the §7.4.3 reset captures a bounded typed copy of the
+     * pre-reset rows and `previousVersionSnapshot()` can read it until
+     * coverage completes, the lease ends, a scope is revoked, the TTL passes,
+     * the data is purged, or the host discards it.
+     */
+    readonly previousVersionContext?: {
+        readonly enabled: boolean;
+        /** Total captured bytes; default 8 MiB. */
+        readonly maxBytes?: number;
+        /** Total captured rows; default 20,000. */
+        readonly maxRows?: number;
+        /** Captured table count; default 32. */
+        readonly maxTables?: number;
+        /** Largest single captured row in bytes; default 1 MiB. */
+        readonly maxRowBytes?: number;
+        /** Aware-binary hygiene TTL; default 24h. It does not bound an
+         * unaware same-schema rollback, which runs none of this code. */
+        readonly maxAgeMs?: number;
+    };
 }
 /** The fail-closed local-replica security lifecycle shared by every host. */
 export type SecurityLifecycle = 'preflight' | 'active';
@@ -282,6 +308,27 @@ export declare class SyncClient {
      * `windowState()` across separate worker/IPC calls.
      */
     querySnapshot<Row = SqlRow>(spec: QueryReadSpec): QuerySnapshot<Row>;
+    /**
+     * RFC 0005 D7: read captured rows from the previous local schema. `state` is
+     * always `'previousVersion'`; the container never makes `querySnapshot()`
+     * coverage complete.
+     */
+    previousVersionSnapshot(spec: PreviousVersionReadSpec): PreviousVersionSnapshot;
+    /** RFC 0005 D6: the pre-reset compatibility audit, advisory only. */
+    previousVersionAudit(): PreviousVersionAudit | undefined;
+    /**
+     * RFC 0005 A2/D9: the executable downgrade step. Drop the container file and
+     * both metadata records, and report whether anything was present.
+     *
+     * Authorized cleanup, so it is gated only on `start()` like
+     * `purgeLocalData`, NOT on `active`: RFC 0006 runs the discard consumer
+     * inside the quiesced security-preflight window, after the barrier and
+     * before reactivation. Reads and the audit stay active-gated.
+     */
+    previousVersionDiscard(): {
+        present: boolean;
+        discarded: boolean;
+    };
     /**
      * Subscribe to fine-grained invalidation. The callback fires ONCE per
      * apply batch (never per row, I1) with the `{tables, scopeKeys}` touched

package/dist/client.js

@@ -23,6 +23,7 @@ import { decodeLocalDataRebootstrapReceipt, encodeLocalDataRebootstrapReceipt, }
 import { appendOutboxCommit, deleteOutboxCommit, dropOutboxCommitsInScope, encodeOutboxCommit, listOutbox, iterateOutbox, countOutbox, listOutboxBeforeImages, OutboxEncodeError, replaceOutboxBeforeImages, } from './outbox.js';
 import { activeFailureRecords, listCommitOutcomes, persistCommitOutcomeResolution, pruneCommitOutcomes, commitOutcome as readCommitOutcome, recordCommitOutcome, } from './outcomes.js';
 import { assertReadOnlyQuery } from './query-guard.js';
+import { buildPreviousVersionAudit, capturePreviousVersion, clearPreviousVersionAudit, clearPreviousVersionRefusal, dropPreviousVersionContainer, loadLocalSchemaDescriptor, PREVIOUS_VERSION_CONTAINER_NAME, PREVIOUS_VERSION_MAX_LIMIT, readPreviousVersionContainer, readPreviousVersionRows, setLocalSchemaDescriptor, storedPreviousVersionAudit, storedPreviousVersionRefusal, withPreviousVersionContainer, writePreviousVersionAudit, writePreviousVersionRefusal, } from './previous-version.js';
 import { compileClientSchema, dropAndRecreateSyncedTables, ensureLocalBookkeepingSchema, ensureLocalSyncedSchema, fromSqlValue, coerceSqlRepresentation, jsonToRowValue, LOCAL_SCHEMA_VERSION_KEY, normalizeRecordKeys, OPTIMISTIC_VERSION, quoteIdent, recordToRowValues, rowValueToJson, SYNC_VERSION_COLUMN, stripSyncColumns, } from './schema.js';
 import { bumpLocalRevision, deleteSubscription, getLocalRevision, getMeta, getSubscription, loadSubscriptions, pruneUnknownSubscriptions, resetSubscriptionsForBump, saveSubscription, setMeta, } from './state.js';
 import { deletePendingEviction, deleteWindowUnit, deriveSubId, getWindowUnitBySubId, insertWindowUnit, loadPendingEvictions, loadWindowUnits, savePendingEviction, unitScopes, windowBaseKey, } from './window.js';
@@ -74,6 +75,42 @@ function emptySummary(pushed) {
     };
 }
 const LOG_EPOCH_META_KEY = 'logEpoch';
+/** RFC 0005 defaults (D2/A4/D7). */
+const PREVIOUS_VERSION_DEFAULT_MAX_BYTES = 8 * 1024 * 1024;
+const PREVIOUS_VERSION_DEFAULT_MAX_ROWS = 20_000;
+const PREVIOUS_VERSION_DEFAULT_MAX_TABLES = 32;
+const PREVIOUS_VERSION_DEFAULT_MAX_ROW_BYTES = 1024 * 1024;
+const PREVIOUS_VERSION_DEFAULT_MAX_AGE_MS = 24 * 60 * 60 * 1000;
+function boundedBudget(value, fallback, name) {
+    if (value === undefined)
+        return fallback;
+    if (!Number.isSafeInteger(value) || value < 1) {
+        throw new ClientSyncError('sync.invalid_request', `previousVersionContext.${name} must be a positive safe integer`);
+    }
+    return value;
+}
+function resolvePreviousVersionCaptureConfig(config) {
+    if (config === undefined || config.enabled !== true)
+        return undefined;
+    return {
+        maxBytes: boundedBudget(config.maxBytes, PREVIOUS_VERSION_DEFAULT_MAX_BYTES, 'maxBytes'),
+        maxRows: boundedBudget(config.maxRows, PREVIOUS_VERSION_DEFAULT_MAX_ROWS, 'maxRows'),
+        maxTables: boundedBudget(config.maxTables, PREVIOUS_VERSION_DEFAULT_MAX_TABLES, 'maxTables'),
+        maxRowBytes: boundedBudget(config.maxRowBytes, PREVIOUS_VERSION_DEFAULT_MAX_ROW_BYTES, 'maxRowBytes'),
+    };
+}
+function previousVersionMaxAgeMs(config) {
+    return boundedBudget(config?.maxAgeMs, PREVIOUS_VERSION_DEFAULT_MAX_AGE_MS, 'maxAgeMs');
+}
+/** RFC 0005 D7: `limit` defaults to 50 and is capped at 200. */
+function resolvePreviousVersionLimit(limit) {
+    if (limit === undefined)
+        return 50;
+    if (!Number.isFinite(limit) || limit < 1) {
+        throw new ClientSyncError('sync.invalid_request', 'previousVersionSnapshot limit must be a positive number');
+    }
+    return Math.min(PREVIOUS_VERSION_MAX_LIMIT, Math.trunc(limit));
+}
 function isFinalPushResult(frame) {
     return (frame.status !== 'rejected' ||
         !frame.results.some((result) => result.status === 'error' &&
@@ -86,6 +123,8 @@ export class SyncClient {
     #schema;
     /** §5.11 client-side encryption config; undefined ⇒ E2EE off. */
     #encryption;
+    /** RFC 0005 resolved capture budgets; undefined ⇒ feature off. */
+    #previousVersion;
     #securityLifecycle;
     #now;
     #outcomeRetentionMaxEntries;
@@ -182,6 +221,13 @@ export class SyncClient {
             throw new ClientSyncError('sync.invalid_request', 'outcomeRetentionMaxEntries must be a positive safe integer');
         }
         this.#outcomeRetentionMaxEntries = outcomeRetentionMaxEntries;
+        // RFC 0005: the container needs a sibling database file. A host without
+        // that capability (native bridges today) has no storage for it, so the
+        // feature resolves as not configured rather than pretending to capture.
+        this.#previousVersion =
+            this.#db.openSibling === undefined
+                ? undefined
+                : resolvePreviousVersionCaptureConfig(config.previousVersionContext);
         this.#hasBlobs = schemaHasBlobs(this.#schema);
     }
     // -- lifecycle ------------------------------------------------------------
@@ -225,6 +271,10 @@ export class SyncClient {
         // before the first sync round. A fresh install (no marker) is treated as
         // already at the generated version.
         this.#detectAndResetSchema();
+        // RFC 0005 D9: a container with missing/stale metadata, or past its TTL, is
+        // discarded at boot before anything can read it. The orphan/stale sweep is
+        // unconditional; the TTL is aware-binary hygiene only.
+        this.#reconcilePreviousVersionAtBoot();
         // A registration remains app intent only while its table exists in the
         // running schema. Removed-table registrations would poison every pull.
         const subscriptions = pruneUnknownSubscriptions(this.#db, loadSubscriptions(this.#db), new Set(this.#schema.tables.keys()));
@@ -269,14 +319,22 @@ export class SyncClient {
         const markerJson = getMeta(this.#db, LOCAL_SCHEMA_VERSION_KEY);
         if (markerJson === undefined) {
             // Fresh install: the tables just created match the running code.
-            ensureLocalSyncedSchema(this.#db, this.#schema);
-            setMeta(this.#db, LOCAL_SCHEMA_VERSION_KEY, String(this.#schema.version));
+            this.#db.transaction(() => {
+                ensureLocalSyncedSchema(this.#db, this.#schema);
+                setMeta(this.#db, LOCAL_SCHEMA_VERSION_KEY, String(this.#schema.version));
+                setLocalSchemaDescriptor(this.#db, this.#schema);
+            });
             return;
         }
         const marker = Number(markerJson);
         if (marker === this.#schema.version) {
-            // Same-version opens remain self-healing for absent tables/indexes.
-            ensureLocalSyncedSchema(this.#db, this.#schema);
+            // Same-version opens remain self-healing for absent tables/indexes, and
+            // RFC 0005 D1 backfills the descriptor for a database first opened by
+            // 0.22.0 or earlier WITHOUT a schema bump.
+            this.#db.transaction(() => {
+                ensureLocalSyncedSchema(this.#db, this.#schema);
+                setLocalSchemaDescriptor(this.#db, this.#schema);
+            });
             return;
         }
         this.#runSchemaReset();
@@ -289,12 +347,24 @@ export class SyncClient {
      * The bump is idempotent by the marker (rewritten last).
      */
     #runSchemaReset() {
+        const previousVersion = Number(getMeta(this.#db, LOCAL_SCHEMA_VERSION_KEY) ?? this.#schema.version);
         this.#setUpgrading(true);
+        // D5 step 1: the container file is swept FIRST, then captured into its own
+        // transaction, then the reset transaction runs with the marker LAST. A
+        // crash before the reset commit leaves the OLD marker, so the next boot
+        // re-runs the reset and the sweep removes the container: idempotent by the
+        // existing marker, with no cross-file transaction.
+        this.#sweepPreviousVersionContainer();
+        this.#capturePreviousVersion(previousVersion);
         this.#applyBatch((batch) => {
             this.#db.transaction(() => {
+                if (this.#previousVersion !== undefined) {
+                    writePreviousVersionAudit(this.#db, buildPreviousVersionAudit(this.#schema, listOutbox(this.#db), previousVersion, this.#schema.version, this.#now()));
+                }
                 dropAndRecreateSyncedTables(this.#db, this.#schema);
                 resetSubscriptionsForBump(this.#db);
                 setMeta(this.#db, LOCAL_SCHEMA_VERSION_KEY, String(this.#schema.version));
+                setLocalSchemaDescriptor(this.#db, this.#schema);
             });
             // Whole-DB reset: every synced table's rows changed (I1 eviction-shaped).
             for (const table of this.#schema.tables.values())
@@ -306,11 +376,69 @@ export class SyncClient {
         this.#setSchemaFloor(undefined);
         this.#replayOutbox();
     }
+    /**
+     * RFC 0005 D5 steps 2-5: capture the previous-version context into its own
+     * database file, in its own transaction, before the wipe. A refused capture
+     * stores nothing and records its reason for the read surface.
+     */
+    #capturePreviousVersion(previousVersion) {
+        const config = this.#previousVersion;
+        if (config === undefined)
+            return;
+        const descriptor = loadLocalSchemaDescriptor(this.#db);
+        if (descriptor === undefined || descriptor.version !== previousVersion) {
+            writePreviousVersionRefusal(this.#db, 'no-previous-descriptor', {
+                tables: 0,
+                rows: 0,
+                bytes: 0,
+            });
+            return;
+        }
+        const handle = this.#db.openSibling?.(PREVIOUS_VERSION_CONTAINER_NAME);
+        if (handle === undefined)
+            return;
+        let captured = false;
+        try {
+            const outcome = capturePreviousVersion(this.#db, handle.database, descriptor, this.#schema, config, this.#now());
+            if (outcome.ok) {
+                captured = true;
+                clearPreviousVersionRefusal(this.#db);
+            }
+            else {
+                writePreviousVersionRefusal(this.#db, outcome.reason, outcome.measurement);
+            }
+        }
+        finally {
+            handle.close();
+            // A refused capture must leave no container file at all.
+            if (!captured)
+                handle.removeFile();
+        }
+    }
+    /** D5 step 1: unconditional orphan sweep on the container file. */
+    #sweepPreviousVersionContainer() {
+        if (this.#dropPreviousVersionContainerFile()) {
+            clearPreviousVersionRefusal(this.#db);
+        }
+    }
+    /**
+     * Drop the container file when present and report whether it was. Shared by
+     * the orphan sweep and the discard path; the file is gone either way.
+     */
+    #dropPreviousVersionContainerFile() {
+        return (withPreviousVersionContainer(this.#db, (container) => {
+            dropPreviousVersionContainer(container);
+            return true;
+        }, true) === true);
+    }
     /** §2.1 reset after the server reports a different log continuity. */
     #runLogEpochReset(logEpoch) {
         const subscriptions = loadSubscriptions(this.#db);
         const pending = listOutbox(this.#db);
         this.#setUpgrading(true);
+        // RFC 0005 D5: the log-epoch reset is not a schema bump. It performs the
+        // orphan sweep but captures no new shadow.
+        this.#sweepPreviousVersionContainer();
         this.#applyBatch((batch) => {
             this.#db.transaction(() => {
                 dropAndRecreateSyncedTables(this.#db, this.#schema);
@@ -474,6 +602,8 @@ export class SyncClient {
     query(sql, params) {
         this.#requireActive();
         assertReadOnlyQuery(sql);
+        // RFC 0005's container lives in a separate database file, so this
+        // connection cannot see it and there is no table-access guard to run.
         return stripSyncColumns(this.#db.query(sql, params));
     }
     /** Current durable local observer revision (SPEC §7.5). */
@@ -527,6 +657,187 @@ export class SyncClient {
             };
         });
     }
+    // -- previous-version context (RFC 0005) ----------------------------------
+    /**
+     * RFC 0005 D7: read captured rows from the previous local schema. `state` is
+     * always `'previousVersion'`; the container never makes `querySnapshot()`
+     * coverage complete.
+     */
+    previousVersionSnapshot(spec) {
+        this.#requireActive();
+        const currentVersion = this.#schema.version;
+        if (this.#previousVersion === undefined) {
+            return this.#previousVersionUnavailable(currentVersion, 'not-configured');
+        }
+        const record = this.#readPreviousVersionRecord();
+        const nowMs = this.#now();
+        if (this.#previousVersionLeaseInactive(nowMs)) {
+            this.#discardPreviousVersion();
+            return this.#previousVersionUnavailable(currentVersion, 'lease-inactive');
+        }
+        if (loadSubscriptions(this.#db).some((sub) => sub.status === 'revoked')) {
+            this.#discardPreviousVersion();
+            return this.#previousVersionUnavailable(currentVersion, 'scope-revoked');
+        }
+        // Coverage completion is a live predicate: the container is normally
+        // dropped by the sync path first, so a read can be the first observer.
+        if (this.#previousVersionCoverageComplete()) {
+            this.#discardPreviousVersion();
+            return this.#previousVersionUnavailable(currentVersion, 'coverage-complete');
+        }
+        if (record === undefined) {
+            const refusal = storedPreviousVersionRefusal(this.#db);
+            return this.#previousVersionUnavailable(currentVersion, refusal?.reason ?? 'no-previous-descriptor');
+        }
+        if (nowMs - record.createdAtMs >
+            previousVersionMaxAgeMs(this.#config.previousVersionContext)) {
+            this.#discardPreviousVersion();
+            return this.#previousVersionUnavailable(currentVersion, 'expired');
+        }
+        const table = record.tables.find((entry) => entry.name === spec.table);
+        if (table === undefined) {
+            throw new ClientSyncError('sync.invalid_request', `previousVersionSnapshot names unknown previous table ${JSON.stringify(spec.table)}`);
+        }
+        const read = withPreviousVersionContainer(this.#db, (container) => readPreviousVersionRows(container, table, spec.rowIds?.map(String) ?? [], resolvePreviousVersionLimit(spec.limit)));
+        if (read === undefined) {
+            return this.#previousVersionUnavailable(currentVersion, 'no-previous-descriptor');
+        }
+        return {
+            state: 'previousVersion',
+            available: true,
+            previousVersion: record.previousVersion,
+            currentVersion,
+            rows: read.rows,
+            truncated: read.truncated,
+        };
+    }
+    /** RFC 0005 D6: the pre-reset compatibility audit, advisory only. */
+    previousVersionAudit() {
+        this.#requireActive();
+        return storedPreviousVersionAudit(this.#db);
+    }
+    /**
+     * RFC 0005 A2/D9: the executable downgrade step. Drop the container file and
+     * both metadata records, and report whether anything was present.
+     *
+     * Authorized cleanup, so it is gated only on `start()` like
+     * `purgeLocalData`, NOT on `active`: RFC 0006 runs the discard consumer
+     * inside the quiesced security-preflight window, after the barrier and
+     * before reactivation. Reads and the audit stay active-gated.
+     */
+    previousVersionDiscard() {
+        this.#requireStarted();
+        const present = this.#dropPreviousVersion();
+        return { present, discarded: present };
+    }
+    #previousVersionUnavailable(currentVersion, reason) {
+        return {
+            state: 'previousVersion',
+            available: false,
+            currentVersion,
+            reason,
+            rows: [],
+            truncated: false,
+        };
+    }
+    #previousVersionExists() {
+        return this.#db.siblingExists?.(PREVIOUS_VERSION_CONTAINER_NAME) === true;
+    }
+    /** Read the container's own metadata; opens the file for that window only. */
+    #readPreviousVersionRecord() {
+        return withPreviousVersionContainer(this.#db, readPreviousVersionContainer);
+    }
+    /** RFC 0005 A2: presence for `statusSnapshot()`, without creating the file. */
+    #previousVersionStatus() {
+        const record = this.#readPreviousVersionRecord();
+        if (record === undefined)
+            return { present: this.#previousVersionExists() };
+        return { present: true, createdAtMs: record.createdAtMs };
+    }
+    #previousVersionLeaseInactive(nowMs) {
+        const lease = this.#leaseState;
+        if (lease?.errorCode !== undefined)
+            return true;
+        return lease?.expiresAtMs !== undefined && lease.expiresAtMs <= nowMs;
+    }
+    /**
+     * RFC 0005 D7: the §7.4.5 replacement-coverage predicate — every active
+     * subscription has `cursor >= 0` and no resume token. Window units own
+     * subscriptions, so their pendency is included. An empty active set is not
+     * completion.
+     */
+    #previousVersionCoverageComplete() {
+        const active = loadSubscriptions(this.#db).filter((sub) => sub.status === 'active');
+        if (active.length === 0)
+            return false;
+        return active.every((sub) => sub.cursor >= 0 && sub.bootstrapState === undefined);
+    }
+    /**
+     * Remove the container file and both metadata records. Returns whether
+     * anything was present. No status notification — callers that change client
+     * state wrap it with {@link #discardPreviousVersion}.
+     */
+    #dropPreviousVersion() {
+        const present = this.#dropPreviousVersionContainerFile() ||
+            storedPreviousVersionRefusal(this.#db) !== undefined ||
+            storedPreviousVersionAudit(this.#db) !== undefined;
+        this.#db.transaction(() => {
+            clearPreviousVersionRefusal(this.#db);
+            clearPreviousVersionAudit(this.#db);
+        });
+        return present;
+    }
+    #discardPreviousVersion() {
+        const present = this.#dropPreviousVersion();
+        if (present)
+            this.#applyBatch((batch) => batch.status());
+        return present;
+    }
+    /** RFC 0005 D7: lifetime triggers evaluated after a sync round. */
+    #previousVersionLifetimeCheck() {
+        if (this.#previousVersion === undefined)
+            return;
+        const nowMs = this.#now();
+        if (this.#previousVersionLeaseInactive(nowMs)) {
+            this.#discardPreviousVersion();
+            return;
+        }
+        const record = this.#readPreviousVersionRecord();
+        if (record === undefined)
+            return;
+        if (loadSubscriptions(this.#db).some((sub) => sub.status === 'revoked')) {
+            this.#discardPreviousVersion();
+            return;
+        }
+        if (nowMs - record.createdAtMs >
+            previousVersionMaxAgeMs(this.#config.previousVersionContext)) {
+            this.#discardPreviousVersion();
+            return;
+        }
+        if (this.#previousVersionCoverageComplete()) {
+            this.#discardPreviousVersion();
+        }
+    }
+    /**
+     * RFC 0005 D9 boot hygiene: an orphan/stale container is discarded before any
+     * read. The TTL runs only for an aware binary; it makes no claim about an
+     * unaware same-schema rollback, which executes none of this code.
+     */
+    #reconcilePreviousVersionAtBoot() {
+        if (!this.#previousVersionExists())
+            return;
+        const record = this.#readPreviousVersionRecord();
+        let discard = record === undefined || record.currentVersion !== this.#schema.version;
+        if (!discard &&
+            record !== undefined &&
+            this.#previousVersion !== undefined &&
+            this.#now() - record.createdAtMs >
+                previousVersionMaxAgeMs(this.#config.previousVersionContext)) {
+            discard = true;
+        }
+        if (discard)
+            this.#dropPreviousVersion();
+    }
     // -- live-query invalidation ----------------------------------------------
     /**
      * Subscribe to fine-grained invalidation. The callback fires ONCE per
@@ -774,6 +1085,7 @@ export class SyncClient {
             leaseState: this.#leaseState,
             schemaFloor: this.#schemaFloor,
             syncNeeded: this.#needsPull,
+            previousVersionContext: this.#previousVersionStatus(),
         };
     }
     /**
@@ -1577,6 +1889,10 @@ export class SyncClient {
             }
             return { alreadyApplied: true, purgedRows: 0, droppedCommits: 0 };
         }
+        // RFC 0005 D7: the container file cannot be a purge target (its name is not
+        // in the running schema), so purge drops it as a fixed step, before any
+        // mirror row is touched and unconditionally.
+        this.#dropPreviousVersion();
         const rejectionCount = this.#rejections.length;
         try {
             return this.#applyBatch((batch) => {
@@ -1788,6 +2104,9 @@ export class SyncClient {
             setMeta(this.#db, 'leaseState', JSON.stringify(next));
             batch.status();
         });
+        // RFC 0005 D7: a lease stop state ends the previous-version context.
+        if (next.errorCode !== undefined)
+            this.#discardPreviousVersion();
     }
     /** The request-level lease error codes (§7.3.4): stop-and-surface. */
     #isLeaseErrorCode(code) {
@@ -2701,6 +3020,9 @@ export class SyncClient {
             this.#localResetEpoch === resetEpoch) {
             this.#setUpgrading(false);
         }
+        // RFC 0005 D7: coverage completion, lease end, scope revocation and TTL are
+        // evaluated once per round, after the apply.
+        this.#previousVersionLifetimeCheck();
         return { ...summary, bootstrapping };
     }
     #handlePushResult(frame, commitsById, summary, batch, rejectionDetails) {

package/dist/database.d.ts

@@ -7,6 +7,23 @@
  */
 export type SqlValue = string | number | bigint | boolean | Uint8Array | null;
 export type SqlRow = Record<string, SqlValue>;
+/**
+ * RFC 0005: a second database file in this database's own storage scope (the
+ * same on-disk directory, or the same OPFS SAH pool directory). Used to keep
+ * the previous-version container off the connection `query()` and unaware code
+ * use. The read guarantee is narrow: 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.
+ */
+export interface SiblingDatabase {
+    /** The open connection; the caller closes it before removal. */
+    readonly database: ClientDatabase;
+    /** Close the handle. A live handle blocks physical removal. */
+    close(): void;
+    /** Best-effort physical removal of the backing file. Close the handle first. */
+    removeFile(): void;
+}
 export interface ClientDatabase {
     /** Execute a single statement (no result rows). */
     exec(sql: string, params?: readonly SqlValue[]): void;
@@ -26,6 +43,16 @@ export interface ClientDatabase {
      * transaction (SQLite cannot ATTACH inside one); `fn` may open its own.
      */
     withSqliteImage?<T>(bytes: Uint8Array, alias: string, fn: () => T | Promise<T>): Promise<T>;
+    /**
+     * RFC 0005: open (creating on demand) the named sibling database file.
+     * `undefined` means the host provides no sibling capability, which makes the
+     * previous-version feature unavailable there. The NAME is code-derived and is
+     * not persisted in the replica database (data minimisation; not a security
+     * control).
+     */
+    openSibling?(name: string): SiblingDatabase | undefined;
+    /** RFC 0005: non-creating existence probe for {@link openSibling}. */
+    siblingExists?(name: string): boolean;
     close(): void;
 }
 /** Attach-schema aliases are code-chosen, never user input — enforce it. */

package/dist/index.d.ts

@@ -28,6 +28,7 @@ export * from './multi-tab.js';
 export * from './naming.js';
 export * from './outbox.js';
 export * from './outcomes.js';
+export { decodePreviousVersionAuditResult, decodePreviousVersionDiscardResult, decodePreviousVersionSnapshot, type PreviousVersionAudit, type PreviousVersionReadSpec, type PreviousVersionReason, type PreviousVersionSnapshot, } from './previous-version.js';
 export * from './query-guard.js';
 export * from './reactive-store.js';
 export * from './remote.js';

package/dist/index.js

@@ -28,6 +28,11 @@ export * from './multi-tab.js';
 export * from './naming.js';
 export * from './outbox.js';
 export * from './outcomes.js';
+// RFC 0005: explicit public surface. Everything else in the module is
+// implementation detail used by `client.ts` (capture, container file, durable
+// refusal/audit codecs), not package API. The feature is opt-in and its
+// consumer-facing contract is exactly the read spec and the two result types.
+export { decodePreviousVersionAuditResult, decodePreviousVersionDiscardResult, decodePreviousVersionSnapshot, } from './previous-version.js';
 export * from './query-guard.js';
 export * from './reactive-store.js';
 export * from './remote.js';

package/dist/invalidation.d.ts

@@ -26,6 +26,15 @@ export interface SyncStatusSnapshot {
     readonly leaseState: LeaseState | undefined;
     readonly schemaFloor: SchemaFloor | undefined;
     readonly syncNeeded: boolean;
+    /**
+     * RFC 0005 A2: whether a previous-version cache is present, so a host's
+     * update/rollback path can require its discard. `createdAtMs` is the capture
+     * time when a readable cache exists.
+     */
+    readonly previousVersionContext: {
+        readonly present: boolean;
+        readonly createdAtMs?: number;
+    };
 }
 export interface ClientChangeBatch {
     readonly revision: LocalRevision;

package/dist/node-database.d.ts

@@ -3,13 +3,16 @@
  * adapter: synchronous queries, nested transactions, and SQLite image attach.
  */
 import { DatabaseSync } from 'node:sqlite';
-import { type ClientDatabase, type SqlRow, type SqlValue } from './database.js';
+import { type ClientDatabase, type SiblingDatabase, type SqlRow, type SqlValue } from './database.js';
 export declare class NodeClientDatabase implements ClientDatabase {
     #private;
     readonly db: DatabaseSync;
     constructor(path?: string);
     exec(sql: string, params?: readonly SqlValue[]): void;
     query(sql: string, params?: readonly SqlValue[]): SqlRow[];
+    /** RFC 0005: a sibling file beside the replica, e.g. `<path>.prev-context`. */
+    openSibling(name: string): SiblingDatabase;
+    siblingExists(name: string): boolean;
     transaction<T>(fn: () => T): T;
     /** §5.3 image import through a private file attached for one callback. */
     withSqliteImage<T>(bytes: Uint8Array, alias: string, fn: () => T | Promise<T>): Promise<T>;