@nwire/forge 0.12.1 → 0.13.0

package/dist/primitives/define-actor.js

@@ -1,170 +1,180 @@
 /**
  * `defineActor` — the primitive for entities that carry state, transitions,
- * and timers. The actor is data + state machine in one declaration.
+ * and timers. An actor is a thing with identity that guards an invariant: one
+ * instance per id, it owns its state, and it's the only thing that changes it.
  *
- *   export const Submission = defineActor('submission', {
- *     schema: SubmissionSchema,
- *     key: 'submissionId',
- *     initial: 'submitted',
- *     states: {
- *       submitted: {
- *         on: {
- *           [AnswerFlaggedEvent.name]: {
- *             target: 'under-review',
- *             assign: (ctx, event) => ({ confidence: event.confidence })
- *           },
- *           [AnswerAutoGradedEvent.name]: {
- *             target: 'graded',
- *             assign: (ctx, event) => ({
- *               verdict: event.verdict,
- *               confidence: event.confidence,
- *               gradedAt: event.gradedAt
- *             })
- *           }
- *         }
- *       },
- *       'under-review': {
- *         on: {
- *           [SubmissionManuallyGradedEvent.name]: {
- *             target: 'graded',
- *             assign: (ctx, event) => ({ verdict: event.verdict })
- *           }
- *         },
- *         after: {
- *           '3d': sendReviewReminder
- *         }
- *       },
- *       graded: { final: true }
- *     }
- *   })
+ * Same builder shape as `defineWorkflow` — a closure with the one event verb
+ * `when` — plus identity + durability. State, key, and lifecycle come from a
+ * `defineSchema`; the closure declares the transitions:
  *
- * See:
- *   - `__docs__/framework/foundation-v3-spec.md` — design rationale
- *   - `ADR-006-actors-vs-reactions.md` — when to use defineActor vs `when`
- *   - `ADR-007-declarative-state-via-assign.md` — why `assign` returns partials
+ *   export const Submission = defineActor("submission",
+ *     ({ data, id, validate, recordThat, states, when, after }) => {
+ *       const { submitted, underReview, graded } = states;   // callable state bodies
+ *       const flag = (reason: string) => { validate(data, [isSubmitted]); recordThat(Flagged({ id, reason })); };
+ *       submitted(() => {
+ *         when(AnswerWasSubmitted,      (e, { assign }) => { assign({ ...e }); });        // stay
+ *         when(SubmissionWasAutoGraded, (e, { assign }) => { assign({ ...e }); return graded; });
+ *         when(SubmissionWasFlagged,    () => underReview);
+ *       });
+ *       when(SubmissionDeleted, () => deleted);               // top-level = always-listener
+ *       underReview(() => after("review-reminder", "3d", sendReviewReminder));
+ *       return { flag };                                      // methods: a plain object from the closure
+ *     },
+ *     { schema: SubmissionData, stuckThresholds, slas },
+ *   );
+ *
+ * A `when` at the closure top is active in every state; a `when` inside a state
+ * body fires only in that state; the state-scoped one wins. A `when` returns a
+ * state to transition (nothing to stay); `ctx.assign(patch)` folds the actor's
+ * data. Identical to a workflow reaction — the difference is identity (keyed by
+ * the schema's `key`) and durability (an actor always persists).
+ *
+ * Default lifecycle: an actor always has a terminal. If the schema declares no
+ * `final` state, `deleted` (final) is injected — a free soft-delete terminal.
+ *
+ * `assign` vs `methods`: `assign(patch)` is a pure data fold during a
+ * transition. `methods` (in the options) are pure invariant-enforcers called
+ * from a handler via `ctx.actor(Actor, id)` — they receive state, return an
+ * event (or throw), and never do I/O.
  */
-import { captureSourceLocation } from "@nwire/messages";
-import { isSchemaDefinition } from "./define-schema.js";
-export function defineActor(
-// eslint-disable-next-line @typescript-eslint/no-explicit-any
-...args) {
-    const $source = captureSourceLocation();
-    // Three signatures:
-    //   (name: string, options: ActorOptions)                                  → classic
-    //   (options: ActorOptionsBound)                                            → schema-bound object form
-    //   (schema: SchemaDefinition, body: (ctx) => methods, options?: {...})    → closure form
-    const [first, second, third] = args;
-    const attach = (def) => Object.defineProperty(def, "$source", {
-        value: $source,
-        enumerable: false,
-        configurable: true,
-    });
-    // Closure form: first arg is a SchemaDefinition, second is a function.
-    if (isSchemaDefinition(first) && typeof second === "function") {
-        return attach(defineActorClosure(first, 
-        // eslint-disable-next-line @typescript-eslint/no-explicit-any
-        second, (third ?? {})));
-    }
-    // Schema-bound object form: first arg is an options object with a schema field.
-    if (typeof first === "object" &&
-        first !== null &&
-        isSchemaDefinition(first.schema)) {
-        return attach(defineActorBound(first));
-    }
-    // Classic form.
-    if (typeof first !== "string" || !second) {
-        throw new Error("defineActor: signatures are (name, options) | (boundOptions) | (schema, closure, options?).");
-    }
-    return attach(defineActorClassic(first, second));
-}
 /**
- * Closure-form implementation.
- *
- * Define-time pass: run the body with a recording context. We capture:
- *   - each `when(Event, fn)` call → one transition per state (initially
- *     applied to all non-final states; per-state scoping is also supported).
- *   - the methods object returned (or via `methods(obj)`).
+ * Define an actor — one builder closure + a `defineSchema` for the shape.
  *
- * Runtime pass (per `use()` call): the binder re-invokes the body with the
- * live state + id, returning the bound methods. `recordThat` calls push to
- * an array that `loadActorView` exposes; the runtime publishes them after
- * the method returns.
+ * The closure runs once at define time (stub ctx) to collect transitions
+ * (`when`) and timers (`after`), with state bodies scoping them; the runtime
+ * folds events through `actors-chain` (locking, OCC, persistence, the
+ * transition hook). Methods are defined in the closure and returned as a plain
+ * object — `return { create, update }` — and bound over the live instance per
+ * `ctx.actor(Actor, id)` (no `methods()` wrapper, no static methods option).
  */
-function defineActorClosure(schema, body, options) {
-    const name = options.name ?? schema.name;
-    const schemaStates = schema.states;
-    // Build state refs once — same identity across all closure invocations.
+export function defineActor(name, body, options) {
+    const schema = options.schema;
+    // ── State set: the schema's states, plus an injected `deleted` terminal
+    //    when the schema declares no `final` state (free soft-delete lifecycle).
+    const stateSpecs = { ...schema.states };
+    if (schema.finals.length === 0) {
+        stateSpecs.deleted = { final: true };
+    }
+    // ── Callable state bodies. Calling `x(() => …)` scopes the `when`s inside
+    //    to "x"; returning `x` from a reaction transitions there.
+    let currentScope;
     const stateRefs = {};
-    for (const stateName of Object.keys(schemaStates)) {
-        stateRefs[stateName] = Object.freeze({ $kind: "state-ref", name: stateName });
-        // Provide camelCase alias for kebab-case state names: "under-review" → underReview
+    const makeStateRef = (stateName) => {
+        const ref = ((bodyFn) => {
+            const prev = currentScope;
+            currentScope = stateName;
+            try {
+                bodyFn();
+            }
+            finally {
+                currentScope = prev;
+            }
+        });
+        Object.defineProperties(ref, {
+            $kind: { value: "state-ref", enumerable: true },
+            name: { value: stateName, enumerable: true, configurable: true },
+        });
+        return ref;
+    };
+    for (const stateName of Object.keys(stateSpecs)) {
+        stateRefs[stateName] = makeStateRef(stateName);
+        // camelCase alias for kebab names: "under-review" → underReview
         const camel = stateName.replace(/-([a-z])/g, (_, c) => c.toUpperCase());
         if (camel !== stateName)
             stateRefs[camel] = stateRefs[stateName];
     }
     const captured = [];
-    const defineTimeCtx = {
-        data: new Proxy({}, {
-            get: () => undefined,
-            has: () => false,
-        }),
-        id: "",
-        validate: () => { },
-        recordThat: () => { },
+    const timers = [];
+    // Live data view — `buildReaction` points `liveData` at the instance's
+    // current data before running a reaction, so `data.x` reads the right value.
+    let liveData = {};
+    const dataProxy = new Proxy({}, {
+        get: (_t, p) => liveData[p],
+        has: (_t, p) => p in liveData,
+    });
+    const ctx = {
+        data: dataProxy,
+        id: "", // placeholder at define time; live in the per-use binder below
+        validate: () => { }, // no-op at define time
+        recordThat: () => { }, // no-op at define time
         states: stateRefs,
         when: (event, fn) => {
             captured.push({
                 eventName: event.name,
+                scope: currentScope,
                 // eslint-disable-next-line @typescript-eslint/no-explicit-any
                 fn: fn,
             });
         },
-        methods: (obj) => obj,
+        after: (timerName, delay, action) => {
+            const actionName = typeof action === "string" ? action : action.name;
+            timers.push({ scope: currentScope, name: timerName, spec: { delay, action: actionName } });
+        },
+    };
+    // Define-time pass: collects when/after (above) and the method names from the
+    // returned object. The returned method bodies are discarded here — they bind
+    // over live state in `closureBinder` below.
+    body(ctx);
+    // Final states are absorbing — a reaction scoped to one is a mistake.
+    for (const c of captured) {
+        if (c.scope && stateSpecs[c.scope]?.final) {
+            throw new Error(`defineActor("${name}"): state "${c.scope}" is final and cannot declare event reactions.`);
+        }
+    }
+    // ── BUILD the runtime state machine. For each non-final state, lay down the
+    //    always-listeners first, then let state-scoped reactions override
+    //    (most-specific wins). Final states get no reactions.
+    const buildReaction = (fn) => {
+        let target;
+        let delta = {};
+        return {
+            assign: (state, event) => {
+                target = undefined;
+                delta = {};
+                liveData = state;
+                const result = fn(event, {
+                    assign: (d) => {
+                        delta = { ...delta, ...d };
+                    },
+                });
+                if (result &&
+                    typeof result === "object" &&
+                    result.$kind === "state-ref") {
+                    target = result.name;
+                }
+                return delta;
+            },
+            get target() {
+                return target;
+            },
+        };
     };
-    const defineTimeReturn = body(defineTimeCtx) ?? {};
-    const methodNames = Object.keys(defineTimeReturn);
-    // ── BUILD ACTOR STATE MACHINE ────────────────────────────────────
-    // Each captured `when(Event, fn)` becomes a reaction entry in every
-    // non-final state. The reaction's `assign` runs the fn against a buffer;
-    // its `target` is set if the fn returned a state ref.
     const mergedStates = {};
-    for (const [stateName, stateSpec] of Object.entries(schemaStates)) {
-        if (stateSpec.final) {
+    for (const [stateName, spec] of Object.entries(stateSpecs)) {
+        if (spec.final) {
             mergedStates[stateName] = { final: true };
             continue;
         }
-        const onEntries = {};
-        for (const { eventName, fn } of captured) {
-            // If multiple `when()` for the same event, only the last wins per
-            // state. (Closure-form de-duplication semantics; document this.)
-            let target;
-            let delta = {};
-            onEntries[eventName] = {
-                assign: (_currentState, event) => {
-                    target = undefined;
-                    delta = {};
-                    const transCtx = {
-                        assign: (d) => {
-                            delta = { ...delta, ...d };
-                        },
-                    };
-                    const result = fn(event, transCtx);
-                    if (result &&
-                        typeof result === "object" &&
-                        "$kind" in result &&
-                        result.$kind === "state-ref") {
-                        target = result.name;
-                    }
-                    return delta;
-                },
-                get target() {
-                    return target;
-                },
-            };
-        }
-        mergedStates[stateName] = { on: onEntries };
+        const on = {};
+        for (const c of captured)
+            if (c.scope === undefined)
+                on[c.eventName] = buildReaction(c.fn);
+        for (const c of captured)
+            if (c.scope === stateName)
+                on[c.eventName] = buildReaction(c.fn);
+        const after = {};
+        for (const t of timers)
+            if (t.scope === stateName)
+                after[t.name] = t.spec;
+        mergedStates[stateName] = {
+            on,
+            ...(Object.keys(after).length > 0 ? { after } : {}),
+        };
     }
-    // ── PER-USE BINDER — re-invoke body with live state + id ─────────
+    // ── PER-USE BINDER — re-invoke the closure with live state + id so methods
+    //    bind over real values. `validate` enforces invariants; `recordThat`
+    //    buffers events the runtime collects after the method returns. `when` /
+    //    `after` are no-ops here (transitions were collected at define time).
     const closureBinder = (state, id) => {
         const recorded = [];
         const liveCtx = {
@@ -189,93 +199,28 @@ function defineActorClosure(schema, body, options) {
             },
             states: stateRefs,
             when: () => { }, // no-op at runtime
-            methods: (obj) => obj,
+            after: () => { }, // no-op at runtime
         };
-        const methodsObj = (body(liveCtx) ?? {});
-        return { methods: methodsObj, recorded };
+        const methods = (body(liveCtx) ?? {});
+        return { methods, recorded };
     };
-    // Runtime schema = partial of the schema's zodSchema, like schema-bound form.
+    // Actor instances accumulate state across events — every field present-or-
+    // pending — so the runtime parser is the schema's `.partial()`.
     const runtimeSchema = schema.zodSchema.partial();
-    return {
+    const def = {
         $kind: "actor",
         name,
         schema: runtimeSchema,
         key: schema.key,
         initial: schema.initial,
         states: mergedStates,
-        // No object-form methods — runtime detects closureBinder and uses it.
         methods: undefined,
-        stuckThresholds: options.stuckThresholds,
-        slas: options.slas,
-        eventIndex: buildEventIndex(mergedStates),
         closureBinder,
-        // eslint-disable-next-line @typescript-eslint/no-explicit-any
-    };
-}
-function defineActorClassic(name, options) {
-    if (!options.states[options.initial]) {
-        throw new Error(`defineActor("${name}"): initial state "${options.initial}" is not declared in states.`);
-    }
-    for (const [stateName, stateConfig] of Object.entries(options.states)) {
-        if (stateConfig.on && stateConfig.final) {
-            throw new Error(`defineActor("${name}"): final state "${stateName}" must not declare event reactions (final states are absorbing).`);
-        }
-    }
-    return {
-        $kind: "actor",
-        name,
-        schema: options.schema,
-        key: options.key,
-        initial: options.initial,
-        states: options.states,
-        methods: options.methods,
-        stuckThresholds: options.stuckThresholds,
-        slas: options.slas,
-        eventIndex: buildEventIndex(options.states),
-    };
-}
-function defineActorBound(options) {
-    const name = options.name ?? options.schema.name;
-    const schemaStates = options.schema.states;
-    const transitions = options.states ?? {};
-    // Every state we declare transitions for must exist in the schema.
-    for (const stateName of Object.keys(transitions)) {
-        if (!(stateName in schemaStates)) {
-            throw new Error(`defineActor("${name}"): state "${stateName}" is not declared in schema "${options.schema.name}".states.`);
-        }
-        if (schemaStates[stateName]?.final && transitions[stateName]?.on) {
-            throw new Error(`defineActor("${name}"): state "${stateName}" is final in schema "${options.schema.name}" and cannot declare \`on:\` reactions.`);
-        }
-    }
-    // Build the merged states map: every schema state appears, with the actor's
-    // transitions overlaid + `final: true` propagated from the schema.
-    const mergedStates = {};
-    for (const [stateName, stateSpec] of Object.entries(schemaStates)) {
-        const t = transitions[stateName];
-        mergedStates[stateName] = {
-            ...(t ?? {}),
-            ...(stateSpec.final ? { final: true } : {}),
-        };
-    }
-    // Actor instances accumulate state across events — every field is
-    // present-or-pending. `.partial()` keeps each field's *type* validation
-    // (a string field still rejects a number) but lets the object be empty
-    // mid-lifecycle, matching how the classic positional form is used.
-    // The static type stays z.ZodObject<TFields> (what callers see); the
-    // runtime parser is the partial.
-    const runtimeSchema = options.schema.zodSchema.partial();
-    return {
-        $kind: "actor",
-        name,
-        schema: runtimeSchema,
-        key: options.schema.key,
-        initial: options.schema.initial,
-        states: mergedStates,
-        methods: options.methods,
         stuckThresholds: options.stuckThresholds,
         slas: options.slas,
         eventIndex: buildEventIndex(mergedStates),
     };
+    return def;
 }
 function buildEventIndex(states) {
     const eventIndex = new Map();
@@ -290,11 +235,7 @@ function buildEventIndex(states) {
     }
     return eventIndex;
 }
-/**
- * Helper: turn an `EventDefinition` reference into a string suitable for the
- * `on` map key. Equivalent to `Event.name` but reads as `eventKey(Event)` at
- * call sites where the import is shorter.
- */
+/** Helper: `Event.name` as a string. Reads as `eventKey(Event)` at call sites. */
 export function eventKey(event) {
     return event.name;
 }

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

@@ -1,35 +1,26 @@
 /**
- * `defineHandler` — handlers orchestrate and return events.
+ * Handler ctx + return types for forge actions.
  *
- * The handler reads the world (external APIs, cross-module `request`s), decides
- * what happened, and returns event(s). It never touches actor state, never
- * persists, never knows what state any actor is in. State changes happen
- * inside actors, driven by the events the handler returns.
+ * A forge action IS a `@nwire/handler` handler (`defineAction =
+ * defineHandler.kind("action")`). There is no separate forge handler object:
+ * this module only declares the *ctx* a forge handler body receives and what
+ * it may *return*. The handler body takes one `ctx` arg (`{ input, ... }`),
+ * the same shape as the kernel handler.
  *
- *   defineHandler(autoGrade, async (input, { request }) => {
- *     const grade = await request(evaluateGrade, { ... })
- *     return grade.confidence >= THRESHOLD
- *       ? AnswerAutoGradedEvent({ ... })
- *       : AnswerFlaggedEvent({ ... })
- *   })
- *
- * The first argument is the action's `ActionDefinition`. The action carries
- * the name + schema; the handler reads input typed against the schema. The
- * returned events route to actors + workflows and commit atomically.
- *
- * If the handler does pure side effects (no events to commit), return `void`.
- *
- * For CRUD-style handlers that don't emit events but want to surface a small
- * record to the caller (e.g. `{ userId }` for the HTTP layer to echo back),
- * return a plain object. The runtime treats it as a non-event return: nothing
- * is published, and the value flows through `runtime.dispatch`'s return + the
- * `ActionCompleted` framework event. Events vs records are disambiguated by
- * the `eventName` + `payload` shape — plain objects pass straight through.
+ * A handler orchestrates and returns events: it reads the world (external
+ * APIs, cross-module `request`s), decides what happened, and returns event(s).
+ * It never touches actor state, never persists. State changes happen inside
+ * actors, driven by the events the handler returns. For pure side effects
+ * (no events to commit) return `void`; for a CRUD record to echo to the
+ * caller, return a plain object or a `ResponseInstance` (`created(...)` /
+ * `ok(...)`).
  */
 import type { z } from "zod";
-import type { ZodTypeAny, SourceLocation } from "@nwire/messages";
+import type { ZodTypeAny, EventDefinition, EventPayload } from "@nwire/messages";
 import type { Container } from "@nwire/container";
 import type { MessageEnvelope } from "@nwire/envelope";
+import type { MessageRef } from "@nwire/app";
+import type { ResponseInstance } from "@nwire/handler";
 import type { EventMessage } from "../messages/event-message.js";
 import type { ActionDefinition, ActionInput, ActionResult } from "./define-action.js";
 import type { ActorDefinition, ActorInstanceView } from "./define-actor.js";
@@ -42,73 +33,49 @@ export interface HandlerContext {
     /** Convenience getter — equivalent to `envelope.messageId`. */
     readonly requestId: string;
     /**
-     * Cancellation signal for this dispatch. Linked to the caller (e.g.
-     * the HTTP request); when the caller closes the connection mid-flight
-     * the wire layer aborts the controller and this signal flips.
-     *
-     * Observation is opt-in — handlers may call `ctx.signal.throwIfAborted()`
-     * at await points to bail early. The runtime itself checks
-     * `signal.aborted` between retry attempts and skips remaining retries
-     * + DLQ when the caller has already given up.
-     *
-     * When `runtime.dispatch` is invoked without an explicit `signal`, this
-     * exposes an `AbortSignal` from a controller the runtime owns — never
-     * aborted, so existing handlers see the same "always runs to completion"
-     * behavior. Adding `{ signal }` to the dispatch call is the migration
-     * point.
+     * Cancellation signal for this dispatch. Linked to the caller (HTTP request,
+     * queue lock); handlers may call `ctx.signal.throwIfAborted()` at await
+     * points. The runtime checks it between retry attempts.
      */
     readonly signal: AbortSignal;
     /** Look up a dependency by name. Shortcut for `container.resolve(name)`. */
     resolve<T = unknown>(name: string): T;
     /**
-     * Logger scoped to this envelope — `messageId`, `correlationId`,
-     * `causationId`, `tenant`, `userId` are auto-attached to every line.
-     * Domain code never threads ids manually.
+     * Logger scoped to this envelope — ids auto-attached to every line. Domain
+     * code never threads ids manually.
      */
     readonly logger: Logger;
     /**
      * Universal "ask and wait." Calls another action by reference, returns its
-     * result. The framework derives a child envelope (same correlationId,
-     * causationId = this handler's messageId) and handles transport routing.
+     * result. The framework derives a child envelope and routes transport.
      */
     request<A extends ActionDefinition>(action: A, input: ActionInput<A>): Promise<ActionResult<A>>;
     /**
-     * Read-during-handler — invoke a query (projection-backed read function)
-     * scoped to the envelope's tenant. Used by reactions that need to look up
-     * state to decide what action to dispatch.
-     *
-     * Per ADR-008, queries always read projections, never actor stores. Per
-     * ADR-007, handlers stay pure of state mutation; reads via `query` are the
-     * sanctioned way to inform a handler's decision.
+     * Read-during-handler — invoke a query (projection-backed read) scoped to the
+     * envelope's tenant.
      */
     query<TResult = unknown>(query: QueryDefinition<any, any, any>, input: unknown): Promise<TResult>;
     /**
-     * Fire-and-forget dispatch of another action. Returns when the message is
-     * accepted by the transport, not when the handler completes.
+     * Fire-and-forget dispatch of another action. Returns a {@link MessageRef}
+     * naming the dispatched message as soon as it is accepted.
      */
-    send<A extends ActionDefinition>(action: A, input: ActionInput<A>): Promise<void>;
+    send<A extends ActionDefinition>(action: A, input: ActionInput<A>): Promise<MessageRef>;
+    /**
+     * Emit a domain event as a side-effect of this handler, in addition to
+     * whatever the handler returns. Publishes through the forge chain under this
+     * handler's envelope.
+     */
+    emit<E extends EventDefinition>(event: E, payload: EventPayload<E>): Promise<void>;
     /**
      * Load an actor instance by id (envelope.tenant-scoped) and return a view
      * with `state`, `stateName`, `key`, plus every method declared on the actor
-     * pre-bound to the loaded state. The view is a snapshot — subsequent
-     * dispatches do not refresh it. Re-call `ctx.use` after a dispatch that
-     * mutated the actor to observe the new state.
-     *
-     * Methods are pure: they take state, return event(s) or read values. To
-     * apply an event the method minted, return it from the handler.
-     *
-     *   const submission = await ctx.use(Submission, input.submissionId)
-     *   if (!submission.isGradable()) throw new Error('not gradable')
-     *   return submission.grade(input.verdict)  // event consumed by handler
+     * pre-bound to the loaded state.
      */
-    use<TActor extends ActorDefinition>(actor: TActor, id: string): Promise<ActorInstanceView<TActor>>;
+    actor<TActor extends ActorDefinition>(actor: TActor, id: string): Promise<ActorInstanceView<TActor>>;
     /**
-     * Invoke a declared external call (HTTP/RPC to another system). The
-     * runtime threads the declared idempotency key, applies retry policy,
-     * and emits `external.call.started/.completed/.failed` telemetry. The
-     * actual transport is the registered `ExternalCallExecutor` for this
-     * definition; if none is registered the call throws at runtime so
-     * misconfigured wiring surfaces loudly.
+     * Invoke a declared external call (HTTP/RPC to another system). The runtime
+     * threads the declared idempotency key, applies retry policy, and emits
+     * `external.call.*` telemetry.
      */
     externalCall<TRequest extends ZodTypeAny, TResponse extends ZodTypeAny>(call: ExternalCallDefinition<TRequest, TResponse>, request: z.output<TRequest>): Promise<z.output<TResponse>>;
 }
@@ -117,45 +84,8 @@ export interface HandlerContext {
  *
  * - `void` / `null` / `undefined` — pure side-effect handler, nothing to publish.
  * - `EventMessage` / `EventMessage[]` — events the runtime publishes atomically.
- * - `Record<string, unknown>` — a plain data record (e.g. `{ userId }`) that
- *   is NOT published. It flows out via `runtime.dispatch`'s return value and
- *   the `ActionCompleted` framework event. Distinguished from `EventMessage`
- *   at runtime by the missing `eventName` + `payload` shape.
- */
-export type HandlerReturn = void | EventMessage | EventMessage[] | Record<string, unknown> | null;
-/**
- * Outer-ctx shape `HandlerDefinition.run` consumes. Matches what
- * `@nwire/app`'s `Runtime.execute` builds: `input`, `envelope`, and a
- * `resolve` looking up bindings on the per-request scope. Forge's `.run`
- * implementation pulls the forge dispatcher off the container and
- * delegates so the full dispatcher pipeline (validation, action.before/
- * after hooks, retry, telemetry, persistence, …) fires.
+ * - `Record<string, unknown>` — a plain data record (e.g. `{ userId }`), NOT
+ *   published; flows out via the dispatch return + `ActionCompleted`.
+ * - `ResponseInstance` — a transport-shaped result (`created(...)` / `ok(...)`).
  */
-export interface HandlerRunCtx<TSchema extends ZodTypeAny = ZodTypeAny> {
-    readonly input: z.output<TSchema>;
-    readonly envelope?: MessageEnvelope;
-    resolve<T = unknown>(name: string): T;
-}
-export interface HandlerRunOptions {
-    readonly signal?: AbortSignal;
-}
-export interface HandlerDefinition<TSchema extends ZodTypeAny = ZodTypeAny> {
-    readonly $kind: "handler";
-    readonly action: ActionDefinition<TSchema>;
-    readonly handler: (input: z.output<TSchema>, ctx: HandlerContext) => Promise<HandlerReturn> | HandlerReturn;
-    /** Where the handler was declared. Studio uses this for IDE-open links. */
-    readonly $source?: SourceLocation;
-    /**
-     * Forge handlers satisfy the `@nwire/handler.HandlerDefinition` shape
-     * structurally so `Runtime.execute(handler, input, envelope)` works
-     * directly without the adopter knowing about forge. The fields below
-     * expose the metadata `Runtime` reads + the canonical `run()` entry
-     * point that routes through the forge dispatcher.
-     */
-    readonly name: string;
-    readonly input: TSchema;
-    run(ctx: HandlerRunCtx<TSchema>, opts?: HandlerRunOptions): Promise<{
-        result: ActionResult<ActionDefinition<TSchema>>;
-    }>;
-}
-export declare function defineHandler<TSchema extends ZodTypeAny>(action: ActionDefinition<TSchema>, handler: HandlerDefinition<TSchema>["handler"]): HandlerDefinition<TSchema>;
+export type HandlerReturn = void | EventMessage | EventMessage[] | Record<string, unknown> | ResponseInstance | null;