@syncular/client 0.1.3 → 0.2.1

package/dist/index.js

@@ -1,15 +1,28 @@
-export * from './blob-limits.js';
-export * from './bridge-client.js';
+/**
+ * @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.js';
+export * from './blob.js';
 export * from './client.js';
-export * from './client-config.js';
-export * from './command-history.js';
-export * from './console-diagnostics.js';
+export * from './content-type.js';
 export * from './database.js';
+export * from './encryption.js';
 export * from './errors.js';
-export * from './mutations.js';
-export * from './network.js';
-export * from './runtime-contract.js';
-export * from './types.js';
-export { getSyncularPackagedRuntimeArtifacts, getSyncularRuntimeArtifact, getSyncularRuntimeArtifactCatalogUrl, getSyncularWasmGlueUrl, getSyncularWasmUrl, resolveSyncularRuntimeArtifactCatalog, selectSyncularRuntimeArtifact, } from './wasm-runtime.js';
-export * from './worker-client.js';
-//# sourceMappingURL=index.js.map
+export * from './http.js';
+export * from './invalidation.js';
+export * from './leader-lock.js';
+export * from './multi-tab.js';
+export * from './outbox.js';
+export * from './schema.js';
+export * from './state.js';
+export * from './transport.js';
+export * from './window.js';
+export * from './worker-host.js';
+export * from './worker-protocol.js';

package/dist/invalidation.d.ts

@@ -0,0 +1,69 @@
+/**
+ * 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.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 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 declare class Invalidation {
+    #private;
+    /** Mark a whole table dirty (the floor for any apply). */
+    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).
+     */
+    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;
+    get touched(): boolean;
+    /** Freeze into an event, or undefined when nothing was touched. */
+    finish(): InvalidationEvent | undefined;
+}
+/**
+ * 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 declare class InvalidationEmitter {
+    #private;
+    on(listener: InvalidationListener): () => void;
+    emit(event: InvalidationEvent): void;
+    get size(): number;
+}

package/dist/invalidation.js

@@ -0,0 +1,84 @@
+/**
+ * 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;
+    #scopeKeys;
+    /** Mark a whole table dirty (the floor for any apply). */
+    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).
+     */
+    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}`);
+        }
+    }
+    /** A COMMIT change's stored scopes (variable → single value, §4.5). */
+    changeScopes(table, scopes) {
+        for (const [variable, value] of Object.entries(scopes)) {
+            const prefix = table.scopePrefixByVariable.get(variable);
+            if (prefix !== undefined)
+                this.scopeKey(`${prefix}:${value}`);
+        }
+    }
+    get touched() {
+        return this.#tables !== undefined || this.#scopeKeys !== undefined;
+    }
+    /** Freeze into an event, or undefined when nothing was touched. */
+    finish() {
+        if (!this.touched)
+            return undefined;
+        return {
+            tables: this.#tables ?? EMPTY,
+            scopeKeys: this.#scopeKeys ?? EMPTY,
+        };
+    }
+}
+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.
+ */
+export class InvalidationEmitter {
+    #listeners = new Set();
+    on(listener) {
+        this.#listeners.add(listener);
+        return () => {
+            this.#listeners.delete(listener);
+        };
+    }
+    emit(event) {
+        for (const listener of this.#listeners) {
+            try {
+                listener(event);
+            }
+            catch {
+                // A UI listener must never break the apply path (I1).
+            }
+        }
+    }
+    get size() {
+        return this.#listeners.size;
+    }
+}

package/dist/leader-lock.d.ts

@@ -0,0 +1,28 @@
+/**
+ * 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 declare function singleOwnerLock(): LeaderLock;
+/**
+ * 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 declare function webLocksLeaderLock(locks?: LockManager): LeaderLock;

package/dist/leader-lock.js

@@ -0,0 +1,38 @@
+/** Single-owner environments (tests, dedicated workers): always leader. */
+export function singleOwnerLock() {
+    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) {
+    const manager = locks ?? navigator.locks;
+    return {
+        acquire: (name) => new Promise((resolveAcquire, rejectAcquire) => {
+            manager
+                .request(name, { mode: 'exclusive' }, () => new Promise((resolveHold) => {
+                resolveAcquire({ release: () => resolveHold() });
+            }))
+                .catch((error) => rejectAcquire(error));
+        }),
+        tryAcquire: (name) => new Promise((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((resolveHold) => {
+                    resolveTry({ release: () => resolveHold() });
+                });
+            })
+                .catch((error) => rejectTry(error));
+        }),
+    };
+}

package/dist/multi-tab.d.ts

@@ -0,0 +1,134 @@
+import type { SyncWorkerEvent } from './worker-protocol.js';
+/** Client-local: a follower call could not reach a leader before its deadline. */
+export declare const FOLLOWER_TIMEOUT_CODE = "client.follower_timeout";
+/** Default deadline for a follower request (covers a leader-handover gap). */
+export declare const DEFAULT_FOLLOWER_CALL_TIMEOUT_MS = 10000;
+/** Max follower calls queued across a handover before we fail loudly. */
+export declare const DEFAULT_FOLLOWER_QUEUE_LIMIT = 256;
+interface HelloMessage {
+    readonly t: 'hello';
+    readonly fromId: string;
+    /** Highest epoch the sender has observed (helps a promoter monotonically
+     * advance even if it never saw the previous leader's announce). */
+    readonly epoch?: number;
+}
+interface ByeMessage {
+    readonly t: 'bye';
+    readonly fromId: string;
+}
+interface ReqMessage {
+    readonly t: 'req';
+    readonly epoch: number;
+    readonly fromId: string;
+    readonly reqId: number;
+    readonly method: string;
+    readonly args: readonly unknown[];
+}
+interface AnnounceMessage {
+    readonly t: 'announce';
+    readonly epoch: number;
+    readonly clientId: string;
+}
+interface ResMessage {
+    readonly t: 'res';
+    readonly epoch: number;
+    readonly reqId: number;
+    readonly ok: boolean;
+    readonly value?: unknown;
+    readonly error?: {
+        code: string;
+        message: string;
+        retryable: boolean;
+    };
+}
+interface EventMessage {
+    readonly t: 'event';
+    readonly epoch: number;
+    readonly event: SyncWorkerEvent;
+}
+export type MultiTabMessage = HelloMessage | ByeMessage | ReqMessage | AnnounceMessage | ResMessage | EventMessage;
+/**
+ * The tiny cross-tab channel surface we depend on — the DOM `BroadcastChannel`
+ * satisfies it. Injectable so bun tests can pair two instances by name.
+ */
+export interface CrossTabChannel {
+    postMessage(message: MultiTabMessage): void;
+    addEventListener(type: 'message', listener: (event: {
+        data: MultiTabMessage;
+    }) => void): void;
+    removeEventListener(type: 'message', listener: (event: {
+        data: MultiTabMessage;
+    }) => void): void;
+    close(): void;
+}
+/** Default channel factory: a real `BroadcastChannel` named per lock. */
+export declare function broadcastChannelFactory(): (name: string) => CrossTabChannel;
+/** The channel name a leader and its followers rendezvous on. */
+export declare function multiTabChannelName(lockName: string): string;
+/** A per-tab identity for addressing (not a presence identity). */
+export declare function newTabId(): string;
+/**
+ * Runs on the leader tab. Announces leadership, answers follower `req`s by
+ * invoking the (already-running) worker via `invoke`, and rebroadcasts every
+ * worker event to followers. Owns nothing about the worker lifecycle — the
+ * worker-host stays the single core owner; this is a relay.
+ */
+export declare class LeaderBridge {
+    #private;
+    constructor(options: {
+        channel: CrossTabChannel;
+        epoch: number;
+        clientId: string;
+        invoke: (method: string, args: readonly unknown[]) => Promise<unknown>;
+    });
+    /** Re-announce leadership (on promotion and on a follower `hello`). */
+    announce(): void;
+    /** Fan a worker event out to all followers on the current epoch. */
+    broadcastEvent(event: SyncWorkerEvent): void;
+    close(): void;
+}
+/**
+ * Runs on a follower tab. Sends `req`s to the leader and settles them on the
+ * matching `res`; queues calls (bounded, timed) while no leader is bound (the
+ * handover gap) and flushes them once an `announce` binds a new leader.
+ * Feeds fanned-out events to `onEvent`. Learns leadership changes and hands
+ * the resolved leader `clientId` back through `onLeaderChange`.
+ */
+export declare class FollowerLink {
+    #private;
+    constructor(options: {
+        channel: CrossTabChannel;
+        fromId: string;
+        onEvent: (event: SyncWorkerEvent) => void;
+        onLeaderChange: (clientId: string) => void;
+        callTimeoutMs?: number;
+        queueLimit?: number;
+    });
+    get epoch(): number;
+    get maxEpochSeen(): number;
+    get leaderClientId(): string;
+    /** Whether a leader is currently bound (an announce has been heard). */
+    get bound(): boolean;
+    /**
+     * Resolve once the link is bound to a leader (the first `announce` arrived),
+     * or reject if `timeoutMs` elapses first. A caller awaits this before
+     * treating the follower as ready: until an announce is processed the link's
+     * epoch is -1, so any fanned-out `event` in that window is dropped (an
+     * unbound follower cannot match the leader's epoch). Awaiting binding closes
+     * that gap — a just-opened follower tab never misses an invalidation emitted
+     * between its `hello` and the leader's `announce`. Resolves synchronously
+     * when already bound.
+     */
+    waitUntilBound(timeoutMs?: number): Promise<void>;
+    /** Forward one logical API call to the leader (queued if unbound). */
+    call(method: string, args: readonly unknown[]): Promise<unknown>;
+    /**
+     * The leader we were bound to went away (its lock released). Un-bind so new
+     * calls queue again; re-request an announce so the next leader finds us.
+     * In-flight calls stay pending — their per-call timeout is the backstop,
+     * and the winner's announce will flush any that were queued.
+     */
+    unbind(): void;
+    close(): void;
+}
+export {};