@voltro/local-first 0.51.0 → 0.53.0

package/dist/index.d.ts

@@ -62,18 +62,29 @@ export declare interface ConnectionState {
     readonly attempt: number;
 }
 
-/**
- * A CRDT implementation. One per library. The default is {@link yjsBackend}.
- *
- * `merge` and `decodeText` are STATELESS with respect to any live handle: they
- * operate purely on encoded bytes, which is what lets the sync layer and tests
- * converge two states without holding a document open.
- */
 export declare interface CrdtBackend {
     /** Identifies the library, e.g. `"yjs"`. Surfaced for diagnostics/telemetry. */
     readonly name: string;
     /** Create a fresh text buffer, optionally seeded with `initial`. */
     createText: (initial?: string) => CrdtTextHandle;
+    /** Create a whole-document handle, optionally seeded from encoded state. */
+    createDoc: (initial?: CrdtState) => CrdtDocHandle;
+    /**
+     * Re-encode a state through a live document so the backend garbage-collects
+     * what it can (Yjs: `mergeUpdates` never GCs tombstones, so a hot document's
+     * blob grows monotonically without this). Loses UPDATE HISTORY by design —
+     * a version-history feature must snapshot BEFORE compacting.
+     */
+    compact: (state: CrdtState) => CrdtState;
+    /**
+     * HARD compaction for a text state: re-create the document from its
+     * MATERIALISED text, dropping all history, tombstones and client ids. The
+     * result is minimal — and a NEW EPOCH: it does not merge with updates from
+     * the old lineage, so the server treats a rebase as a fresh snapshot for
+     * every subscriber (which the subscription lane already handles as a
+     * reset). Use when `compact` no longer bounds a hot document.
+     */
+    rebaseText: (state: CrdtState) => CrdtState;
     /**
      * Merge two encoded states into one converged encoded state.
      *
@@ -89,6 +100,54 @@ export declare interface CrdtBackend {
     emptyState: () => CrdtState;
 }
 
+/**
+ * A CRDT implementation. One per library. The default is {@link yjsBackend}.
+ *
+ * `merge` and `decodeText` are STATELESS with respect to any live handle: they
+ * operate purely on encoded bytes, which is what lets the sync layer and tests
+ * converge two states without holding a document open.
+ */
+/**
+ * A live, mutable CRDT DOCUMENT — the whole-doc generalisation `crdtDoc()`
+ * stores (rich text, maps, arrays; whatever the backend's document model
+ * holds). `crdtText()` remains the single-field specialisation over the same
+ * backend.
+ */
+declare interface CrdtDocHandle {
+    /**
+     * The underlying library document (a `Y.Doc` for the yjs backend), typed
+     * opaquely: an EDITOR BINDING needs the real object (Tiptap's Collaboration
+     * extension takes a Y.Doc), while every sync-layer consumer only moves
+     * encoded bytes and must never reach in. Cast at the binding, nowhere else.
+     */
+    readonly raw: unknown;
+    /** Full state, encoded for transport or merge. */
+    encodeState: () => CrdtState;
+    /** This doc's state VECTOR — the compact "what I have" summary a peer
+     *  diffs against. */
+    stateVector: () => Uint8Array;
+    /**
+     * Encode only what a peer holding `sinceVector` is missing — the
+     * INCREMENTAL update lane. A 1-character edit against a 100 KB doc encodes
+     * to a few dozen bytes, not the full state.
+     */
+    encodeUpdateSince: (sinceVector: Uint8Array) => CrdtState;
+    /** Fold an encoded state or incremental update into this doc, in place. */
+    applyState: (state: CrdtState) => void;
+    /** Subscribe to update blobs this doc produces (local edits AND applied
+     *  remote states). Returns the unsubscribe. */
+    onUpdate: (handler: (update: CrdtState) => void) => () => void;
+    /**
+     * Encode a stable ANCHOR at `index` of the named text field — a position
+     * that survives concurrent edits (the primitive an inline-comment UI pins
+     * threads with; the UI itself is the comments plugin's business).
+     */
+    encodeAnchor: (field: string, index: number) => Uint8Array;
+    /** Resolve an anchor back to its current index, or `undefined` when the
+     *  anchored region was deleted. */
+    resolveAnchor: (encoded: Uint8Array) => number | undefined;
+}
+
 /** Identifies one CRDT-managed cell: a `crdtText()` COLUMN of one ROW of one TABLE. */
 export declare interface CrdtDocKey {
     readonly table: string;
@@ -96,6 +155,14 @@ export declare interface CrdtDocKey {
     readonly column: string;
 }
 
+/**
+ * The client half of the CRDT downstream lane (plan 18): fold a `mergeCells`
+ * delta op's INCREMENTAL update into the held cell state. Pass as
+ * `@voltro/client`'s `SubscriptionCacheOptions.mergeCell`. A held cell that
+ * is not bytes (never delivered yet) takes the update as the new state.
+ */
+export declare const crdtMergeCell: (_column: string, prevValue: unknown, update: unknown) => unknown;
+
 /**
  * An encoded CRDT state or delta, as opaque bytes. Produced by
  * {@link CrdtBackend.encodeState} / {@link CrdtTextHandle.encodeState},
@@ -168,6 +235,26 @@ export declare interface CrdtWritePayload extends CrdtDocKey {
     readonly update: CrdtState;
 }
 
+/**
+ * The fallback-aware entry: durable when the environment allows it, in-memory
+ * + online-only otherwise — the plan's storage-fallback rule. The caller gets
+ * told which one it got; silence here would make a lockdown browser look like
+ * a working offline app until the first reload lost everything.
+ */
+export declare const createDurableKv: (options?: {
+    readonly factory?: KvIndexedDbFactory;
+    readonly databaseName?: string;
+}) => Promise<DurableKvResult>;
+
+/**
+ * A durable KvStore over IndexedDB. Throws when no factory is available —
+ * `createDurableKv` below is the fallback-aware entry callers should use.
+ */
+export declare const createIndexedDbKv: (options?: {
+    readonly factory?: KvIndexedDbFactory;
+    readonly databaseName?: string;
+}) => Promise<KvStore>;
+
 /**
  * Create a durable {@link PersistenceAdapter} over IndexedDB.
  *
@@ -181,6 +268,9 @@ export declare const createIndexedDbPersistence: (options?: {
     readonly databaseName?: string;
 }) => Promise<PersistenceAdapter>;
 
+/** In-memory KvStore — real (copies nothing; values are caller-owned JSON). */
+export declare const createInMemoryKv: () => KvStore;
+
 /**
  * An in-memory {@link PersistenceAdapter} backed by Maps. Real, not a stub: it
  * fully satisfies the contract, and copies bytes on the way in and out so a
@@ -214,6 +304,18 @@ export declare const createInMemoryPresenceChannel: (bus?: InMemoryPresenceBus)
  */
 export declare const createPresenceRoom: <TPresence>(options: PresenceRoomOptions<TPresence>) => PresenceRoom<TPresence>;
 
+export declare const createQueryMirror: (kv: KvStore, partition: MirrorPartition, options?: QueryMirrorOptions, now?: () => number) => QueryMirror;
+
+/**
+ * Bind a partitioned {@link QueryMirror} to the subscription cache's mirror
+ * seam. Only declared tags persist; the mirror's own encrypted-column strip
+ * runs through `metadata` via the tag→table map.
+ *
+ * NOTE the mirror instance must already carry the CURRENT subject's
+ * partition — see the partition-switch note in the file header.
+ */
+export declare const createSubscriptionMirrorBinding: (mirror: QueryMirror, options: MirrorBindingOptions) => SubscriptionMirrorShape;
+
 /**
  * Create a sync client over a {@link SyncTransport}.
  *
@@ -245,6 +347,26 @@ export declare const defaultCrdtBackend: CrdtBackend;
  */
 export declare const deriveSyncStatus: (phase: ConnectionPhase, outstanding: number) => SyncStatus;
 
+export declare interface DrainLockOptions {
+    /** Injectable locks implementation. Defaults to `navigator.locks` (which
+     *  node 22+ and every modern browser provide). Pass `null` to force the
+     *  no-locks path — a host genuinely without the API, or a test. */
+    readonly locks?: WebLocksLike | null;
+    /** Partition discriminator — one drainer per (subject, tenant) queue. */
+    readonly name: string;
+}
+
+export declare type DrainOutcome = 'drained' | 'held-elsewhere' | 'no-locks';
+
+export declare interface DurableKvResult {
+    readonly kv: KvStore;
+    /** `'durable'` when IndexedDB opened; `'memory'` when the environment has
+     *  none (non-browser host, lockdown mode) or the open failed (quota, a
+     *  private tab that refuses at open time). VISIBLE degradation — render it
+     *  in a sync status — never a crash. */
+    readonly durability: 'durable' | 'memory';
+}
+
 /** The encoded empty state — the identity element for {@link mergeCrdtStates}. */
 export declare const emptyCrdtState: (backend?: CrdtBackend) => CrdtState;
 
@@ -268,16 +390,35 @@ declare interface IDBDatabaseLike {
     createObjectStore: (name: string) => IDBObjectStoreLike;
 }
 
+declare interface IDBDatabaseLike_2 {
+    transaction(name: string, mode: 'readonly' | 'readwrite'): IDBTransactionLike_2;
+    objectStoreNames: {
+        contains(name: string): boolean;
+    };
+    createObjectStore(name: string): unknown;
+}
+
 declare interface IDBObjectStoreLike {
     get: (key: string) => IDBRequestLike<unknown>;
     put: (value: unknown, key: string) => IDBRequestLike<unknown>;
     delete: (key: string) => IDBRequestLike<unknown>;
 }
 
+declare interface IDBObjectStoreLike_2 {
+    get(key: string): IDBRequestLike_2<unknown>;
+    put(value: unknown, key: string): IDBRequestLike_2<unknown>;
+    delete(key: string): IDBRequestLike_2<unknown>;
+    getAllKeys(range?: unknown): IDBRequestLike_2<ReadonlyArray<string>>;
+}
+
 declare interface IDBOpenRequestLike extends IDBRequestLike<IDBDatabaseLike> {
     onupgradeneeded: ((this: unknown, ev: unknown) => void) | null;
 }
 
+declare interface IDBOpenRequestLike_2 extends IDBRequestLike_2<IDBDatabaseLike_2> {
+    onupgradeneeded: ((this: unknown, ev: unknown) => void) | null;
+}
+
 declare interface IDBRequestLike<T> {
     result: T;
     error: unknown;
@@ -285,18 +426,36 @@ declare interface IDBRequestLike<T> {
     onerror: ((this: unknown, ev: unknown) => void) | null;
 }
 
+declare interface IDBRequestLike_2<T> {
+    result: T;
+    error: unknown;
+    onsuccess: ((this: unknown, ev: unknown) => void) | null;
+    onerror: ((this: unknown, ev: unknown) => void) | null;
+}
+
 declare interface IDBTransactionLike {
     objectStore: (name: string) => IDBObjectStoreLike;
 }
 
+declare interface IDBTransactionLike_2 {
+    objectStore(name: string): IDBObjectStoreLike_2;
+}
+
 /**
  * DONE — Durable persistence.
  *   `createIndexedDbPersistence` (./persistence/indexedDb) is a durable
  *   `PersistenceAdapter` over IndexedDB — no WASM, no added dependency, tested
  *   against a fake IDB backend that survives a reopen. `createInMemoryPersistence`
- *   remains the ephemeral default. REMAINING (optional): a wa-sqlite / Turso
- *   adapter for cross-tab SQL, a sibling file behind the SAME interface + the
- *   plan's LRU eviction. Nothing above the adapter changes when it lands.
+ *   remains the ephemeral default. The engine's query mirror adds `KvStore`
+ *   (in-memory + IndexedDB + `createDurableKv` with a VISIBLE memory
+ *   fallback) beneath `createQueryMirror` — budget eviction included
+ *   (`enforceBudget`, oldest-saved first). wa-sqlite was considered and
+ *   REJECTED with the reasoning recorded in `mirror/queryMirror.ts`: the
+ *   client's query surface is `(tag, input)`, predicates never exist
+ *   client-side, so a browser SQL engine would evaluate a language the
+ *   client never sees. A SQLite BACKING behind `KvStore` remains possible
+ *   without touching a consumer (mobile's expo-sqlite adapter takes exactly
+ *   that seam).
  *
  * DONE — Bi-directional sync wire.
  *   `createSyncClient` (./sync/syncClient) maps the pure sync-queue reducer onto
@@ -323,10 +482,14 @@ declare interface IDBTransactionLike {
  *   ephemeral awareness over a `PresenceChannel` — join/leave, announce-back
  *   discovery, cursor propagation, TTL expiry. Tested over the in-memory channel
  *   (`createInMemoryPresenceChannel`), which is the SAME dumb string-payload
- *   shape as the framework's `BroadcastProvider`. REMAINING (runtime binding):
- *   a `PresenceChannel` that forwards onto the app's provisioned broker
- *   (in-memory locally; Redis / NATS at scale — both already shipped in
- *   `@voltro/plugin-broadcast`). That is a network hop, not new logic.
+ *   shape as the framework's `BroadcastProvider`. The runtime binding is DONE
+ *   (plan 02 phase 1): `usePresenceChannel` in `@voltro/plugin-presence/web`
+ *   rides the framework's EXISTING presence lane — `presence.heartbeat`
+ *   carries the payload as member meta, the push-driven `presence.list`
+ *   roster delivers it — so cross-replica fan-out is plugin-broadcast's and
+ *   there is ONE presence wire, not two. The shape parity is pinned by
+ *   `presence/channelParity.test-d.ts` (structural restatement, no
+ *   production dependency edge).
  *
  * DONE — localFirst mixin + discovery.
  *   `localFirst()` (`@voltro/database`) marks a table; the runtime SchemaRegistry
@@ -355,6 +518,20 @@ export declare interface InMemoryPresenceBus {
     readonly rooms: Map<string, Set<(payload: string) => void>>;
 }
 
+export declare interface KvIndexedDbFactory {
+    open(name: string, version: number): IDBOpenRequestLike_2;
+}
+
+export declare interface KvStore {
+    /** Identifies the backing (`"in-memory"` / `"indexeddb"`). Diagnostics. */
+    readonly kind: string;
+    readonly get: (key: string) => Promise<unknown>;
+    readonly put: (key: string, value: unknown) => Promise<void>;
+    readonly del: (key: string) => Promise<void>;
+    /** All stored keys starting with `prefix`, unordered. */
+    readonly keysWithPrefix: (prefix: string) => Promise<ReadonlyArray<string>>;
+}
+
 /**
  * Last-write-wins: newer `updatedAt` wins; exact ties break on the (stable,
  * symmetric) tiebreak key so both peers converge on the same value.
@@ -372,15 +549,82 @@ export declare const lastWriteWins: ConflictResolver;
  */
 export declare const loadPersistedSyncQueue: <T = unknown>(adapter: PersistenceAdapter, online?: boolean) => Promise<PersistedSyncQueue<T>>;
 
+export declare const mergeCrdtStates: (a: CrdtState, b: CrdtState, backend?: CrdtBackend) => CrdtState;
+
+export declare interface MirrorBindingOptions {
+    /** Which rpc tags are backed by which `localFirst()` table — the app's
+     *  declaration of its sync set. A tag absent here is NOT mirrored. */
+    readonly tags: Readonly<Record<string, string>>;
+    /** The codegen-emitted metadata (`localFirstTables` from
+     *  `.framework/localFirst.generated.ts`): table → columns to strip. */
+    readonly metadata?: Readonly<Record<string, {
+        readonly encryptedColumns: ReadonlyArray<string>;
+    }>>;
+    /**
+     * Schema fingerprint of the CLIENT build (any stable string — a build hash,
+     * an app version, `JSON.stringify(localFirstTables)`). The local-DB
+     * migration path: entries persist under the fingerprint they were written
+     * with, and a load under a DIFFERENT fingerprint returns nothing — a
+     * v1-mirrored row set is never rendered into a v2 UI whose columns moved.
+     * The DISCARD is visible as a plain cold start (loading, then the server's
+     * fresh snapshot), never a crash or a mixed-shape render. The offline
+     * QUEUE deliberately does not gate on this: a queued v1 write replays
+     * against the v2 server, whose input schema is the authority — a write it
+     * rejects surfaces as a failed/conflicted outbox entry the user can see
+     * and resolve, which beats silently dropping their work.
+     */
+    readonly schemaFingerprint?: string;
+}
+
+export declare interface MirroredQuery {
+    /** The rpc tag — kept for diagnostics and schema-migration checks. */
+    readonly tag: string;
+    /** The materialised rows (or single value) as the client would render them. */
+    readonly data: unknown;
+    /** The subscription revision `data` corresponds to — presented on
+     *  re-subscribe as `voltro-resume-from`, so a reload inside the resume
+     *  window continues with deltas instead of a snapshot. */
+    readonly revision: number;
+    /** When this entry was last written (ms epoch) — budget eviction input. */
+    readonly savedAt: number;
+    /** Schema fingerprint of the build that wrote the entry (see the binding's
+     *  `schemaFingerprint` — the local-DB migration gate). Absent when the app
+     *  does not stamp builds. */
+    readonly fingerprint?: string;
+}
+
+export declare interface MirrorPartition {
+    readonly subjectId: string;
+    readonly tenantId: string;
+}
+
+/** Structural mirror of `@voltro/client`'s `OutboxEntry` — kept structural so
+ *  this package does not depend on the client package (the client consumes
+ *  US through its `OutboxPersistence` seam, not the other way around). */
+export declare interface OutboxEntryShape {
+    readonly id: string;
+    readonly tag: string;
+    readonly input: unknown;
+    readonly status: 'pending' | 'sent' | 'failed' | 'conflict';
+    readonly attempts: number;
+    readonly error?: unknown;
+}
+
 /**
- * The heart of the package: converge two encoded CRDT states into one.
+ * Bind an outbox to a {@link PersistenceAdapter}. Pass the result as
+ * `useOutbox({ persistence })`.
  *
- * Deterministic and order-independent up to the resulting text
- * (`decodeCrdtText(mergeCrdtStates(a, b))` equals the same for `(b, a)`),
- * idempotent (re-merging a state already contained is a no-op on the text), and
- * treats {@link CrdtBackend.emptyState} as identity.
+ * `now` is injectable for determinism (the adapter's `QueuedWrite` carries an
+ * `enqueuedAt`); entries that do not decode as outbox entries are DROPPED on
+ * load rather than crashing the hydration — a queue poisoned by another
+ * writer's shape degrades to the entries it can vouch for.
  */
-export declare const mergeCrdtStates: (a: CrdtState, b: CrdtState, backend?: CrdtBackend) => CrdtState;
+export declare const outboxPersistence: (adapter: PersistenceAdapter, now?: () => number) => OutboxPersistenceBinding;
+
+export declare interface OutboxPersistenceBinding {
+    readonly load: () => Promise<ReadonlyArray<OutboxEntryShape>>;
+    readonly save: (queue: ReadonlyArray<OutboxEntryShape>) => Promise<void>;
+}
 
 /** Total outstanding writes (pending + the one in flight). 0 means fully synced. */
 export declare const outstandingCount: (state: SyncQueueState) => number;
@@ -472,6 +716,25 @@ export declare interface PresenceRoomOptions<TPresence> {
     readonly now?: () => number;
 }
 
+export declare interface QueryMirror {
+    readonly partition: MirrorPartition;
+    readonly save: (queryKey: string, entry: Omit<MirroredQuery, 'savedAt'>) => Promise<void>;
+    readonly load: (queryKey: string) => Promise<MirroredQuery | undefined>;
+    /** Drop every mirrored query of THIS partition (logout, revocation). */
+    readonly purge: () => Promise<void>;
+    /** Enforce the storage budget: evict least-recently-saved entries until the
+     *  serialised size estimate fits `maxBytes`. Returns evicted keys. */
+    readonly enforceBudget: (maxBytes: number) => Promise<ReadonlyArray<string>>;
+}
+
+export declare interface QueryMirrorOptions {
+    /** Column-exposure metadata for `localFirst()` tables, as emitted by the
+     *  codegen: table → columns that must NEVER be persisted locally
+     *  (`.encrypted()`). The mirror strips them from every row of a saved
+     *  entry when `tableOf` resolves the entry's tag to a table. */
+    readonly encryptedColumnsOf?: (tag: string) => ReadonlyArray<string> | undefined;
+}
+
 /** A single queued write. `payload` is opaque to the queue — the wire seam owns its shape. */
 export declare interface QueuedWrite<T = unknown> {
     readonly id: string;
@@ -487,6 +750,20 @@ export declare interface RemoteCrdtState extends CrdtDocKey {
     readonly state: CrdtState;
 }
 
+/**
+ * Resolve a conflicted row write: CRDT columns merge, the rest go through the
+ * policy. `local`/`remote` carry per-field `{ value, updatedAt, writer }`;
+ * CRDT columns' values are their encoded states.
+ */
+export declare const resolveWithPolicy: (policy: ConflictPolicy, local: VersionedRecord, remote: VersionedRecord, options?: ResolveWithPolicyOptions) => Record<string, unknown>;
+
+export declare interface ResolveWithPolicyOptions {
+    /** Column names that are `crdtText()` cells — merged, never policy-resolved.
+     *  Comes from the codegen's localFirst column metadata. */
+    readonly crdtColumns?: ReadonlyArray<string>;
+    readonly backend?: CrdtBackend;
+}
+
 /**
  * The genuinely REMAINING runtime seams — provisioned infra + the two app-level
  * NAMES nothing can derive, not un-built framework code:
@@ -499,6 +776,20 @@ export declare const RUNTIME_SEAMS: readonly ["sync-transport-app-tags", "presen
 
 export declare type RuntimeSeam = (typeof RUNTIME_SEAMS)[number];
 
+/** Structural mirror of `@voltro/client`'s SubscriptionMirror — restated so
+ *  this package carries no client dependency; the client consumes US. */
+export declare interface SubscriptionMirrorShape {
+    readonly load: (key: string) => Promise<{
+        readonly data: unknown;
+        readonly revision: number;
+    } | undefined>;
+    readonly save: (key: string, snap: {
+        readonly tag: string | undefined;
+        readonly data: unknown;
+        readonly revision: number;
+    }) => Promise<void>;
+}
+
 export declare interface SyncClient {
     /** Apply a local edit: merge it into local state immediately (optimistic),
      *  persist, queue it, and start draining if online. */
@@ -609,6 +900,24 @@ export declare interface SyncTransport {
 /** A record's fields, each carrying its version metadata. */
 export declare type VersionedRecord = Record<string, FieldValue>;
 
+export declare interface WebLocksLike {
+    readonly request: (name: string, options: {
+        readonly mode: 'exclusive';
+        readonly ifAvailable: boolean;
+    }, callback: (lock: unknown | null) => Promise<void>) => Promise<void>;
+}
+
+/**
+ * Run `drain` under the partition's exclusive cross-tab lock.
+ *
+ * `ifAvailable: true` — a tab that finds the lock held does NOT queue behind
+ * it (the holder is already draining the same shared queue; a second run the
+ * moment it finishes would replay an already-compacted queue). It reports
+ * `held-elsewhere` and relies on the holder's drain + its own next trigger
+ * (reconnect, enqueue) to try again.
+ */
+export declare const withDrainLock: (options: DrainLockOptions, drain: () => Promise<void>) => Promise<DrainOutcome>;
+
 export declare const yjsBackend: CrdtBackend;
 
 export { }