@datafn/client 0.0.1 → 0.0.2

package/dist/index.d.ts

@@ -1,4 +1,5 @@
-import { DatafnEvent, DatafnSignal, DatafnSchema, DatafnPlugin, DatafnErrorCode } from '@datafn/core';
+import { DatafnEvent, DatafnSchema, DfqlQueryFragment, DfqlMutationFragment, DfqlTransact, DatafnSignal, DatafnPlugin, SearchProvider, DatafnErrorCode } from '@datafn/core';
+export { KV_RESOURCE_NAME, kvId, ns } from '@datafn/core';
 
 /**
  * Event filtering logic
@@ -12,6 +13,7 @@ interface EventFilter {
     action?: string | string[];
     fields?: string | string[];
     contextKeys?: string[];
+    context?: Record<string, unknown>;
 }
 /**
  * Check if an event matches the filter
@@ -23,42 +25,52 @@ declare function matchesFilter(event: DatafnEvent, filter?: EventFilter): boolea
  */
 
 type EventHandler = (event: DatafnEvent) => void;
+interface EventBusOptions {
+    /**
+     * Error handler called when a subscriber throws an error.
+     * Default: logs to console.error
+     */
+    onError?: (error: unknown, event: DatafnEvent) => void;
+}
 /**
- * Simple in-process event bus
+ * Simple in-process event bus with fault-tolerant delivery
  */
 declare class EventBus {
     private subscriptions;
     private nextId;
+    private onError;
+    constructor(options?: EventBusOptions);
     /**
      * Subscribe to events with optional filtering
      */
     subscribe(handler: EventHandler, filter?: EventFilter): () => void;
     /**
-     * Emit an event to all matching subscribers
+     * Emit an event to all matching subscribers.
+     * Errors in handlers are isolated - a throwing handler will not prevent delivery to other handlers.
      */
     emit(event: DatafnEvent): void;
-}
-
-/**
- * DataFn Table Handle
- *
- * Represents a table/resource from the schema with methods for query, mutation, signals, and subscriptions.
- */
-
-interface DatafnTable<TRecord = unknown> {
-    name: string;
-    version: number;
-    query(q: unknown): Promise<unknown>;
-    mutate(m: unknown): Promise<unknown>;
-    transact(payload: unknown): Promise<unknown>;
-    signal(q: unknown): DatafnSignal<unknown>;
-    subscribe(handler: EventHandler, filter?: EventFilter): () => void;
+    /**
+     * Remove all subscriptions
+     */
+    clear(): void;
 }
 
 /**
  * Storage adapter types for local persistence
  */
 type DatafnHydrationState = "notStarted" | "hydrating" | "ready";
+/**
+ * Factory function for creating storage adapters with namespace-based isolation.
+ * Used for multi-user/multi-tenant data isolation.
+ *
+ * @example
+ * ```typescript
+ * const storageFactory: DatafnStorageFactory = (namespace) => {
+ *   return IndexedDbStorageAdapter.createForNamespace("my-app", namespace);
+ * };
+ * ```
+ */
+type DatafnStorageFactory = (namespace: string) => DatafnStorageAdapter;
 type DatafnChangelogEntry = {
     /** Monotonic local sequence (assigned by storage adapter). */
     seq: number;
@@ -66,17 +78,31 @@ type DatafnChangelogEntry = {
     mutationId: string;
     mutation: Record<string, unknown>;
     timestampMs: number;
+    /** Actor ID for audit attribution (when available) - AUD-001 */
+    actorId?: string;
+    /** ISO 8601 timestamp - AUD-001 */
+    timestamp?: string;
 };
 interface DatafnStorageAdapter {
     getRecord(resource: string, id: string): Promise<Record<string, unknown> | null>;
     listRecords(resource: string): Promise<Record<string, unknown>[]>;
     upsertRecord(resource: string, record: Record<string, unknown>): Promise<void>;
     deleteRecord(resource: string, id: string): Promise<void>;
+    /**
+     * Atomic read-modify-write merge. MUST execute in a single transaction.
+     * If record doesn't exist, upserts with partial as the full record.
+     * Uses one-level-deep merge for object-type fields.
+     */
+    mergeRecord(resource: string, id: string, partial: Record<string, unknown>): Promise<Record<string, unknown>>;
     listJoinRows(relationKey: string): Promise<Array<Record<string, unknown>>>;
+    getJoinRows(relationKey: string, fromId: string): Promise<Array<Record<string, unknown>>>;
+    getJoinRowsInverse(relationKey: string, toId: string): Promise<Array<Record<string, unknown>>>;
     upsertJoinRow(relationKey: string, row: Record<string, unknown>): Promise<void>;
+    setJoinRows(relationKey: string, rows: Array<Record<string, unknown>>): Promise<void>;
     deleteJoinRow(relationKey: string, from: string, to: string): Promise<void>;
+    findRecords(resource: string, field: string, value: unknown): Promise<Record<string, unknown>[]>;
     getCursor(resource: string): Promise<string | null>;
-    setCursor(resource: string, cursor: string): Promise<void>;
+    setCursor(resource: string, cursor: string | null): Promise<void>;
     getHydrationState(resource: string): Promise<DatafnHydrationState>;
     setHydrationState(resource: string, state: DatafnHydrationState): Promise<void>;
     changelogAppend(entry: Omit<DatafnChangelogEntry, "seq">): Promise<DatafnChangelogEntry>;
@@ -86,13 +112,135 @@ interface DatafnStorageAdapter {
     changelogAck(options: {
         throughSeq: number;
     }): Promise<void>;
+    countRecords(resource: string): Promise<number>;
+    countJoinRows(relationKey: string): Promise<number>;
+    /** Close all connections and release resources. */
+    close(): Promise<void>;
+    /** Delete all data across all stores. */
+    clearAll(): Promise<void>;
+    /**
+     * Health check: verify core stores exist and are accessible.
+     * Returns { ok: true, issues: [] } when healthy.
+     * Returns { ok: false, issues: [...] } when corrupted or inaccessible.
+     */
+    healthCheck(): Promise<{
+        ok: boolean;
+        issues: string[];
+    }>;
+}
+
+/**
+ * Mutation Execution Utilities
+ *
+ * Handles mutation execution via remote adapter with event emission.
+ */
+
+type ShareScope = "record" | "resource";
+type PrincipalShareMutationInput = {
+    principalId: string;
+    level: string;
+    scope?: ShareScope;
+    id?: string;
+};
+type PrincipalUnshareMutationInput = {
+    principalId: string;
+    scope?: ShareScope;
+    id?: string;
+};
+
+/**
+ * Query Execution Utilities
+ *
+ * Handles query execution via remote adapter or local storage based on hydration state.
+ */
+
+type PermissionEntry = {
+    userId: string;
+    level: string;
+    grantedBy: string;
+    grantedAt: number;
+};
+
+/**
+ * DataFn Table Handle
+ *
+ * Represents a table/resource from the schema with methods for query, mutation, signals, and subscriptions.
+ */
+
+type QueryMetadata = {
+    includeTrashed?: boolean;
+    includeArchived?: boolean;
+};
+interface DatafnTable<S extends DatafnSchema = DatafnSchema, Name extends string = string, TRecord = unknown> {
+    name: Name;
+    version: number;
+    query(q: DfqlQueryFragment & {
+        metadata?: QueryMetadata;
+    }): Promise<unknown>;
+    mutate(m: DfqlMutationFragment | DfqlMutationFragment[]): Promise<unknown>;
+    delete(id: string): Promise<unknown>;
+    trash?: (id: string) => Promise<unknown>;
+    restore?: (id: string) => Promise<unknown>;
+    archive?: (id: string) => Promise<unknown>;
+    unarchive?: (id: string) => Promise<unknown>;
+    share?: {
+        (id: string, userId: string, level: string): Promise<unknown>;
+        (input: PrincipalShareMutationInput): Promise<unknown>;
+    };
+    unshare?: {
+        (id: string, userId: string): Promise<unknown>;
+        (input: PrincipalUnshareMutationInput): Promise<unknown>;
+    };
+    getPermissions?: (id: string) => Promise<PermissionEntry[]>;
+    transact(payload: DfqlTransact): Promise<unknown>;
+    signal(q: DfqlQueryFragment, options?: {
+        disableOptimistic?: boolean;
+    }): DatafnSignal<unknown>;
+    subscribe(handler: EventHandler, filter?: EventFilter): () => void;
 }
 
+type CloneUpOptions = {
+    resources?: string[];
+    includeManyMany?: boolean;
+    recordOperation?: "merge" | "replace" | "insert";
+    batchSize?: number;
+    maxRetries?: number;
+    failFast?: boolean;
+    clearChangelogOnSuccess?: boolean;
+    setGlobalCursorOnSuccess?: boolean;
+    pullAfter?: boolean;
+    mutationIdPrefix?: string;
+};
+type CloneUpResult = {
+    ok: boolean;
+    cursor: string;
+    stats: {
+        resources: Record<string, {
+            records: number;
+            mutations: number;
+        }>;
+        joinStores: Record<string, {
+            rows: number;
+            mutations: number;
+        }>;
+        batches: number;
+    };
+    errors: Array<{
+        mutationId: string;
+        code: string;
+        message: string;
+        path: string;
+    }>;
+    /** Optional total count of uploaded records (for event context) */
+    uploadedCount?: number;
+};
+
 /**
  * Sync Facade
  *
  * Client-side sync methods that delegate to remote adapter.
  * When storage is configured, clone/pull results are applied to local storage.
+ * Implements HOOK-001 and EVT-003: beforeSync/afterSync hooks and sync lifecycle events
  */
 
 interface SyncFacade {
@@ -100,12 +248,57 @@ interface SyncFacade {
     clone(payload: unknown): Promise<unknown>;
     pull(payload: unknown): Promise<unknown>;
     push(payload: unknown): Promise<unknown>;
+    cloneUp(options?: CloneUpOptions): Promise<CloneUpResult>;
+}
+
+/**
+ * KV API implementation for datafn
+ * Provides a first-class key-value store that works with signals and events.
+ */
+
+interface DatafnKvApi {
+    get<T = unknown>(key: string): Promise<T | null>;
+    set<T = unknown>(key: string, value: T, params?: {
+        context?: Record<string, unknown>;
+        debounceMs?: number;
+    }): Promise<{
+        ok: true;
+        key: string;
+    } | {
+        ok: false;
+        error: unknown;
+    }>;
+    merge(key: string, patch: Record<string, unknown>, params?: {
+        context?: Record<string, unknown>;
+        debounceMs?: number;
+    }): Promise<{
+        ok: true;
+        key: string;
+    } | {
+        ok: false;
+        error: unknown;
+    }>;
+    delete(key: string, params?: {
+        context?: Record<string, unknown>;
+    }): Promise<{
+        ok: true;
+        key: string;
+    } | {
+        ok: false;
+        error: unknown;
+    }>;
+    getOrSeed<T = unknown>(key: string, defaults: T): Promise<T>;
+    flush(key?: string): Promise<void>;
+    signal<T = unknown>(key: string, options?: {
+        defaultValue?: T;
+    }): DatafnSignal<T>;
 }
 
 /**
  * DataFn client factory
  */
 
+type ResourceNames<S extends DatafnSchema> = S["resources"][number]["name"];
 interface DatafnRemoteAdapter {
     query(q: unknown): Promise<unknown>;
     mutation(m: unknown): Promise<unknown>;
@@ -114,10 +307,132 @@ interface DatafnRemoteAdapter {
     clone(payload: unknown): Promise<unknown>;
     pull(payload: unknown): Promise<unknown>;
     push(payload: unknown): Promise<unknown>;
+    reconcile(payload: unknown): Promise<unknown>;
+    search?(payload: unknown): Promise<unknown>;
+}
+interface DatafnSyncConfig {
+    /**
+     * Enable offline support. Requires `storage` adapter.
+     */
+    offlinability?: boolean;
+    /**
+     * Remote server URL used by the default HTTP transport and for deriving wsUrl.
+     * Optional when `remoteAdapter` is provided.
+     */
+    remote?: string;
+    /**
+     * Optional injected adapter used instead of DefaultHttpTransport.
+     * Required for extension environments.
+     */
+    remoteAdapter?: DatafnRemoteAdapter;
+    /**
+     * Enable WebSocket updates.
+     */
+    ws?: boolean;
+    /**
+     * WebSocket URL. If not provided, derived from `remote` when `ws` is enabled.
+     */
+    wsUrl?: string;
+    /**
+     * Batch push interval in milliseconds.
+     * Must be a positive integer.
+     */
+    pushInterval?: number;
+    /**
+     * Batch push page size.
+     * Must be a positive integer. Default 100.
+     */
+    pushBatchSize?: number;
+    /**
+     * Max retries for push.
+     * Must be a non-negative integer. Default 3.
+     */
+    pushMaxRetries?: number;
+    /**
+     * Hydration plan for large datasets.
+     */
+    hydration?: {
+        /**
+         * Resources that MUST be cloned to `ready` before the app can consider itself hydrated.
+         */
+        bootResources?: string[];
+        /**
+         * Resources that MAY hydrate in the background after boot.
+         */
+        backgroundResources?: string[];
+        /**
+         * Per-resource clone page size limits used by paginated clone.
+         */
+        clonePageSize?: number | Record<string, number>;
+    };
+    /**
+     * Explicit mode selection.
+     * - "sync": requires remote or remoteAdapter.
+     * - "local-only": remote is not required; all local tables start as `ready`.
+     */
+    mode?: "sync" | "local-only";
+    /**
+     * WebSocket reconnection configuration with exponential backoff and jitter.
+     * Default: enabled with baseDelayMs=1000, multiplier=2, maxDelayMs=60000, jitterMs=500.
+     */
+    wsReconnect?: {
+        enabled?: boolean;
+        baseDelayMs?: number;
+        maxDelayMs?: number;
+        multiplier?: number;
+        jitterMs?: number;
+    };
+    /**
+     * Push retry exponential backoff configuration.
+     * Default: baseDelayMs=1000, multiplier=2, maxDelayMs=60000, jitterMs=500.
+     */
+    pushRetryBackoff?: {
+        baseDelayMs?: number;
+        maxDelayMs?: number;
+        multiplier?: number;
+        jitterMs?: number;
+    };
+    /**
+     * Push interval exponential backoff configuration when push keeps failing.
+     * When a push round exhausts all retries and fails, the next round is delayed
+     * using exponential backoff: pushInterval * multiplier^consecutiveFailures.
+     * On first success after failures, backoff is reset to configured pushInterval.
+     * Default: baseMultiplier=2, maxDelayMs=300000 (5 minutes), jitterMs=1000.
+     */
+    pushIntervalBackoff?: {
+        baseMultiplier?: number;
+        maxDelayMs?: number;
+        jitterMs?: number;
+    };
+    /**
+     * Pull batch size limit per request.
+     * Must be a positive integer between 10 and 10000.
+     * Default: 200.
+     */
+    pullBatchSize?: number;
+    /**
+     * Maximum number of catch-up pull iterations per sync cycle (CLIENT-PULL-003).
+     * Prevents infinite loops if the server continuously returns hasMore=true.
+     * Default: 50.
+     */
+    maxPullIterations?: number;
+    /**
+     * Enable cross-tab coordination via BroadcastChannel.
+     * When enabled, mutation events are relayed to other same-origin tabs for near-instant reactivity.
+     * Default: false (opt-in).
+     */
+    crossTab?: boolean;
+    /**
+     * Defer search indexing for initial clone and rebuild asynchronously after clone completion.
+     */
+    skipCloneIndexing?: boolean;
 }
-interface DatafnClientConfig {
-    schema: DatafnSchema;
-    remote: DatafnRemoteAdapter;
+interface DatafnClientConfig<S extends DatafnSchema> {
+    schema: S;
+    /**
+     * Sync configuration.
+     */
+    sync?: DatafnSyncConfig;
     /**
      * Optional plugins for client-side hook execution
      */
@@ -126,25 +441,114 @@ interface DatafnClientConfig {
      * Stable client/device identifier used for idempotency and offline change logs.
      * Required when `storage` is provided.
      */
-    clientId?: string;
+    clientId: string;
+    /**
+     * Local persistence adapter. Can be:
+     * - A direct `DatafnStorageAdapter` instance
+     * - A factory function `(namespace: string) => DatafnStorageAdapter` for multi-user isolation
+     *
+     * When using a factory function, `namespace` must also be provided.
+     */
+    storage?: DatafnStorageAdapter | DatafnStorageFactory;
     /**
-     * Local persistence adapter. When provided, sync results are applied to local storage.
+     * Namespace for client-side data isolation.
+     * Used to construct isolated storage (IndexedDB database names, BroadcastChannel names).
+     * Required when `storage` is a factory function.
      */
-    storage?: DatafnStorageAdapter;
+    namespace?: string;
     getTimestamp?: () => number;
+    /**
+     * Resource-aware ID generator function for insert operations.
+     * If not provided, defaults to crypto.randomUUID() with resource prefix.
+     * Allows users to use custom ID strategies (UUID v7, ULID, etc.)
+     * without adding dependencies to @datafn/client.
+     */
+    generateId?: (params: {
+        resource: string;
+        idPrefix?: string;
+    }) => string;
+    /**
+     * Optional search provider for client-side search query routing.
+     */
+    searchProvider?: SearchProvider;
 }
-interface DatafnClient {
-    table<TRecord = unknown>(name: string): DatafnTable<TRecord>;
+/**
+ * Override options for switchContext.
+ * Only the provided fields are changed; everything else is inherited from the current config.
+ */
+type SwitchContextOverride = {
+    /** New namespace (replaces current) */
+    namespace?: string;
+    /** New sync configuration (replaces current, not merged) */
+    sync?: DatafnSyncConfig;
+    /** New storage adapter or factory (replaces current) */
+    storage?: DatafnStorageAdapter | DatafnStorageFactory;
+};
+type DatafnClient<S extends DatafnSchema> = {
+    table<Name extends ResourceNames<S>>(name: Name): DatafnTable<S, Name>;
     query(q: unknown | unknown[]): Promise<unknown>;
     mutate(mutation: unknown | unknown[]): Promise<unknown>;
     transact(payload: unknown): Promise<unknown>;
     subscribe(handler: EventHandler, filter?: EventFilter): () => void;
-    sync: SyncFacade;
-}
+    sync: SyncFacade & {
+        start(): Promise<void>;
+        stop(): void;
+        pullNow(): Promise<void>;
+        cloneNow(): Promise<void>;
+        reconcileNow(): Promise<void>;
+    };
+    kv: DatafnKvApi;
+    /** Tear down client: stop sync, close connections, unsubscribe all, release resources. */
+    destroy(): Promise<void>;
+    /** Wipe all local data (IndexedDB stores, cursors, changelog, hydration state). */
+    clear(): Promise<void>;
+    /** Flush a specific debounced mutation immediately. */
+    flush(key?: string): Promise<void>;
+    /** Flush all pending debounced mutations immediately. */
+    flushAll(): Promise<void>;
+    /** Export all local records as structured JSON. */
+    exportData(options?: {
+        resources?: string[];
+    }): Promise<unknown>;
+    /** Import records from a structured JSON payload. */
+    importData(data: unknown, options?: {
+        triggerCloneUp?: boolean;
+    }): Promise<unknown>;
+    /** Check storage health and verify hydration state consistency. */
+    checkHealth(): Promise<{
+        ok: boolean;
+        issues: string[];
+        action?: "none" | "reclone";
+    }>;
+    /** Perform a cross-resource search using the configured search provider. */
+    search(params: unknown): Promise<unknown>;
+    /**
+     * Switch to a different configuration context (auth, sync mode, or storage).
+     * Destroys the current underlying client and recreates it with merged config.
+     * Concurrent calls are serialized. Auto-starts sync when sync.mode is "sync".
+     */
+    switchContext(override: SwitchContextOverride): Promise<void>;
+    /** Get the current resolved namespace, or undefined if not configured. */
+    currentNamespace(): string | undefined;
+    /**
+     * Subscribe to client lifecycle changes.
+     * The callback fires immediately with the stable proxy reference,
+     * and again after every switchContext() completes.
+     * Returns an unsubscribe function.
+     */
+    subscribeClient(fn: (client: DatafnClient<S>) => void): () => void;
+} & {
+    [Name in ResourceNames<S>]: DatafnTable<S, Name>;
+};
 /**
- * Create a DataFn client
+ * Create a DataFn client with built-in context switching.
+ *
+ * The returned client is a stable Proxy reference that always delegates to the
+ * current underlying client. Use `switchContext()` to switch auth, sync mode,
+ * or storage without replacing the reference. Use `subscribeClient()` to react
+ * to switches (e.g. to recreate signals in framework adapters).
  */
-declare function createDatafnClient(config: DatafnClientConfig): DatafnClient;
+declare function createDatafnClient<S extends DatafnSchema>(config: DatafnClientConfig<S>): DatafnClient<S>;
 
 /**
  * DataFn Client Error Types
@@ -159,12 +563,16 @@ type DatafnClientError = {
     };
 };
 /**
- * Create a DataFnClientError and throw it
+ * Build and throw a DatafnClientError.
  */
-declare function createClientError(code: DatafnClientError["code"], message: string, details: {
+declare function throwClientError(code: DatafnClientError["code"], message: string, details: {
     path: string;
     [key: string]: unknown;
 }): never;
+/**
+ * Alias for `throwClientError`.
+ */
+declare const createClientError: typeof throwClientError;
 
 /**
  * Remote Response Unwrapping Utilities
@@ -194,16 +602,28 @@ declare class MemoryStorageAdapter implements DatafnStorageAdapter {
     private hydration;
     private changelog;
     private changelogSeq;
-    constructor();
+    private changelogIndex;
+    private validResources?;
+    constructor(resources?: string[]);
+    private validateTableName;
     getRecord(resource: string, id: string): Promise<Record<string, unknown> | null>;
     listRecords(resource: string): Promise<Record<string, unknown>[]>;
     upsertRecord(resource: string, record: Record<string, unknown>): Promise<void>;
     deleteRecord(resource: string, id: string): Promise<void>;
+    /**
+     * Atomic read-modify-write merge using one-level-deep merge.
+     */
+    mergeRecord(resource: string, id: string, partial: Record<string, unknown>): Promise<Record<string, unknown>>;
+    private deepMergeOneLevel;
     listJoinRows(relationKey: string): Promise<Array<Record<string, unknown>>>;
+    getJoinRows(relationKey: string, fromId: string): Promise<Array<Record<string, unknown>>>;
+    getJoinRowsInverse(relationKey: string, toId: string): Promise<Array<Record<string, unknown>>>;
     upsertJoinRow(relationKey: string, row: Record<string, unknown>): Promise<void>;
+    setJoinRows(relationKey: string, rows: Array<Record<string, unknown>>): Promise<void>;
     deleteJoinRow(relationKey: string, from: string, to: string): Promise<void>;
+    findRecords(resource: string, field: string, value: unknown): Promise<Record<string, unknown>[]>;
     getCursor(resource: string): Promise<string | null>;
-    setCursor(resource: string, cursor: string): Promise<void>;
+    setCursor(resource: string, cursor: string | null): Promise<void>;
     getHydrationState(resource: string): Promise<DatafnHydrationState>;
     setHydrationState(resource: string, state: DatafnHydrationState): Promise<void>;
     changelogAppend(entry: Omit<DatafnChangelogEntry, "seq">): Promise<DatafnChangelogEntry>;
@@ -213,7 +633,14 @@ declare class MemoryStorageAdapter implements DatafnStorageAdapter {
     changelogAck(options: {
         throughSeq: number;
     }): Promise<void>;
-    clear(): void;
+    countRecords(resource: string): Promise<number>;
+    countJoinRows(relationKey: string): Promise<number>;
+    close(): Promise<void>;
+    clearAll(): Promise<void>;
+    healthCheck(): Promise<{
+        ok: boolean;
+        issues: string[];
+    }>;
 }
 
 /**
@@ -223,17 +650,76 @@ declare class MemoryStorageAdapter implements DatafnStorageAdapter {
 
 declare class IndexedDbStorageAdapter implements DatafnStorageAdapter {
     private dbPromise;
-    constructor(dbName?: string);
+    private validResources?;
+    private schema?;
+    readonly dbName: string;
+    /**
+     * Create an IndexedDB storage adapter with schema-aware store creation.
+     * This is the **recommended** way to create the adapter — schema is required,
+     * ensuring all resource object stores and join tables are created in IndexedDB.
+     *
+     * If the database already exists but is missing stores (stale DB), the adapter
+     * automatically bumps the version and creates the missing stores.
+     *
+     * @param options.dbName - Database name (e.g., "my-app-db")
+     * @param options.schema - DataFn schema (required — used to create object stores)
+     *
+     * @example
+     * ```typescript
+     * const storage = IndexedDbStorageAdapter.create({
+     *   dbName: "my-app-db",
+     *   schema,
+     * });
+     * ```
+     */
+    static create(options: {
+        dbName: string;
+        schema: DatafnSchema;
+    }): IndexedDbStorageAdapter;
+    /**
+     * Create a storage adapter with a namespace-derived database name.
+     * The namespace string has `:` replaced with `_` for the IDB database name.
+     *
+     * @example
+     * ```typescript
+     * const storage = IndexedDbStorageAdapter.createForNamespace("my-app", "org:user-1");
+     * // IDB database name: "my-app_org_user-1"
+     * ```
+     */
+    static createForNamespace(baseDbName: string, namespace: string, resources?: string[], schema?: DatafnSchema): IndexedDbStorageAdapter;
+    constructor(dbName?: string, resources?: string[], schema?: DatafnSchema);
+    /**
+     * Open (or upgrade) the IndexedDB database at the given version.
+     * All object store creation happens inside `onupgradeneeded`.
+     */
+    private openDatabase;
+    /**
+     * Verify all expected stores exist after initial open.
+     * If stores are missing (stale DB opened without schema previously),
+     * close the database and reopen with a bumped version to trigger
+     * `onupgradeneeded`, which will create the missing stores.
+     */
+    private ensureStores;
+    private validateTableName;
     private getStore;
     getRecord(resource: string, id: string): Promise<Record<string, unknown> | null>;
     listRecords(resource: string): Promise<Record<string, unknown>[]>;
     upsertRecord(resource: string, record: Record<string, unknown>): Promise<void>;
     deleteRecord(resource: string, id: string): Promise<void>;
-    listJoinRows(relationKey: string): Promise<Array<Record<string, unknown>>>;
-    upsertJoinRow(relationKey: string, row: Record<string, unknown>): Promise<void>;
-    deleteJoinRow(relationKey: string, from: string, to: string): Promise<void>;
+    /**
+     * Atomic read-modify-write merge using a single transaction.
+     * Uses one-level-deep merge for object-type fields.
+     */
+    mergeRecord(resource: string, id: string, partial: Record<string, unknown>): Promise<Record<string, unknown>>;
+    listJoinRows(storeName: string): Promise<Array<Record<string, unknown>>>;
+    getJoinRows(storeName: string, fromId: string): Promise<Array<Record<string, unknown>>>;
+    getJoinRowsInverse(storeName: string, toId: string): Promise<Array<Record<string, unknown>>>;
+    upsertJoinRow(storeName: string, row: Record<string, unknown>): Promise<void>;
+    setJoinRows(storeName: string, rows: Array<Record<string, unknown>>): Promise<void>;
+    deleteJoinRow(storeName: string, from: string, to: string): Promise<void>;
+    findRecords(resource: string, field: string, value: unknown): Promise<Record<string, unknown>[]>;
     getCursor(resource: string): Promise<string | null>;
-    setCursor(resource: string, cursor: string): Promise<void>;
+    setCursor(resource: string, cursor: string | null): Promise<void>;
     getHydrationState(resource: string): Promise<DatafnHydrationState>;
     setHydrationState(resource: string, state: DatafnHydrationState): Promise<void>;
     changelogAppend(entry: Omit<DatafnChangelogEntry, "seq">): Promise<DatafnChangelogEntry>;
@@ -243,6 +729,54 @@ declare class IndexedDbStorageAdapter implements DatafnStorageAdapter {
     changelogAck(options: {
         throughSeq: number;
     }): Promise<void>;
+    countRecords(resource: string): Promise<number>;
+    countJoinRows(relationKey: string): Promise<number>;
+    close(): Promise<void>;
+    clearAll(): Promise<void>;
+    healthCheck(): Promise<{
+        ok: boolean;
+        issues: string[];
+    }>;
 }
 
-export { type DatafnChangelogEntry, type DatafnClient, type DatafnClientConfig, type DatafnClientError, type DatafnHydrationState, type DatafnRemoteAdapter, type DatafnStorageAdapter, type DatafnTable, EventBus, type EventFilter, type EventHandler, IndexedDbStorageAdapter, MemoryStorageAdapter, createClientError, createDatafnClient, matchesFilter, unwrapRemoteSuccess };
+/**
+ * Date Codec (CODEC-001)
+ *
+ * Provides schema-driven date serialization and parsing:
+ * - Outbound (mutation): Date objects → epoch milliseconds (number)
+ * - Inbound (query result): epoch milliseconds or ISO strings → Date objects for schema date fields
+ * - Deterministic error behavior for invalid dates
+ */
+
+/**
+ * Serialize Date fields in mutation records to epoch milliseconds (CODEC-001 outbound)
+ *
+ * @param schema Schema definition
+ * @param resource Resource name
+ * @param record Record to serialize
+ * @returns Serialized record with Date → epoch milliseconds (number)
+ * @throws DFQL_INVALID if a date field contains a non-Date value
+ */
+declare function serializeDateFields(schema: DatafnSchema, resource: string, record: Record<string, unknown>): Record<string, unknown>;
+/**
+ * Parse date fields in query results from epoch milliseconds or ISO strings to Date objects (CODEC-001 inbound)
+ *
+ * @param schema Schema definition
+ * @param resource Resource name
+ * @param record Record to parse
+ * @returns Parsed record with epoch milliseconds or ISO string → Date
+ * @throws DFQL_INVALID if a date field contains an invalid value
+ */
+declare function parseDateFields(schema: DatafnSchema, resource: string, record: Record<string, unknown>): Record<string, unknown>;
+/**
+ * Parse date fields in a query result payload
+ * Handles both non-aggregate (data array) and aggregate (groups array) results
+ *
+ * @param schema Schema definition
+ * @param resource Resource name
+ * @param result Query result payload
+ * @returns Result with parsed Date fields
+ */
+declare function parseQueryResultDates(schema: DatafnSchema, resource: string, result: any): any;
+
+export { type CloneUpOptions, type CloneUpResult, type DatafnChangelogEntry, type DatafnClient, type DatafnClientConfig, type DatafnClientError, type DatafnHydrationState, type DatafnKvApi, type DatafnRemoteAdapter, type DatafnStorageAdapter, type DatafnStorageFactory, type DatafnTable, EventBus, type EventFilter, type EventHandler, IndexedDbStorageAdapter, MemoryStorageAdapter, type PermissionEntry, type SwitchContextOverride, createClientError, createDatafnClient, matchesFilter, parseDateFields, parseQueryResultDates, serializeDateFields, throwClientError, unwrapRemoteSuccess };