@syncular/client 0.1.3 → 0.2.1

package/src/index.ts

@@ -1,23 +1,28 @@
-export * from './blob-limits';
-export * from './bridge-client';
+/**
+ * @syncular/client — the B3 TypeScript client protocol core
+ * (SPEC.md is normative; REVISE.md B3 is the architectural mandate).
+ *
+ * Browser-safe root: database backends live behind subpath exports
+ * (`./bun` for bun:sqlite tests, `./wasm` for sqlite-wasm + OPFS); the
+ * worker-side bootstrap lives behind `./worker`. The main-thread handle
+ * (`worker-host`) and the RPC protocol types are root exports — they
+ * import no SQLite.
+ */
+export * from './apply';
+export * from './blob';
 export * from './client';
-export * from './client-config';
-export * from './command-history';
-export * from './console-diagnostics';
+export * from './content-type';
 export * from './database';
+export * from './encryption';
 export * from './errors';
-export * from './mutations';
-export * from './network';
-export * from './runtime-contract';
-export * from './types';
-export type { SyncularWasmArtifactVariant } from './wasm-runtime';
-export {
-  getSyncularPackagedRuntimeArtifacts,
-  getSyncularRuntimeArtifact,
-  getSyncularRuntimeArtifactCatalogUrl,
-  getSyncularWasmGlueUrl,
-  getSyncularWasmUrl,
-  resolveSyncularRuntimeArtifactCatalog,
-  selectSyncularRuntimeArtifact,
-} from './wasm-runtime';
-export * from './worker-client';
+export * from './http';
+export * from './invalidation';
+export * from './leader-lock';
+export * from './multi-tab';
+export * from './outbox';
+export * from './schema';
+export * from './state';
+export * from './transport';
+export * from './window';
+export * from './worker-host';
+export * from './worker-protocol';

package/src/invalidation.ts

@@ -0,0 +1,128 @@
+/**
+ * The ONE apply-path invalidation choke point (TODO 3.1 / DESIGN-eviction
+ * I1–I4). Every local mutation — `COMMIT` apply, segment apply (rows +
+ * sqlite images), optimistic overlay rebuild, revocation purge, schema-bump
+ * reset, and (future) window eviction — routes its touched keys through a
+ * single {@link Invalidation} accumulator, and the client emits exactly ONE
+ * {@link InvalidationEvent} per apply batch (never per row). Live queries
+ * subscribe via `SyncClient.onInvalidate` and re-run only when a table they
+ * depend on appears.
+ *
+ * Granularity truth (honest to the wire, §4.5 / §5.2):
+ * - `COMMIT` changes carry per-row `scopes` (variable → value), so their
+ *   `prefix:value` scope keys (§3.1 vocabulary, I2) are emitted precisely.
+ * - Segments carry only a table + `scopeDigest`, NOT per-row scope keys, so
+ *   a segment apply invalidates at the **table** granularity plus the
+ *   subscription's requested/effective scope keys (the coarsest honest key
+ *   the wire supports for bulk data).
+ * - Purge / reset / optimistic / eviction are keyed by table (and effective
+ *   scope keys where a scope map is in hand).
+ *
+ * `tables` is therefore always the reliable floor; `scopeKeys` is a
+ * best-effort refinement present where the source carried it. A live query
+ * that cannot express its scope footprint keys off `tables` alone.
+ */
+import type { ScopeMap } from '@syncular/core';
+import type { CompiledClientTable } from './schema';
+
+/** One coalesced invalidation batch (I1). Empty batches are not emitted. */
+export interface InvalidationEvent {
+  /** Tables whose local rows changed this batch — the reliable floor. */
+  readonly tables: ReadonlySet<string>;
+  /** `prefix:value` scope keys touched, where the source carried them (I2). */
+  readonly scopeKeys: ReadonlySet<string>;
+}
+
+export type InvalidationListener = (event: InvalidationEvent) => void;
+
+/**
+ * A per-batch accumulator. One is created at the top of each apply batch,
+ * fed by the apply paths, and flushed once at the batch boundary. Mutable
+ * and cheap on purpose — no allocation until something is actually touched.
+ */
+export class Invalidation {
+  #tables: Set<string> | undefined;
+  #scopeKeys: Set<string> | undefined;
+
+  /** Mark a whole table dirty (the floor for any apply). */
+  table(name: string): void {
+    if (this.#tables === undefined) this.#tables = new Set();
+    this.#tables.add(name);
+  }
+
+  /** Add a raw `prefix:value` scope key (§3.1). */
+  scopeKey(key: string): void {
+    if (this.#scopeKeys === undefined) this.#scopeKeys = new Set();
+    this.#scopeKeys.add(key);
+  }
+
+  /**
+   * Add the `prefix:value` keys for an effective/requested scope map on
+   * `table` (variable → list(value)), skipping variables the table has no
+   * prefix for (never guesses a key).
+   */
+  scopeMap(table: CompiledClientTable, scopes: ScopeMap): void {
+    for (const [variable, values] of Object.entries(scopes)) {
+      const prefix = table.scopePrefixByVariable.get(variable);
+      if (prefix === undefined) continue;
+      for (const v of values) this.scopeKey(`${prefix}:${v}`);
+    }
+  }
+
+  /** A COMMIT change's stored scopes (variable → single value, §4.5). */
+  changeScopes(
+    table: CompiledClientTable,
+    scopes: Record<string, string>,
+  ): void {
+    for (const [variable, value] of Object.entries(scopes)) {
+      const prefix = table.scopePrefixByVariable.get(variable);
+      if (prefix !== undefined) this.scopeKey(`${prefix}:${value}`);
+    }
+  }
+
+  get touched(): boolean {
+    return this.#tables !== undefined || this.#scopeKeys !== undefined;
+  }
+
+  /** Freeze into an event, or undefined when nothing was touched. */
+  finish(): InvalidationEvent | undefined {
+    if (!this.touched) return undefined;
+    return {
+      tables: this.#tables ?? EMPTY,
+      scopeKeys: this.#scopeKeys ?? EMPTY,
+    };
+  }
+}
+
+const EMPTY: ReadonlySet<string> = new Set();
+
+/**
+ * A tiny subscribable listener set. Notification is synchronous and
+ * exception-isolated (one throwing listener never starves the rest, and
+ * never corrupts the emitting apply path). Reused by the worker handle so
+ * both cores expose the identical `onInvalidate` surface.
+ */
+export class InvalidationEmitter {
+  readonly #listeners = new Set<InvalidationListener>();
+
+  on(listener: InvalidationListener): () => void {
+    this.#listeners.add(listener);
+    return () => {
+      this.#listeners.delete(listener);
+    };
+  }
+
+  emit(event: InvalidationEvent): void {
+    for (const listener of this.#listeners) {
+      try {
+        listener(event);
+      } catch {
+        // A UI listener must never break the apply path (I1).
+      }
+    }
+  }
+
+  get size(): number {
+    return this.#listeners.size;
+  }
+}

package/src/leader-lock.ts

@@ -0,0 +1,68 @@
+/**
+ * Multi-tab ownership seam (REVISE B3): exactly one core instance owns the
+ * local database. The interface is the whole B3 deliverable — cross-tab
+ * follower fanout is post-gate. Browsers use Web Locks; tests use the
+ * no-op single-owner lock.
+ */
+export interface LeaderLease {
+  release(): void | Promise<void>;
+}
+
+export interface LeaderLock {
+  /** Resolves when this instance holds leadership for `name`. */
+  acquire(name: string): Promise<LeaderLease>;
+  /**
+   * Resolves immediately: the lease when leadership was free, `undefined`
+   * when another owner holds it. The worker handle uses this so a second
+   * tab gets a clear not-leader state instead of blocking forever
+   * (followers are post-gate, TODO 3.2).
+   */
+  tryAcquire?(name: string): Promise<LeaderLease | undefined>;
+}
+
+/** Single-owner environments (tests, dedicated workers): always leader. */
+export function singleOwnerLock(): LeaderLock {
+  return {
+    acquire: () => Promise.resolve({ release: () => {} }),
+    tryAcquire: () => Promise.resolve({ release: () => {} }),
+  };
+}
+
+/**
+ * Web Locks leader election: resolves once the exclusive lock is granted
+ * and holds it until the lease is released (tab close releases it
+ * implicitly, letting the next tab take over).
+ */
+export function webLocksLeaderLock(locks?: LockManager): LeaderLock {
+  const manager = locks ?? navigator.locks;
+  return {
+    acquire: (name) =>
+      new Promise<LeaderLease>((resolveAcquire, rejectAcquire) => {
+        manager
+          .request(
+            name,
+            { mode: 'exclusive' },
+            () =>
+              new Promise<void>((resolveHold) => {
+                resolveAcquire({ release: () => resolveHold() });
+              }),
+          )
+          .catch((error: unknown) => rejectAcquire(error));
+      }),
+    tryAcquire: (name) =>
+      new Promise<LeaderLease | undefined>((resolveTry, rejectTry) => {
+        manager
+          .request(name, { mode: 'exclusive', ifAvailable: true }, (lock) => {
+            // `ifAvailable` grants `null` instead of waiting (Web Locks).
+            if (lock === null) {
+              resolveTry(undefined);
+              return undefined;
+            }
+            return new Promise<void>((resolveHold) => {
+              resolveTry({ release: () => resolveHold() });
+            });
+          })
+          .catch((error: unknown) => rejectTry(error));
+      }),
+  };
+}