@happyvertical/smrt-web 0.38.2 → 0.38.3

package/dist/index.d.ts

@@ -93,6 +93,16 @@ export declare interface CreateSmrtCollectionOptions<TData extends object = obje
      * `staleTimeMs` window.
      */
     initialData?: SmrtWebRow<TData>[];
+    /**
+     * Capability plug-ins hooking the collection lifecycle (#1755) — the seam
+     * that lets the offline outbox (#1762), persistence (#1764), and live SSE
+     * invalidation (#1763-client) slices each live in their own module instead of
+     * contending on this factory. Capabilities run in array order at six fixed
+     * points (see {@link SmrtWebCapability}). Additive and defaulting to none: an
+     * undefined or empty array is byte-for-byte the collection of today (the
+     * no-op guarantee), so this ships zero concrete capabilities by design.
+     */
+    capabilities?: SmrtWebCapability<TData>[];
 }
 
 /**
@@ -102,6 +112,86 @@ export declare interface CreateSmrtCollectionOptions<TData extends object = obje
  */
 export declare function createSmrtWebClient(): SmrtWebClient;
 
+/**
+ * Create the app-wide live-updates subscriber. Feature-detects ONCE at
+ * construction: an available EventSource connects the SSE stream; otherwise it
+ * starts the `_changes` poll loop. A fatal SSE error later downgrades to
+ * polling for the rest of the subscriber's life (no flap-back).
+ */
+export declare function createSmrtWebEventSubscriber(config: SmrtWebEventSubscriberConfig): SmrtWebEventSubscriber;
+
+/**
+ * A durable artifact registered under a namespace — the outbox queue (#1762) or
+ * a persisted collection store (#1764). Each owns its storage engine and
+ * exposes only a `clear()` so {@link wipeDurableStore} can tear it down without
+ * knowing which engine backs it.
+ */
+export declare interface DurableResource {
+    /** Which slice owns this artifact — for diagnostics and selective sweeps. */
+    readonly kind: 'outbox' | 'persisted-collection';
+    /** Drop this artifact's durable storage. Best-effort; may reject. */
+    clear(): Promise<void>;
+}
+
+/**
+ * @happyvertical/smrt-web — shared durable-store foundation (#1755).
+ *
+ * The ONE SMRT-layer namespacing + wipe registry that the future offline
+ * outbox (#1762) and persistence (#1764) slices both build on. Pure bookkeeping
+ * — ZERO client-data-engine (`@tanstack/*`) imports — so it stays inside the
+ * engine-absorption boundary and ships now, before either consumer exists, so
+ * the two slices agree on it from day one.
+ *
+ * Why a SMRT-layer registry rather than one storage engine: TanStack DB
+ * persistence (SQLite-WASM / OPFS) and `@tanstack/offline-transactions`
+ * (IndexedDB) are SEPARATE storage engines. There is no single primitive that
+ * spans both, so the shared foundation lives one level up — a deterministic
+ * namespace both slices key their own storage under, plus a registry so
+ * {@link wipeDurableStore} can clear BOTH through one call without the outbox
+ * and persistence modules importing each other. A logout / tenant-switch wipes
+ * every durable artifact for a namespace in one place.
+ *
+ * Nothing in this package calls these yet — the seam ships ahead of its
+ * consumers by design (see PRD #1755).
+ */
+/**
+ * The identity a durable namespace is derived from. Combining the API base with
+ * the tenant + identity + manifest hash means a logout, a tenant switch, or a
+ * schema change each land on a DIFFERENT namespace, so durable artifacts are
+ * never reused across those boundaries.
+ *
+ * `manifestHash` is supplied by the caller (its source is #1764's call — a
+ * schema-shape digest); this module is source-agnostic and treats it as an
+ * opaque discriminator.
+ */
+export declare interface DurableStoreKey {
+    /** API base path the durable data was fetched against (e.g. `/api/v1`). */
+    apiBase: string;
+    /** Active tenant id, if any — absent means the single-tenant / global scope. */
+    tenantId?: string;
+    /** Authenticated identity id, if any — absent means anonymous. */
+    identityId?: string;
+    /** Opaque schema-shape digest; a change forces a fresh namespace. */
+    manifestHash: string;
+}
+
+/**
+ * Compute the deterministic storage namespace for a {@link DurableStoreKey}.
+ * The same key always yields the same string; **any differing segment yields a
+ * different one** (injective) — this is critical because the namespace IS the
+ * tenant/identity/api isolation + wipe boundary, so a collision would reuse or
+ * wipe durable data ACROSS those boundaries.
+ *
+ * Injectivity is guaranteed three ways: every segment is `encodeURIComponent`-
+ * encoded, so a raw `:` in a value becomes `%3A` and can never be mistaken for a
+ * separator; an ABSENT `tenantId` / `identityId` maps to the empty string while
+ * a PRESENT value is prefixed with `_` (so undefined→``, ``→`_`, `x`→`_x`) — so
+ * an explicitly-EMPTY id no longer collides with "no id", nor does a real id of
+ * `-`. Both future slices key their own storage primitive (IndexedDB store name,
+ * OPFS path, …) under this string.
+ */
+export declare function durableStoreNamespace(key: DurableStoreKey): string;
+
 /**
  * Retrieve the underlying engine collection backing a handle — an advanced
  * bridge for trusted framework bindings (e.g. the smrt-svelte live-query
@@ -112,6 +202,50 @@ export declare function createSmrtWebClient(): SmrtWebClient;
  */
 export declare function getEngineCollection<TData extends object>(handle: SmrtWebCollection<TData>): unknown;
 
+/**
+ * Retrieve the programmatic {@link OutboxHandle} for a durable-store namespace,
+ * or `undefined` if no opted-in collection is currently attached under it. The
+ * bridge for trusted callers (outbox UI, smrt-svelte binding, tests) to read the
+ * durable queue and force retries. Pass the SAME
+ * `durableStoreNamespace(config.namespace)` string the capability used.
+ *
+ * Mirrors the `getEngineCollection` bridge convention: an escape hatch that
+ * returns a narrow SMRT-owned surface rather than the engine itself.
+ */
+export declare function getOutboxHandle(namespace: string): OutboxHandle | undefined;
+
+/**
+ * A thin per-collection capability that subscribes THIS collection to live
+ * signals for its `tableName`. On attach it registers `ctx.invalidate` (the
+ * factory's relationship-derived refetch primitive) with the shared subscriber;
+ * on teardown it unregisters. All transport, reconnection, and fan-out live in
+ * the {@link createSmrtWebEventSubscriber}; this capability is just the wire
+ * between one collection and that one subscriber.
+ */
+export declare function liveInvalidation<TData extends object = object>(config: LiveInvalidationConfig): SmrtWebCapability<TData>;
+
+/** Configuration for the {@link liveInvalidation} capability. */
+export declare interface LiveInvalidationConfig {
+    /** The one app-wide subscriber from {@link createSmrtWebEventSubscriber}. */
+    subscriber: Pick<SmrtWebEventSubscriber, 'registerTable' | 'invalidateAll' | 'transport'>;
+    /**
+     * The PHYSICAL table name this collection reads. EXPLICIT because a
+     * `SmrtWebCollectionDefinition` has no physical-table field and STI children
+     * share one base table — the subscriber keys signals by physical table, so a
+     * guess would mis-route invalidations.
+     */
+    tableName: string;
+}
+
+/** The settle outcome handed to {@link SmrtWebCapability.onSettled}. */
+export declare type MutationSettleOutcome = {
+    ok: true;
+    result: unknown;
+} | {
+    ok: false;
+    error: unknown;
+};
+
 /**
  * Generate a client-local id for optimistic inserts. The generated REST layer
  * strips client-supplied ids on create (mass-assignment guard #1540), so this
@@ -120,6 +254,187 @@ export declare function getEngineCollection<TData extends object>(handle: SmrtWe
  */
 export declare function newLocalId(): string;
 
+/**
+ * Build a durable offline-outbox capability for a collection. Add the returned
+ * capability to the collection's `capabilities` array; a collection without it
+ * is unaffected (the seam's no-op guarantee — the "opt-in per model" AC).
+ *
+ * The same `namespace` across multiple collections shares ONE engine (one IDB
+ * db, one leader lock, one FIFO queue) — so cross-collection ordering and the
+ * multi-tab single-replayer guarantee hold across every opted-in collection of a
+ * given identity.
+ */
+export declare function offlineOutbox<TData extends object = object>(config: OfflineOutboxConfig<TData>): SmrtWebCapability<TData>;
+
+/**
+ * Configuration for {@link offlineOutbox}. Generic in the collection's row type
+ * `TData` so the capability matches the collection it plugs into.
+ */
+export declare interface OfflineOutboxConfig<TData extends object = object> {
+    /**
+     * The generated collection definition this outbox serves — its `name` is the
+     * sync-apply `object` route segment, so it MUST be the SAME definition passed
+     * to {@link createSmrtCollection}. (Named `object` to mirror the capability
+     * context; carries the collection's REST route segment.)
+     */
+    object: {
+        name: string;
+        _row?: TData;
+    };
+    /**
+     * The durable-store identity this outbox's queue is namespaced under — folds
+     * api base / tenant / identity / manifest hash, so a logout or tenant switch
+     * lands on a different IndexedDB database (never cross-identity reuse). Shared
+     * with #1764's persistence slice via the same {@link durableStoreNamespace}.
+     * `manifestHash` is opaque caller-supplied config for #1762; its canonical
+     * source is #1764's call (a schema-shape digest) — comment your call site.
+     */
+    namespace: DurableStoreKey;
+    /**
+     * API base path the sync-apply endpoint lives under (`POST
+     * {syncApplyBasePath}/sync/apply`). Defaults to `/api/v1`, matching the REST
+     * generator's default. Set to the SvelteKit route base (`/api`) when replaying
+     * against the generated SvelteKit `sync/apply/+server.ts`.
+     */
+    syncApplyBasePath?: string;
+    /** Fetch implementation override (tests, SSR). Defaults to global fetch. */
+    fetchFn?: typeof fetch;
+    /** Exponential-backoff tuning for retryable replay failures. */
+    backoff?: OutboxBackoff;
+    /**
+     * Called on every observable sync-state transition of a captured mutation
+     * (`pending → uploading → synced`, `→ failed`, and the `pending` re-arm after
+     * a retryable failure). A push callback; smrt-svelte turns it into a reactive
+     * binding later.
+     */
+    onSyncStateChange?: (event: SyncStateEvent) => void;
+    /**
+     * Called when a replayed mutation comes back `conflict` — a RESOLVED outcome
+     * (server state won; the item leaves the queue with terminal state `synced`).
+     * Persist `serverUpdatedAt` as the new `baseUpdatedAt`, refetch the row, and
+     * surface the conflict to the user as appropriate.
+     */
+    onConflict?: (conflict: OutboxConflict) => void;
+    /** Test-only: inject a deterministic RNG for backoff jitter. */
+    random?: () => number;
+}
+
+/** Exponential-backoff tuning for retryable replay failures. */
+export declare interface OutboxBackoff {
+    /** Delay before the first retry, ms (default 1000). */
+    initialDelayMs?: number;
+    /** Multiplier applied per attempt (default 2). */
+    multiplier?: number;
+    /** Ceiling on the computed delay, ms (default 60000). */
+    maxDelayMs?: number;
+}
+
+/**
+ * A conflict surfaced to {@link OfflineOutboxConfig.onConflict} when a replayed
+ * item comes back `conflict`. Per the contract this is a RESOLVED outcome — the
+ * server state won, the item is removed, and its terminal observable state is
+ * `synced` — so an app treats it as "your write was superseded; here is the
+ * server's `updatedAt` to rebase from", NOT as a failure to retry.
+ */
+export declare interface OutboxConflict {
+    /** The queue row's `itemId`. */
+    itemId: string;
+    /** The collection route segment. */
+    object: string;
+    /** The client-generated row UUID that conflicted. */
+    rowId: string;
+    /**
+     * Why the item conflicted: `stale_write` (an update/delete whose
+     * `baseUpdatedAt` was older than the server row) or `create_conflict` (a
+     * create landing on an existing, diverged row).
+     */
+    reason: 'stale_write' | 'create_conflict';
+    /**
+     * The server row's `updated_at` after processing — the value to persist as
+     * the new `baseUpdatedAt` before re-editing. Present when the endpoint
+     * returned it.
+     */
+    serverUpdatedAt?: string;
+}
+
+/**
+ * A programmatic handle to one namespace's outbox — the bridge pattern (like
+ * `getEngineCollection`) for trusted callers (an app's outbox panel, a
+ * smrt-svelte binding, tests). Fetched via {@link getOutboxHandle}.
+ */
+export declare interface OutboxHandle {
+    /**
+     * A read-only snapshot of the durable queue (every state). The way to prove
+     * durability after a reload, since this slice does not rehydrate the read
+     * cache (that's #1764).
+     */
+    snapshot(): Promise<OutboxSnapshotItem[]>;
+    /**
+     * Force a retry of a specific queued item now (clears its backoff gate, wakes
+     * the loop, and clears an auth pause). A no-op for an item no longer queued.
+     */
+    retry(itemId: string): Promise<void>;
+}
+
+/** One item in an {@link OutboxHandle.snapshot} result. */
+export declare interface OutboxSnapshotItem {
+    /** The queue row's idempotency handle. */
+    itemId: string;
+    /** The collection route segment. */
+    object: string;
+    /** The mutation kind, in sync-apply terms. */
+    op: 'create' | 'update' | 'delete';
+    /** The client-generated row UUID. */
+    rowId: string;
+    /** The on-disk lifecycle state. */
+    state: 'pending' | 'synced' | 'failed';
+    /** Replay attempts so far. */
+    attempts: number;
+    /** Epoch ms before which this row won't be retried (backoff). */
+    nextAttemptAt: number;
+    /** Last replay error, if any. */
+    lastError?: string;
+}
+
+/**
+ * The app-observable sync state of a queued mutation — the SAME four-state
+ * machine the KMP mobile foundation exposes (ADR 0001), so web and mobile
+ * outbox indicators render identically:
+ *
+ * - `pending` — enqueued, awaiting (re)send.
+ * - `uploading` — currently in a sync-apply POST.
+ * - `synced` — the mutation's effect is confirmed on the server (a terminal
+ *   success — INCLUDING a surfaced conflict, which is a RESOLVED outcome: the
+ *   server state won and the item left the queue).
+ * - `failed` — a terminal rejection the client cannot resolve by retrying
+ *   (`invalid_*`, `not_found`, `id_conflict`, `op_not_allowed`, …) — surfaced
+ *   for app-level handling.
+ */
+export declare type OutboxSyncState = 'pending' | 'uploading' | 'synced' | 'failed';
+
+/**
+ * Register a durable artifact under a namespace so {@link wipeDurableStore} can
+ * later clear it. Returns an unregister function that removes just this
+ * resource — call it when the artifact is disposed on its own (before any
+ * namespace-wide wipe) so it is not cleared twice.
+ */
+export declare function registerDurableResource(namespace: string, resource: DurableResource): () => void;
+
+/**
+ * Run the `wrapMutation` hook across `capabilities` in array order for one
+ * mutation, short-circuiting on the FIRST capability that returns `{ handled:
+ * true }` (later capabilities' `wrapMutation` are then skipped). A capability
+ * that returns `{ handled: false }`, `undefined`, or omits the hook declines,
+ * and the next is tried. When every capability declines, resolves `{ handled:
+ * false }` so the factory falls through to the real fetcher.
+ */
+export declare function runWrapMutation<TData extends object>(capabilities: readonly SmrtWebCapability<TData>[], envelope: SmrtWebMutationEnvelope, ctx: SmrtWebCapabilityContext<TData>): Promise<{
+    handled: true;
+    result: unknown;
+} | {
+    handled: false;
+}>;
+
 /**
  * The per-collection CRUD surface of the generated REST client
  * (`createClient(basePath).<collection>` from `@happyvertical/smrt-virt-client`).
@@ -136,6 +451,92 @@ export declare interface SmrtCrudFetchers {
     delete?(id: string): Promise<unknown>;
 }
 
+/**
+ * A capability plugged into {@link createSmrtCollection}. Every hook is
+ * optional; a capability implements only the points its slice needs. Hooks fire
+ * in these fixed places, and capabilities run in ARRAY ORDER:
+ *
+ * - `contributeCacheKey` — ONCE, before the engine collection is constructed.
+ * - `warmStart` — ONCE, before the first read (seeds the cache).
+ * - `wrapMutation` — per mutation, BEFORE the fetcher, with a chance to handle
+ *   the write itself (offline).
+ * - `onSettled` — per mutation, AFTER it settles (success AND fetcher-throw).
+ * - `onAttach` — ONCE, right after the engine collection is constructed; the
+ *   ONLY place a capability registers an external (non-mutation) trigger such as
+ *   an SSE subscription.
+ * - `teardown` — in `cleanup()`, after the engine's own cleanup.
+ */
+export declare interface SmrtWebCapability<TData extends object = object> {
+    /** Diagnostic name (e.g. `'offline-outbox'`). */
+    readonly name: string;
+    /**
+     * Contribute extra cache-key segments so this capability can partition the
+     * collection's cache (e.g. an outbox variant). Runs ONCE, before construction;
+     * returned segments are appended to the collection's cache key/id. Return
+     * `undefined` (or omit) to contribute nothing.
+     */
+    contributeCacheKey?(ctx: SmrtWebCapabilityContext<TData>): string[] | undefined;
+    /**
+     * Provide rows to seed the cache before the first read — the persistence
+     * slice's rehydrate-from-disk path. Runs ONCE, before construction. NOTE:
+     * caller-supplied `initialData` (fresher same-request SSR truth) WINS over any
+     * capability `warmStart`. Return `undefined` to contribute no seed.
+     */
+    warmStart?(ctx: SmrtWebCapabilityContext<TData>): Promise<SmrtWebRow<TData>[] | undefined> | SmrtWebRow<TData>[] | undefined;
+    /**
+     * Intercept a mutation BEFORE its fetcher runs. Return `{ handled: true,
+     * result }` to take over the write (the fetcher is skipped and `result`
+     * reconciles the optimistic row — the offline path); return `{ handled: false
+     * }` or `undefined` to fall through to the real fetcher. With multiple
+     * capabilities the FIRST `{ handled: true }` wins and later capabilities'
+     * `wrapMutation` are skipped.
+     */
+    wrapMutation?(envelope: SmrtWebMutationEnvelope, ctx: SmrtWebCapabilityContext<TData>): Promise<WrapMutationOutcome> | WrapMutationOutcome;
+    /**
+     * Observe a mutation after it settles — on BOTH a successful persist and a
+     * fetcher throw (before the optimistic rollback propagates). Never swallows
+     * the error: a thrown fetcher error still rolls the transaction back.
+     */
+    onSettled?(envelope: SmrtWebMutationEnvelope, outcome: MutationSettleOutcome, ctx: SmrtWebCapabilityContext<TData>): void;
+    /**
+     * Run ONCE, right after the engine collection is constructed. The ONLY hook
+     * where a capability wires an external trigger (SSE subscription, focus
+     * listener) — `ctx.invalidate()` is callable here.
+     */
+    onAttach?(ctx: SmrtWebCapabilityContext<TData>): void;
+    /** Run inside `cleanup()`, AFTER the engine's own cleanup. Awaited if async. */
+    teardown?(ctx: SmrtWebCapabilityContext<TData>): void | Promise<void>;
+}
+
+/**
+ * The context every capability hook receives — a stable, engine-free view of
+ * the collection being built. All fields are the exact values the factory uses
+ * internally (the resolved cache key/id, the same fetchers), so a capability
+ * keys its own storage or subscriptions off the identical discriminators.
+ */
+export declare interface SmrtWebCapabilityContext<TData extends object = object> {
+    /** The generated definition this collection materializes. */
+    readonly definition: SmrtWebCollectionDefinition<TData>;
+    /** The CRUD fetchers the collection persists through. */
+    readonly fetchers: SmrtCrudFetchers;
+    /**
+     * The `queryKey` segments the collection's reads use — a LIVE view: from
+     * `onAttach`/`warmStart` onward it is the final key (including every
+     * capability-contributed segment); read during `contributeCacheKey` it omits
+     * that capability's own not-yet-applied segment. Treat as read-only.
+     */
+    readonly cacheKey: readonly string[];
+    /** The engine-collection id string (mirrors {@link cacheKey}). */
+    readonly cacheId: string;
+    /**
+     * Enter the SAME relationship-derived invalidation the factory runs after a
+     * settled mutation. A capability calls this to refetch this collection and its
+     * manifest-related collections in response to an EXTERNAL trigger (e.g. an SSE
+     * message) without reaching into the engine.
+     */
+    invalidate(): void;
+}
+
 /**
  * Opaque handle to the shared client cache / request-dedup layer. Create one
  * with {@link createSmrtWebClient} and pass the SAME instance to every
@@ -209,42 +610,88 @@ export declare interface SmrtWebCollectionDefinition<TData extends object = obje
 }
 
 /**
- * @happyvertical/smrt-web — browser client data runtime (#1761).
- *
- * A typed collection factory that materializes the manifest-generated web
- * collection definitions (`@happyvertical/smrt-virt-web`) as cached, reactive
- * collections over the generated SMRT REST surface.
- *
- * This package is the **engine-absorption boundary**: the client-data engine
- * (currently TanStack DB) is an implementation detail held entirely inside
- * this module. Its types never appear on the public API — collections are
- * handed back as the SMRT-owned {@link SmrtWebCollection}, and the shared cache
- * as the opaque {@link SmrtWebClient} — so the engine stays swappable without a
- * consumer-visible break. Consumers never import `@tanstack/*` directly.
- *
- * Framework-agnostic by construction: this entry imports no UI framework.
- * Svelte live-query bindings ship separately (see PRD #1755) so this core never
- * pulls the Svelte-only `@tanstack/svelte-db` export condition.
- *
- * Scope of this slice:
- * - stale-while-revalidate reads (a `staleTimeMs` window, background revalidation)
- * - concurrent-read dedup (one network request per in-flight collection load)
- * - optimistic create that persists through the generated REST surface and
- *   rolls back automatically when the server errors
- * - relationship-derived invalidation (#1761): a settled mutation invalidates
- *   the caches of the collections related to the mutated one, with the edges
- *   derived from the manifest (`definition.relationships`) — no hand-wired
- *   cache keys. Cross-collection reach requires a shared client from
- *   {@link createSmrtWebClient}; with a private client only the mutated
- *   collection refetches.
- * - hydration seeding (#1761): rows fetched server-side (a SvelteKit
- *   `+page.server.ts` load) seed the shared cache via
- *   {@link CreateSmrtCollectionOptions.initialData}, so the first client read
- *   serves them WITHOUT a duplicate first-render fetch.
- *
- * Deliberately NOT here yet (see PRD #1755): offline outbox, SSE invalidation,
- * persistence, version awareness.
+ * The minimal `EventSource` surface the subscriber uses — declared here so a
+ * test injects a fake without a real DOM, and so this module compiles without
+ * DOM `lib` beyond the ambient global. A real `EventSource` satisfies it
+ * structurally.
  */
+export declare interface SmrtWebEventSource {
+    /** Native reconnect fires this after (re)connect. */
+    onopen: ((this: unknown, ev: unknown) => unknown) | null;
+    /**
+     * Fires on a stream error. A transient drop leaves `readyState` at OPEN
+     * (0→…) and the browser auto-reconnects with `Last-Event-ID`; a fatal error
+     * (server 401 / route disabled) leaves it CLOSED.
+     */
+    onerror: ((this: unknown, ev: unknown) => unknown) | null;
+    /**
+     * Fires only for UNNAMED (`message`) events. The `_events` frames are NAMED
+     * (`change` / `resync`), so this never fires for them — the subscriber uses
+     * {@link addEventListener} instead. Present only to satisfy the structural
+     * type of a real EventSource.
+     */
+    onmessage: ((this: unknown, ev: unknown) => unknown) | null;
+    /** Register a listener for a NAMED event (`change`, `resync`). */
+    addEventListener(type: string, listener: (ev: {
+        data: string;
+        lastEventId: string;
+    }) => void): void;
+    /** Close the stream (stops reconnection). */
+    close(): void;
+    /** `CONNECTING` (0), `OPEN` (1), or `CLOSED` (2). */
+    readonly readyState: number;
+}
+
+/** Factory that constructs an {@link SmrtWebEventSource} for a URL. */
+export declare type SmrtWebEventSourceFactory = (url: string, init: {
+    withCredentials: boolean;
+}) => SmrtWebEventSource | null | undefined;
+
+/**
+ * The ONE app-wide live-updates subscriber. Construct once (see
+ * {@link createSmrtWebEventSubscriber}) and pass it to every
+ * {@link liveInvalidation} capability.
+ */
+export declare interface SmrtWebEventSubscriber {
+    /**
+     * The live transport: `'sse'` while the EventSource is the source of truth,
+     * `'polling'` when running (or downgraded to) the `_changes` fallback,
+     * `'idle'` before any transport starts.
+     */
+    readonly transport: SmrtWebSubscriberTransport;
+    /**
+     * Register an invalidator for a physical table. Returns an unregister
+     * function. Multiple invalidators may share a table (two live collections);
+     * a `change` for that table fires them all.
+     */
+    registerTable(table: string, invalidate: () => void): () => void;
+    /** Invalidate every registered table (a `resync` / `resyncRequired`). */
+    invalidateAll(): void;
+    /** Tear down the live transport and drop all registrations. */
+    close(): void;
+}
+
+/** Configuration for {@link createSmrtWebEventSubscriber}. */
+export declare interface SmrtWebEventSubscriberConfig {
+    /** Absolute or same-origin URL of the generated `_events` SSE route. */
+    eventsUrl: string;
+    /** Absolute or same-origin URL of the generated `_changes` route (fallback). */
+    changesUrl: string;
+    /** `fetch` implementation for the polling fallback. Defaults to global fetch. */
+    fetchFn?: typeof fetch;
+    /**
+     * Factory for the EventSource. Defaults to `new globalThis.EventSource(url,
+     * { withCredentials })`, guarded by a `typeof` check — when EventSource is
+     * absent (or the factory yields nothing) the subscriber starts on the polling
+     * fallback instead.
+     */
+    eventSourceFactory?: SmrtWebEventSourceFactory;
+    /** Poll interval for the `_changes` fallback (ms). Default 5000. */
+    pollIntervalMs?: number;
+    /** `withCredentials` for the EventSource (cookie auth). Default true. */
+    withCredentials?: boolean;
+}
+
 /**
  * Field metadata emitted per column by the `@happyvertical/smrt-virt-web`
  * virtual module (generated from the package manifest).
@@ -255,6 +702,31 @@ export declare interface SmrtWebFieldDefinition {
     default?: unknown;
 }
 
+/**
+ * A single mutation described in SMRT-owned terms — handed to
+ * {@link SmrtWebCapability.wrapMutation} and {@link SmrtWebCapability.onSettled}
+ * so a capability can inspect or intercept a write without touching the engine's
+ * transaction type.
+ */
+export declare interface SmrtWebMutationEnvelope {
+    /** Which mutation kind this describes. */
+    readonly kind: 'insert' | 'update' | 'delete';
+    /** The row key: the client-local id on insert, else the target row's id. */
+    readonly key: string;
+    /**
+     * The write payload: the full row on insert, the changed fields on update,
+     * and an empty object on delete (the key carries the target).
+     */
+    readonly data: Record<string, unknown>;
+    /**
+     * The server `updated_at` / `updatedAt` value the mutation is based on, when
+     * known. Update/delete handlers capture this from the original row so offline
+     * replay can preserve the sync/apply conflict guard even when the write
+     * payload only carries changed fields (or no fields for delete).
+     */
+    readonly baseUpdatedAt?: string;
+}
+
 /**
  * A manifest-derived edge from this collection to a sibling REST collection,
  * emitted by the `@happyvertical/smrt-virt-web` virtual module. When a mutation
@@ -293,6 +765,9 @@ export declare type SmrtWebRow<TData extends object> = TData & {
     id: string;
 };
 
+/** Which transport a subscriber is currently using. */
+export declare type SmrtWebSubscriberTransport = 'sse' | 'polling' | 'idle';
+
 /** A change-subscription handle. Call {@link unsubscribe} to detach. */
 export declare interface SmrtWebSubscription {
     unsubscribe(): void;
@@ -309,6 +784,27 @@ export declare interface SmrtWebTransaction {
     };
 }
 
+/**
+ * A sync-state transition delivered to {@link OfflineOutboxConfig.onSyncStateChange}.
+ * A PUSH callback (not a subscribable store): smrt-svelte wraps it into a
+ * reactive binding later (#1762 follow-on). Carries enough for an app to render
+ * a per-row indicator and a retry affordance.
+ */
+export declare interface SyncStateEvent {
+    /** The queue row's `itemId` (its idempotency handle) this state is for. */
+    itemId: string;
+    /** The client-generated row UUID the mutation targets. */
+    rowId: string;
+    /** The collection route segment (e.g. `products`). */
+    object: string;
+    /** The new observable state. */
+    state: OutboxSyncState;
+    /** How many replay attempts have run (0 until the first send). */
+    attempts: number;
+    /** The last replay error message, when `state` is `pending` after a retry. */
+    error?: string;
+}
+
 /**
  * Normalize a generated-client item result (create/update) to a row.
  * `{ error }` payloads become failures — inside mutation handlers this is what
@@ -325,4 +821,24 @@ export declare function unwrapItemResult(result: unknown, context: string): Reco
  */
 export declare function unwrapListResult(result: unknown, collectionName: string): Array<Record<string, unknown>>;
 
+/**
+ * Clear every durable artifact registered under `namespace`, then drop the
+ * namespace. This is the single teardown point a logout / tenant-switch calls:
+ * it fans out across BOTH the outbox and persistence slices via the registry,
+ * so neither module needs to import the other.
+ *
+ * Best-effort: a resource whose `clear()` rejects does not abort the sweep —
+ * every registered resource is still cleared (a wipe is a teardown, not a
+ * transaction). A safe no-op on an unknown or empty namespace.
+ */
+export declare function wipeDurableStore(namespace: string): Promise<void>;
+
+/** The outcome handed to {@link SmrtWebCapability.wrapMutation}. */
+export declare type WrapMutationOutcome = {
+    handled: true;
+    result: unknown;
+} | {
+    handled: false;
+} | undefined;
+
 export { }