@atscript/moost-wf 0.1.68 → 0.1.70

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 (`finishWfWithData`, `finishWfWithRedirect`, `finishWfWithChoice`, …) 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[];
@@ -124,32 +31,123 @@ interface TFormActions {
 declare function extractPassContext(type: TAtscriptAnnotatedType, wfContext: Record<string, unknown>): Record<string, unknown>;
 /**
  * Read declared action names from `@ui.form.action` and `@wf.action.withData` annotations.
- * Also reads legacy `@ui.altAction` as a stateless action fallback.
  * Results are cached per type identity.
  */
 declare function getFormActions(type: TAtscriptAnnotatedType): TFormActions;
 //#endregion
-//#region src/form-input/use-wf-action.d.ts
+//#region src/wf-io/use-wf-action-slot.d.ts
 /**
- * Composable that reads and writes the workflow action from the event context.
+ * Low-level accessor for the workflow action slot in the current wf event context.
+ *
+ * Used by:
+ * - Transport adapters (HTTP / CLI / WS controllers) to **write** the action
+ *   from the incoming request (`useWfActionSlot().setAction(body.action)`).
+ * - Composable helpers that need to **read + clear** the slot atomically
+ *   (e.g. one-shot action consumption patterns).
+ *
+ * In step handlers, prefer `useAtscriptWf(Type).resolveAction()` — it reads
+ * the same slot but validates the value against the schema's
+ * `@ui.form.action` / `@wf.action.withData` declarations and throws
+ * `StepRetriableError` on unknown actions.
  *
- * **In the HTTP trigger** (to set the action from the request body):
+ * **In a transport adapter** (to set the action from the request body):
  * ```ts
- * const { setAction } = useWfAction()
+ * const { setAction } = useWfActionSlot()
  * setAction(body.action)
  * ```
  *
- * **In step handlers** (to read the action — prefer `@AltAction()` decorator):
+ * **In step handlers** (raw read — prefer `@WfAction()` / `useAtscriptWf().resolveAction()`):
  * ```ts
- * const { getAction } = useWfAction()
+ * const { getAction } = useWfActionSlot()
  * const action = getAction()
  * ```
  */
-declare function useWfAction(): {
+declare function useWfActionSlot(): {
   getAction: () => string | undefined;
   setAction: (action: string | undefined) => void;
 };
 //#endregion
+//#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
+/**
+ * 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.
+ *
+ * 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(@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 that resolves to the current workflow action name.
+ *
+ * If the parameter is annotated with an atscript type, the action is
+ * validated against the type's `@ui.form.action` / `@wf.action.withData`
+ * declarations — unknown actions throw `StepRetriableError`. When no
+ * annotated type is available the action is returned raw (or `undefined`).
+ *
+ * @example
+ * ```ts
+ * @Step('mfa-verify')
+ * async mfaVerify(
+ *   @WfInput() input: PincodeForm,
+ *   @WfAction() action: string | undefined,
+ * ) {
+ *   if (action === 'resend') return this.sendOtp()
+ *   await this.verifyCode(input.code)
+ * }
+ * ```
+ */
+declare function WfAction(): ParameterDecorator;
+//#endregion
 //#region src/outlet.d.ts
 /**
  * `createHttpOutlet` pre-configured for `<AsWfForm>` consumers.
@@ -179,7 +177,7 @@ interface WfFinished<TData = unknown> {
   finished: true;
   data?: TData;
   message?: WfMessage;
-  end?: WfFinishedEnd;
+  next?: WfNext;
   aborted?: boolean;
   reason?: string;
 }
@@ -187,27 +185,27 @@ interface WfMessage {
   level: "info" | "success" | "warn" | "error";
   text: string;
 }
-type WfFinishedEnd = {
-  mode: "immediate";
-  action: WfAction;
+type WfNext = {
+  trigger: "immediate";
+  action: WfActionRequest;
 } | {
-  mode: "auto";
+  trigger: "auto";
   timeoutMs: number;
-  action: WfAction;
+  action: WfActionRequest;
   skipButton?: {
     label: string;
     behavior?: "now" | "cancel";
   };
 } | {
-  mode: "manual";
+  trigger: "manual";
   primary?: WfButton;
   options?: WfButton[];
 };
 interface WfButton {
   label: string;
-  action: WfAction;
+  action: WfActionRequest;
 }
-type WfAction = {
+type WfActionRequest = {
   type: "redirect";
   target: string;
   reason?: string;
@@ -218,28 +216,41 @@ type WfAction = {
 };
 /** Type-guard for the unified envelope. */
 declare function isWfFinished(v: unknown): v is WfFinished;
-declare function finishWf<T>(payload: WfFinished<T>): void;
-declare function finishWfWithData<T>(data: T, message?: WfMessage): void;
-declare function finishWfWithMessage(level: WfMessage["level"], text: string): void;
-interface RedirectOpts {
-  reason?: string;
-  message?: WfMessage;
-  /** Present → `mode: 'auto'` with countdown; absent → `mode: 'immediate'`. */
-  autoMs?: number;
-  /** Only honored when `autoMs` is set — adds a "skip / cancel" button. */
-  skipLabel?: string;
-}
-declare function finishWfWithRedirect(target: string, opts?: RedirectOpts): void;
-interface ChoiceOpts {
-  data?: unknown;
+/**
+ * Options bag shared by `finishWf` and `abortWf`. Every field is optional
+ * — pick whichever envelope properties the terminal screen needs.
+ */
+interface FinishWfOpts<T = unknown> {
+  data?: T;
   message?: WfMessage;
-  primary?: WfButton;
-  options?: WfButton[];
+  next?: WfNext;
 }
-declare function finishWfWithChoice(opts: ChoiceOpts): void;
-declare function finishWfAborted(reason: string, opts?: {
-  message?: WfMessage;
-  end?: WfFinishedEnd;
-}): void;
+/**
+ * Build a `WfFinished` envelope and hand it to wooks. All envelope
+ * properties are optional; pass `data`, `message`, and/or `next`:
+ *
+ *   finishWf({ data: { id: 42 } });
+ *   finishWf({ message: { level: "success", text: "Saved." } });
+ *   finishWf({
+ *     next: {
+ *       trigger: "auto",
+ *       timeoutMs: 3000,
+ *       action: { type: "redirect", target: "/home" },
+ *     },
+ *   });
+ */
+declare function finishWf<T = unknown>(opts?: FinishWfOpts<T>): void;
+/**
+ * Build an aborted `WfFinished` envelope (`aborted: true` + `reason`) and
+ * hand it to wooks. The same options as `finishWf` are accepted — an
+ * aborted flow may still carry partial `data`, a `message`, or a `next`
+ * action that lets the user navigate away.
+ *
+ *   abortWf("user-cancelled");
+ *   abortWf("rate-limited", {
+ *     message: { level: "warn", text: "Try again later." },
+ *   });
+ */
+declare function abortWf(reason: string, opts?: FinishWfOpts): void;
 //#endregion
-export { AltAction, type ChoiceOpts, FormInput, FormInputRequired, type RedirectOpts, type TFormInput, type WfAction, type WfButton, type WfFinished, type WfFinishedEnd, type WfMessage, createAsHttpOutlet, extractPassContext, finishWf, finishWfAborted, finishWfWithChoice, finishWfWithData, finishWfWithMessage, finishWfWithRedirect, 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, useWfActionSlot };

package/dist/index.mjs

@@ -1,13 +1,12 @@
-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";
-const UI_ALT_ACTION = "ui.altAction";
 const formActionsCache = /* @__PURE__ */ new WeakMap();
 /**
 * Extract whitelisted context keys from workflow state.
@@ -22,7 +21,6 @@ function extractPassContext(type, wfContext) {
 }
 /**
 * Read declared action names from `@ui.form.action` and `@wf.action.withData` annotations.
-* Also reads legacy `@ui.altAction` as a stateless action fallback.
 * Results are cached per type identity.
 */
 function getFormActions(type) {
@@ -50,8 +48,6 @@ function getFormActions(type) {
 			actionsWithData.push(wfAction);
 			continue;
 		}
-		const altAction = fieldType.metadata.get(UI_ALT_ACTION);
-		if (altAction) actions.push(typeof altAction === "string" ? altAction : altAction.id);
 	}
 	const result = {
 		actions,
@@ -61,7 +57,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.
@@ -88,92 +84,44 @@ function serializeFormSchema(type) {
 	return schema;
 }
 //#endregion
-//#region src/form-input/required.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.
-*/
-var FormInputRequired = class {
-	constructor(schema, errors, context) {
-		this.schema = schema;
-		this.errors = errors;
-		this.context = context;
-	}
-};
-//#endregion
-//#region src/form-input/use.ts
+//#region src/wf-io/wf-keys.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:
+* Internal event context key for the workflow action name.
 *
-* ```ts
-* const { requireInput } = useFormInput()
-* throw requireInput({ password: 'Invalid credentials' })
-* ```
+* Not exported from the package barrel — HTTP triggers should call
+* `useWfActionSlot().setAction(body.action)` before `wf.resume()`, and step
+* handlers should read via `@WfAction()` or `useAtscriptWf()`.
 */
-function useFormInput(type) {
-	const wfState = useWfState();
-	/**
-	* Returns the current form input data from the workflow event.
-	*/
-	function data() {
-		return wfState.input();
-	}
-	/**
-	* 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));
-	}
-	return {
-		data,
-		requireInput
-	};
-}
+const actionKey = key("wf.action");
 //#endregion
-//#region src/form-input/wf-keys.ts
+//#region src/wf-io/use-wf-action-slot.ts
 /**
-* Event context key for the workflow action name.
+* Low-level accessor for the workflow action slot in the current wf event context.
 *
-* 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)
-* ```
+* Used by:
+* - Transport adapters (HTTP / CLI / WS controllers) to **write** the action
+*   from the incoming request (`useWfActionSlot().setAction(body.action)`).
+* - Composable helpers that need to **read + clear** the slot atomically
+*   (e.g. one-shot action consumption patterns).
 *
-* `@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 step handlers, prefer `useAtscriptWf(Type).resolveAction()` — it reads
+* the same slot but validates the value against the schema's
+* `@ui.form.action` / `@wf.action.withData` declarations and throws
+* `StepRetriableError` on unknown actions.
 *
-* **In the HTTP trigger** (to set the action from the request body):
+* **In a transport adapter** (to set the action from the request body):
 * ```ts
-* const { setAction } = useWfAction()
+* const { setAction } = useWfActionSlot()
 * setAction(body.action)
 * ```
 *
-* **In step handlers** (to read the action — prefer `@AltAction()` decorator):
+* **In step handlers** (raw read — prefer `@WfAction()` / `useAtscriptWf().resolveAction()`):
 * ```ts
-* const { getAction } = useWfAction()
+* const { getAction } = useWfActionSlot()
 * const action = getAction()
 * ```
 */
-function useWfAction() {
+function useWfActionSlot() {
 	const ctx = current();
 	return {
 		getAction: () => ctx.has(actionKey) ? ctx.get(actionKey) : void 0,
@@ -181,154 +129,167 @@ function useWfAction() {
 	};
 }
 //#endregion
-//#region src/form-input/decorator.ts
+//#region src/wf-io/validator-cache.ts
+const cache = /* @__PURE__ */ new WeakMap();
 /**
-* 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.
+* 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.
+*/
+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/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();
+	const wfAction = useWfActionSlot();
+	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;
+		}
+	}
+	function resolveInput(opts) {
+		const input = wfState.input();
+		if (input === void 0) throw requireInput();
+		validateOrThrow(input, opts?.partial === "deep" ? {
+			partial: "deep",
+			unknownProps: "strip"
+		} : { unknownProps: "strip" });
+		return input;
+	}
+	function resolveAction() {
+		const action = wfAction.getAction();
+		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 {
+		resolveInput,
+		resolveAction,
+		requireInput
+	};
+}
+//#endregion
+//#region src/wf-io/wf-input.decorator.ts
+/**
+* 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();
 				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 that resolves to the current workflow action name.
+*
+* If the parameter is annotated with an atscript type, the action is
+* validated against the type's `@ui.form.action` / `@wf.action.withData`
+* declarations — unknown actions throw `StepRetriableError`. When no
+* annotated type is available the action is returned raw (or `undefined`).
 *
 * @example
 * ```ts
 * @Step('mfa-verify')
 * async mfaVerify(
-*   @FormInput() form: TFormInput<PincodeForm>,
-*   @AltAction() action: string | undefined,
+*   @WfInput() input: PincodeForm,
+*   @WfAction() 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() {
+	return (target, key, index) => {
+		if (typeof index !== "number") return;
+		Resolve((metas) => {
+			const type = metas?.targetMeta?.type;
+			if (type && isAnnotatedType(type)) return useAtscriptWf(type).resolveAction();
+			return useWfActionSlot().getAction();
+		}, "WfAction")(target, key, index);
 	};
 }
 //#endregion
@@ -419,67 +380,44 @@ function setEnvelope(envelope) {
 		value: envelope
 	});
 }
-function finishWf(payload) {
-	setEnvelope(payload);
-}
-function finishWfWithData(data, message) {
-	finishWf({
-		finished: true,
-		data,
-		message
-	});
-}
-function finishWfWithMessage(level, text) {
-	finishWf({
-		finished: true,
-		message: {
-			level,
-			text
-		}
-	});
-}
-function finishWfWithRedirect(target, opts = {}) {
-	const action = {
-		type: "redirect",
-		target,
-		reason: opts.reason
-	};
-	const end = opts.autoMs ? {
-		mode: "auto",
-		timeoutMs: opts.autoMs,
-		action,
-		skipButton: opts.skipLabel ? { label: opts.skipLabel } : void 0
-	} : {
-		mode: "immediate",
-		action
-	};
-	finishWf({
-		finished: true,
-		message: opts.message,
-		end
-	});
-}
-function finishWfWithChoice(opts) {
-	if (!opts.primary && (!opts.options || opts.options.length === 0)) throw new Error("finishWfWithChoice() requires at least a primary button or one option.");
-	finishWf({
+/**
+* Build a `WfFinished` envelope and hand it to wooks. All envelope
+* properties are optional; pass `data`, `message`, and/or `next`:
+*
+*   finishWf({ data: { id: 42 } });
+*   finishWf({ message: { level: "success", text: "Saved." } });
+*   finishWf({
+*     next: {
+*       trigger: "auto",
+*       timeoutMs: 3000,
+*       action: { type: "redirect", target: "/home" },
+*     },
+*   });
+*/
+function finishWf(opts) {
+	setEnvelope({
 		finished: true,
-		data: opts.data,
-		message: opts.message,
-		end: {
-			mode: "manual",
-			primary: opts.primary,
-			options: opts.options
-		}
+		...opts
 	});
 }
-function finishWfAborted(reason, opts = {}) {
-	finishWf({
+/**
+* Build an aborted `WfFinished` envelope (`aborted: true` + `reason`) and
+* hand it to wooks. The same options as `finishWf` are accepted — an
+* aborted flow may still carry partial `data`, a `message`, or a `next`
+* action that lets the user navigate away.
+*
+*   abortWf("user-cancelled");
+*   abortWf("rate-limited", {
+*     message: { level: "warn", text: "Try again later." },
+*   });
+*/
+function abortWf(reason, opts) {
+	setEnvelope({
 		finished: true,
 		aborted: true,
 		reason,
-		message: opts.message,
-		end: opts.end
+		...opts
 	});
 }
 //#endregion
-export { AltAction, FormInput, FormInputRequired, createAsHttpOutlet, extractPassContext, finishWf, finishWfAborted, finishWfWithChoice, finishWfWithData, finishWfWithMessage, finishWfWithRedirect, formInputInterceptor, getFormActions, handleAsOutletRequest, isWfFinished, serializeFormSchema, useFormInput, useWfAction };
+export { WfAction, WfInput, abortWf, createAsHttpOutlet, extractPassContext, finishWf, getFormActions, handleAsOutletRequest, isWfFinished, serializeFormSchema, useAtscriptWf, useWfActionSlot };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@atscript/moost-wf",
-  "version": "0.1.68",
+  "version": "0.1.70",
   "description": "Workflow form integration for moost — decorators, interceptors, and serialization driven by atscript type metadata",
   "keywords": [
     "atscript",
@@ -51,26 +51,26 @@
     "access": "public"
   },
   "devDependencies": {
-    "@atscript/core": "^0.1.56",
-    "@atscript/db": "^0.1.80",
-    "@atscript/db-sqlite": "^0.1.80",
-    "@atscript/typescript": "^0.1.56",
-    "@moostjs/event-wf": "^0.6.10",
+    "@atscript/core": "^0.1.58",
+    "@atscript/db": "^0.1.82",
+    "@atscript/db-sqlite": "^0.1.82",
+    "@atscript/typescript": "^0.1.58",
+    "@moostjs/event-wf": "^0.6.14",
     "@prostojs/wf": "^0.1.1",
-    "@wooksjs/event-core": "^0.7.12",
-    "@wooksjs/event-wf": "^0.7.12",
-    "moost": "^0.6.10",
-    "unplugin-atscript": "^0.1.56",
-    "vitest": "npm:@voidzero-dev/vite-plus-test@latest",
-    "@atscript/ui": "^0.1.68"
+    "@wooksjs/event-core": "^0.7.13",
+    "@wooksjs/event-wf": "^0.7.13",
+    "moost": "^0.6.14",
+    "unplugin-atscript": "^0.1.58",
+    "vitest": "npm:@voidzero-dev/vite-plus-test@0.1.14",
+    "@atscript/ui": "^0.1.70"
   },
   "peerDependencies": {
-    "@atscript/core": "^0.1.56",
-    "@atscript/typescript": "^0.1.56",
-    "@moostjs/event-wf": "^0.6.10",
-    "@wooksjs/event-core": "^0.7.12",
-    "@wooksjs/event-wf": "^0.7.12",
-    "moost": "^0.6.10"
+    "@atscript/core": "^0.1.58",
+    "@atscript/typescript": "^0.1.58",
+    "@moostjs/event-wf": "^0.6.14",
+    "@wooksjs/event-core": "^0.7.13",
+    "@wooksjs/event-wf": "^0.7.13",
+    "moost": "^0.6.14"
   },
   "scripts": {
     "build": "vp pack",