@happyvertical/smrt-web 0.43.3 → 0.43.5

package/AGENTS.md

@@ -38,7 +38,7 @@ 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) | — |
@@ -61,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
@@ -79,3 +107,17 @@ different request id — before they reach a UI surface.
 
 `packages/products` consumes the runtime as its reference store across npm,
 federation, and standalone modes (see the smrt-web track, PRD #1755).
+
+## WebMCP integration fixture
+
+`src/webmcp-e2e.integration.test.ts` is the production-shaped composition
+fixture for generated WebMCP tools. It uses `smrtVitestPlugin()`, a real
+in-memory SQLite database, and generated REST handlers. Only the browser
+`document.modelContext` and external AI boundary are doubled. Keep this fixture
+focused on the WebMCP contract: auth failures, effect/exposure policy,
+tool-only fetches, custom actions, relationship cache invalidation, and
+registration disposal. Its descriptors come from the OXC manifest adapter so
+the test follows the same generation path as the virtual WebMCP module; the
+Vitest config excludes test files from the package manifest to avoid exposing
+fixture-only classes to package discovery. The integration model is documented in
+`docs/content/webmcp-integration.md`.

package/README.md

@@ -133,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

package/dist/chunks/{src-D9RvoJSQ.js → src-n14q6RHC.js}

@@ -2116,38 +2116,266 @@ function getModelContext() {
 	if (mc && typeof mc.registerTool === "function") return mc;
 }
 function registerWebMcpTools(definitions, options = {}) {
+	const exposure = validateExposurePolicy(options);
 	const ctx = getModelContext();
-	if (!ctx) return () => {};
+	if (!ctx) return registrationDisposer(() => {}, Promise.resolve());
 	const basePath = options.basePath ?? "/api/v1";
+	const client = options.client;
+	const { tools, allowedEffects } = selectProspectiveTools(definitions, options, exposure);
+	if (client && tools.some((tool) => tool.kind === "canonical" && tool.effect !== "read")) validateSmrtWebClient(client);
 	const controller = new AbortController();
 	const collections = /* @__PURE__ */ new Map();
-	for (const definition of definitions) {
-		const descriptors = definition.toolDescriptors;
-		if (!descriptors || descriptors.length === 0) continue;
-		const fetchers = options.resolveFetchers ? options.resolveFetchers(definition) : createDefinitionFetchers(definition, basePath, options.fetchFn);
-		const collection = createSmrtCollection(definition, {
-			fetchers,
-			basePath,
-			fetchFn: options.fetchFn,
-			...options.client ? { client: options.client } : {},
-			...options.scope ? { scope: options.scope } : {}
-		});
-		collections.set(definition, collection);
-		for (const descriptor of descriptors) {
-			if (options.filter && !options.filter(definition, descriptor)) continue;
-			ctx.registerTool({
-				name: descriptor.name,
-				description: descriptor.description,
-				inputSchema: descriptor.inputSchema,
-				annotations: { readOnlyHint: descriptor.readOnly },
-				execute: (args) => dispatch(fetchers, collection, definition, descriptor.action, descriptor.route, args ?? {})
-			}, { signal: controller.signal });
-		}
-	}
-	return () => {
+	const collectionFetchers = /* @__PURE__ */ new Map();
+	let disposed = false;
+	const dispose = () => {
+		if (disposed) return;
+		disposed = true;
 		controller.abort();
 		for (const collection of collections.values()) collection.cleanup().catch(() => void 0);
 	};
+	const registrations = [];
+	try {
+		for (const tool of tools) {
+			if (tool.kind === "legacy") {
+				const { definition: definition2, descriptor } = tool;
+				let fetchers2 = collectionFetchers.get(definition2);
+				let collection = collections.get(definition2);
+				if (!fetchers2 || !collection) {
+					fetchers2 = options.resolveFetchers ? options.resolveFetchers(snapshotLegacyDefinition(definition2)) : createDefinitionFetchers(definition2, basePath, options.fetchFn);
+					collection = createSmrtCollection(definition2, {
+						fetchers: fetchers2,
+						basePath,
+						fetchFn: options.fetchFn,
+						...client ? { client } : {},
+						...options.scope ? { scope: options.scope } : {}
+					});
+					collectionFetchers.set(definition2, fetchers2);
+					collections.set(definition2, collection);
+				}
+				registrations.push(Promise.resolve(ctx.registerTool({
+					name: tool.name,
+					description: descriptor.description,
+					inputSchema: descriptor.inputSchema,
+					annotations: annotationsFor(tool),
+					execute: guardedExecute(tool, allowedEffects, () => disposed, (args) => dispatchCollection(fetchers2, collection, definition2, descriptor.action, descriptor.route, args))
+				}, { signal: controller.signal })));
+				continue;
+			}
+			const { definition } = tool;
+			const fetchers = options.resolveToolFetchers ? options.resolveToolFetchers(snapshotCanonicalDefinition(definition, {
+				effect: tool.effect,
+				destructive: tool.destructive,
+				idempotent: tool.idempotent,
+				openWorld: tool.openWorld
+			})) : createDefinitionFetchers({
+				name: definition.collection,
+				endpoint: definition.endpoint
+			}, basePath, options.fetchFn);
+			registrations.push(Promise.resolve(ctx.registerTool({
+				name: tool.name,
+				description: definition.description,
+				inputSchema: definition.inputSchema,
+				annotations: annotationsFor(tool),
+				execute: guardedExecute(tool, allowedEffects, () => disposed, (args) => dispatchDirect(fetchers, definition, args, client))
+			}, { signal: controller.signal })));
+		}
+	} catch (error) {
+		Promise.all(registrations).catch(() => void 0);
+		dispose();
+		throw error;
+	}
+	const ready = Promise.all(registrations).then(() => void 0).catch((error) => {
+		dispose();
+		throw error;
+	});
+	ready.catch(() => void 0);
+	return registrationDisposer(dispose, ready);
+}
+function registrationDisposer(dispose, ready) {
+	return Object.assign(dispose, { ready });
+}
+var VALID_EFFECTS = [
+	"read",
+	"write",
+	"destructive"
+];
+var NAMESPACE_PATTERN = /^[A-Za-z0-9][A-Za-z0-9_-]*$/;
+function validateExposurePolicy(options) {
+	const effects = options.effects ?? ["read"];
+	for (const effect of effects) if (!VALID_EFFECTS.includes(effect)) throw new Error(`Invalid WebMCP effect: ${String(effect)}`);
+	const maxTools = options.maxTools;
+	if (maxTools !== void 0 && (!Number.isSafeInteger(maxTools) || maxTools < 0)) throw new Error("WebMCP maxTools must be a non-negative safe integer");
+	const namespace = options.namespace;
+	if (namespace !== void 0 && !NAMESPACE_PATTERN.test(namespace)) throw new Error("WebMCP namespace must start with an alphanumeric character and contain only letters, numbers, underscores, or hyphens");
+	return {
+		allowedEffects: new Set(effects),
+		...maxTools !== void 0 ? { maxTools } : {},
+		...namespace !== void 0 ? { namespace } : {}
+	};
+}
+function selectProspectiveTools(definitions, options, exposure) {
+	const { allowedEffects, maxTools, namespace } = exposure;
+	const stableDefinitions = definitions.map((definition) => snapshotValue(definition));
+	const tools = [];
+	for (const definition of stableDefinitions) {
+		if (isCanonicalToolDefinition(definition)) {
+			const semantics = actionSemantics(definition.action, definition);
+			if (!allowedEffects.has(semantics.effect)) continue;
+			if (options.filter && !options.filterTool) throw new Error("[smrt-web] canonical WebMCP definitions require filterTool when filter is configured");
+			const stableDefinition2 = snapshotCanonicalDefinition(definition, semantics);
+			if (options.filterTool && !options.filterTool(snapshotCanonicalDefinition(stableDefinition2, semantics))) continue;
+			tools.push({
+				kind: "canonical",
+				definition: stableDefinition2,
+				descriptor: stableDefinition2,
+				name: qualifiedToolName(stableDefinition2.name, namespace),
+				identity: `${stableDefinition2.collection}#${stableDefinition2.action}`,
+				...semantics
+			});
+			continue;
+		}
+		const stableDefinition = snapshotLegacyDefinition(definition);
+		for (const descriptor of stableDefinition.toolDescriptors ?? []) {
+			if (!stableDefinition.actions.includes(descriptor.action)) throw new Error(`WebMCP tool ${descriptor.name} exposes action ${descriptor.action} outside ${stableDefinition.name}'s allowed actions`);
+			const semantics = actionSemantics(descriptor.action, descriptor);
+			if (!allowedEffects.has(semantics.effect)) continue;
+			if (options.filterTool && !options.filter) throw new Error("[smrt-web] legacy WebMCP definitions require filter when filterTool is configured");
+			const stableDescriptor = snapshotLegacyDescriptor(descriptor, semantics);
+			if (options.filter && !options.filter(snapshotLegacyDefinition(stableDefinition), snapshotLegacyDescriptor(stableDescriptor, semantics))) continue;
+			tools.push({
+				kind: "legacy",
+				definition: stableDefinition,
+				descriptor: stableDescriptor,
+				name: qualifiedToolName(stableDescriptor.name, namespace),
+				identity: `${stableDefinition.name}#${stableDescriptor.action}`,
+				...semantics
+			});
+		}
+	}
+	validateProspectiveTools(tools, maxTools);
+	return {
+		tools,
+		allowedEffects
+	};
+}
+function qualifiedToolName(name, namespace) {
+	return namespace ? `${namespace}_${name}` : name;
+}
+function actionSemantics(action, declared) {
+	switch (action) {
+		case "list":
+		case "get": return {
+			effect: "read",
+			destructive: false,
+			idempotent: true,
+			openWorld: false
+		};
+		case "create": return {
+			effect: "write",
+			destructive: true,
+			idempotent: false,
+			openWorld: false
+		};
+		case "update": return {
+			effect: "write",
+			destructive: true,
+			idempotent: true,
+			openWorld: false
+		};
+		case "delete": return {
+			effect: "destructive",
+			destructive: true,
+			idempotent: true,
+			openWorld: false
+		};
+		default: {
+			const effect = VALID_EFFECTS.includes(declared.effect) ? declared.effect : "destructive";
+			return {
+				effect,
+				destructive: effect !== "read",
+				idempotent: declared.idempotent ?? false,
+				openWorld: declared.openWorld ?? true
+			};
+		}
+	}
+}
+function snapshotRoute(route) {
+	return route ? snapshotValue(route) : void 0;
+}
+function snapshotValue(value, active = /* @__PURE__ */ new WeakSet(), path = "$") {
+	if (value && typeof value === "object") {
+		if (active.has(value)) throw new Error(`[smrt-web] WebMCP definitions must be acyclic (cycle at ${path})`);
+		active.add(value);
+	}
+	try {
+		if (Array.isArray(value)) return value.map((entry, index) => snapshotValue(entry, active, `${path}[${index}]`));
+		if (value && typeof value === "object") {
+			const snapshot = {};
+			for (const [key, entry] of Object.entries(value)) snapshot[key] = snapshotValue(entry, active, `${path}.${key}`);
+			return snapshot;
+		}
+		return value;
+	} finally {
+		if (value && typeof value === "object") active.delete(value);
+	}
+}
+function snapshotLegacyDescriptor(descriptor, semantics) {
+	return snapshotValue({
+		...descriptor,
+		effect: semantics.effect,
+		idempotent: semantics.idempotent,
+		openWorld: semantics.openWorld,
+		readOnly: semantics.effect === "read",
+		route: snapshotRoute(descriptor.route)
+	});
+}
+function snapshotLegacyDefinition(definition) {
+	const snapshot = snapshotValue({
+		...definition,
+		actions: [...definition.actions]
+	});
+	snapshot.toolDescriptors = snapshot.toolDescriptors?.map((descriptor) => snapshotLegacyDescriptor(descriptor, actionSemantics(descriptor.action, descriptor)));
+	return snapshot;
+}
+function snapshotCanonicalDefinition(definition, semantics) {
+	return snapshotValue({
+		...definition,
+		effect: semantics.effect,
+		idempotent: semantics.idempotent,
+		openWorld: semantics.openWorld,
+		readOnly: semantics.effect === "read",
+		route: snapshotRoute(definition.route)
+	});
+}
+function validateProspectiveTools(tools, maxTools) {
+	if (maxTools !== void 0 && tools.length > maxTools) throw new Error(`WebMCP tool budget exceeded: ${tools.length} tools selected, maximum is ${maxTools}`);
+	const names = /* @__PURE__ */ new Set();
+	const identities = /* @__PURE__ */ new Set();
+	for (const tool of tools) {
+		if (names.has(tool.name)) throw new Error(`Duplicate WebMCP tool name: ${tool.name}`);
+		names.add(tool.name);
+		if (identities.has(tool.identity)) throw new Error(`Duplicate WebMCP tool identity: ${tool.identity}`);
+		identities.add(tool.identity);
+	}
+}
+function annotationsFor(tool) {
+	return {
+		readOnlyHint: tool.effect === "read",
+		destructiveHint: tool.destructive,
+		idempotentHint: tool.idempotent,
+		openWorldHint: tool.openWorld,
+		untrustedContentHint: true
+	};
+}
+function guardedExecute(tool, allowedEffects, isDisposed, execute) {
+	return (args) => {
+		if (isDisposed()) throw new Error(`WebMCP tool ${tool.name} is no longer registered`);
+		if (!allowedEffects.has(tool.effect)) throw new Error(`WebMCP policy no longer allows ${tool.effect} tool ${tool.name}`);
+		return execute(args ?? {});
+	};
+}
+function isCanonicalToolDefinition(definition) {
+	return "collection" in definition && "readOnly" in definition;
 }
 function requireId(args, action) {
 	const id = args.id;
@@ -2167,7 +2395,7 @@ function listParams(args) {
 	if (args.where !== void 0) params.where = args.where;
 	return params;
 }
-async function dispatch(fetchers, collection, definition, action, route, args) {
+async function dispatchCollection(fetchers, collection, definition, action, route, args) {
 	switch (action) {
 		case "list": {
 			const rows = unwrapListResult(await fetchers.list(listParams(args)), definition.name);
@@ -2208,6 +2436,45 @@ async function dispatch(fetchers, collection, definition, action, route, args) {
 			return JSON.stringify(await collection.action(action, args, route));
 	}
 }
+async function dispatchDirect(fetchers, definition, args, client) {
+	let result;
+	switch (definition.action) {
+		case "list":
+			if (!fetchers.list) throw new Error(`${definition.collection} has no list action`);
+			result = unwrapListResult(await fetchers.list(listParams(args)), definition.collection);
+			break;
+		case "get":
+			if (!fetchers.get) throw new Error(`${definition.collection} has no get action`);
+			result = unwrapItemResult(await fetchers.get(requireIdentifier(args)), `get(${definition.collection})`);
+			break;
+		case "create":
+			if (!fetchers.create) throw new Error(`${definition.collection} has no create action`);
+			result = unwrapItemResult(await fetchers.create(args), `create(${definition.collection})`);
+			break;
+		case "update": {
+			if (!fetchers.update) throw new Error(`${definition.collection} has no update action`);
+			const id = requireId(args, "update");
+			const { id: _id, ...body } = args;
+			result = unwrapItemResult(await fetchers.update(id, body), `update(${definition.collection})`);
+			break;
+		}
+		case "delete": {
+			if (!fetchers.delete) throw new Error(`${definition.collection} has no delete action`);
+			const id = requireId(args, "delete");
+			throwIfSmrtWebError(await fetchers.delete(id), `delete(${definition.collection})`);
+			result = {
+				success: true,
+				id
+			};
+			break;
+		}
+		default:
+			if (!fetchers.custom) throw new Error(`${definition.collection} has no custom action fetcher`);
+			result = throwIfSmrtWebError(await fetchers.custom(definition.action, args, definition.route), `${definition.action}(${definition.collection})`);
+	}
+	if (!definition.readOnly && client) invalidateSmrtWebCollections(client, [definition.collection, ...definition.relationships.map((relationship) => relationship.relatedCollection)]);
+	return JSON.stringify(result);
+}
 async function settleTransaction(transaction, collection, key, fallback) {
 	await transaction.isPersisted.promise;
 	const persisted = persistedMutationResults.get(collection)?.get(key);
@@ -2256,23 +2523,34 @@ function createHttpRequestError(collectionName, status, payload) {
 	return new SmrtWebRequestError(`[smrt-web] ${collectionName} request failed: ${detail.message ?? `HTTP ${status}`}`, payload, status, detail.code);
 }
 function unwrapListResult(result, collectionName) {
+	throwIfSmrtWebError(result, `list(${collectionName})`);
 	if (Array.isArray(result)) return result;
 	if (result && typeof result === "object") {
 		const record = result;
-		if (typeof record.error === "string") throw new SmrtWebRequestError(`[smrt-web] list(${collectionName}) failed: ${record.error}`, result);
 		if (Array.isArray(record.data)) return record.data;
 	}
 	throw new SmrtWebRequestError(`[smrt-web] list(${collectionName}) returned an unexpected payload shape`, result);
 }
 function unwrapItemResult(result, context) {
+	throwIfSmrtWebError(result, context);
 	if (result && typeof result === "object" && !Array.isArray(result)) {
 		const record = result;
-		if (typeof record.error === "string") throw new SmrtWebRequestError(`[smrt-web] ${context} failed: ${record.error}`, result);
 		if (record.data && typeof record.data === "object" && !Array.isArray(record.data)) return record.data;
 		return record;
 	}
 	throw new SmrtWebRequestError(`[smrt-web] ${context} returned an unexpected payload shape`, result);
 }
+function throwIfSmrtWebError(result, context) {
+	if (!result || typeof result !== "object" || Array.isArray(result)) return result;
+	const error = result.error;
+	if (typeof error === "string") throw new SmrtWebRequestError(`[smrt-web] ${context} failed: ${error}`, result);
+	if (!error || typeof error !== "object" || Array.isArray(error)) return result;
+	const failure = error;
+	if (failure.ok !== false || typeof failure.code !== "string" || typeof failure.message !== "string") return result;
+	const status = typeof failure.status === "number" && Number.isInteger(failure.status) && failure.status >= 400 && failure.status <= 599 ? failure.status : void 0;
+	if (status !== void 0 && status >= 500) throw new SmrtWebRequestError(`[smrt-web] ${context} failed: server error`, void 0, status);
+	throw new SmrtWebRequestError(`[smrt-web] ${context} failed: ${failure.message}`, result, status, failure.code);
+}
 var SMRT_TO_REST_OPERATOR = {
 	">": "gt",
 	">=": "gte",
@@ -2374,12 +2652,12 @@ function createDefinitionFetchers(definition, basePath = "/api/v1", fetchFn = (.
 			if (customRoute.method !== "GET") init.body = JSON.stringify(body);
 			else {
 				const queryParams = new URLSearchParams();
-				if (optionsBag) if (optionsValue === void 0) queryParams.set(CUSTOM_OPTIONS_QUERY_MARKER, "undefined");
-				else if (optionsValue === null) queryParams.set(CUSTOM_OPTIONS_QUERY_MARKER, "null");
+				if (optionsBag) if (optionsValue === void 0 && pathArgs.size === 0) queryParams.set(CUSTOM_OPTIONS_QUERY_MARKER, "undefined");
+				else if (optionsValue === null && pathArgs.size === 0) queryParams.set(CUSTOM_OPTIONS_QUERY_MARKER, "null");
 				else {
-					const entries = Object.entries(typeof optionsValue === "object" && !Array.isArray(optionsValue) ? optionsValue : {}).filter(([, value]) => value !== void 0 && value !== null);
+					const entries = Object.entries(optionsValue !== null && typeof optionsValue === "object" && !Array.isArray(optionsValue) ? optionsValue : {}).filter(([, value]) => value !== void 0 && value !== null);
 					for (const [key, value] of entries) queryParams.set(key, typeof value === "object" ? JSON.stringify(value) : String(value));
-					if (entries.length === 0) queryParams.set(CUSTOM_OPTIONS_QUERY_MARKER, "object");
+					if (entries.length === 0 && pathArgs.size === 0) queryParams.set(CUSTOM_OPTIONS_QUERY_MARKER, "object");
 				}
 				else {
 					const queryBody = body !== null && typeof body === "object" && !Array.isArray(body) ? body : {};
@@ -2400,18 +2678,36 @@ function newLocalId() {
 	if (cryptoRef?.randomUUID) return cryptoRef.randomUUID();
 	return `local-${Date.now()}-${Math.random().toString(36).slice(2)}`;
 }
+var smrtWebClientHandles = /* @__PURE__ */ new WeakSet();
 function createSmrtWebClient() {
-	return {
+	const engine = {
 		__smrtWebClient: "SmrtWebClient",
 		queryClient: new QueryClient()
 	};
+	smrtWebClientHandles.add(engine);
+	return engine;
 }
 function resolveQueryClient(client) {
 	if (!client) return new QueryClient();
 	const engine = client;
-	if (engine.__smrtWebClient !== "SmrtWebClient" || !engine.queryClient) throw new SmrtWebRequestError("[smrt-web] options.client must be a handle from createSmrtWebClient()");
+	if (!smrtWebClientHandles.has(engine) || engine.__smrtWebClient !== "SmrtWebClient" || !engine.queryClient) throw new SmrtWebRequestError("[smrt-web] options.client must be a handle from createSmrtWebClient()");
 	return engine.queryClient;
 }
+function validateSmrtWebClient(client) {
+	resolveQueryClient(client);
+}
+function invalidateCollectionQueries(queryClient, collectionNames) {
+	if (collectionNames.size === 0) return;
+	queryClient.invalidateQueries({ predicate: (query) => {
+		const key = query.queryKey;
+		if (!Array.isArray(key) || key.length === 0) return false;
+		const collectionSegment = key[key.length - 1];
+		return typeof collectionSegment === "string" && collectionNames.has(collectionSegment);
+	} });
+}
+function invalidateSmrtWebCollections(client, collectionNames) {
+	invalidateCollectionQueries(resolveQueryClient(client), new Set(collectionNames));
+}
 function toPlainRow(row) {
 	const plain = {};
 	for (const [key, value] of Object.entries(row)) if (key.charCodeAt(0) !== 36) plain[key] = value;
@@ -2460,12 +2756,7 @@ function createSmrtCollection(definition, options) {
 	const invalidationTargets = /* @__PURE__ */ new Set([definition.name]);
 	for (const relationship of definition.relationships ?? []) invalidationTargets.add(relationship.relatedCollection);
 	const invalidateRelated = () => {
-		queryClient.invalidateQueries({ predicate: (query) => {
-			const key = query.queryKey;
-			if (!Array.isArray(key) || key.length === 0) return false;
-			const collectionSegment = key[key.length - 1];
-			return typeof collectionSegment === "string" && invalidationTargets.has(collectionSegment);
-		} });
+		invalidateCollectionQueries(queryClient, invalidationTargets);
 	};
 	const ctx = {
 		definition,
@@ -2629,7 +2920,7 @@ function createSmrtCollection(definition, options) {
 					data: {},
 					baseUpdatedAt: getBaseUpdatedAt(mutation.original)
 				};
-				const outcome = await persistMutation(envelope, async () => fetchers.delete(key));
+				const outcome = await persistMutation(envelope, async () => throwIfSmrtWebError(await fetchers.delete(key), `delete(${definition.name})`));
 				mutationResults.set(envelope.key, outcome.result);
 				anyHandled = anyHandled || outcome.handled;
 			}
@@ -2688,6 +2979,7 @@ function createSmrtCollection(definition, options) {
 		async action(action, args, route) {
 			if (!fetchers.custom) throw new Error(`${definition.name} has no custom action fetcher`);
 			const result = route === void 0 ? await fetchers.custom(action, args) : await fetchers.custom(action, args, route);
+			throwIfSmrtWebError(result, `${action}(${definition.name})`);
 			invalidateRelated();
 			return result;
 		}
@@ -2706,6 +2998,6 @@ function createSmrtCollection(definition, options) {
 	return handle;
 }
 //#endregion
-export { MAX_SMRT_WEB_DATA_QUERY_WARNINGS as A, MAX_SMRT_WEB_DATA_QUERY_FACETS as C, MAX_SMRT_WEB_DATA_QUERY_RESULT_BYTES as D, MAX_SMRT_WEB_DATA_QUERY_PAGE_LIMIT as E, normalizeSmrtWebDataQueryResult as M, runWrapMutation as N, MAX_SMRT_WEB_DATA_QUERY_ROWS as O, MAX_SMRT_WEB_DATA_QUERY_CONTAINER_ITEMS as S, MAX_SMRT_WEB_DATA_QUERY_OFFSET as T, getOutboxHandle as _, createSmrtWebClient as a, registerDurableResource as b, unwrapItemResult as c, createUpdateState as d, createSmrtWebEventSubscriber as f, persistCollection as g, DEFAULT_PERSIST_DEBOUNCE_MS as h, createSmrtCollection as i, executeSmrtWebDataQuery as j, MAX_SMRT_WEB_DATA_QUERY_STRING_LENGTH as k, unwrapListResult as l, createSmrtWebQuery as m, buildListQuery as n, getEngineCollection as o, liveInvalidation as p, createDefinitionFetchers as r, newLocalId as s, SmrtWebRequestError as t, registerWebMcpTools as u, offlineOutbox as v, MAX_SMRT_WEB_DATA_QUERY_FACET_VALUES as w, wipeDurableStore as x, durableStoreNamespace as y };
+export { MAX_SMRT_WEB_DATA_QUERY_RESULT_BYTES as A, registerDurableResource as C, MAX_SMRT_WEB_DATA_QUERY_FACET_VALUES as D, MAX_SMRT_WEB_DATA_QUERY_FACETS as E, normalizeSmrtWebDataQueryResult as F, runWrapMutation as I, MAX_SMRT_WEB_DATA_QUERY_STRING_LENGTH as M, MAX_SMRT_WEB_DATA_QUERY_WARNINGS as N, MAX_SMRT_WEB_DATA_QUERY_OFFSET as O, executeSmrtWebDataQuery as P, durableStoreNamespace as S, MAX_SMRT_WEB_DATA_QUERY_CONTAINER_ITEMS as T, createSmrtWebQuery as _, createSmrtWebClient as a, getOutboxHandle as b, newLocalId as c, unwrapListResult as d, validateSmrtWebClient as f, liveInvalidation as g, createSmrtWebEventSubscriber as h, createSmrtCollection as i, MAX_SMRT_WEB_DATA_QUERY_ROWS as j, MAX_SMRT_WEB_DATA_QUERY_PAGE_LIMIT as k, throwIfSmrtWebError as l, createUpdateState as m, buildListQuery as n, getEngineCollection as o, registerWebMcpTools as p, createDefinitionFetchers as r, invalidateSmrtWebCollections as s, SmrtWebRequestError as t, unwrapItemResult as u, DEFAULT_PERSIST_DEBOUNCE_MS as v, wipeDurableStore as w, offlineOutbox as x, persistCollection as y };
 
-//# sourceMappingURL=src-D9RvoJSQ.js.map
+//# sourceMappingURL=src-n14q6RHC.js.map