@syncular/client 0.4.0 → 0.5.0

package/dist/index.d.ts

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

package/dist/index.js

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

package/dist/invalidation.d.ts

@@ -1,69 +1,102 @@
 /**
- * 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.js';
 import type { CompiledClientTable } from './schema.js';
-/** 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 declare const NO_COMMAND_EFFECTS: CommandEffects;
 /**
- * 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 declare class Invalidation {
+export declare class ChangeAccumulator {
     #private;
-    /** 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;
-    /** Add a raw `prefix:value` scope key (§3.1). */
-    scopeKey(key: string): void;
-    /**
-     * 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).
-     */
+    /** Associate a precise `prefix:value` key with its table. */
+    scope(table: string, key: string): void;
+    /** Record registration/completeness change for one window unit. */
+    window(baseKey: string, table: string, unit: string): void;
+    status(): void;
+    conflicts(): void;
+    rejections(): void;
+    /** Add precise keys for a requested/effective scope map. */
     scopeMap(table: CompiledClientTable, scopes: ScopeMap): void;
-    /** A COMMIT change's stored scopes (variable → single value, §4.5). */
-    changeScopes(table: CompiledClientTable, scopes: Record<string, string>): void;
+    /** Add precise keys for a COMMIT change's stored scope values. */
+    changeScopes(table: CompiledClientTable, scopes: Readonly<Record<string, string>>): void;
     get touched(): boolean;
-    /** Freeze into an event, or undefined when nothing was touched. */
-    finish(): InvalidationEvent | undefined;
+    get statusChanged(): boolean;
+    finish(revision: LocalRevision, status: SyncStatusSnapshot | undefined): ClientChangeBatch;
+}
+/** Exception-isolated synchronous change listener set. */
+export declare class ChangeEmitter {
+    #private;
+    on(listener: ClientChangeListener): () => void;
+    emit(batch: ClientChangeBatch): void;
+    get size(): number;
 }
 /**
- * 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 declare function invalidationFromChange(batch: ClientChangeBatch): InvalidationEvent | undefined;
 export declare class InvalidationEmitter {
     #private;
     on(listener: InvalidationListener): () => void;
     emit(event: InvalidationEvent): void;
     get size(): number;
 }
+/** @deprecated Use {@link ChangeAccumulator}. */
+export { ChangeAccumulator as Invalidation };

package/dist/invalidation.js

@@ -1,65 +1,151 @@
+export const NO_COMMAND_EFFECTS = {
+    sync: { kind: 'none' },
+};
 /**
- * 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;
-    #scopeKeys;
-    /** Mark a whole table dirty (the floor for any apply). */
+export class ChangeAccumulator {
+    #tables = new Map();
+    #windows = new Map();
+    #status = false;
+    #conflicts = false;
+    #rejections = false;
+    /** Mark a whole table dirty, discarding any weaker scope-only facts. */
     table(name) {
-        if (this.#tables === undefined)
-            this.#tables = new Set();
-        this.#tables.add(name);
-    }
-    /** Add a raw `prefix:value` scope key (§3.1). */
-    scopeKey(key) {
-        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).
-     */
+        this.#tables.set(name, { tableWide: true, scopeKeys: undefined });
+    }
+    /** Associate a precise `prefix:value` key with its table. */
+    scope(table, key) {
+        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, table, unit) {
+        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);
+    }
+    status() {
+        this.#status = true;
+    }
+    conflicts() {
+        this.#conflicts = true;
+    }
+    rejections() {
+        this.#rejections = true;
+    }
+    /** Add precise keys for a requested/effective scope map. */
     scopeMap(table, scopes) {
         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, scopes) {
         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() {
-        return this.#tables !== undefined || this.#scopeKeys !== undefined;
+        return (this.#tables.size > 0 ||
+            this.#windows.size > 0 ||
+            this.#status ||
+            this.#conflicts ||
+            this.#rejections);
+    }
+    get statusChanged() {
+        return this.#status;
     }
-    /** Freeze into an event, or undefined when nothing was touched. */
-    finish() {
-        if (!this.touched)
-            return undefined;
+    finish(revision, status) {
+        if (this.#status && status === undefined) {
+            throw new Error('status change batch requires a post-commit snapshot');
+        }
+        const tables = [];
+        for (const [table, change] of this.#tables) {
+            tables.push(change.tableWide
+                ? { table }
+                : { table, scopeKeys: change.scopeKeys });
+        }
+        const windows = [];
+        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 } : {}),
+            conflictsChanged: this.#conflicts,
+            rejectionsChanged: this.#rejections,
         };
     }
 }
-const EMPTY = 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.
- */
+/** Exception-isolated synchronous change listener set. */
+export class ChangeEmitter {
+    #listeners = new Set();
+    on(listener) {
+        this.#listeners.add(listener);
+        return () => {
+            this.#listeners.delete(listener);
+        };
+    }
+    emit(batch) {
+        for (const listener of this.#listeners) {
+            try {
+                listener(batch);
+            }
+            catch {
+                // Observer code must never corrupt the committed core path.
+            }
+        }
+    }
+    get size() {
+        return this.#listeners.size;
+    }
+}
+export function invalidationFromChange(batch) {
+    if (batch.tables.length === 0 && batch.windows.length === 0)
+        return undefined;
+    const tables = new Set();
+    const scopeKeys = new Set();
+    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 {
     #listeners = new Set();
     on(listener) {
@@ -74,7 +160,7 @@ export class InvalidationEmitter {
                 listener(event);
             }
             catch {
-                // A UI listener must never break the apply path (I1).
+                // Compatibility observers are isolated like exact observers.
             }
         }
     }
@@ -82,3 +168,5 @@ export class InvalidationEmitter {
         return this.#listeners.size;
     }
 }
+/** @deprecated Use {@link ChangeAccumulator}. */
+export { ChangeAccumulator as Invalidation };

package/dist/reactive-store.d.ts

@@ -0,0 +1,74 @@
+import type { QueryReadSpec, QuerySnapshot, WindowCoverage, WindowState } from './client.js';
+import type { SqlValue } from './database.js';
+import type { ClientChangeListener, SyncStatusSnapshot } from './invalidation.js';
+import { type WindowBase } from './window.js';
+export interface QueryDependency {
+    readonly table: string;
+    readonly scopeKeys?: readonly string[];
+}
+export interface ReactiveQuerySpec<Row> {
+    readonly id: string;
+    readonly sql: string;
+    readonly params?: readonly SqlValue[];
+    readonly dependencies: readonly QueryDependency[];
+    readonly coverage?: readonly WindowCoverage[];
+    readonly rowKey?: (row: Row) => readonly SqlValue[];
+    readonly claimCoverage?: boolean;
+}
+export type LiveQueryPhase = 'loading' | 'partial' | 'ready' | 'error';
+export interface LiveQueryResult<Row> {
+    readonly rows: readonly Row[];
+    readonly phase: LiveQueryPhase;
+    readonly revision: bigint | undefined;
+    readonly error: Error | undefined;
+    readonly isRefreshing: boolean;
+}
+export interface ReactiveQueryClient {
+    onChange(listener: ClientChangeListener): () => void;
+    querySnapshot<Row = Record<string, SqlValue>>(spec: QueryReadSpec): QuerySnapshot<Row> | Promise<QuerySnapshot<Row>>;
+    statusSnapshot(): SyncStatusSnapshot | Promise<SyncStatusSnapshot>;
+    readonly conflicts: readonly unknown[] | (() => readonly unknown[] | Promise<readonly unknown[]>);
+    readonly rejections: readonly unknown[] | (() => readonly unknown[] | Promise<readonly unknown[]>);
+    setWindow(base: WindowBase, units: readonly string[]): void | Promise<void>;
+    windowState(base: WindowBase): WindowState | Promise<WindowState>;
+}
+export interface ExternalStoreEntry<T> {
+    subscribe(listener: () => void): () => void;
+    getSnapshot(): T;
+    refresh(): void;
+}
+export interface WindowRetention {
+    /** Resolves once this retained claim has reached the core window. */
+    readonly ready: Promise<void>;
+    /** Release only this retention owner's units from the composable union. */
+    readonly release: () => void;
+}
+export interface StatusStoreSnapshot {
+    readonly status: SyncStatusSnapshot | undefined;
+    readonly error: Error | undefined;
+    readonly isLoading: boolean;
+}
+export interface ConflictStoreSnapshot<Conflict = unknown, Rejection = unknown> {
+    readonly conflicts: readonly Conflict[];
+    readonly rejections: readonly Rejection[];
+    readonly error: Error | undefined;
+    readonly isLoading: boolean;
+}
+/** Lossless deterministic identity for query params, bytes, and row keys. */
+export declare function canonicalValue(value: unknown): string;
+export declare class ReactiveClientStore {
+    #private;
+    readonly client: ReactiveQueryClient;
+    readonly status: ExternalStoreEntry<StatusStoreSnapshot>;
+    readonly conflicts: ExternalStoreEntry<ConflictStoreSnapshot>;
+    constructor(client: ReactiveQueryClient);
+    query<Row>(spec: ReactiveQuerySpec<Row>): ExternalStoreEntry<LiveQueryResult<Row>>;
+    /** Retain a composable window working set outside React. The returned
+     * handle exposes registration completion and releases only this owner. */
+    retainWindow(base: WindowBase, units: readonly string[]): WindowRetention;
+    window(base: WindowBase): ExternalStoreEntry<WindowState>;
+    setWindowClaim(owner: symbol, base: WindowBase, units: readonly string[]): Promise<void>;
+    releaseWindowClaims(owner: symbol): void;
+    start(): void;
+    dispose(): void;
+}