@atscript/moost-wf 0.1.69 → 0.1.71

package/README.md

@@ -6,18 +6,23 @@
 
 # @atscript/moost-wf
 
-📚 **Documentation:** [ui.atscript.dev](https://ui.atscript.dev)
+Documentation: [ui.atscript.dev](https://ui.atscript.dev)
 
-Server-side workflow integration for [Moost](https://github.com/moostjs/moost) — decorators, interceptors, and serialization that pair with [`@atscript/vue-wf`](../vue-wf) to drive multi-step forms from atscript-annotated `.as` types.
+Server-side workflow integration for [Moost](https://github.com/moostjs/moost) — decorators, composables, and serialization that pair with [`@atscript/vue-wf`](../vue-wf) to drive multi-step forms from atscript-annotated `.as` types.
 
 Part of the [atscript-ui](https://github.com/moostjs/atscript-ui) monorepo.
 
 ## What it provides
 
-- Workflow decorators that wrap Moost handlers and expose them as `@atscript/vue-wf`-compatible endpoints
-- Interceptors that serialize / deserialize workflow state across HTTP requests
-- `@AsWfState` storage abstraction with a default `@atscript/db`-backed implementation
-- Unified `WfFinished` envelope + helpers (`finishWf(opts)`, `abortWf(reason, opts)`) for terminal-screen UX. See [Finish Screens](https://ui.atscript.dev/workflows/finish-screens).
+- `useAtscriptWf(Type)` composable — schema-aware `resolveInput()` / `resolveAction()` / `requireInput()` for step handlers.
+- `@WfInput()` / `@WfAction()` parameter decorators — sugar over `useAtscriptWf()` with the full action-vs-input policy matrix.
+- `useWfActionSlot()` for low-level action context access (transport adapters writing the action; raw read+clear flows). Step handlers should prefer `useAtscriptWf(Type).resolveAction()`.
+- Schema helpers: `serializeFormSchema`, `extractPassContext`, `getFormActions`.
+- HTTP outlet integration: `createAsHttpOutlet`, `handleAsOutletRequest`.
+- Finish-screen envelope helpers: `finishWf`, `abortWf`, `isWfFinished`, and the `WfFinished` / `WfNext` / `WfMessage` / `WfButton` / `WfActionRequest` types rendered by `<AsWfFinish>`. See [Finish Screens](https://ui.atscript.dev/workflows/finish-screens).
+- Opt-in persistent state store `AsWfStore` (subpath `/store`) backed by `@atscript/db`.
+
+The workflow engine catches `StepRetriableError` (thrown by `requireInput()`) natively — no global interceptor wiring required.
 
 ## Install
 
@@ -25,17 +30,17 @@ Part of the [atscript-ui](https://github.com/moostjs/atscript-ui) monorepo.
 pnpm add @atscript/moost-wf
 ```
 
-Peer requirements: `moost`, `@moostjs/event-wf`, `@atscript/core`, `@atscript/typescript`.
+Peer requirements: `moost`, `@moostjs/event-wf`, `@wooksjs/event-core`, `@wooksjs/event-wf`, `@atscript/core`, `@atscript/typescript`.
 
 ## Entry points
 
 | Subpath                       | What it exports                                                                    |
 | ----------------------------- | ---------------------------------------------------------------------------------- |
-| `@atscript/moost-wf`          | Workflow decorators, interceptors, runtime                                         |
-| `@atscript/moost-wf/plugin`   | atscript build-time plugin                                                         |
-| `@atscript/moost-wf/store`    | Generated runtime for `AsWfStateRecord`                                            |
+| `@atscript/moost-wf`          | Workflow decorators, composables, outlet helpers, finish-screen envelope helpers   |
+| `@atscript/moost-wf/plugin`   | atscript build-time plugin (registers `@wf.*` annotations)                         |
+| `@atscript/moost-wf/store`    | `AsWfStore` runtime + `AsWfStateRecord` model                                      |
 | `@atscript/moost-wf/store.as` | Raw `.as` source for the workflow-state record — re-import if you customize fields |
 
 ## License
 
-MIT © Artem Maltsev
+MIT &copy; Artem Maltsev

package/dist/index.d.mts

@@ -1,101 +1,8 @@
+import { InferDataType, TAtscriptAnnotatedType, TAtscriptTypeDef } from "@atscript/typescript/utils";
 import { WfOutlet, WfOutletTriggerConfig, WfOutletTriggerDeps } from "@moostjs/event-wf";
-import { TInterceptorDef } from "moost";
-import { TAtscriptAnnotatedType } from "@atscript/typescript/utils";
+import { StepRetriableError } from "@wooksjs/event-wf";
 
-//#region src/form-input/required.d.ts
-/**
- * Thrown by @FormInput() to signal that the workflow should pause
- * and request form input from the client.
- *
- * Caught by {@link formInputInterceptor} and converted to an
- * `inputRequired` outlet response.
- */
-declare class FormInputRequired {
-  readonly schema: unknown;
-  readonly errors?: Record<string, string> | undefined;
-  readonly context?: Record<string, unknown> | undefined;
-  constructor(schema: unknown, errors?: Record<string, string> | undefined, context?: Record<string, unknown> | undefined);
-}
-//#endregion
-//#region src/form-input/use.d.ts
-/**
- * Composable that provides access to form data and the `requireInput()` helper
- * inside workflow step handlers.
- *
- * Called by the `@FormInput()` Resolve callback. Can also be used standalone
- * when you need to manually re-pause with errors:
- *
- * ```ts
- * const { requireInput } = useFormInput()
- * throw requireInput({ password: 'Invalid credentials' })
- * ```
- */
-declare function useFormInput(type?: TAtscriptAnnotatedType): {
-  data: <T = unknown>() => T | undefined;
-  requireInput: (errors?: Record<string, string>) => FormInputRequired;
-};
-//#endregion
-//#region src/form-input/decorator.d.ts
-/**
- * Parameter decorator for workflow steps that need form input.
- *
- * Combines parameter injection (via Resolve) with a method interceptor
- * (via Intercept) that validates input before the step handler executes.
- *
- * The injected value is `{ data(), requireInput(errors?) }`.
- *
- * @example
- * ```ts
- * @Step('login')
- * async login(@FormInput() form: TFormInput<LoginForm>) {
- *   const input = form.data()
- *   try {
- *     await this.auth.login(input.username, input.password)
- *   } catch (e) {
- *     throw form.requireInput({ password: 'Invalid credentials' })
- *   }
- * }
- * ```
- */
-declare function FormInput(): ParameterDecorator;
-type TFormInput<_T = unknown> = ReturnType<typeof useFormInput>;
-//#endregion
-//#region src/form-input/alt-action.decorator.d.ts
-/**
- * Parameter decorator that resolves the action name from the current
- * workflow event context. Returns `undefined` for normal form submits.
- *
- * @example
- * ```ts
- * @Step('mfa-verify')
- * async mfaVerify(
- *   @FormInput() form: TFormInput<PincodeForm>,
- *   @AltAction() action: string | undefined,
- * ) {
- *   if (action === 'resend') {
- *     await this.sendOtp(ctx.email)
- *     return
- *   }
- *   await this.verifyCode(form.data().code)
- * }
- * ```
- */
-declare const AltAction: () => ParameterDecorator & PropertyDecorator;
-//#endregion
-//#region src/form-input/interceptor.d.ts
-/**
- * Global interceptor that catches {@link FormInputRequired} signals
- * thrown by step handlers (via `form.requireInput()`) and converts them
- * to `inputRequired` outlet responses.
- *
- * Apply globally:
- * ```ts
- * app.applyGlobalInterceptors(formInputInterceptor())
- * ```
- */
-declare function formInputInterceptor(): TInterceptorDef;
-//#endregion
-//#region src/form-input/serialize.d.ts
+//#region src/wf-io/serialize.d.ts
 /**
  * Serialize an atscript annotated type to a JSON-transportable form schema.
  *
@@ -112,7 +19,7 @@ declare function formInputInterceptor(): TInterceptorDef;
  */
 declare function serializeFormSchema(type: TAtscriptAnnotatedType): unknown;
 //#endregion
-//#region src/form-input/context.d.ts
+//#region src/wf-io/context.d.ts
 interface TFormActions {
   actions: string[];
   actionsWithData: string[];
@@ -128,26 +35,89 @@ declare function extractPassContext(type: TAtscriptAnnotatedType, wfContext: Rec
  */
 declare function getFormActions(type: TAtscriptAnnotatedType): TFormActions;
 //#endregion
-//#region src/form-input/use-wf-action.d.ts
+//#region src/wf-io/use-atscript-wf.d.ts
+/**
+ * Schema-driven workflow I/O primitives for atscript types. Returned helpers
+ * are pure and independent — composable consumers can interleave their own
+ * logic between checking the action and validating the input.
+ *
+ * - `resolveInput(opts?)` validates the current step input against the type
+ *   schema and returns it typed; throws `StepRetriableError` when input is
+ *   missing or invalid. Does NOT look at the wf action.
+ * - `resolveAction()` returns the current wf action name (or `undefined`),
+ *   throwing `StepRetriableError` when the action is unknown to the schema.
+ *   Does NOT look at the wf input.
+ * - `requireInput(opts?)` builds the `StepRetriableError` carrying the form
+ *   schema + whitelisted context. Exposed so callers (composables, the
+ *   `@WfInput` decorator) can throw their own custom failures.
+ *
+ * Validator instances are cached per `(type, opts)` pair.
+ */
+declare function useAtscriptWf<T extends TAtscriptTypeDef>(type: TAtscriptAnnotatedType<T>): {
+  resolveInput(opts?: {
+    partial?: "deep";
+  }): InferDataType<T>;
+  resolveAction(): string | undefined;
+  requireInput(opts?: {
+    errors?: Record<string, string>;
+    formMessage?: string;
+  }): StepRetriableError<{
+    outlet: "http";
+    payload: unknown;
+    context: Record<string, unknown>;
+  }>;
+};
+//#endregion
+//#region src/wf-io/wf-input.decorator.d.ts
 /**
- * Composable that reads and writes the workflow action from the event context.
+ * Parameter decorator that resolves to the validated typed input for the
+ * current workflow step. Owns the action-vs-input policy matrix on top of
+ * the pure `useAtscriptWf` primitives.
  *
- * **In the HTTP trigger** (to set the action from the request body):
+ * Policy:
+ * - No action fired → strict full validation.
+ * - With-data action → input required, partial-deep validation.
+ * - No-data action → input must be absent; returns `undefined` only when
+ *   `pass: true` opts the step into ignoring the no-data action.
+ * - Unknown action → `StepRetriableError` (propagated from `resolveAction`).
+ *
+ * @example
  * ```ts
- * const { setAction } = useWfAction()
- * setAction(body.action)
+ * @Step('login')
+ * async login(@WfInput() input: LoginForm) {
+ *   await this.auth.login(input.username, input.password)
+ * }
  * ```
+ */
+declare function WfInput(opts?: {
+  pass?: boolean;
+}): ParameterDecorator;
+//#endregion
+//#region src/wf-io/wf-action.decorator.d.ts
+/**
+ * Parameter decorator — sugar for `useAtscriptWf(Type).resolveAction()`.
+ *
+ * Resolves to the current workflow action name from the input envelope, or
+ * `undefined` when no action was submitted.
  *
- * **In step handlers** (to read the action — prefer `@AltAction()` decorator):
+ * The form type is **required**: the decorator validates the action against
+ * the form's declared `@ui.form.action` / `@wf.action.withData` whitelist and
+ * throws `StepRetriableError` for any unknown action — the step body never
+ * sees actions that aren't part of the form's contract.
+ *
+ * @example
  * ```ts
- * const { getAction } = useWfAction()
- * const action = getAction()
+ * @Step('mfa-verify')
+ * async mfaVerify(
+ *   @WfInput() input: PincodeForm,
+ *   @WfAction(PincodeForm) action: string | undefined,
+ * ) {
+ *   if (action === 'resend') return this.sendOtp()
+ *   await this.verifyCode(input.code)
+ * }
  * ```
  */
-declare function useWfAction(): {
-  getAction: () => string | undefined;
-  setAction: (action: string | undefined) => void;
-};
+declare function WfAction<T extends TAtscriptTypeDef>(type: TAtscriptAnnotatedType<T>): ParameterDecorator;
 //#endregion
 //#region src/outlet.d.ts
 /**
@@ -188,11 +158,11 @@ interface WfMessage {
 }
 type WfNext = {
   trigger: "immediate";
-  action: WfAction;
+  action: WfActionRequest;
 } | {
   trigger: "auto";
   timeoutMs: number;
-  action: WfAction;
+  action: WfActionRequest;
   skipButton?: {
     label: string;
     behavior?: "now" | "cancel";
@@ -204,9 +174,9 @@ type WfNext = {
 };
 interface WfButton {
   label: string;
-  action: WfAction;
+  action: WfActionRequest;
 }
-type WfAction = {
+type WfActionRequest = {
   type: "redirect";
   target: string;
   reason?: string;
@@ -254,4 +224,4 @@ declare function finishWf<T = unknown>(opts?: FinishWfOpts<T>): void;
  */
 declare function abortWf(reason: string, opts?: FinishWfOpts): void;
 //#endregion
-export { AltAction, type FinishWfOpts, FormInput, FormInputRequired, type TFormInput, type WfAction, type WfButton, type WfFinished, type WfMessage, type WfNext, abortWf, createAsHttpOutlet, extractPassContext, finishWf, formInputInterceptor, getFormActions, handleAsOutletRequest, isWfFinished, serializeFormSchema, useFormInput, useWfAction };
+export { type FinishWfOpts, WfAction, type WfActionRequest, type WfButton, type WfFinished, WfInput, type WfMessage, type WfNext, abortWf, createAsHttpOutlet, extractPassContext, finishWf, getFormActions, handleAsOutletRequest, isWfFinished, serializeFormSchema, useAtscriptWf };

package/dist/index.mjs

@@ -1,9 +1,8 @@
-import { createHttpOutlet, handleWfOutletRequest, useWfState } from "@moostjs/event-wf";
-import { Intercept, Resolve, TInterceptorPriority, useControllerContext } from "moost";
 import { isAnnotatedType, serializeAnnotatedType } from "@atscript/typescript/utils";
-import { current, key } from "@wooksjs/event-core";
-import { useWfFinished } from "@wooksjs/event-wf";
-//#region src/form-input/context.ts
+import { createHttpOutlet, handleWfOutletRequest, useWfState } from "@moostjs/event-wf";
+import { StepRetriableError, useWfFinished } from "@wooksjs/event-wf";
+import { Optional, Resolve } from "moost";
+//#region src/wf-io/context.ts
 const WF_CONTEXT_PASS = "wf.context.pass";
 const UI_FORM_ACTION = "ui.form.action";
 const WF_ACTION_WITH_DATA = "wf.action.withData";
@@ -57,7 +56,7 @@ function getFormActions(type) {
 	return result;
 }
 //#endregion
-//#region src/form-input/serialize.ts
+//#region src/wf-io/serialize.ts
 const schemaCache = /* @__PURE__ */ new WeakMap();
 /**
 * Serialize an atscript annotated type to a JSON-transportable form schema.
@@ -84,247 +83,165 @@ function serializeFormSchema(type) {
 	return schema;
 }
 //#endregion
-//#region src/form-input/required.ts
+//#region src/wf-io/validator-cache.ts
+const cache = /* @__PURE__ */ new WeakMap();
 /**
-* Thrown by @FormInput() to signal that the workflow should pause
-* and request form input from the client.
-*
-* Caught by {@link formInputInterceptor} and converted to an
-* `inputRequired` outlet response.
+* Memoize `type.validator(opts)` by `(type, opts)`. Outer WeakMap keyed by the
+* atscript type identity; inner Map keyed by the two opts we care about
+* (`partial`, `unknownProps`). Returns the same validator instance for the
+* same `(type, opts)` pair.
 */
-var FormInputRequired = class {
-	constructor(schema, errors, context) {
-		this.schema = schema;
-		this.errors = errors;
-		this.context = context;
+function getCachedValidator(type, opts) {
+	const key = `${String(opts?.partial ?? "-")}|${String(opts?.unknownProps ?? "-")}`;
+	let perType = cache.get(type);
+	if (!perType) {
+		perType = /* @__PURE__ */ new Map();
+		cache.set(type, perType);
 	}
-};
+	let validator = perType.get(key);
+	if (!validator) {
+		validator = type.validator(opts);
+		perType.set(key, validator);
+	}
+	return validator;
+}
 //#endregion
-//#region src/form-input/use.ts
-/**
-* Composable that provides access to form data and the `requireInput()` helper
-* inside workflow step handlers.
-*
-* Called by the `@FormInput()` Resolve callback. Can also be used standalone
-* when you need to manually re-pause with errors:
-*
-* ```ts
-* const { requireInput } = useFormInput()
-* throw requireInput({ password: 'Invalid credentials' })
-* ```
-*/
-function useFormInput(type) {
+//#region src/wf-io/use-atscript-wf.ts
+function flattenValidatorErrors(err) {
+	const out = {};
+	for (const e of err.errors) out[e.path] = e.message;
+	return out;
+}
+function isValidatorError(err) {
+	return err !== null && typeof err === "object" && "errors" in err && Array.isArray(err.errors);
+}
+function useAtscriptWf(type) {
 	const wfState = useWfState();
-	/**
-	* Returns the current form input data from the workflow event.
-	*/
-	function data() {
-		return wfState.input();
+	function requireInput({ errors, formMessage } = {}) {
+		const passContext = extractPassContext(type, wfState.ctx() ?? {});
+		const mergedErrors = errors ? { ...errors } : formMessage ? {} : void 0;
+		if (formMessage && mergedErrors) mergedErrors.__form = formMessage;
+		const context = mergedErrors ? {
+			...passContext,
+			errors: mergedErrors
+		} : { ...passContext };
+		return new StepRetriableError(new Error(formMessage ?? "Input required"), void 0, {
+			outlet: "http",
+			payload: serializeFormSchema(type),
+			context
+		});
+	}
+	function validateOrThrow(input, opts) {
+		const validator = getCachedValidator(type, opts);
+		try {
+			validator.validate(input);
+		} catch (err) {
+			if (isValidatorError(err)) throw requireInput({ errors: flattenValidatorErrors(err) });
+			throw err;
+		}
 	}
-	/**
-	* Creates a FormInputRequired signal that re-pauses the workflow
-	* with the serialized form schema, whitelisted context, and optional errors.
-	*
-	* Usage: `throw requireInput({ fieldName: 'Error message' })`
-	*/
-	function requireInput(errors) {
-		if (!type || !isAnnotatedType(type)) throw new Error("useFormInput(): no atscript type available. Ensure @FormInput() is applied on the same method parameter.");
-		const wfContext = wfState.ctx();
-		return new FormInputRequired(serializeFormSchema(type), errors, extractPassContext(type, wfContext));
+	function resolveInput(opts) {
+		const input = wfState.input()?.formData;
+		if (input === void 0) throw requireInput();
+		validateOrThrow(input, opts?.partial === "deep" ? {
+			partial: "deep",
+			unknownProps: "strip"
+		} : { unknownProps: "strip" });
+		return input;
+	}
+	function resolveAction() {
+		const action = wfState.input()?.action;
+		if (action === void 0) return void 0;
+		const { actions, actionsWithData } = getFormActions(type);
+		if (!actions.includes(action) && !actionsWithData.includes(action)) throw requireInput({ formMessage: `Action "${action}" is not supported` });
+		return action;
 	}
 	return {
-		data,
+		resolveInput,
+		resolveAction,
 		requireInput
 	};
 }
 //#endregion
-//#region src/form-input/wf-keys.ts
-/**
-* Event context key for the workflow action name.
-*
-* The HTTP trigger should set this before calling `wf.resume()`:
-* ```ts
-* import { current } from '@wooksjs/event-core'
-* import { actionKey } from '@atscript/moost-wf'
-* current().set(actionKey, body.action)
-* ```
-*
-* `@AltAction()` and `@FormInput()` read from this key.
-*/
-const actionKey = key("wf.action");
-//#endregion
-//#region src/form-input/use-wf-action.ts
-/**
-* Composable that reads and writes the workflow action from the event context.
-*
-* **In the HTTP trigger** (to set the action from the request body):
-* ```ts
-* const { setAction } = useWfAction()
-* setAction(body.action)
-* ```
-*
-* **In step handlers** (to read the action — prefer `@AltAction()` decorator):
-* ```ts
-* const { getAction } = useWfAction()
-* const action = getAction()
-* ```
-*/
-function useWfAction() {
-	const ctx = current();
-	return {
-		getAction: () => ctx.has(actionKey) ? ctx.get(actionKey) : void 0,
-		setAction: (action) => ctx.set(actionKey, action)
-	};
-}
-//#endregion
-//#region src/form-input/decorator.ts
+//#region src/wf-io/wf-input.decorator.ts
 /**
-* Parameter decorator for workflow steps that need form input.
-*
-* Combines parameter injection (via Resolve) with a method interceptor
-* (via Intercept) that validates input before the step handler executes.
+* Parameter decorator that resolves to the validated typed input for the
+* current workflow step. Owns the action-vs-input policy matrix on top of
+* the pure `useAtscriptWf` primitives.
 *
-* The injected value is `{ data(), requireInput(errors?) }`.
+* Policy:
+* - No action fired → strict full validation.
+* - With-data action → input required, partial-deep validation.
+* - No-data action → input must be absent; returns `undefined` only when
+*   `pass: true` opts the step into ignoring the no-data action.
+* - Unknown action → `StepRetriableError` (propagated from `resolveAction`).
 *
 * @example
 * ```ts
 * @Step('login')
-* async login(@FormInput() form: TFormInput<LoginForm>) {
-*   const input = form.data()
-*   try {
-*     await this.auth.login(input.username, input.password)
-*   } catch (e) {
-*     throw form.requireInput({ password: 'Invalid credentials' })
-*   }
+* async login(@WfInput() input: LoginForm) {
+*   await this.auth.login(input.username, input.password)
 * }
 * ```
 */
-function FormInput() {
+function WfInput(opts) {
 	return (target, key, index) => {
 		if (typeof index !== "number") return;
 		Resolve((metas) => {
 			const type = metas?.targetMeta?.type;
-			return useFormInput(type);
-		}, "FormInput")(target, key, index);
-		Intercept(formInputCheckFn())(target, key, Object.getOwnPropertyDescriptor(target, key));
-	};
-}
-function formInputCheckFn() {
-	return {
-		priority: TInterceptorPriority.INTERCEPTOR,
-		async before(reply) {
-			const wfState = useWfState();
-			const input = wfState.input();
-			const action = useWfAction().getAction();
-			const { getMethodMeta } = useControllerContext();
-			const paramMetas = getMethodMeta()?.params;
-			let type;
-			if (paramMetas) {
-				for (const param of paramMetas) if (param?.targetMeta?.type && isAnnotatedType(param.targetMeta.type)) {
-					type = param.targetMeta.type;
-					break;
-				}
-			}
-			if (!type) return;
-			if (input === void 0 && !action) {
-				reply(toInputRequired(type, wfState));
-				return;
-			}
+			if (!type || !isAnnotatedType(type)) throw new Error("@WfInput(): no atscript type available on the parameter. Annotate the parameter with an atscript-derived type.");
+			const wf = useAtscriptWf(type);
+			const pass = opts?.pass === true;
+			const action = wf.resolveAction();
 			if (action) {
+				const wfInput = useWfState().input()?.formData;
 				const { actions, actionsWithData } = getFormActions(type);
-				if (actionsWithData.includes(action)) {
-					validateOrReply(type, wfState, input ?? {}, {
-						partial: "deep",
-						unknownProps: "strip"
-					}, reply);
+				const isNoData = actions.includes(action);
+				const isWithData = actionsWithData.includes(action);
+				if (isNoData) {
+					if (!pass) throw wf.requireInput({ formMessage: wfInput === void 0 ? `Action "${action}" requires no data but this step expects input` : `Action "${action}" requires no data; input not allowed here` });
+					if (wfInput !== void 0) throw wf.requireInput({ formMessage: `Action "${action}" requires no data; input not allowed here` });
 					return;
 				}
-				if (actions.includes(action)) return;
-				reply(toInputRequired(type, wfState, { __form: `Action "${action}" is not supported` }));
-				return;
+				if (isWithData) {
+					if (wfInput === void 0) throw wf.requireInput({ formMessage: `Action "${action}" expects input` });
+					return wf.resolveInput({ partial: "deep" });
+				}
 			}
-			validateOrReply(type, wfState, input, { unknownProps: "strip" }, reply);
-		}
+			return wf.resolveInput();
+		}, "WfInput")(target, key, index);
+		if (opts?.pass === true) Optional()(target, key, index);
 	};
 }
-function validateOrReply(type, wfState, input, validatorOpts, reply) {
-	const validator = type.validator(validatorOpts);
-	try {
-		validator.validate(input);
-	} catch (err) {
-		if (isValidatorError(err)) {
-			reply(toInputRequired(type, wfState, flattenErrors(err)));
-			return;
-		}
-		throw err;
-	}
-}
-function toInputRequired(type, wfState, errors) {
-	const passedContext = extractPassContext(type, wfState.ctx());
-	return { inputRequired: {
-		payload: serializeFormSchema(type),
-		transport: "http",
-		context: errors ? {
-			...passedContext,
-			errors
-		} : { ...passedContext }
-	} };
-}
-function flattenErrors(err) {
-	const errors = {};
-	for (const e of err.errors) errors[e.path] = e.message;
-	return errors;
-}
-function isValidatorError(err) {
-	return err !== null && typeof err === "object" && "errors" in err && Array.isArray(err.errors);
-}
 //#endregion
-//#region src/form-input/alt-action.decorator.ts
+//#region src/wf-io/wf-action.decorator.ts
 /**
-* Parameter decorator that resolves the action name from the current
-* workflow event context. Returns `undefined` for normal form submits.
+* Parameter decorator — sugar for `useAtscriptWf(Type).resolveAction()`.
+*
+* Resolves to the current workflow action name from the input envelope, or
+* `undefined` when no action was submitted.
+*
+* The form type is **required**: the decorator validates the action against
+* the form's declared `@ui.form.action` / `@wf.action.withData` whitelist and
+* throws `StepRetriableError` for any unknown action — the step body never
+* sees actions that aren't part of the form's contract.
 *
 * @example
 * ```ts
 * @Step('mfa-verify')
 * async mfaVerify(
-*   @FormInput() form: TFormInput<PincodeForm>,
-*   @AltAction() action: string | undefined,
+*   @WfInput() input: PincodeForm,
+*   @WfAction(PincodeForm) action: string | undefined,
 * ) {
-*   if (action === 'resend') {
-*     await this.sendOtp(ctx.email)
-*     return
-*   }
-*   await this.verifyCode(form.data().code)
+*   if (action === 'resend') return this.sendOtp()
+*   await this.verifyCode(input.code)
 * }
 * ```
 */
-const AltAction = () => Resolve(() => useWfAction().getAction(), "AltAction");
-//#endregion
-//#region src/form-input/interceptor.ts
-/**
-* Global interceptor that catches {@link FormInputRequired} signals
-* thrown by step handlers (via `form.requireInput()`) and converts them
-* to `inputRequired` outlet responses.
-*
-* Apply globally:
-* ```ts
-* app.applyGlobalInterceptors(formInputInterceptor())
-* ```
-*/
-function formInputInterceptor() {
-	return {
-		priority: TInterceptorPriority.CATCH_ERROR,
-		error(error, reply) {
-			if (error instanceof FormInputRequired) reply({ inputRequired: {
-				payload: error.schema,
-				transport: "http",
-				context: error.errors ? {
-					...error.context,
-					errors: error.errors
-				} : { ...error.context }
-			} });
-		}
+function WfAction(type) {
+	return (target, key, index) => {
+		if (typeof index !== "number") return;
+		Resolve(() => useAtscriptWf(type).resolveAction(), "WfAction")(target, key, index);
 	};
 }
 //#endregion
@@ -455,4 +372,4 @@ function abortWf(reason, opts) {
 	});
 }
 //#endregion
-export { AltAction, FormInput, FormInputRequired, abortWf, createAsHttpOutlet, extractPassContext, finishWf, formInputInterceptor, getFormActions, handleAsOutletRequest, isWfFinished, serializeFormSchema, useFormInput, useWfAction };
+export { WfAction, WfInput, abortWf, createAsHttpOutlet, extractPassContext, finishWf, getFormActions, handleAsOutletRequest, isWfFinished, serializeFormSchema, useAtscriptWf };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@atscript/moost-wf",
-  "version": "0.1.69",
+  "version": "0.1.71",
   "description": "Workflow form integration for moost — decorators, interceptors, and serialization driven by atscript type metadata",
   "keywords": [
     "atscript",
@@ -62,7 +62,7 @@
     "moost": "^0.6.14",
     "unplugin-atscript": "^0.1.58",
     "vitest": "npm:@voidzero-dev/vite-plus-test@0.1.14",
-    "@atscript/ui": "^0.1.69"
+    "@atscript/ui": "^0.1.71"
   },
   "peerDependencies": {
     "@atscript/core": "^0.1.58",