@syncular/client 0.21.1 → 0.23.0

package/src/database.ts

@@ -9,6 +9,24 @@ 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;
@@ -32,6 +50,16 @@ export interface ClientDatabase {
     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;
 }
 

package/src/index.ts

@@ -28,6 +28,19 @@ export * from './multi-tab';
 export * from './naming';
 export * from './outbox';
 export * from './outcomes';
+// 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,
+  type PreviousVersionAudit,
+  type PreviousVersionReadSpec,
+  type PreviousVersionReason,
+  type PreviousVersionSnapshot,
+} from './previous-version';
 export * from './query-guard';
 export * from './reactive-store';
 export * from './remote';

package/src/invalidation.ts

@@ -30,6 +30,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 {

package/src/node-database.ts

@@ -3,13 +3,14 @@
  * adapter: synchronous queries, nested transactions, and SQLite image attach.
  */
 import { DatabaseSync, type SQLInputValue } 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,
   type ClientDatabase,
   runTransaction,
+  type SiblingDatabase,
   type SqlRow,
   type SqlValue,
 } from './database';
@@ -36,9 +37,11 @@ function normalizeRow(row: Record<string, unknown>): SqlRow {
 
 export class NodeClientDatabase implements ClientDatabase {
   readonly db: DatabaseSync;
+  readonly #path: string;
   #tx = { depth: 0 };
 
   constructor(path = ':memory:') {
+    this.#path = path;
     this.db = new DatabaseSync(path);
     try {
       this.db.exec('PRAGMA journal_mode = WAL');
@@ -58,6 +61,28 @@ export class NodeClientDatabase implements ClientDatabase {
     return rows.map(normalizeRow);
   }
 
+  /** RFC 0005: a sibling file beside the replica, e.g. `<path>.prev-context`. */
+  openSibling(name: string): SiblingDatabase {
+    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: string): boolean {
+    if (this.#path === ':memory:') return false;
+    return existsSync(`${this.#path}.${name}`);
+  }
+
   transaction<T>(fn: () => T): T {
     return runTransaction(this.#tx, (sql) => this.db.exec(sql), fn);
   }