@happyvertical/smrt-web 0.38.6 → 0.38.8

package/AGENTS.md

@@ -282,6 +282,91 @@ replayed signal STILL fires, which is exactly what makes a reconnect miss no
 invalidation. `lastSeq` is a resume cursor for the poll fallback, not a dedup
 filter.
 
+## Version awareness & persistence (#1764)
+
+The read-side twin of the outbox plus a first-class "an update is available"
+signal. Two locked architecture decisions (maintainer): the manifest-hash source
+is a **build-time inject** (core's web-module generator emits a `manifestHash`
+constant — NOT a runtime endpoint), and the ETag salt is **folded into this PR**
+(the same hash threads into `computeTableVersionEtag`, closing #1765's documented
+shape-change staleness gap). See `packages/core/AGENTS.md` for the core halves.
+
+### Persistence capability — `persistCollection(config)` (opt-in)
+
+The read-cache rehydrate the outbox left to #1764. Add it to a collection's
+`capabilities`; a collection **without** it is byte-for-byte non-persistent — the
+seam's no-op guarantee, and the "opt-in per model" AC. **Sensitive models simply
+omit the capability and never touch disk.**
+
+- `warmStart(ctx)` reads the persisted snapshot for
+  `(durableStoreNamespace(namespace), collection)` and returns its rows to seed
+  the cache — the stale render paints instantly; the engine then revalidates in
+  the background via its normal SWR (the preload path AWAITS the async warmStart,
+  so the first `list()` is suppressed). **Manifest-hash change drops caches
+  automatically:** the namespace INCLUDES `manifestHash`, so a contract-changing
+  deploy lands on a DIFFERENT IndexedDB database → the old snapshot is never found
+  → an empty warmStart → a fresh fetch with NO stale-schema hydration. No explicit
+  invalidation.
+- Write-back: `onAttach` subscribes to the collection's changes (via the seam's
+  engine-free `ctx.subscribe`/`ctx.snapshot` — added for this slice, plain-DTO
+  payloads only, no engine type) and persists the current rows DEBOUNCED (250ms
+  trailing default; the scheduler is timer-based even at 0ms so a pending write is
+  cancelable). `teardown` sets `detached` and CLEARS the pending timer FIRST so
+  the "rows removed" change that the engine's own `cleanup()` fires just before
+  teardown can't persist an empty snapshot over the good one, then drains any
+  in-flight write. The per-change write-back already persisted the latest rows
+  during the collection's life, so the durable snapshot survives for the next
+  load.
+- Storage: `persistence/snapshot-store.ts` — raw IndexedDB, ONE blob per
+  `(namespace, collection)`, mirroring the outbox's hand-rolled queue (ZERO
+  `@tanstack/*`; the boundary check is the proof). N collections under one
+  namespace share ONE ref-counted store; the last detach closes the db.
+- `registerDurableResource(namespace, { kind: 'persisted-collection', clear })` at
+  first attach, unregistered on last detach BEFORE the db closes (so a later
+  `wipeDurableStore` is a no-op, not a double-clear — the #1762 discipline).
+- **Namespace segregation:** the namespace folds api/tenant/identity/manifest, so
+  switching users on one device lands on a different database — one user can never
+  read another's persisted rows.
+- **Logout wipe clears the outbox too:** the outbox (#1762) registers its queue
+  under the SAME namespace, so ONE `wipeDurableStore(namespace)` clears BOTH the
+  persisted collections AND the outbox queue.
+- **IndexedDB unavailable** (probe `open()` throws — private mode, sandboxed
+  iframe): `console.warn` ONCE + behave as non-persistent (warmStart returns
+  nothing, write-back is a no-op). Never throws — the outbox's `probeIndexedDb`
+  posture.
+
+### `updateAvailable` primitive — `createUpdateState(config)` (framework-free)
+
+A tiny pub/sub (`update-state.ts`) with TWO INDEPENDENT signals; `updateAvailable
+= bundle || contract`:
+
+- **bundle** — the client BUNDLE changed on the server. SvelteKit detects it
+  natively (`updated` store); the consumer/smrt-svelte binding pushes it via
+  `notifyBundleUpdated()`. This module owns no polling.
+- **contract** — the API CONTRACT (manifest hash) changed, which only SMRT knows.
+  Under BUILD-TIME INJECT: on init the primitive compares the RUNNING build's
+  `manifestHash` (passed in by the consumer, imported from
+  `@happyvertical/smrt-virt-web`) against a persisted "last-seen manifestHash" in
+  durable storage; if they differ → fire `contract` + store the new value. First
+  run (no baseline) records without firing.
+
+The last-seen hash lives in `update-state/meta-store.ts` (a tiny IDB key/value
+store) under the durable namespace, registered as a durable resource so
+`wipeDurableStore` clears it too (the "wipe clears the last-seen-hash record"
+AC). Degrades gracefully if IndexedDB is absent (bundle-only) or no running hash
+is supplied.
+
+> **Trade-off / documented follow-up:** contract detection under build-time
+> inject fires at most once **per load** (compare-on-init). LIVE-while-open
+> contract detection — learning mid-session that the server redeployed (an SSE
+> deploy signal / runtime version endpoint) — is an EXPLICIT follow-up, not this
+> slice; it would push a second `contract` signal into the same primitive, which
+> is shaped for it.
+
+The reactive Svelte binding (`useUpdateAvailable`) ships in
+`@happyvertical/smrt-svelte/web` — it wires SvelteKit's `updated` store into the
+bundle signal and surfaces both reactively for a toast/reload UX.
+
 ## The engine-absorption boundary (ratified conditions, #1761)
 
 1. **No engine types in the public API.** `@tanstack/*` types must never appear

package/dist/index.d.ts

@@ -1,3 +1,13 @@
+/**
+ * Serialize `list` query params into the query string the generated REST list
+ * route parses (`handleList` in `core/src/generators/rest.ts`): `limit`,
+ * `offset`, `orderBy` as scalars, and `where` entries as `field=value`
+ * (equality) or `field[op]=value` for a `{ op, value }` condition (`in` joins an
+ * array with commas). Called with no params (the collection runtime's argument-
+ * free `list()`) it returns `''`, so the bare-URL behavior is unchanged.
+ */
+export declare function buildListQuery(params?: Record<string, unknown>): string;
+
 /**
  * Build CRUD fetchers from a generated collection definition — the same URL
  * scheme and payload handling as the generated REST client
@@ -120,6 +130,17 @@ export declare function createSmrtWebClient(): SmrtWebClient;
  */
 export declare function createSmrtWebEventSubscriber(config: SmrtWebEventSubscriberConfig): SmrtWebEventSubscriber;
 
+/**
+ * Create the framework-free `updateAvailable` primitive. Kicks off async
+ * contract detection immediately (compare running vs. persisted manifest hash);
+ * {@link UpdateState.notifyBundleUpdated} feeds the bundle signal. A change to
+ * EITHER signal notifies subscribers.
+ */
+export declare function createUpdateState(config: UpdateStateConfig): UpdateState;
+
+/** Default trailing-debounce window (ms) for the write-back. */
+export declare const DEFAULT_PERSIST_DEBOUNCE_MS = 250;
+
 /**
  * A durable artifact registered under a namespace — the outbox queue (#1762) or
  * a persisted collection store (#1764). Each owns its storage engine and
@@ -412,6 +433,51 @@ export declare interface OutboxSnapshotItem {
  */
 export declare type OutboxSyncState = 'pending' | 'uploading' | 'synced' | 'failed';
 
+/**
+ * Build a durable persistence 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 snapshot database
+ * (one open, one durable resource, one wipe), and each collection is keyed by
+ * its own `collection` name within it.
+ */
+export declare function persistCollection<TData extends object = object>(config: PersistCollectionConfig<TData>): SmrtWebCapability<TData>;
+
+/**
+ * Configuration for {@link persistCollection}. Generic in the collection's row
+ * type `TData` so the capability matches the collection it plugs into.
+ */
+export declare interface PersistCollectionConfig<TData extends object = object> {
+    /**
+     * The REST collection name this snapshot is keyed by — MUST be the SAME
+     * `definition.name` passed to {@link createSmrtCollection} (it is the store
+     * key under the namespace). Provided explicitly (not read off the ctx) so the
+     * config is self-describing and testable.
+     */
+    collection: string;
+    /**
+     * The durable-store identity this snapshot is namespaced under — folds api
+     * base / tenant / identity / manifest hash, so a logout, tenant switch, or a
+     * contract-changing deploy lands on a different IndexedDB database (never
+     * cross-identity reuse, and a shape change drops old snapshots). Shared with
+     * the outbox (#1762) via the same {@link durableStoreNamespace}, so one
+     * {@link wipeDurableStore} clears both.
+     *
+     * The canonical `manifestHash` source is the build-time inject — the
+     * `manifestHash` constant the generated `@happyvertical/smrt-virt-web` module
+     * exports (#1764). Thread it here at the call site.
+     */
+    namespace: DurableStoreKey;
+    /**
+     * Trailing-debounce window (ms) for the write-back snapshot. A burst of
+     * mutations within the window collapses to ONE IndexedDB write of the final
+     * row set. Default {@link DEFAULT_PERSIST_DEBOUNCE_MS}. Set 0 to write on
+     * every change (tests).
+     */
+    debounceMs?: number;
+}
+
 /**
  * Register a durable artifact under a namespace so {@link wipeDurableStore} can
  * later clear it. Returns an unregister function that removes just this
@@ -420,6 +486,29 @@ export declare type OutboxSyncState = 'pending' | 'uploading' | 'synced' | 'fail
  */
 export declare function registerDurableResource(namespace: string, resource: DurableResource): () => void;
 
+/**
+ * Register every collection's generated tool descriptors with WebMCP.
+ *
+ * @returns a disposer that deregisters all tools this call registered. On a
+ * browser without WebMCP the call is a no-op and the disposer is inert.
+ */
+export declare function registerWebMcpTools(definitions: SmrtWebCollectionDefinition[], options?: RegisterWebMcpToolsOptions): () => void;
+
+export declare interface RegisterWebMcpToolsOptions {
+    /** REST base path for the fetchers (default `/api/v1`). */
+    basePath?: string;
+    /** Injectable fetch (tests / SSR-safe wrappers). */
+    fetchFn?: typeof fetch;
+    /**
+     * Override how a definition's CRUD fetchers are built. Defaults to
+     * {@link createDefinitionFetchers}; the primary seam for testing `execute`
+     * without a live server.
+     */
+    resolveFetchers?: (definition: SmrtWebCollectionDefinition) => SmrtCrudFetchers;
+    /** Predicate to include/exclude individual tools (e.g. reads-only surfaces). */
+    filter?: (definition: SmrtWebCollectionDefinition, descriptor: NonNullable<SmrtWebCollectionDefinition['toolDescriptors']>[number]) => boolean;
+}
+
 /**
  * Run the `wrapMutation` hook across `capabilities` in array order for one
  * mutation, short-circuiting on the FIRST capability that returns `{ handled:
@@ -535,6 +624,34 @@ export declare interface SmrtWebCapabilityContext<TData extends object = object>
      * message) without reaching into the engine.
      */
     invalidate(): void;
+    /**
+     * A snapshot of the collection's current rows as plain public DTOs — the same
+     * projection as {@link SmrtWebCollection.toArray}, so the engine's virtual
+     * props never cross the boundary. The persistence slice (#1764) reads this in
+     * its write-back to serialize the current cache to disk. Populated by the real
+     * factory; a hand-built test context may omit it, so callers guard for its
+     * presence.
+     *
+     * SAFE ONLY FROM `onAttach` ONWARD. The factory's implementation closes over
+     * the engine collection, which is constructed AFTER `contributeCacheKey` and
+     * `warmStart` run — calling this from those earlier hooks would throw
+     * (temporal-dead-zone). Read rows from `onAttach`, `onSettled`, or an external
+     * trigger, never during construction.
+     */
+    snapshot?(): ReadonlyArray<SmrtWebRow<TData>>;
+    /**
+     * Subscribe to the collection's change notifications — the same stream as
+     * {@link SmrtWebCollection.subscribeChanges} (plain-DTO payloads). The
+     * persistence slice (#1764) wires its debounced write-back here in `onAttach`
+     * and detaches in `teardown`. Engine-free by construction: the payload is
+     * `unknown` (the capability only needs the change SIGNAL, then re-reads via
+     * {@link snapshot}), so no engine type crosses the seam. Populated by the real
+     * factory; a hand-built test context may omit it.
+     *
+     * SAFE ONLY FROM `onAttach` ONWARD (same reason as {@link snapshot}): it closes
+     * over the engine collection built after the pre-construction hooks.
+     */
+    subscribe?(callback: (changes: unknown) => void): SmrtWebSubscription;
 }
 
 /**
@@ -578,12 +695,6 @@ export declare interface SmrtWebCollection<TData extends object> {
     insert(row: SmrtWebRow<TData>): SmrtWebTransaction;
 }
 
-/**
- * One generated collection definition: everything needed to construct a client
- * collection over the generated REST surface. The `_row` property is a phantom
- * type carrier threaded through codegen — it never exists at runtime, it only
- * lets factories infer the row type from a definition.
- */
 export declare interface SmrtWebCollectionDefinition<TData extends object = object> {
     /** REST collection name (e.g. `products`). */
     name: string;
@@ -595,6 +706,12 @@ export declare interface SmrtWebCollectionDefinition<TData extends object = obje
     idField: string;
     /** CRUD + custom actions exposed by the api decorator config. */
     actions: string[];
+    /**
+     * WebMCP/MCP tool descriptors for the exposed actions (#1812). Optional so
+     * hand-built definitions (older codegen, tests) still satisfy the type; a
+     * missing value means "no WebMCP tools to register".
+     */
+    toolDescriptors?: WebToolDescriptor[];
     /** Persisted field metadata keyed by field name. */
     fields: Record<string, SmrtWebFieldDefinition>;
     /**
@@ -821,6 +938,90 @@ export declare function unwrapItemResult(result: unknown, context: string): Reco
  */
 export declare function unwrapListResult(result: unknown, collectionName: string): Array<Record<string, unknown>>;
 
+/** The two independent update signals plus their derived union. */
+export declare interface UpdateAvailableState {
+    /** The client bundle changed on the server (SvelteKit `updated`). */
+    readonly bundle: boolean;
+    /** The API contract (manifest hash) changed across this load. */
+    readonly contract: boolean;
+    /** `bundle || contract` — either means an update is available. */
+    readonly updateAvailable: boolean;
+}
+
+/** The framework-free update-available primitive. */
+export declare interface UpdateState {
+    /** The current signal state (a fresh immutable snapshot). */
+    get(): UpdateAvailableState;
+    /**
+     * Subscribe to state changes; the callback fires immediately with the current
+     * state and again on every transition. Returns an unsubscribe function.
+     */
+    subscribe(callback: (state: UpdateAvailableState) => void): () => void;
+    /**
+     * Push the BUNDLE signal — call from the consumer/smrt-svelte binding when
+     * SvelteKit's `updated` store flips true. Idempotent: once set it stays set
+     * (a bundle update does not un-happen).
+     */
+    notifyBundleUpdated(): void;
+    /**
+     * Resolves once the async contract detection has settled (compared the running
+     * hash against the persisted last-seen value and fired the signal if needed).
+     * Primarily for tests/SSR; UI code just subscribes.
+     */
+    readonly ready: Promise<void>;
+    /** Detach the durable resource (does NOT wipe — that's wipeDurableStore). */
+    dispose(): void;
+}
+
+/** Configuration for {@link createUpdateState}. */
+export declare interface UpdateStateConfig {
+    /**
+     * The RUNNING build's web-collection shape digest — the `manifestHash`
+     * constant the generated `@happyvertical/smrt-virt-web` module exports
+     * (#1764). Compared against the persisted last-seen value to detect a contract
+     * change across loads. Omit to disable contract detection (bundle-only).
+     */
+    manifestHash?: string;
+    /**
+     * The durable-store identity the last-seen manifest hash is namespaced under —
+     * folds api base / tenant / identity (and, yes, the manifest hash itself, but
+     * see below). Shared with persistence/outbox so one {@link wipeDurableStore}
+     * clears the last-seen record too.
+     *
+     * NOTE the namespace's OWN `manifestHash` segment should be a STABLE value
+     * (e.g. the app's api-version or a constant), NOT the running build hash —
+     * otherwise a contract change would move the namespace and the compare would
+     * never find the prior value (always "first run"). Contract change is detected
+     * by the STORED VALUE under a stable namespace, not by the namespace moving.
+     */
+    namespace: DurableStoreKey;
+}
+
+/**
+ * One generated collection definition: everything needed to construct a client
+ * collection over the generated REST surface. The `_row` property is a phantom
+ * type carrier threaded through codegen — it never exists at runtime, it only
+ * lets factories infer the row type from a definition.
+ */
+/**
+ * One WebMCP / MCP tool descriptor for a collection action (#1812). Emitted by
+ * the core web-collections codegen as PLAIN DATA (this package has no smrt
+ * dependency), shaped to match Chrome's `document.modelContext.registerTool`
+ * input — see https://developer.chrome.com/docs/ai/webmcp. Consumed by
+ * {@link registerWebMcpTools} in `./webmcp`.
+ */
+export declare interface WebToolDescriptor {
+    /** The action this tool performs (`list` | `get` | … | a custom method name). */
+    action: string;
+    /** Tool id, `${className.toLowerCase()}_${action}` (e.g. `product_list`). */
+    name: string;
+    description: string;
+    /** JSON Schema for the tool's arguments. */
+    inputSchema: Record<string, unknown>;
+    /** True for non-mutating reads → WebMCP `annotations.readOnlyHint`. */
+    readOnly: boolean;
+}
+
 /**
  * Clear every durable artifact registered under `namespace`, then drop the
  * namespace. This is the single teardown point a logout / tenant-switch calls: