@happyvertical/smrt-core 0.46.0 → 0.47.1

package/dist/generators/custom-action.js

@@ -303,9 +303,9 @@ function customActionParameterInputName(_metadata, parameterName) {
 */
 function resolveCustomActionMetadata(options) {
 	const defaultScope = options.defaultScope ?? (options.method?.isStatic ? "collection" : "item");
-	const requestedScope = readConfiguredScope(options.apiConfig, options.actionName);
+	const requestedScope = readConfiguredScope(options);
 	const scope = requestedScope === defaultScope ? requestedScope : defaultScope;
-	const configured = readConfiguredToolMetadata(options.apiConfig, options.actionName);
+	const configured = readConfiguredToolMetadata(options);
 	const effect = configured.effect ?? "destructive";
 	return {
 		scope,
@@ -317,6 +317,25 @@ function resolveCustomActionMetadata(options) {
 		openWorld: configured.openWorld ?? true
 	};
 }
+/**
+* The declared scope, when it contradicts the receiver the method actually
+* has; `undefined` when there is no declaration or it agrees.
+*
+* A scope is a DECLARATION about a method, not a relocation of it: nothing in
+* a config can move an instance method onto the class. Silently ignoring a
+* contradiction leaves an author believing a route exists at a collection URL
+* that was never written, so the generators report this at build time
+* (#2686).
+*/
+function resolveDeclaredScopeMismatch(options) {
+	const declared = resolveEffectiveActionMetadata({
+		actionName: options.actionName,
+		...options.method ? { method: options.method } : {},
+		apiConfig: options.apiConfig
+	}).scope;
+	if (!declared || declared === options.effectiveScope) return void 0;
+	return declared;
+}
 /** Build the custom-action portion of an MCP/WebMCP JSON Schema. */
 function buildCustomActionInputSchema(metadata) {
 	const properties = {};
@@ -365,7 +384,7 @@ function buildCustomActionInvocationArgs(metadata, args) {
 	if (!metadata.parameters) return [isRecord(options) && Object.keys(options).length > 0 ? options : directArgs];
 	if (metadata.parameters.length === 0) return [];
 	if (metadata.parameters.length === 1 && metadata.parameters[0]?.name === "options") return [options];
-	return metadata.parameters.map((parameter) => args[customActionParameterInputName(metadata, parameter.name)]);
+	return metadata.parameters.map((parameter) => coerceCustomActionArgument(args[customActionParameterInputName(metadata, parameter.name)], parameter.type));
 }
 /** Stable MCP `_meta` member shared with the app discovery contract (#2181). */
 var SMRT_CUSTOM_ACTION_ERROR_METADATA_KEY = "io.happyvertical/smrt";
@@ -388,21 +407,24 @@ function normalizeCustomActionFailure(value) {
 		...typeof value.correlationId === "string" ? { correlationId: value.correlationId } : {}
 	};
 }
-function readConfiguredScope(apiConfig, actionName) {
-	if (!isRecord(apiConfig) || !isRecord(apiConfig.routes)) return void 0;
-	const route = apiConfig.routes[actionName];
-	return isRecord(route) && (route.scope === "item" || route.scope === "collection") ? route.scope : void 0;
+function readConfiguredScope(options) {
+	return resolveEffectiveActionMetadata({
+		actionName: options.actionName,
+		...options.method ? { method: options.method } : {},
+		apiConfig: options.apiConfig
+	}).scope;
 }
-function readConfiguredToolMetadata(apiConfig, actionName) {
-	if (!isRecord(apiConfig) || !isRecord(apiConfig.routes)) return {};
-	const route = apiConfig.routes[actionName];
-	if (!isRecord(route)) return {};
-	const effect = route.effect === "read" || route.effect === "write" || route.effect === "destructive" ? route.effect : void 0;
-	if (effect === "read" && (route.method === "PUT" || route.method === "PATCH" || route.method === "DELETE")) throw new Error(`Custom action ${actionName} cannot declare a read effect for a ${route.method} route`);
+function readConfiguredToolMetadata(options) {
+	const effective = resolveEffectiveActionMetadata({
+		actionName: options.actionName,
+		...options.method ? { method: options.method } : {},
+		apiConfig: options.apiConfig
+	});
+	if (effective.effect === "read" && (effective.httpMethod === "PUT" || effective.httpMethod === "PATCH" || effective.httpMethod === "DELETE")) throw new Error(`Custom action ${options.actionName} cannot declare a read effect for a ${effective.httpMethod} route`);
 	return {
-		...effect ? { effect } : {},
-		...typeof route.idempotent === "boolean" ? { idempotent: route.idempotent } : {},
-		...typeof route.openWorld === "boolean" ? { openWorld: route.openWorld } : {}
+		...effective.effect ? { effect: effective.effect } : {},
+		...effective.idempotent !== void 0 ? { idempotent: effective.idempotent } : {},
+		...effective.openWorld !== void 0 ? { openWorld: effective.openWorld } : {}
 	};
 }
 function redactValue(value, seen = /* @__PURE__ */ new WeakSet()) {
@@ -426,7 +448,662 @@ function isSensitiveKey(key) {
 function isRecord(value) {
 	return value !== null && typeof value === "object" && !Array.isArray(value);
 }
+/**
+* Read and validate the `@method()` config the scanner put on a manifest
+* method. Returns `undefined` for an undecorated method.
+*/
+function readMethodDecoratorConfig(method) {
+	const raw = method?.decoratorConfig;
+	if (!isRecord(raw)) return void 0;
+	const scope = raw.scope === "item" || raw.scope === "collection" ? raw.scope : void 0;
+	const effect = raw.effect === "read" || raw.effect === "write" || raw.effect === "destructive" ? raw.effect : void 0;
+	return {
+		...typeof raw.expose === "boolean" ? { expose: raw.expose } : {},
+		...typeof raw.reason === "string" ? { reason: raw.reason } : {},
+		...isApiHttpMethod(raw.httpMethod) ? { httpMethod: raw.httpMethod } : {},
+		...typeof raw.path === "string" ? { path: raw.path } : {},
+		...scope ? { scope } : {},
+		...effect ? { effect } : {},
+		...typeof raw.idempotent === "boolean" ? { idempotent: raw.idempotent } : {},
+		...typeof raw.openWorld === "boolean" ? { openWorld: raw.openWorld } : {},
+		...typeof raw.description === "string" ? { description: raw.description } : {}
+	};
+}
+function isApiHttpMethod(value) {
+	return value === "GET" || value === "POST" || value === "PUT" || value === "PATCH" || value === "DELETE";
+}
+/**
+* JavaScript values a JSON request body or query string cannot carry, keyed by
+* the type NAME the manifest records for them.
+*
+* Deliberately a name list rather than "anything not primitive": the manifest
+* cannot tell an interface from a class, so an unrecognized capitalized name
+* is assumed to be a plain data bag (see {@link isWireableTypeName}). These are
+* the well-known exceptions where that assumption is wrong for every project.
+* Model classes are excluded separately, by asking the manifest.
+*/
+var NON_SERIALIZABLE_TYPE_NAMES = /* @__PURE__ */ new Set([
+	"Function",
+	"bigint",
+	"symbol",
+	"Buffer",
+	"ArrayBuffer",
+	"SharedArrayBuffer",
+	"DataView",
+	"Uint8Array",
+	"Int8Array",
+	"Uint16Array",
+	"Int16Array",
+	"Uint32Array",
+	"Int32Array",
+	"Float32Array",
+	"Float64Array",
+	"BigInt64Array",
+	"BigUint64Array",
+	"Blob",
+	"File",
+	"FormData",
+	"ReadableStream",
+	"WritableStream",
+	"TransformStream",
+	"Stream",
+	"Readable",
+	"Writable",
+	"Request",
+	"Response",
+	"Headers",
+	"URL",
+	"URLSearchParams",
+	"AbortSignal",
+	"AbortController",
+	"Map",
+	"Set",
+	"WeakMap",
+	"WeakSet",
+	"RegExp",
+	"Error",
+	"Symbol",
+	"Promise",
+	"SmrtDatabase",
+	"DatabaseInterface",
+	"SmrtCollection",
+	"SmrtObject"
+]);
+/**
+* Generic container names whose ARGUMENTS carry the payload. `Record` is
+* included: its value type is checked, its key type is always a string-ish
+* index and never a receiver.
+*/
+var JSON_CONTAINER_TYPE_NAMES = /* @__PURE__ */ new Set([
+	"Array",
+	"ReadonlyArray",
+	"Record",
+	"Partial",
+	"Required",
+	"Readonly",
+	"Pick",
+	"Omit",
+	"NonNullable"
+]);
+/** Primitive/JSON-native type names a wire request can always carry. */
+var JSON_PRIMITIVE_TYPE_NAMES = /* @__PURE__ */ new Set([
+	"string",
+	"number",
+	"boolean",
+	"null",
+	"undefined",
+	"void",
+	"any",
+	"unknown",
+	"object",
+	"Date"
+]);
+var WIREABLE = { wireable: true };
+/**
+* True when a manifest type NAME can be carried by a JSON request body.
+*
+* The default is ACCEPT: the manifest records types as strings and cannot tell
+* `RunContentReviewOptions` (an interface — a plain bag) from `Content` (a
+* model class). Rejecting every unrecognized capitalized name would withhold
+* routes from the overwhelmingly common options-bag shape, so an unrecognized
+* name is assumed to be a bag and rejection is driven by positive evidence:
+* a known non-serializable runtime type, a manifest class, or a bare type
+* parameter.
+*/
+function classifyTypeName(typeName, options, depth) {
+	const type = typeName.trim();
+	if (type === "") return WIREABLE;
+	if (type === "Date" && depth > 0) return {
+		wireable: false,
+		reason: "`Date` is only hydrated as a top-level parameter, so a nested one arrives as a string"
+	};
+	const unionParts = splitTopLevel(type, "|");
+	if (unionParts.length > 1) {
+		const branches = unionParts.filter((branch) => branch !== "null" && branch !== "undefined");
+		if (branches.length === 0) return WIREABLE;
+		const verdicts = branches.map((branch) => classifyTypeName(branch, options, depth));
+		if (verdicts.some((verdict) => verdict.wireable)) return WIREABLE;
+		return {
+			wireable: false,
+			reason: `every branch of \`${type}\` is unreachable over HTTP (${verdicts[0]?.reason ?? "not JSON-shaped"})`
+		};
+	}
+	if (type.endsWith("[]")) return classifyTypeName(type.slice(0, -2), options, depth + 1);
+	if (/^'.*'$/su.test(type) || /^-?\d/u.test(type)) return WIREABLE;
+	const generic = /^([\w$.]+)\s*<(.*)>$/su.exec(type);
+	if (generic) {
+		const base = generic[1];
+		if (JSON_CONTAINER_TYPE_NAMES.has(base)) {
+			if (depth >= WIREABILITY_MAX_DEPTH) return WIREABLE;
+			const args = splitTopLevel(generic[2], ",");
+			for (const arg of args) {
+				const verdict = classifyTypeName(arg, options, depth + 1);
+				if (!verdict.wireable) return verdict;
+			}
+			return WIREABLE;
+		}
+		return classifyTypeName(base, options, depth + 1);
+	}
+	if (type === "this") return {
+		wireable: false,
+		reason: "`this` is an instance of the declaring model class, not JSON data"
+	};
+	if (NON_SERIALIZABLE_TYPE_NAMES.has(type)) return {
+		wireable: false,
+		reason: `\`${type}\` is a runtime value a JSON request cannot carry`
+	};
+	if (JSON_PRIMITIVE_TYPE_NAMES.has(type)) return WIREABLE;
+	if (/^T(?:[0-9]|[A-Z][A-Za-z0-9]*)?$/u.test(type) || /^[A-Z]$/u.test(type)) return {
+		wireable: false,
+		reason: `\`${type}\` is an unresolved type parameter`
+	};
+	const simpleName = type.includes(".") ? type.split(".").pop() : type;
+	if (options.isModelClassName?.(simpleName)) return {
+		wireable: false,
+		reason: `\`${simpleName}\` is a model class instance, not JSON data`
+	};
+	return WIREABLE;
+}
+/** Recursion bound for generic type arguments. */
+var WIREABILITY_MAX_DEPTH = 6;
+/**
+* Class names a manifest knows about, cached per manifest object.
+*
+* The manifest is rebuilt, never mutated in place, so identity is a safe cache
+* key; a `WeakMap` keeps a discarded manifest's set collectable.
+*/
+var manifestClassNameCache = /* @__PURE__ */ new WeakMap();
+/**
+* Build the `isModelClassName` predicate {@link classifyMethodWireability}
+* needs, from a manifest.
+*
+* Both the SIMPLE and QUALIFIED name of every manifest class are registered: a
+* parameter is annotated with the simple name in source, but a qualified name
+* can reach the predicate through a `TSQualifiedName` annotation.
+*
+* Returns `undefined` for a missing manifest, which widens the gate — see
+* {@link WireabilityOptions.isModelClassName}.
+*/
+function createManifestClassNamePredicate(manifest) {
+	if (!manifest) return void 0;
+	let names = manifestClassNameCache.get(manifest);
+	if (!names) {
+		const collected = /* @__PURE__ */ new Set();
+		for (const [key, object] of Object.entries(manifest.objects ?? {})) {
+			collected.add(key);
+			if (object?.className) collected.add(object.className);
+			if (object?.qualifiedName) collected.add(object.qualifiedName);
+		}
+		names = collected;
+		manifestClassNameCache.set(manifest, names);
+	}
+	return createClassNamePredicate(names);
+}
+/**
+* The same predicate from a bare name list, for a caller whose class inventory
+* is the live `ObjectRegistry` rather than a manifest — notably
+* `@happyvertical/smrt-users`' CLI resource listing, which iterates
+* `ObjectRegistry.getAllClasses()` and has no manifest to hand.
+*
+* Exported so that caller does not grow its own copy: without a predicate the
+* gate half-applies (every rejection EXCEPT model instances), which is worse
+* than either extreme because the consumer then disagrees with the emitters on
+* exactly the largest group of withheld methods.
+*/
+function createClassNamePredicate(names) {
+	const resolved = names instanceof Set ? names : new Set(names);
+	return (name) => resolved.has(name);
+}
+/**
+* Split a type string on `delimiter`, but only where it appears OUTSIDE every
+* bracket pair — so `Record<string, Asset | null>` splits into two parts on
+* `,` and one part on `|`, never into truncated fragments like `Record<string`.
+*
+* A naive `split()` on either delimiter produces fragments that match no
+* classification rule and are therefore accepted by the default-accept path,
+* silently widening the gate. Both the union test and the type-argument scan
+* read this one implementation.
+*/
+function splitTopLevel(source, delimiter) {
+	const parts = [];
+	let depth = 0;
+	let start = 0;
+	for (let index = 0; index < source.length; index += 1) {
+		const char = source[index];
+		if (char === "<" || char === "(" || char === "[" || char === "{") depth += 1;
+		else if (char === ">" || char === ")" || char === "]" || char === "}") depth -= 1;
+		else if (char === delimiter && depth === 0) {
+			parts.push(source.slice(start, index));
+			start = index + 1;
+		}
+	}
+	parts.push(source.slice(start));
+	return parts.map((part) => part.trim()).filter(Boolean);
+}
+/**
+* Whether one declared parameter can be built from a JSON request body or
+* query string.
+*/
+function classifyParameterWireability(parameter, options = {}) {
+	if (parameter.name.startsWith("...")) return {
+		wireable: false,
+		reason: `rest parameter \`${parameter.name}\` cannot be projected from a request body`
+	};
+	if (parameter.typeUnresolved) return {
+		wireable: false,
+		reason: `the declared type of \`${parameter.name}\` could not be resolved by the scanner`
+	};
+	const unionBranches = parameter.unionBranches;
+	if (unionBranches && unionBranches.length > 0) {
+		for (const branch of unionBranches) {
+			if ((branch.memberTypes ?? []).find((memberType) => !classifyTypeName(memberType, options, 1).wireable) !== void 0) continue;
+			if (classifyTypeName(branch.type, options, 0).wireable) return WIREABLE;
+		}
+		return {
+			wireable: false,
+			reason: `parameter \`${parameter.name}\`: no branch of \`${parameter.type ?? "any"}\` can be built from a JSON request`
+		};
+	}
+	for (const memberType of parameter.memberTypes ?? []) {
+		const verdict = classifyTypeName(memberType, options, 1);
+		if (!verdict.wireable) return {
+			wireable: false,
+			reason: `\`${parameter.name}\` contains a member where ${verdict.reason}`
+		};
+	}
+	const verdict = classifyTypeName(parameter.type ?? "any", options, 0);
+	if (verdict.wireable) return WIREABLE;
+	return {
+		wireable: false,
+		reason: `parameter \`${parameter.name}\`: ${verdict.reason}`
+	};
+}
+/**
+* Whether every declared parameter of a method can be built from a JSON
+* request body or query string.
+*
+* A method with NO manifest parameter metadata is wire-able: that is the
+* legacy options-bag contract every transport already supports, and absent
+* metadata is not evidence of a hostile signature.
+*/
+function classifyMethodWireability(method, options = {}) {
+	for (const parameter of method.parameters ?? []) {
+		const verdict = classifyParameterWireability(parameter, options);
+		if (!verdict.wireable) return verdict;
+	}
+	return WIREABLE;
+}
+var EXPOSED = { exposed: true };
+/**
+* The single decision every generated-API consumer asks: is this method
+* reachable as a custom REST action, and if not, why?
+*
+* ONE resolver, four consumers — both SvelteKit route emitters
+* (`generateRoutesForObject`, `generateCollectionRoutesForObject`), the
+* cli↔api coherence resolver (`resolveApiActionSet`), and the knowledge
+* artifact's API projection. They previously each re-derived a subset: the
+* emitters filtered on `shouldIncludeInApi` plus their own receiver skip,
+* `resolveApiActionSet` mirrored both, and `knowledge.ts` mirrored the
+* receiver half a third time. A gate added to only one of them would report a
+* method as unavailable while still writing its route file, which is the exact
+* incoherence this issue exists to close (#2686).
+*
+* Order matters, and is the tested precedence contract:
+*
+* 1. `api: false` — the class has no REST surface at all.
+* 2. A CRUD verb — the generated operation already owns the name (#2646).
+* 3. Non-public — never a surface.
+* 4. A framework lifecycle method (`save`, `initialize`, `toJSON`, ...) — the
+*    mechanism behind generated CRUD, not a distinct operation, even when a
+*    subclass declares its own override. `CLIGenerator` and `MCPGenerator`
+*    already gate on this; REST did not, and this is where it joins them
+*    (#2638, #2657).
+* 5. `api.exclude` — an explicit withdrawal.
+* 6. `api.include` — an explicit allowlist boundary.
+* 7. `@method({ expose: false })` — an explicit withdrawal that outranks every
+*    remaining rule, including a legacy `api.routes` entry for the same
+*    method. This is why the decorator is `@method()` and not `@action()`:
+*    declaring something an action in order to say it is not one contradicts
+*    itself.
+* 8. Explicit legacy exposure — a name listed in `api.include` or carrying an
+*    `api.routes` entry is a DECLARATION that this method is a route, made
+*    before the heuristic existed. It bypasses the heuristic. This is the
+*    documented compatibility exception that makes "nothing breaks" true for
+*    the 42 existing route entries; without it, migrating a class to the new
+*    gate could silently drop a route its author had spelled out.
+* 9. `@method({ expose: true })` — bypasses the heuristic, and NOTHING else.
+*    It cannot manufacture a receiver (step 10 still applies), reach a
+*    non-public method, or hydrate a parameter the transport cannot build.
+* 10. Wire-ability — every parameter must be constructible from JSON.
+* 11. Receiver — a collection class emits only collection-scoped routes, and a
+*     model class cannot host a collection-scoped instance method.
+*/
+function resolveApiMethodExposure(options) {
+	const { actionName, method, apiConfig, isCollectionClass = false } = options;
+	if (apiConfig === false) return {
+		exposed: false,
+		code: "api-disabled",
+		reason: "api is disabled"
+	};
+	if (isCrudOperation(actionName)) return {
+		exposed: false,
+		code: "crud-reserved",
+		reason: `\`${actionName}\` is reserved by the generated CRUD operation of the same name`
+	};
+	if (method.isPublic === false) return {
+		exposed: false,
+		code: "not-public",
+		reason: "not a public method"
+	};
+	if (isFrameworkLifecycleMethod(actionName)) return {
+		exposed: false,
+		code: "lifecycle-method",
+		reason: `\`${actionName}\` is a framework lifecycle method, not a distinct operation`
+	};
+	const config = getIncludeExclude(apiConfig);
+	if (config.exclude?.includes(actionName)) return {
+		exposed: false,
+		code: "excluded",
+		reason: "listed in api.exclude"
+	};
+	const includedExplicitly = config.include?.includes(actionName) === true;
+	if (config.include !== void 0 && !includedExplicitly) return {
+		exposed: false,
+		code: "not-included",
+		reason: "not listed in api.include"
+	};
+	const declared = readMethodDecoratorConfig(method);
+	if (declared?.expose === false) return {
+		exposed: false,
+		code: "withheld",
+		reason: declared.reason ?? "withheld by @method({ expose: false })"
+	};
+	const hasLegacyRoute = readApiRouteConfig(apiConfig, actionName) !== void 0;
+	if (!(declared?.expose === true || includedExplicitly || hasLegacyRoute)) {
+		const wireability = classifyMethodWireability(method, { ...options.isModelClassName ? { isModelClassName: options.isModelClassName } : {} });
+		if (!wireability.wireable) return {
+			exposed: false,
+			code: "not-wireable",
+			reason: `not routed: ${wireability.reason}`
+		};
+	}
+	const receiver = resolveActionReceiver(actionName, method, apiConfig, isCollectionClass);
+	if (!receiver.hosted) return {
+		exposed: false,
+		code: "no-receiver",
+		reason: receiver.reason
+	};
+	return EXPOSED;
+}
+/**
+* Whether the resolved scope has an executable receiver on this host, matching
+* both route emitters' own skips exactly.
+*
+* UNREACHABLE BY CONSTRUCTION, and deliberately kept:
+* {@link resolveCustomActionMetadata} already collapses a contradicting
+* declared scope back to the receiver-derived one, so the resolved scope always
+* equals `defaultScope` and neither branch below can fire. That was equally
+* true of the two `console.warn` skips in `generateRoutesForObject` /
+* `generateCollectionRoutesForObject` that this replaced — moving them here
+* changed nothing about when they fire, and dropping them would remove the only
+* structural guard should that collapse ever be relaxed.
+*
+* The signal a developer actually sees for a contradicting declaration is
+* {@link resolveDeclaredScopeMismatch}, reported by the emitters at build time.
+*/
+function resolveActionReceiver(actionName, method, apiConfig, isCollectionClass) {
+	const defaultScope = isCollectionClass ? "collection" : method.isStatic ? "collection" : "item";
+	let scope;
+	try {
+		scope = resolveCustomActionMetadata({
+			actionName,
+			method: {
+				...method.isStatic !== void 0 ? { isStatic: method.isStatic } : {},
+				...method.decoratorConfig ? { decoratorConfig: method.decoratorConfig } : {}
+			},
+			apiConfig,
+			defaultScope
+		}).scope;
+	} catch {
+		scope = defaultScope;
+	}
+	if (isCollectionClass) {
+		if (scope !== "collection") return {
+			hosted: false,
+			reason: "collection class methods only support collection-scoped API routes"
+		};
+		return { hosted: true };
+	}
+	if (scope === "collection" && method.isStatic !== true) return {
+		hosted: false,
+		reason: "collection API routes require a static method"
+	};
+	return { hosted: true };
+}
+function resolveEffectiveActionMetadata(options) {
+	const route = readApiRouteConfig(options.apiConfig, options.actionName);
+	const declared = readMethodDecoratorConfig(options.method);
+	const legacyDescription = readAiDescription(options.aiConfig, options.actionName);
+	const httpMethod = declared?.httpMethod ?? normalizeRouteHttpMethod(route?.method);
+	const path = declared?.path ?? (typeof route?.path === "string" ? route.path : void 0);
+	const scope = declared?.scope ?? normalizeRouteScope(route?.scope);
+	const effect = declared?.effect ?? normalizeRouteEffect(route?.effect);
+	const idempotent = declared?.idempotent ?? (typeof route?.idempotent === "boolean" ? route.idempotent : void 0);
+	const openWorld = declared?.openWorld ?? (typeof route?.openWorld === "boolean" ? route.openWorld : void 0);
+	const description = declared?.description ?? legacyDescription;
+	return {
+		...httpMethod ? { httpMethod } : {},
+		...path !== void 0 ? { path } : {},
+		...scope ? { scope } : {},
+		...effect ? { effect } : {},
+		...idempotent !== void 0 ? { idempotent } : {},
+		...openWorld !== void 0 ? { openWorld } : {},
+		...description !== void 0 ? { description } : {}
+	};
+}
+function normalizeRouteHttpMethod(value) {
+	return isApiHttpMethod(value) ? value : void 0;
+}
+function normalizeRouteScope(value) {
+	return value === "item" || value === "collection" ? value : void 0;
+}
+function normalizeRouteEffect(value) {
+	return value === "read" || value === "write" || value === "destructive" ? value : void 0;
+}
+function readAiDescription(aiConfig, actionName) {
+	if (!isRecord(aiConfig) || !isRecord(aiConfig.descriptions)) return void 0;
+	const description = aiConfig.descriptions[actionName];
+	return typeof description === "string" ? description : void 0;
+}
+function readApiRouteConfig(apiConfig, actionName) {
+	if (!isRecord(apiConfig) || !isRecord(apiConfig.routes)) return void 0;
+	const route = apiConfig.routes[actionName];
+	return isRecord(route) ? route : void 0;
+}
+/**
+* Narrow a scanned transport config's `include`/`exclude`.
+*
+* A non-array value is treated as unset rather than throwing later on
+* `.includes()` — the same defensive stance every other reader of scanned
+* decorator config takes, because this data came from an AST, not a compiler.
+*/
+function getIncludeExclude(config) {
+	if (config === true || config === void 0 || !isRecord(config)) return {};
+	return {
+		...Array.isArray(config.include) ? { include: config.include } : {},
+		...Array.isArray(config.exclude) ? { exclude: config.exclude } : {}
+	};
+}
+/**
+* Whether a method's `@method()` declaration is also a RUNTIME REST route
+* declaration, the way an `api.routes[m]` entry is.
+*
+* The runtime `APIGenerator` transport is deliberately declaration-gated: it
+* serves a custom collection action only where one was declared, because its URL
+* shape supports a single segment and an undeclared public method has never had
+* a route there. `dispatchCustomCollectionAction` and the `isRestActionRoutable`
+* preflight prediction must agree on that gate exactly, so both read this (#2686).
+*
+* True for any option that migrates from `ApiCustomRouteConfig` — its complete
+* field set is `scope`, `method`, `path`, `effect`, `idempotent`, `openWorld` —
+* because a legacy `routes: { m: { effect: 'write' } }` entry with no path or
+* verb already dispatches at `POST /<collection>/m`, and migrating it onto the
+* method must not silently delete that endpoint. Also true for an explicit
+* `expose: true`, which is a stronger statement that the method is an action
+* than an empty route entry is.
+*
+* FALSE for a bare `@method()` and for a `description`-only one. Neither
+* migrates from a route entry — `description` migrates from `ai.descriptions`,
+* and a bare decorator is a review marker — so counting them would hand the
+* runtime transport endpoints it never served.
+*/
+function declaresRuntimeRestRoute(method) {
+	if (readMethodDecoratorConfig(method)?.expose === false) return false;
+	return declaresRuntimeRestRouteShape(method);
+}
+/**
+* Whether the author WROTE a runtime REST route declaration on this method,
+* ignoring whether they then withheld it.
+*
+* Deliberately distinct from {@link declaresRuntimeRestRoute}: the dispatcher
+* must still SEE a withheld declaration in order to refuse it explicitly. This
+* router resolves `POST /<collection>/<segment>` to `create` when nothing
+* claims the segment, so dropping a withheld action from the candidate set
+* would turn a request aimed at an explicitly withheld operation into a silent
+* row insert. The candidate set reads this; the preflight PREDICTION reads
+* {@link declaresRuntimeRestRoute}, which adds the `expose: false` veto —
+* "there is a declaration here" and "it is reachable" are different questions.
+*/
+function declaresRuntimeRestRouteShape(method) {
+	const declared = readMethodDecoratorConfig(method);
+	if (!declared) return false;
+	return declared.httpMethod !== void 0 || declared.path !== void 0 || declared.scope !== void 0 || declared.effect !== void 0 || declared.idempotent !== void 0 || declared.openWorld !== void 0 || declared.expose !== void 0;
+}
+/**
+* Coerce one transport-supplied argument into the runtime value the declared
+* parameter type needs.
+*
+* Today that means exactly one conversion: a `Date` parameter, which the
+* wire-ability heuristic accepts as JSON-shaped. JSON has no date type, so a
+* caller can only send an ISO string (or an epoch number) and the receiving
+* method — which calls `getTime()`, or hands the value to a query builder that
+* expects a `Date` — would otherwise get a string. Accepting `Date` as
+* wire-able and NOT hydrating it here would generate a route that 500s, so the
+* two are one decision (#2686).
+*
+* Deliberately narrow:
+* - Only a TOP-LEVEL declared parameter is converted. A `Date` nested inside a
+*   named options bag is invisible to the manifest (the bag is accepted
+*   heuristically, its members unresolved), so it is not hydrated and the
+*   method must accept the string itself.
+* - An already-`Date` value, and anything that is not a string or finite
+*   number, passes through untouched, so a runtime caller invoking the same
+*   helper is never degraded.
+* - An unparseable string passes through as-is rather than becoming an
+*   `Invalid Date`, leaving the method's own validation in charge of the error
+*   message.
+*/
+function coerceCustomActionArgument(value, declaredType) {
+	if (!declaredType || !declaredTypeAcceptsDate(declaredType)) return value;
+	return toCustomActionDate(value);
+}
+/**
+* The `Date` half of {@link coerceCustomActionArgument}, exported on its own
+* because generated SvelteKit route code calls it directly: the generator
+* already knows at build time which parameters are `Date`-typed, so the
+* emitted handler names the conversion rather than re-deriving it from a type
+* string at runtime. Both paths share this one implementation so the two
+* transports cannot drift.
+*/
+function toCustomActionDate(value) {
+	if (value instanceof Date) return value;
+	if (typeof value === "number" && Number.isFinite(value)) return new Date(value);
+	if (typeof value !== "string" || value.trim() === "") return value;
+	const parsed = new Date(value);
+	return Number.isNaN(parsed.getTime()) ? value : parsed;
+}
+/**
+* Decode a `number`-typed action argument that arrived over a QUERY STRING.
+*
+* A GET handler builds its options from `URLSearchParams`, so every value is a
+* string: `limit: number` reached the method as `'2'` and any arithmetic on it
+* silently produced string concatenation or `NaN` (#2686). A JSON body needs no
+* such repair, which is why this is emitted only on GET routes.
+*
+* Leaves anything it cannot decode alone, so a malformed value reaches the
+* method's own validation rather than becoming a silent `NaN`.
+*/
+function toCustomActionNumber(value) {
+	if (typeof value === "number") return value;
+	if (typeof value !== "string" || value.trim() === "") return value;
+	const parsed = Number(value);
+	return Number.isFinite(parsed) ? parsed : value;
+}
+/**
+* The `boolean` counterpart to {@link toCustomActionNumber}. A query string
+* carries `?active=false`, and the bare string `'false'` is TRUTHY — the most
+* dangerous of these coercions, since it inverts a guard rather than degrading
+* it. Only the four canonical spellings decode; anything else is left for the
+* method's own validation.
+*/
+function toCustomActionBoolean(value) {
+	if (typeof value === "boolean") return value;
+	if (typeof value !== "string") return value;
+	const normalized = value.trim().toLowerCase();
+	if (normalized === "true" || normalized === "1") return true;
+	if (normalized === "false" || normalized === "0") return false;
+	return value;
+}
+/**
+* The query-string decoder a GET route should apply to one parameter, or
+* `undefined` when the value passes through untouched.
+*
+* Mirrors {@link declaredTypeAcceptsDate}: a nullish branch does not change the
+* representation, but a genuine alternative (`number | string`) means the
+* method already accepts what the query string sends, so nothing is decoded.
+*/
+function queryStringDecoderFor(declaredType) {
+	if (!declaredType) return void 0;
+	if (declaredTypeAcceptsDate(declaredType)) return "toCustomActionDate";
+	const branches = splitTopLevel(declaredType, "|").map((branch) => branch.trim()).filter((branch) => branch !== "null" && branch !== "undefined");
+	if (branches.length === 0) return void 0;
+	if (branches.every((branch) => branch === "number")) return "toCustomActionNumber";
+	if (branches.every((branch) => branch === "boolean")) return "toCustomActionBoolean";
+}
+/**
+* True when the declared type is a `Date` and nothing else.
+*
+* `Date | null` and `Date | undefined` qualify — a nullish branch is not an
+* alternative representation. `Date | string` deliberately does NOT: that
+* signature already accepts the string a JSON caller sends, so the method's
+* own handling is authoritative and converting behind its back would change
+* which branch it takes.
+*/
+function declaredTypeAcceptsDate(declaredType) {
+	const branches = declaredType.split("|").map((branch) => branch.trim()).filter((branch) => branch !== "null" && branch !== "undefined");
+	return branches.length > 0 && branches.every((branch) => branch === "Date");
+}
 //#endregion
-export { CRUD_OPERATIONS, FRAMEWORK_LIFECYCLE_METHOD_NAMES, SMRT_CUSTOM_ACTION_ERROR_METADATA_KEY, buildCustomActionInputSchema, buildCustomActionInvocationArgs, customActionParameterInputName, isCrudOperation, isCrudToolAction, isFrameworkLifecycleMethod, normalizeCustomActionFailure, resolveCustomActionMetadata, resolveCustomActionNames };
+export { CRUD_OPERATIONS, FRAMEWORK_LIFECYCLE_METHOD_NAMES, SMRT_CUSTOM_ACTION_ERROR_METADATA_KEY, buildCustomActionInputSchema, buildCustomActionInvocationArgs, classifyMethodWireability, classifyParameterWireability, coerceCustomActionArgument, createClassNamePredicate, createManifestClassNamePredicate, customActionParameterInputName, declaredTypeAcceptsDate, declaresRuntimeRestRoute, declaresRuntimeRestRouteShape, isCrudOperation, isCrudToolAction, isFrameworkLifecycleMethod, normalizeCustomActionFailure, queryStringDecoderFor, readMethodDecoratorConfig, resolveApiMethodExposure, resolveCustomActionMetadata, resolveCustomActionNames, resolveDeclaredScopeMismatch, resolveEffectiveActionMetadata, toCustomActionBoolean, toCustomActionDate, toCustomActionNumber };
 
 //# sourceMappingURL=custom-action.js.map