@nwire/forge 0.12.1 → 0.13.0

package/dist/plugins/queries-plugin.d.ts

@@ -1,41 +1,27 @@
 /**
- * `queriesPlugin` — standalone forge query concern.
+ * `queriesPlugin` — the forge read concern as a runtime-native plugin.
  *
  *   import { createApp } from "@nwire/app";
- *   import {
- *     projectionsPlugin,
- *     queriesPlugin,
- *     forgePlugin,
- *   } from "@nwire/forge";
+ *   import { projectionsPlugin, queriesPlugin } from "@nwire/forge";
  *
  *   const app = createApp({
  *     appName: "orders",
- *     plugins: [
- *       forgePlugin,
- *       projectionsPlugin([OrdersDashboard]),
- *       queriesPlugin([listOrders, getOrderById]),
- *     ],
+ *     handlers: [listOrders, getOrderById],          // the app registers queries
+ *     plugins: [projectionsPlugin([OrdersDashboard]), queriesPlugin()],
  *   });
  *
- * Owns:
- *   - the query registry (private to the plugin's `QueryRunner`)
- *   - the `forge.queryRunner` container binding
- *   - the `forge.query` capability (binding consumed by handler ctx as
- *     `ctx.resolve("useProjection")` and equivalent paths)
- *
- * Queries don't participate in the EventPublishing chain. They execute
- * on demand against either a projection's per-tenant state (when
- * `projection + execute` is set) or a handler closure. Projection state
- * comes from the `forge.projectionStore` binding, which `projectionsPlugin`
- * or `forgePlugin` provides.
+ * It owns no query list. A query IS a handler (`defineQuery =
+ * defineHandler.kind("query")`), registered by the app via `createApp({
+ * handlers })`. At setup this plugin scans the runtime for `config.kind ===
+ * "query"` and registers each into the read engine (`QueryRunner`), which loads
+ * projection state or runs the handler closure on demand. Queries do not
+ * participate in the LocalDelivery chain.
  *
- * If `forgePlugin`'s `options.queries` is also passed, two QueryRunners
- * exist and the bundled one is reachable through the existing forge
- * dispatcher binding. Both work, but the standalone plugin's runner is
- * the one bound on `FORGE_QUERY_RUNNER_BINDING`. A warning at AppReady
- * flags the duplicate install.
+ * Owns:
+ *   - the `QueryRunner` (read registry + execution) and the
+ *     `forge.queryRunner` container binding.
+ *   - the `ctx.query` verb — a light read scoped to the envelope's tenant.
  */
 import type { PluginDefinition } from "@nwire/app";
-import type { QueryDefinition } from "../primitives/define-query.js";
 export declare const FORGE_QUERY_RUNNER_BINDING: "forge.queryRunner";
-export declare function queriesPlugin(queries: readonly QueryDefinition<any, any, any>[]): PluginDefinition;
+export declare function queriesPlugin(): PluginDefinition;

package/dist/plugins/queries-plugin.js

@@ -1,73 +1,60 @@
 /**
- * `queriesPlugin` — standalone forge query concern.
+ * `queriesPlugin` — the forge read concern as a runtime-native plugin.
  *
  *   import { createApp } from "@nwire/app";
- *   import {
- *     projectionsPlugin,
- *     queriesPlugin,
- *     forgePlugin,
- *   } from "@nwire/forge";
+ *   import { projectionsPlugin, queriesPlugin } from "@nwire/forge";
  *
  *   const app = createApp({
  *     appName: "orders",
- *     plugins: [
- *       forgePlugin,
- *       projectionsPlugin([OrdersDashboard]),
- *       queriesPlugin([listOrders, getOrderById]),
- *     ],
+ *     handlers: [listOrders, getOrderById],          // the app registers queries
+ *     plugins: [projectionsPlugin([OrdersDashboard]), queriesPlugin()],
  *   });
  *
- * Owns:
- *   - the query registry (private to the plugin's `QueryRunner`)
- *   - the `forge.queryRunner` container binding
- *   - the `forge.query` capability (binding consumed by handler ctx as
- *     `ctx.resolve("useProjection")` and equivalent paths)
- *
- * Queries don't participate in the EventPublishing chain. They execute
- * on demand against either a projection's per-tenant state (when
- * `projection + execute` is set) or a handler closure. Projection state
- * comes from the `forge.projectionStore` binding, which `projectionsPlugin`
- * or `forgePlugin` provides.
+ * It owns no query list. A query IS a handler (`defineQuery =
+ * defineHandler.kind("query")`), registered by the app via `createApp({
+ * handlers })`. At setup this plugin scans the runtime for `config.kind ===
+ * "query"` and registers each into the read engine (`QueryRunner`), which loads
+ * projection state or runs the handler closure on demand. Queries do not
+ * participate in the LocalDelivery chain.
  *
- * If `forgePlugin`'s `options.queries` is also passed, two QueryRunners
- * exist and the bundled one is reachable through the existing forge
- * dispatcher binding. Both work, but the standalone plugin's runner is
- * the one bound on `FORGE_QUERY_RUNNER_BINDING`. A warning at AppReady
- * flags the duplicate install.
+ * Owns:
+ *   - the `QueryRunner` (read registry + execution) and the
+ *     `forge.queryRunner` container binding.
+ *   - the `ctx.query` verb — a light read scoped to the envelope's tenant.
  */
 import { FORGE_PROJECTION_STORE_BINDING } from "./projections-plugin.js";
 import { QueryRunner } from "./queries-chain.js";
 export const FORGE_QUERY_RUNNER_BINDING = "forge.queryRunner";
-export function queriesPlugin(
-// eslint-disable-next-line @typescript-eslint/no-explicit-any
-queries) {
+/** Is this registered handler a forge query? */
+function isQueryHandler(h) {
+    return (h != null &&
+        (typeof h === "object" || typeof h === "function") &&
+        h.config?.kind === "query");
+}
+export function queriesPlugin() {
     return {
         name: "forge.queries",
-        setup({ runtime, container, on }) {
+        setup({ runtime, container }) {
             if (!container.has(FORGE_PROJECTION_STORE_BINDING)) {
                 throw new Error(`queriesPlugin: ${FORGE_PROJECTION_STORE_BINDING} is not bound. ` +
-                    `Install projectionsPlugin or forgePlugin before queriesPlugin so the projection store exists.`);
+                    `Install projectionsPlugin before queriesPlugin so the projection store exists.`);
             }
             const projectionStore = container.resolve(FORGE_PROJECTION_STORE_BINDING);
             const runner = new QueryRunner(runtime, container, projectionStore);
-            for (const query of queries)
-                runner.register(query);
+            // Scan the runtime's registered handlers — the app owns registration.
+            for (const name of runtime.listHandlers()) {
+                const handler = runtime.getHandler(name);
+                if (isQueryHandler(handler))
+                    runner.register(handler);
+            }
             container.register(FORGE_QUERY_RUNNER_BINDING, runner);
-            on("AppReady", () => {
-                // Diagnostic only — the bundled forge dispatcher also exposes
-                // queries via its own internal registry. Both work, but the
-                // standalone runner is the binding consumers see at
-                // FORGE_QUERY_RUNNER_BINDING.
-                const dispatcher = container.has("forge.dispatcher")
-                    ? container.resolve("forge.dispatcher")
-                    : undefined;
-                const bundledNames = dispatcher?.listQueries?.() ?? [];
-                const overlap = runner.listQueries().filter((n) => bundledNames.includes(n));
-                if (overlap.length > 0) {
-                    // eslint-disable-next-line no-console
-                    console.warn(`queriesPlugin: ${overlap.length} query name(s) (${overlap.join(", ")}) are also registered on forgePlugin's bundled queries. ` +
-                        `Install either queriesPlugin OR forgePlugin's options.queries path, not both.`);
-                }
+            // Contribute the `ctx.query` verb — a light read scoped to the envelope's
+            // tenant; the runner routes projection-form vs handler-form.
+            runtime.add({
+                name: "forge.query-ctx",
+                provideCtx: ({ envelope }) => ({
+                    query: (queryDef, input) => runner.run(queryDef.name, input, envelope.tenant ?? "", envelope),
+                }),
             });
         },
     };

package/dist/plugins/workflows-chain.d.ts

@@ -1,5 +1,5 @@
 /**
- * Workflow chain runner — the EventPublishing step that drives every
+ * Workflow chain runner — the LocalDelivery step that drives every
  * registered workflow whose subscribed events include the current one.
  *
  * Self-contained: takes its dependencies (runtime, timer store, effects
@@ -22,7 +22,7 @@ import { type Runtime } from "@nwire/app";
 import type { WorkflowDefinition, WorkflowInstance, WorkflowEffects } from "../primitives/define-workflow.js";
 import { type EventMessage } from "../messages/event-message.js";
 import type { WorkflowFireHookCtx } from "../runtime/forge-types.js";
-import type { WorkflowTimerStore } from "../stores/workflow-timer-store.js";
+import { type WorkflowTimerStore } from "../stores/workflow-timer-store.js";
 /**
  * Resolves the dispatch effects (send / enqueue / publish) the workflow
  * sees on each fire. Returned in a fresh closure per event so envelope
@@ -48,4 +48,11 @@ export declare class WorkflowChainRunner {
     instanceStore(workflowName: string): Map<string, WorkflowInstance>;
     /** Fire every workflow that subscribes to this event. */
     apply(event: EventMessage, envelope: MessageEnvelope, correlationKeyOverride?: string): Promise<void>;
+    /**
+     * Drain every saga timer due at `now` and route each back into its
+     * workflow. Each fire reuses the normal `apply` path with the timer's
+     * `correlationKey` as the override, so the timer reaches the saga instance
+     * that scheduled it. Returns the number of timers fired.
+     */
+    fireDueWorkflowTimers(now?: Date): Promise<number>;
 }

package/dist/plugins/workflows-chain.js

@@ -1,5 +1,5 @@
 /**
- * Workflow chain runner — the EventPublishing step that drives every
+ * Workflow chain runner — the LocalDelivery step that drives every
  * registered workflow whose subscribed events include the current one.
  *
  * Self-contained: takes its dependencies (runtime, timer store, effects
@@ -18,9 +18,11 @@
  */
 import { randomUUID } from "node:crypto";
 import { hook } from "@nwire/hooks";
+import { seedEnvelope } from "@nwire/envelope";
 import { loggerForEnvelope } from "@nwire/logger";
 import { serializeError } from "@nwire/app";
 import { eventFactory } from "../messages/event-message.js";
+import { timerEventName } from "../stores/workflow-timer-store.js";
 import { computeBackoff, parseDelay, sleep } from "../helpers/retry-helpers.js";
 export class WorkflowChainRunner {
     runtime;
@@ -205,4 +207,20 @@ export class WorkflowChainRunner {
             }
         }
     }
+    /**
+     * Drain every saga timer due at `now` and route each back into its
+     * workflow. Each fire reuses the normal `apply` path with the timer's
+     * `correlationKey` as the override, so the timer reaches the saga instance
+     * that scheduled it. Returns the number of timers fired.
+     */
+    async fireDueWorkflowTimers(now = new Date()) {
+        let fired = 0;
+        const envelope = seedEnvelope({});
+        for await (const timer of this.timerStore.drainDue(now)) {
+            const eventName = timerEventName(timer.workflowName, timer.timerName);
+            await this.apply({ eventName, payload: timer.payload }, envelope, timer.correlationKey);
+            fired++;
+        }
+        return fired;
+    }
 }

package/dist/plugins/workflows-plugin.d.ts

@@ -15,7 +15,7 @@
  * Owns:
  *   - the `forge.workflowTimerStore` container binding
  *   - the workflow registry (private to the plugin's `WorkflowChainRunner`)
- *   - the `forge.publish.workflows` step on the EventPublishing chain
+ *   - the `forge.publish.workflows` step on the LocalDelivery chain
  *     (priority 400 — between projections and bus delivery)
  *   - the `forge.workflowChain` container binding so other plugins can
  *     resolve the runner (the timer scheduler fires through it)

package/dist/plugins/workflows-plugin.js

@@ -15,7 +15,7 @@
  * Owns:
  *   - the `forge.workflowTimerStore` container binding
  *   - the workflow registry (private to the plugin's `WorkflowChainRunner`)
- *   - the `forge.publish.workflows` step on the EventPublishing chain
+ *   - the `forge.publish.workflows` step on the LocalDelivery chain
  *     (priority 400 — between projections and bus delivery)
  *   - the `forge.workflowChain` container binding so other plugins can
  *     resolve the runner (the timer scheduler fires through it)
@@ -29,7 +29,7 @@
  * fires at `AppReady` when both attachments are present.
  */
 import { InMemoryWorkflowTimerStore, } from "../stores/workflow-timer-store.js";
-import { FORGE_DISPATCHER_BINDING } from "../runtime/forge-plugin.js";
+import { FORGE_ACTION_RUNNER_BINDING, FORGE_PUBLISH_BINDING } from "./actions-plugin.js";
 import { EVENT_PUBLISHING_PRIORITIES } from "../framework-events.js";
 import { WorkflowChainRunner } from "./workflows-chain.js";
 export const FORGE_WORKFLOW_CHAIN_BINDING = "forge.workflowChain";
@@ -41,21 +41,22 @@ export function workflowsPlugin(workflows, opts = {}) {
             const store = opts.workflowTimerStore ?? new InMemoryWorkflowTimerStore();
             bind(FORGE_WORKFLOW_TIMER_STORE_BINDING, () => store);
         },
-        setup({ runtime, container, on }) {
+        setup({ runtime, container }) {
             const timerStore = container.resolve(FORGE_WORKFLOW_TIMER_STORE_BINDING);
             const chain = new WorkflowChainRunner(runtime, timerStore, (envelope) => {
-                // Effects resolve the dispatcher lazily so the binding exists by
-                // the time a workflow actually fires.
-                const dispatcher = container.resolve(FORGE_DISPATCHER_BINDING);
+                // Effects resolve the action runner + shared publish lazily so the
+                // bindings exist by the time a workflow actually fires.
+                const runner = container.resolve(FORGE_ACTION_RUNNER_BINDING);
+                const publish = container.resolve(FORGE_PUBLISH_BINDING);
                 const effects = {
                     async send(action, input) {
-                        return dispatcher.dispatch(action, input, envelope);
+                        return runner.dispatch(action, input, envelope);
                     },
                     async enqueue(action, input) {
-                        void dispatcher.dispatch(action, input, envelope);
+                        void runner.dispatch(action, input, envelope);
                     },
                     async publish(eventMsg) {
-                        await dispatcher.publish([eventMsg], envelope);
+                        await publish([eventMsg], envelope);
                     },
                 };
                 return effects;
@@ -63,19 +64,10 @@ export function workflowsPlugin(workflows, opts = {}) {
             for (const workflow of workflows)
                 chain.register(workflow);
             container.register(FORGE_WORKFLOW_CHAIN_BINDING, chain);
-            runtime.hooks.EventPublishing.use(async (payload, next) => {
-                await chain.apply(payload.event, payload.envelope);
+            runtime.hooks.LocalDelivery.use(async (payload, next) => {
+                await chain.apply({ eventName: payload.eventName, payload: payload.payload }, payload.envelope);
                 await next();
             }, { name: "forge.publish.workflows", priority: EVENT_PUBLISHING_PRIORITIES.workflows });
-            on("AppReady", () => {
-                const hookChain = runtime.hooks.EventPublishing;
-                const steps = (hookChain.chain ?? []).filter((s) => s.name === "forge.publish.workflows");
-                if (steps.length > 1) {
-                    // eslint-disable-next-line no-console
-                    console.warn(`workflowsPlugin: detected ${steps.length} "forge.publish.workflows" steps on the EventPublishing chain. ` +
-                        `Install either workflowsPlugin OR forgePlugin's options.workflows path, not both.`);
-                }
-            });
         },
     };
 }

package/dist/primitives/define-action.d.ts

@@ -1,41 +1,45 @@
 /**
- * `defineAction` — declares a typed message the system can handle. Actions
- * are the framework's center of gravity: named intent, typed input, no
- * transport concerns. Resolvers wrap actions for HTTP/GraphQL/CLI; workflows
- * dispatch actions in response to events.
+ * `defineAction` — declares a typed command the system can handle. It is sugar
+ * over the one operation primitive:
  *
- *   export const submitAnswer = defineAction({
- *     name: 'submissions.submit-answer',
- *     description: 'Avi submits his answer to an exercise.',
- *     schema: SubmitAnswerInput,
- *   })
+ *   export const defineAction = defineHandler.kind("action");
  *
- * An action carries a `name` (its routing key) and a `schema` (input type).
- * It is BOTH a meta record (`.name`, `.schema`, …) AND a callable factory:
+ * An action IS a handler (`@nwire/handler`) with `config.kind === "action"`,
+ * plus a thin forge decoration: it mints a typed `CommandMessage` when called,
+ * carries the command-side metadata (`retry`, `emits`, `policy`, persona /
+ * journey / SLO for Studio), and exposes `.public()`. There is no separate
+ * `.handler` object — the action object itself is what `runtime.execute`
+ * dispatches and what the app registers.
  *
- *   execute(submitAnswer({ studentId, attemptId, choice }))   // dispatch
- *   defineHandler(submitAnswer, fn)                            // bind handler
- *   ctx.send(submitAnswer, input)                              // also valid
+ *   export const submitAnswer = defineAction({
+ *     name: "submissions.submit-answer",
+ *     input: SubmitAnswerInput,
+ *     emits: [AnswerSubmitted],
+ *     handler: async ({ input, request }) => {
+ *       const grade = await request(evaluateGrade, { ... })
+ *       return grade.ok ? AnswerSubmitted({ ... }) : undefined
+ *     },
+ *   })
  *
- * Calling the action mints a typed `CommandMessage` with input validated
- * against the zod schema — the dispatch site can't pass bad data. Mirrors
- * the `defineEvent → EventMessage` pattern (Phase 41.9).
+ *   execute(submitAnswer({ ... }))     // dispatch via minted CommandMessage
+ *   ctx.request(submitAnswer, input)   // dispatch by reference
+ *   submitAnswer.name                  // "submissions.submit-answer"
  *
- * Inline shorthand: `defineAction({ ..., handler })` synthesizes a handler
- * alongside the contract. For cross-module orchestration where the handler
- * lives elsewhere, leave `handler` undefined and wire via `defineHandler`.
+ * The handler body takes one `ctx` arg — `{ input, request, send, emit, query,
+ * actor, … }` — the same shape as the kernel handler. For cross-module
+ * orchestration where the handler lives elsewhere, leave `handler` undefined —
+ * the action is then a schema-only contract you dispatch toward.
  */
 import type { z } from "zod";
 import type { ZodTypeAny } from "@nwire/messages";
-import type { EventDefinition, SourceLocation } from "@nwire/messages";
-import { type HandlerDefinition, type HandlerReturn, type HandlerContext } from "./define-handler.js";
+import type { EventDefinition } from "@nwire/messages";
+import type { HandlerContext, HandlerReturn } from "./define-handler.js";
 /** RBAC policy tag — string, string list, or CASL-style `[action, subject]` tuple. */
 export type ActionPolicy = string | readonly string[] | readonly [action: string, subject: string];
 /**
  * Retry policy for an action's handler. When a handler throws, the runtime
  * retries up to `max` times with `backoff` strategy between attempts. After
- * `max` attempts fail, the failure goes to the DLQ (dead-letter queue —
- * currently a sink in the runtime; production wires plug in BullMQ DLQ).
+ * `max` attempts fail, the failure goes to the DLQ (dead-letter queue).
  */
 export interface RetryPolicy {
     /** Maximum retry attempts after the initial try. Default: 0 (no retry). */
@@ -48,10 +52,8 @@ export interface RetryPolicy {
     readonly maxDelayMs?: number;
 }
 /**
- * Service-level objective declaration for an action. Studio shows the
- * declared target side-by-side with observed reality (p95 latency from the
- * telemetry stream, success rate from action.completed vs .failed counts).
- * All fields optional; missing fields just don't get scored.
+ * Service-level objective declaration for an action. Studio shows the declared
+ * target side-by-side with observed reality.
  */
 export interface ActionSlo {
     /** Declared p95 latency target in milliseconds. */
@@ -64,29 +66,27 @@ export interface ActionSlo {
  *
  *   const cmd = submitAnswer({ ... })   // { $kind, actionName, input }
  *   execute(cmd)                         // dispatch
- *
- * The runtime's `execute`/`send`/`dispatch` accept either this command
- * message OR the legacy `(action, input)` positional form. Both routes
- * end at the same handler.
  */
 export interface CommandMessage<TSchema extends ZodTypeAny = ZodTypeAny> {
     readonly $kind: "command";
     readonly actionName: string;
     readonly input: z.output<TSchema>;
 }
+/** Ctx a handler body receives — the forge handler ctx with the validated `input` on it. */
+export type ActionCtx<TSchema extends ZodTypeAny = ZodTypeAny> = HandlerContext & {
+    readonly input: z.output<TSchema>;
+};
+/** The handler body — one ctx arg (`{ input, request, send, ... }`). */
+export type ActionHandlerFn<TSchema extends ZodTypeAny = ZodTypeAny> = (ctx: ActionCtx<TSchema>) => Promise<HandlerReturn> | HandlerReturn;
 /**
- * The non-callable action shape — used as the abstract reference type in
- * function signatures (`runtime.dispatch(action: ActionDefinition, …)`,
- * `defineHandler(action: ActionDefinition, …)`, etc.). Concrete actions
- * returned from `defineAction` are `CallableActionDefinition` (this + a
- * call signature); they're assignable wherever `ActionDefinition` is
- * required because the call signature is purely additive.
+ * The non-callable action shape — the abstract reference type used in function
+ * signatures across the runtime. An action is a handler: it carries the kernel
+ * `config` + the hook surface (`run`/`use`) so `runtime.execute` dispatches it
+ * directly, plus the command-side metadata.
  *
- * Why split: TS call signatures are contravariant in their parameter, so
- * a typed `(input: MySchema) => …` is NOT assignable to `(input: unknown)
- * => …`. Keeping the abstract reference type non-callable preserves
- * covariance over `TSchema` — `ActionDefinition<MySchema>` flows freely
- * into `ActionDefinition<ZodTypeAny>` positions across the runtime.
+ * Concrete actions from `defineAction` are `CallableActionDefinition` (this + a
+ * call signature minting a `CommandMessage`); the call signature is additive so
+ * they're assignable wherever `ActionDefinition` is required.
  */
 export interface ActionDefinition<TSchema extends ZodTypeAny = ZodTypeAny> {
     /** Truthy when this definition was marked via `.public()` in a manifest. */
@@ -94,104 +94,72 @@ export interface ActionDefinition<TSchema extends ZodTypeAny = ZodTypeAny> {
     readonly $kind: "action";
     readonly name: string;
     readonly description?: string;
-    readonly schema: TSchema;
+    /** Input schema (zod). */
+    readonly input: TSchema;
     readonly retry?: RetryPolicy;
-    /**
-     * Optional policy tag(s) consumed by authz middleware (`@nwire/auth`).
-     * The framework treats this as an opaque string — interpretation is
-     * the authorizer's job. Examples: `'admin-only'`, `['student', 'self']`.
-     */
+    /** Optional policy tag(s) consumed by authz middleware (`@nwire/auth`). */
     readonly policy?: ActionPolicy;
-    /**
-     * Named persona who triggers this action. Studio uses it to build
-     * persona-grouped journey views ("show me Avi's full flow"). Free-form
-     * label — typically the persona's name with a short qualifier:
-     * `'Avi (9, beginner)'`, `'Dina (curriculum designer)'`.
-     */
+    /** Named persona who triggers this action — Studio journey views. */
     readonly persona?: string;
-    /**
-     * Journey step identifier this action belongs to. Lets Studio reconstruct
-     * the user journey across BCs. Free-form — by convention an id + label:
-     * `'J3-submit-exercise'`.
-     */
+    /** Journey step identifier this action belongs to. */
     readonly journeyStep?: string;
-    /**
-     * High-level capability name (UDOO-framework concept). Groups actions
-     * by what they enable. Example: `'submit-answer'`, `'review-flagged'`.
-     */
+    /** High-level capability name (UDOO concept). */
     readonly capability?: string;
     /** Declared SLO target — Studio scores observed reality against this. */
     readonly slo?: ActionSlo;
     /** Free-form tags for filtering / grouping in Studio. */
     readonly tags?: readonly string[];
     /**
-     * Inline handler synthesized when `defineAction({..., handler})` was used.
-     * `createApp` walks `manifest.actions` and auto-registers this handler if
-     * present. For action contracts that have NO handler in the current module
-     * (cross-module dispatch, public schema-only declarations), leave this
-     * undefined and register the handler separately via `manifest.handlers`.
-     *
-     * Typed as `HandlerDefinition<ZodTypeAny>` (not `HandlerDefinition<TSchema>`)
-     * to preserve ActionDefinition's covariance over TSchema — without this,
-     * `ActionDefinition<MySchema>` would not be assignable to
-     * `ActionDefinition<ZodTypeAny>` (the abstract action reference used by
-     * the runtime, `defineHandler`, ctx.request, etc.).
+     * Declared events this action emits — the *declared intent* the scanner
+     * reads into the static graph. The handler's runtime return is the source
+     * of truth.
      */
-    readonly handler?: HandlerDefinition;
+    readonly emits?: readonly EventDefinition[];
     /**
-     * Declared events this action emits. The handler's runtime return is the
-     * source of truth; this field is the *declared intent* — what the system
-     * promises to emit. The scanner reads it into the static graph so Studio
-     * (and any audit tooling) can draw causation chains at design time, and
-     * runtime observers can detect drift (emitted-but-not-declared or
-     * declared-but-never-fired).
-     *
-     * Carries event names only (event refs are erased to `{ name }` to avoid
-     * coupling the action definition to its event modules at the type level).
+     * The kernel `@nwire/handler` config — `kind:"action"`, the adapted
+     * `(ctx)` handler fn, `input`, `emits`. Present iff an inline handler was
+     * declared. `actionsPlugin` reads `config.handler` to run the pipeline; the
+     * runtime reads it via the registry.
      */
-    readonly emits?: readonly EventDefinition[];
-    /** Where the action was declared. Studio uses this for IDE-open links. */
-    readonly $source?: SourceLocation;
+    readonly config?: any;
+    /** Hook-chain run — delegates to the underlying handler. `runtime.execute` calls this. */
+    run?(ctx: unknown, opts?: {
+        readonly signal?: AbortSignal;
+    }): Promise<unknown>;
+    /** Attach a chain step to the underlying handler's hook. Returns the action. */
+    use?(fn: any, opts?: any): ActionDefinition<TSchema>;
+    /** Attach a listener to the underlying handler's hook. Returns the action. */
+    on?(fn: any, opts?: any): ActionDefinition<TSchema>;
+    /** Detach a previously attached chain/listener fn. Returns the action. */
+    off?(fn: any): ActionDefinition<TSchema>;
     /** Return a callable action clone with `$public: true`. */
     public: () => CallableActionDefinition<TSchema>;
 }
 /**
- * The full action shape returned from `defineAction` — adds the call
- * signature so consumers can mint a typed `CommandMessage` inline:
- *
- *   submitAnswer.name                    // "submissions.submit-answer"
- *   submitAnswer({ studentId, ... })     // CommandMessage
- *   submitAnswer.public()                // callable clone, $public: true
+ * The full action shape returned from `defineAction` — adds the call signature
+ * so consumers can mint a typed `CommandMessage` inline.
  */
 export type CallableActionDefinition<TSchema extends ZodTypeAny = ZodTypeAny> = ActionDefinition<TSchema> & ((input: z.input<TSchema>) => CommandMessage<TSchema>);
 export interface ActionMeta<TSchema extends ZodTypeAny = ZodTypeAny> {
     readonly name: string;
     readonly description?: string;
-    readonly schema: TSchema;
+    /** Input schema (zod). */
+    readonly input: TSchema;
     readonly retry?: RetryPolicy;
     readonly policy?: ActionPolicy;
-    /** See `ActionDefinition.persona`. */
     readonly persona?: string;
-    /** See `ActionDefinition.journeyStep`. */
     readonly journeyStep?: string;
-    /** See `ActionDefinition.capability`. */
     readonly capability?: string;
-    /** See `ActionDefinition.slo`. */
     readonly slo?: ActionSlo;
-    /** See `ActionDefinition.tags`. */
     readonly tags?: readonly string[];
-    /** Declared events this action emits. See `ActionDefinition.emits`. */
+    /** Declared events this action emits. */
     readonly emits?: readonly EventDefinition[];
     /**
-     * Optional inline handler. When set, `defineAction` synthesizes a
-     * `HandlerDefinition` linked to this action and attaches it to the
-     * returned `ActionDefinition.handler`. Use this for the common CRUD case
-     * where contract and handler live together. For cross-module orchestration
-     * (handler wired separately, action referenced from another module),
-     * declare the action without `handler` and use `defineHandler(action, fn)`
-     * in the owning module.
+     * Optional inline handler — the common case where contract and handler live
+     * together. The body takes one `ctx` arg. For cross-module
+     * orchestration, omit it — a schema-only contract.
      */
-    readonly handler?: (input: z.output<TSchema>, ctx: HandlerContext) => Promise<HandlerReturn> | HandlerReturn;
+    readonly handler?: ActionHandlerFn<TSchema>;
 }
 export declare function defineAction<TSchema extends ZodTypeAny>(meta: ActionMeta<TSchema>): CallableActionDefinition<TSchema>;
 export declare function defineAction<TSchema extends ZodTypeAny>(name: string, meta: Omit<ActionMeta<TSchema>, "name">): CallableActionDefinition<TSchema>;
@@ -200,8 +168,8 @@ export type ActionInput<A> = A extends ActionDefinition<infer S> ? z.output<S> :
 export type ActionResult<A> = A extends ActionDefinition ? HandlerReturn : never;
 /**
  * Optional string-literal dispatch registry. Apps implement this on the
- * container so `dispatch("orders.place-order", input)` typechecks when
- * a module augments the registry via declaration merging.
+ * container so `dispatch("orders.place-order", input)` typechecks when a
+ * module augments the registry via declaration merging.
  */
 export interface NwireActionRegistry {
     readonly [actionName: string]: ActionDefinition;
@@ -214,10 +182,7 @@ export interface NwireActionRegistry {
 export declare function isCommandMessage(x: unknown): x is CommandMessage;
 /**
  * Resolve either dispatch form into `(action, input)`. Centralised so every
- * transport surface (execute, send, ctx.request) accepts both call shapes
- * with one helper. When the caller passes a `CommandMessage`, the resolver
- * looks up the action by name on the runtime; when they pass an
- * `ActionDefinition` + input, it short-circuits.
+ * transport surface accepts both call shapes with one helper.
  */
 export declare function resolveDispatch(actionOrCmd: ActionDefinition | CommandMessage, input: unknown, lookup: (name: string) => ActionDefinition | undefined): {
     action: ActionDefinition;