@syncular/client 0.4.1 → 0.5.0

package/src/index.ts

@@ -23,6 +23,7 @@ export * from './multi-tab';
 export * from './naming';
 export * from './outbox';
 export * from './query-guard';
+export * from './reactive-store';
 export * from './schema';
 export * from './sql-tag';
 export * from './state';

package/src/invalidation.ts

@@ -1,107 +1,258 @@
 /**
- * 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.
+ * Revisioned client-local observation events (SPEC §7.5 / RFC 0003).
  *
- * 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.
+ * The core records observer domains while it owns the SQLite transaction,
+ * increments the persisted local revision in that same transaction, and emits
+ * the frozen batch only after commit. Bridges forward this shape verbatim.
  */
 import type { ScopeMap } from '@syncular/core';
+import type { LeaseState, SchemaFloor } from './client';
 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 LocalRevision = bigint;
+
+export interface TableChange {
+  readonly table: string;
+  /** Undefined means honestly table-wide; an empty set is never emitted. */
+  readonly scopeKeys?: ReadonlySet<string>;
 }
 
-export type InvalidationListener = (event: InvalidationEvent) => void;
+export interface WindowChange {
+  readonly baseKey: string;
+  readonly table: string;
+  readonly units: ReadonlySet<string>;
+}
+
+export interface SyncStatusSnapshot {
+  readonly outbox: number;
+  readonly upgrading: boolean;
+  readonly leaseState: LeaseState | undefined;
+  readonly schemaFloor: SchemaFloor | undefined;
+  readonly syncNeeded: boolean;
+}
+
+export interface ClientChangeBatch {
+  readonly revision: LocalRevision;
+  readonly tables: readonly TableChange[];
+  readonly windows: readonly WindowChange[];
+  readonly status?: SyncStatusSnapshot;
+  readonly conflictsChanged: boolean;
+  readonly rejectionsChanged: boolean;
+}
+
+export type ClientChangeListener = (batch: ClientChangeBatch) => void;
+
+/** Network work created by a core command (SPEC §7.5). */
+export type SyncIntent =
+  | { readonly kind: 'none' }
+  | { readonly kind: 'interactive' }
+  | { readonly kind: 'background'; readonly delayMs: number };
+
+export interface CommandEffects {
+  readonly sync: SyncIntent;
+}
+
+export interface CommandResult<T> {
+  readonly value: T;
+  readonly effects: CommandEffects;
+}
+
+export const NO_COMMAND_EFFECTS: CommandEffects = {
+  sync: { kind: 'none' },
+};
+
+interface MutableTableChange {
+  tableWide: boolean;
+  scopeKeys: Set<string> | undefined;
+}
+
+interface MutableWindowChange {
+  table: string;
+  units: Set<string>;
+}
 
 /**
- * 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.
+ * Per-observer-transaction accumulator. It contains no revision itself: the
+ * transaction wrapper assigns the revision only after all writes succeeded.
  */
-export class Invalidation {
-  #tables: Set<string> | undefined;
-  #scopeKeys: Set<string> | undefined;
+export class ChangeAccumulator {
+  readonly #tables = new Map<string, MutableTableChange>();
+  readonly #windows = new Map<string, MutableWindowChange>();
+  #status = false;
+  #conflicts = false;
+  #rejections = false;
 
-  /** Mark a whole table dirty (the floor for any apply). */
+  /** Mark a whole table dirty, discarding any weaker scope-only facts. */
   table(name: string): void {
-    if (this.#tables === undefined) this.#tables = new Set();
-    this.#tables.add(name);
+    this.#tables.set(name, { tableWide: true, scopeKeys: undefined });
   }
 
-  /** 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);
+  /** Associate a precise `prefix:value` key with its table. */
+  scope(table: string, key: string): void {
+    const current = this.#tables.get(table);
+    if (current?.tableWide) return;
+    if (current === undefined) {
+      this.#tables.set(table, {
+        tableWide: false,
+        scopeKeys: new Set([key]),
+      });
+      return;
+    }
+    current.scopeKeys?.add(key);
+  }
+
+  /** Record registration/completeness change for one window unit. */
+  window(baseKey: string, table: string, unit: string): void {
+    const current = this.#windows.get(baseKey);
+    if (current === undefined) {
+      this.#windows.set(baseKey, { table, units: new Set([unit]) });
+      return;
+    }
+    if (current.table !== table) {
+      throw new Error(`window base ${JSON.stringify(baseKey)} changed tables`);
+    }
+    current.units.add(unit);
   }
 
-  /**
-   * 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).
-   */
+  status(): void {
+    this.#status = true;
+  }
+
+  conflicts(): void {
+    this.#conflicts = true;
+  }
+
+  rejections(): void {
+    this.#rejections = true;
+  }
+
+  /** Add precise keys for a requested/effective scope map. */
   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}`);
+      for (const value of values) this.scope(table.name, `${prefix}:${value}`);
     }
   }
 
-  /** A COMMIT change's stored scopes (variable → single value, §4.5). */
+  /** Add precise keys for a COMMIT change's stored scope values. */
   changeScopes(
     table: CompiledClientTable,
-    scopes: Record<string, string>,
+    scopes: Readonly<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}`);
+      if (prefix !== undefined) {
+        this.scope(table.name, `${prefix}:${value}`);
+      }
     }
   }
 
   get touched(): boolean {
-    return this.#tables !== undefined || this.#scopeKeys !== undefined;
+    return (
+      this.#tables.size > 0 ||
+      this.#windows.size > 0 ||
+      this.#status ||
+      this.#conflicts ||
+      this.#rejections
+    );
   }
 
-  /** Freeze into an event, or undefined when nothing was touched. */
-  finish(): InvalidationEvent | undefined {
-    if (!this.touched) return undefined;
+  get statusChanged(): boolean {
+    return this.#status;
+  }
+
+  finish(
+    revision: LocalRevision,
+    status: SyncStatusSnapshot | undefined,
+  ): ClientChangeBatch {
+    if (this.#status && status === undefined) {
+      throw new Error('status change batch requires a post-commit snapshot');
+    }
+    const tables: TableChange[] = [];
+    for (const [table, change] of this.#tables) {
+      tables.push(
+        change.tableWide
+          ? { table }
+          : { table, scopeKeys: change.scopeKeys as ReadonlySet<string> },
+      );
+    }
+    const windows: WindowChange[] = [];
+    for (const [baseKey, change] of this.#windows) {
+      windows.push({
+        baseKey,
+        table: change.table,
+        units: change.units,
+      });
+    }
     return {
-      tables: this.#tables ?? EMPTY,
-      scopeKeys: this.#scopeKeys ?? EMPTY,
+      revision,
+      tables,
+      windows,
+      ...(this.#status ? { status: status as SyncStatusSnapshot } : {}),
+      conflictsChanged: this.#conflicts,
+      rejectionsChanged: this.#rejections,
     };
   }
 }
 
-const EMPTY: ReadonlySet<string> = new Set();
+/** Exception-isolated synchronous change listener set. */
+export class ChangeEmitter {
+  readonly #listeners = new Set<ClientChangeListener>();
+
+  on(listener: ClientChangeListener): () => void {
+    this.#listeners.add(listener);
+    return () => {
+      this.#listeners.delete(listener);
+    };
+  }
+
+  emit(batch: ClientChangeBatch): void {
+    for (const listener of this.#listeners) {
+      try {
+        listener(batch);
+      } catch {
+        // Observer code must never corrupt the committed core path.
+      }
+    }
+  }
+
+  get size(): number {
+    return this.#listeners.size;
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Compatibility projection
+// ---------------------------------------------------------------------------
 
 /**
- * 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.
+ * Legacy invalidation shape. It is derived only from an exact core batch;
+ * missing bridge information is never treated as global.
  */
+export interface InvalidationEvent {
+  readonly tables: ReadonlySet<string>;
+  readonly scopeKeys: ReadonlySet<string>;
+}
+
+export type InvalidationListener = (event: InvalidationEvent) => void;
+
+export function invalidationFromChange(
+  batch: ClientChangeBatch,
+): InvalidationEvent | undefined {
+  if (batch.tables.length === 0 && batch.windows.length === 0) return undefined;
+  const tables = new Set<string>();
+  const scopeKeys = new Set<string>();
+  for (const change of batch.tables) {
+    tables.add(change.table);
+    for (const key of change.scopeKeys ?? []) scopeKeys.add(key);
+  }
+  // Window-only changes project the table for old completeness consumers.
+  // The exact API still keeps this distinct, so new table-only reads do not run.
+  for (const change of batch.windows) tables.add(change.table);
+  return { tables, scopeKeys };
+}
+
 export class InvalidationEmitter {
   readonly #listeners = new Set<InvalidationListener>();
 
@@ -117,7 +268,7 @@ export class InvalidationEmitter {
       try {
         listener(event);
       } catch {
-        // A UI listener must never break the apply path (I1).
+        // Compatibility observers are isolated like exact observers.
       }
     }
   }
@@ -126,3 +277,6 @@ export class InvalidationEmitter {
     return this.#listeners.size;
   }
 }
+
+/** @deprecated Use {@link ChangeAccumulator}. */
+export { ChangeAccumulator as Invalidation };