@happyvertical/smrt-web 0.43.2 → 0.43.4

package/AGENTS.md

@@ -38,9 +38,10 @@ module you are editing. This file keeps what holds in every module.
 | `index.ts` hooks + `durable-store.ts` | the six capability hook points, hook error isolation, the no-op guarantee, and the shared durable-store namespacing/wipe registry | [agents/capability-seam.md](agents/capability-seam.md) |
 | `offline/` | durable offline writes — config, sync-apply-only replay, idempotency, the shared namespace-keyed engine, and Web Locks leader election | [agents/offline-outbox.md](agents/offline-outbox.md) |
 | `sse-client.ts` | the client half of live cache invalidation — the app-wide subscriber, the wire contract it consumes, and SSE-vs-polling behaviour | [agents/live-invalidation.md](agents/live-invalidation.md) |
-| `webmcp.ts` | framework-agnostic WebMCP registrar; registers generated collection tools and routes mutations through shared smrt-web cache state | — |
+| `webmcp.ts` | framework-agnostic WebMCP registrar; validates an optionally bounded/namespaced, effect-filtered prospective set atomically, keeps legacy list-backed tools on collection state, and executes canonical tool-only definitions directly through REST fetchers | — |
 | `persistence/` + `update-state.ts` | the read-cache rehydrate capability and the framework-free `updateAvailable` primitive (bundle + contract signals) | [agents/version-persistence.md](agents/version-persistence.md) |
 | `data-query.ts` | dependency-free browser mirror and defensive response normalizer for the canonical bounded data-query envelope (#2444) | — |
+| `remote-query.ts` | query-shaped remote pages over a `SmrtWebCollection`, with keyed stale cache, execution modes, cancellation/latest-query-wins, and optional query-scoped live subscriptions (#2445) | — |
 
 ## The engine-absorption boundary (ratified conditions, #1761)
 
@@ -60,6 +61,34 @@ module you are editing. This file keeps what holds in every module.
 
 ## Conventions
 
+- **WebMCP definition mirror** — `WebMcpToolDefinition` textually mirrors the
+  generated `@happyvertical/smrt-virt-web` / physical `@smrt/web` declaration.
+  It is transport-complete and does not imply that a list-materialized client
+  collection exists. Keep the mirror dependency-free. Register canonical tools
+  or legacy collection definitions for overlapping collections; when composing
+  the two forms, keep their names and collection/action identities disjoint.
+  Duplicates fail atomically before registration.
+  With no exposure policy, only `read` effects are selected; broader effects
+  require explicit opt-in, and undeclared custom actions are destructive.
+  Direct mutations invalidate their
+  own and relationship-derived collection names through the public
+  `invalidateSmrtWebCollections()` seam when the host supplies its shared
+  `SmrtWebClient`. Legacy `filter` callbacks receive complete collection
+  metadata; canonical definitions use `filterTool`. Supplying either filter for
+  definitions of the other kind fails closed rather than ignoring the predicate
+  or fabricating incomplete metadata for a policy decision. Filters and fetcher
+  resolvers receive isolated value snapshots, so integrations must key external
+  state by stable values such as collection/action rather than definition object
+  identity.
+  Canonical writes validate that shared client handle before registration, and
+  string or structured `{ error }` REST envelopes fail before cache
+  invalidation. The private `__smrt_options` GET sentinel is reserved only for
+  no-path single-options-bag actions; positional actions preserve a legitimate
+  parameter with that name.
+  This capability policy is not authorization:
+  the authenticated REST surface remains the auth, tenant, field-write, and
+  sensitive-data boundary.
+
 - **No inter-smrt dependencies** — depends only on TanStack packages
   (dependency-DAG guardrails). Definitions and fetchers arrive as arguments.
 - **Data-query mirror** — `data-query.ts` mirrors the portable

package/README.md

@@ -9,6 +9,12 @@ Use it for browser-side collection state, shared request deduplication, offline
 writes, persisted read caches, and live invalidation. Svelte bindings live in
 [`@happyvertical/smrt-svelte/web`](../smrt-svelte/README.md).
 
+Query-backed surfaces can use `createSmrtWebQuery(collection, transport)` to
+fetch one canonical bounded page. Visible runs update state; `background`,
+`prefetch`, and `silent` runs stay out of visible state. The controller keeps
+stale rows available while refreshing, cancels superseded visible runs, and can
+attach a query-scoped live subscription.
+
 ## Installation
 
 ```bash
@@ -119,6 +125,7 @@ core.
 | Group | Main exports |
 | --- | --- |
 | Collections | `createSmrtCollection`, `createSmrtWebClient`, `newLocalId` |
+| Remote queries | `createSmrtWebQuery`, `SmrtWebQueryTransport` |
 | HTTP | `createDefinitionFetchers`, `unwrapListResult`, `unwrapItemResult` |
 | Offline | `offlineOutbox`, `getOutboxHandle` |
 | Persistence | `persistCollection`, `wipeDurableStore` |
@@ -126,6 +133,83 @@ core.
 | Version awareness | `createUpdateState` |
 | WebMCP | `registerWebMcpTools` |
 
+## WebMCP capability exposure
+
+`registerWebMcpTools()` is secure by default: omitting an exposure policy
+registers only `read` tools. CRUD effects are fixed (`list`/`get` are `read`,
+`create`/`update` are `write`, and `delete` is `destructive`). A custom action
+without declared metadata is treated as destructive, non-idempotent, and open
+world. Declare safer custom-action semantics in the route metadata only when
+they are true:
+
+```ts
+@smrt({
+  api: {
+    routes: {
+      preview: {
+        method: 'GET',
+        effect: 'read',
+        idempotent: true,
+        openWorld: false,
+      },
+    },
+  },
+})
+class Report extends SmrtObject {}
+```
+
+Opt into broader capabilities explicitly. `namespace` prevents cross-surface
+name collisions, an explicit `maxTools` bounds the selected set, and duplicate
+names or stable collection/action identities reject the entire call before the
+first browser registration. No implicit budget is applied to whole-manifest
+read registration:
+
+```ts
+registerWebMcpTools(definitions, {
+  effects: ['read', 'write', 'destructive'],
+  namespace: 'admin',
+  maxTools: 32,
+  filter: (collection, tool) => collection.fields.tenantId !== undefined,
+  filterTool: (tool) => tool.collection === 'reports',
+});
+```
+
+The returned disposer also exposes a `ready` promise. Await it when the host
+must report browser-side registration rejection; any rejected tool aborts all
+sibling registrations from that call before `ready` rejects.
+
+`filter` receives legacy collection metadata; `filterTool` receives canonical
+per-tool definitions. Configuring only one filter while registering definitions
+for the other filter kind fails closed; canonical tools do not carry complete
+collection field metadata, and legacy descriptors do not satisfy the canonical
+filter contract. Policy callbacks and fetcher resolvers receive isolated value
+snapshots; key host-side maps by stable values such as collection/action or tool
+name, not definition object identity.
+
+Do not concatenate complete legacy and canonical definition sets for the same
+collections. Their duplicate tool names or collection/action identities reject
+the registration atomically. Prefer the canonical set for complete generated
+coverage, or compose only disjoint legacy and canonical subsets.
+
+WebMCP policy controls which capabilities a page advertises; it is not an
+authorization boundary. Execution still uses the page's authenticated REST
+transport, whose auth, tenancy, writable-field, and sensitive-field guards must
+remain enabled. All application-derived tool results are annotated as untrusted
+content, including mutation responses.
+
+Policy only narrows the actions already exposed by the generated API metadata.
+Legacy descriptors outside their collection's `actions` set reject the whole
+registration, and intrinsic CRUD effects cannot be relabeled by caller data.
+
+Migration note: registrations that previously relied on every descriptor being
+exposed must now pass `effects: ['read', 'write', 'destructive']`. Prefer a
+narrower allowlist for each browser surface. Integrations that previously keyed
+filter or resolver state by definition object identity must migrate to stable
+name or collection/action keys. If both legacy and canonical definition arrays
+are available, select one complete source or remove overlaps before combining
+them. Set `maxTools` explicitly on surfaces that need a hard capability budget;
+overflow rejects the complete registration rather than truncating it.
+
 ## Development
 
 ```bash