@nwire/forge 0.12.0 → 0.13.0

package/dist/primitives/define-action.js

@@ -1,64 +1,85 @@
 /**
- * `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 { captureSourceLocation } from "@nwire/messages";
-import { defineHandler, } from "./define-handler.js";
+import { defineHandler } from "@nwire/handler";
 export function defineAction(nameOrMeta, maybeMeta) {
-    const $source = captureSourceLocation();
     const meta = typeof nameOrMeta === "string"
         ? { ...(maybeMeta ?? {}), name: nameOrMeta }
         : nameOrMeta;
-    return buildAction(meta, $source, false);
+    return buildAction(meta, false);
 }
 /**
- * Internal — build the callable action with all meta props attached.
- * Separated so `.public()` can re-build a clone with `$public: true` while
- * sharing one construction path (avoids drift between fresh-defined and
- * cloned actions).
+ * Internal — build the callable action with the kernel handler bridged on.
+ * Separated so `.public()` re-builds a clone sharing one construction path.
  */
-function buildAction(meta, $source, isPublic) {
+function buildAction(meta, isPublic) {
+    const schema = meta.input;
+    if (!schema) {
+        throw new Error(`defineAction("${meta.name}"): an \`input\` (zod) schema is required.`);
+    }
     const factory = (input) => ({
         $kind: "command",
         actionName: meta.name,
-        input: meta.schema.parse(input),
+        input: schema.parse(input),
     });
-    // Inline handler — delegate to `defineHandler` so there is a single
-    // construction path for HandlerDefinition.
-    let handler;
-    if (meta.handler) {
-        // Will be patched onto `factory` below; build the handler def first so it
-        // references the action contract (factory itself, post-property-attach).
-        handler = undefined; // placeholder, set after props attach
-    }
+    // The action IS a handler: build it via the one definer, adapting the forge
+    // `(input, ctx)` body to the kernel single-`ctx` shape. Studio meta rides in
+    // `config.meta`; the command pipeline (retry/emits) reads forge-shaped fields
+    // off the action object directly.
+    const kernel = meta.handler
+        ? defineHandler.kind("action")(meta.name, {
+            input: schema,
+            // The body is `(ctx) => …` with `input` on ctx — same shape the kernel
+            // handler passes, so it's the handler directly (no adapter).
+            // eslint-disable-next-line @typescript-eslint/no-explicit-any
+            handler: meta.handler,
+            // eslint-disable-next-line @typescript-eslint/no-explicit-any
+            emits: meta.emits,
+            description: meta.description,
+            meta: {
+                persona: meta.persona,
+                journeyStep: meta.journeyStep,
+                capability: meta.capability,
+                slo: meta.slo,
+                tags: meta.tags,
+                // eslint-disable-next-line @typescript-eslint/no-explicit-any
+            },
+        })
+        : undefined;
     Object.defineProperties(factory, {
         $kind: { value: "action", enumerable: true },
         name: { value: meta.name, enumerable: true, configurable: true },
         description: { value: meta.description, enumerable: true },
-        schema: { value: meta.schema, enumerable: true },
+        input: { value: schema, enumerable: true },
         retry: { value: meta.retry, enumerable: true },
         policy: { value: meta.policy, enumerable: true },
         persona: { value: meta.persona, enumerable: true },
@@ -68,8 +89,55 @@ function buildAction(meta, $source, isPublic) {
         tags: { value: meta.tags, enumerable: true },
         emits: { value: meta.emits, enumerable: true },
         toString: { value: () => meta.name, enumerable: false },
-        $source: { value: $source, enumerable: false, configurable: true },
     });
+    if (kernel) {
+        Object.defineProperties(factory, {
+            // The kernel config — `runtime.execute` + `actionsPlugin` read it.
+            config: { value: kernel.config, enumerable: true, configurable: true },
+            run: {
+                value: (ctx, opts) => 
+                // eslint-disable-next-line @typescript-eslint/no-explicit-any
+                kernel.run(ctx, opts),
+                enumerable: false,
+                configurable: true,
+            },
+            use: {
+                // eslint-disable-next-line @typescript-eslint/no-explicit-any
+                value: (fn, opts) => {
+                    kernel.use(fn, opts);
+                    return factory;
+                },
+                enumerable: false,
+            },
+            on: {
+                // eslint-disable-next-line @typescript-eslint/no-explicit-any
+                value: (fn, opts) => {
+                    kernel.on(fn, opts);
+                    return factory;
+                },
+                enumerable: false,
+            },
+            off: {
+                // eslint-disable-next-line @typescript-eslint/no-explicit-any
+                value: (fn) => {
+                    kernel.off(fn);
+                    return factory;
+                },
+                enumerable: false,
+            },
+            runDetailed: {
+                // eslint-disable-next-line @typescript-eslint/no-explicit-any
+                value: (ctx, opts) => kernel.runDetailed(ctx, opts),
+                enumerable: false,
+            },
+            tap: {
+                // eslint-disable-next-line @typescript-eslint/no-explicit-any
+                value: (observer) => kernel.tap(observer),
+                enumerable: false,
+            },
+            stepCounts: { value: () => kernel.stepCounts(), enumerable: false },
+        });
+    }
     if (isPublic) {
         Object.defineProperty(factory, "$public", {
             value: true,
@@ -77,19 +145,9 @@ function buildAction(meta, $source, isPublic) {
             configurable: true,
         });
     }
-    // Now that `factory` carries all action metadata, defineHandler can bind
-    // to it as a proper ActionDefinition reference.
-    if (meta.handler) {
-        handler = defineHandler(factory, meta.handler);
-        Object.defineProperty(factory, "handler", {
-            value: handler,
-            enumerable: true,
-            configurable: true,
-        });
-    }
     Object.defineProperty(factory, "public", {
         value: function publicMarker() {
-            return buildAction(meta, $source, true);
+            return buildAction(meta, true);
         },
         enumerable: false,
         configurable: true,
@@ -109,10 +167,7 @@ export function isCommandMessage(x) {
 }
 /**
  * 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 function resolveDispatch(actionOrCmd, input, lookup) {
     if (isCommandMessage(actionOrCmd)) {
@@ -120,7 +175,7 @@ export function resolveDispatch(actionOrCmd, input, lookup) {
         if (!action) {
             throw new Error(`dispatch: action "${actionOrCmd.actionName}" is not registered. ` +
                 `If you used the callable form (\`execute(myAction(input))\`), make ` +
-                `sure the action is included in a module's \`actions\` array.`);
+                `sure the action is included in the app's \`handlers\`.`);
         }
         return { action, input: actionOrCmd.input };
     }

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

@@ -1,195 +1,143 @@
 /**
  * `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 type { z } from "zod";
-import type { ZodTypeAny, SourceLocation } from "@nwire/messages";
-import type { EventDefinition } from "@nwire/messages";
-import { type SchemaDefinition } from "./define-schema.js";
+import type { ZodTypeAny, EventDefinition } from "@nwire/messages";
+import type { SchemaDefinition } from "./define-schema.js";
 /**
  * Reaction to one event in one state.
- *
- *   - `target` — name of the state to transition to (omit to stay in this state).
- *   - `assign` — pure function returning a partial to merge into ctx.
- *               MUST be synchronous, MUST NOT mutate ctx, MUST NOT do I/O.
+ *   - `target` — name of the state to transition to (omit to stay).
+ *   - `assign` — pure function returning a partial to merge into the data.
  */
 export interface ActorReaction<TCtx, TEvent> {
     readonly target?: string;
     readonly assign?: (ctx: Readonly<TCtx>, event: TEvent) => Partial<TCtx>;
 }
-/**
- * Spec for one timer in a state's `after` block. `'3d'` = key, value is the
- * action to send when the timer fires (or an `{ delay, action }` form when the
- * timer name and the delay differ).
- */
+/** Spec for one timer in a state's `after` block. */
 export interface ActorTimerSpec {
     readonly delay: string;
     /** The action name to dispatch when the timer fires. */
     readonly action: string;
-    /**
-     * Optional: a function that builds the action's input from the actor's
-     * current ctx + key. Defaults to `{ <key>: actorKey }`.
-     */
+    /** Optional: build the action's input from ctx + key. Defaults to `{ <key>: actorKey }`. */
     readonly buildInput?: (ctx: unknown, key: string) => unknown;
 }
-/**
- * Configuration for one state of an actor.
- */
+/** Configuration for one state of an actor (the runtime-facing shape). */
 export interface ActorStateConfig<TCtx> {
     /** Reactions to events while in this state. Keyed by event name. */
     readonly on?: Readonly<Record<string, ActorReaction<TCtx, unknown>>>;
-    /**
-     * Timers scheduled on entry to this state, cancelled on exit.
-     * Keyed by timer name. Value is either a delay string + action name,
-     * or just an action name with the timer name used as the delay key.
-     */
+    /** Timers scheduled on entry, cancelled on exit. Keyed by timer name. */
     readonly after?: Readonly<Record<string, string | ActorTimerSpec>>;
     /** Mark this state as the lifecycle end. */
     readonly final?: boolean;
 }
 /**
- * A pure invariant-enforcer + event-minter method. Methods take the actor's
- * current state (read-only) plus method args, and either return an event
- * (or events), throw on invariant violation, or return a read-only value
- * (for queries like `isGradable()`). Methods MUST NOT do I/O or read other
- * actors — that lives in the handler.
- *
- *   methods: {
- *       flagForReview(state, reason: string): EventMessage {
- *           if (state.status !== 'pending') throw new Error('only pending')
- *           return FlaggedForReviewEvent({ reason, flaggedAt: ... })
- *       },
- *       isGradable(state): boolean {
- *           return state.status === 'pending' && state.flags === 0
- *       }
- *   }
+ * A pure invariant-enforcer + event-minter method. Takes the actor's current
+ * state (read-only) plus args; returns event(s), throws on invariant violation,
+ * or returns a read value. MUST NOT do I/O or read other actors.
  */
 export type ActorMethod<TCtx> = (state: TCtx, ...args: any[]) => any;
-/**
- * `defineActor` options. `TSchema` typically a `z.ZodObject` describing the
- * actor's data shape — every field of the schema is part of the actor's `ctx`.
- */
-/**
- * Per-state "stuck" thresholds (milliseconds). When an actor instance has
- * been in this state for >= the threshold, Studio surfaces it in the
- * stuck-state inbox. Use this to declare "if a submission is in
- * under-review for >48h, something needs Dina's attention."
- */
+/** Per-state "stuck" thresholds (ms) — Studio surfaces instances exceeding them. */
 export type ActorStuckThresholds = Readonly<Record<string, number>>;
-/**
- * Per-state SLA declaration. `maxDurationMs` is the hard limit; once
- * crossed, Studio raises an alert. `escalateTo` is a free-form audience tag
- * (consumed by alerting integrations).
- */
+/** Per-state SLA declaration with escalation hint. */
 export interface ActorSlaConfig {
     readonly maxDurationMs: number;
     readonly escalateTo?: string;
 }
 export type ActorSlas = Readonly<Record<string, ActorSlaConfig>>;
-export interface ActorOptions<TSchema extends ZodTypeAny, TMethods extends Readonly<Record<string, ActorMethod<z.output<TSchema>>>> = Readonly<Record<string, ActorMethod<z.output<TSchema>>>>> {
-    readonly schema: TSchema;
-    /** Field path in event payloads used to look up the actor instance. */
-    readonly key: string;
-    /** Initial state name. The first event for an unknown key starts here. */
-    readonly initial: string;
-    /** State machine configuration. */
-    readonly states: Readonly<Record<string, ActorStateConfig<z.output<TSchema>>>>;
-    /**
-     * Optional pure methods callable from a handler via `ctx.use(Actor, id)`.
-     * Each method receives the current state pre-bound; it returns event(s)
-     * (which the handler returns to the runtime), throws on invariant
-     * violation, or returns a non-event read value.
-     */
-    readonly methods?: TMethods;
-    /**
-     * Studio-aware: stuck-state thresholds in ms. Studio surfaces actor
-     * instances exceeding the threshold. Example for Submission actor:
-     * `{ 'under-review': 3 * 24 * 60 * 60 * 1000 }` (3 days).
-     */
-    readonly stuckThresholds?: ActorStuckThresholds;
-    /**
-     * Studio-aware: per-state hard SLAs with escalation hints.
-     * `{ 'under-review': { maxDurationMs: 7 * 24 * 60 * 60 * 1000, escalateTo: 'curriculum-lead' } }`.
-     */
-    readonly slas?: ActorSlas;
-}
 /**
- * A typed state reference produced by `states.<name>` inside the closure
- * form. Returning a StateRef from a transition tells the runtime which state
- * to transition into.
+ * A callable state body — `states.<name>`. Call it with a body to scope the
+ * `when`s inside to that state (`submitted(() => when(…))`); return it from a
+ * reaction to transition there (`return graded`). Same idea as the workflow
+ * state callable.
  */
 export interface StateRef {
+    (body: () => void): void;
     readonly $kind: "state-ref";
     readonly name: string;
 }
-/**
- * Closure-form context — what the actor body receives when called as
- * `defineActor(schema, ({data, id, validate, recordThat, states, when, methods}) => ...)`.
- * At define time `data`/`id` are placeholders; at each `use()` call the
- * closure is re-invoked with the live instance state + key.
- */
-export interface ActorClosureContext<TState> {
-    readonly data: TState;
+/** Action reference (or bare name) used as a timer's target. */
+export type ActorTimerAction = string | {
+    readonly name: string;
+};
+/** What the actor builder closure receives — the workflow ctx, minus effects. */
+export interface ActorBuilderContext<TState> {
+    /**
+     * Live view of the instance's current data — a proxy that reads the data the
+     * reaction is folding over. Read it to compute the next value (e.g.
+     * `assign({ count: (data.count ?? 0) + 1 })`), same as a workflow's `data`.
+     */
+    readonly data: Readonly<TState>;
+    /** The instance id (the schema `key`'s value). Live inside a method call. */
     readonly id: string;
+    /**
+     * Enforce invariants from a method: each predicate returns `true` or a
+     * failure message; any failure throws an `InvariantError`. `state` defaults
+     * to the live instance data. No-op during the define-time pass.
+     */
     readonly validate: <TIn>(input: TIn, predicates: ReadonlyArray<(input: TIn, state?: TState) => true | string>, state?: TState) => void;
+    /** Mint a domain event from a method; collected + published after the call. */
     readonly recordThat: (event: {
         eventName: string;
         payload: unknown;
     }) => void;
+    /** Callable state bodies, sourced from the schema (+ injected terminal). */
     readonly states: Record<string, StateRef>;
-    readonly when: <E extends {
+    /** The one event verb. Top-level = always-active; inside a state body = scoped. */
+    when<E extends {
         name: string;
     }>(event: E, fn: (payload: any, ctx: {
         assign: (delta: Partial<TState>) => void;
-    }) => StateRef | void) => void;
-    readonly methods: <T extends Record<string, (...args: never[]) => unknown>>(obj: T) => T;
+    }) => StateRef | void): void;
+    /** Schedule a state-entry timer (cancelled on exit). Scoped to the current state body. */
+    after(name: string, delay: string, action: ActorTimerAction): void;
+}
+/** Options for `defineActor(name, body, options)`. */
+export interface ActorOptions<TFields extends Readonly<Record<string, ZodTypeAny>>> {
+    /** Data shape + key + lifecycle states (from `defineSchema`). */
+    readonly schema: SchemaDefinition<TFields>;
+    readonly stuckThresholds?: ActorStuckThresholds;
+    readonly slas?: ActorSlas;
 }
 /**
  * `ActorDefinition` is the data the runtime registers and dispatches against.
- * `defineActor` returns this; consumers should not construct it manually.
  */
-export interface ActorDefinition<TSchema extends ZodTypeAny = ZodTypeAny, TMethods extends Readonly<Record<string, ActorMethod<z.output<TSchema>>>> = Readonly<Record<string, ActorMethod<z.output<TSchema>>>>> {
+export interface ActorDefinition<TSchema extends ZodTypeAny = ZodTypeAny, TMethods extends Readonly<Record<string, (...args: any[]) => unknown>> = Readonly<Record<string, (...args: any[]) => unknown>>> {
     readonly $kind: "actor";
     readonly name: string;
     readonly schema: TSchema;
@@ -199,105 +147,46 @@ export interface ActorDefinition<TSchema extends ZodTypeAny = ZodTypeAny, TMetho
     readonly methods?: TMethods;
     readonly stuckThresholds?: ActorStuckThresholds;
     readonly slas?: ActorSlas;
-    /**
-     * Quick-lookup index: every event name this actor reacts to in any state,
-     * with the list of (stateName, reaction) entries that handle it. Built at
-     * definition time so dispatch is O(1) per event.
-     */
+    /** event name → [(state, reaction)] handling it. Built at definition time. */
     readonly eventIndex: ReadonlyMap<string, ReadonlyArray<{
         state: string;
         reaction: ActorReaction<z.output<TSchema>, unknown>;
     }>>;
     /**
-     * Closure-form binder. When set, `runtime.use(Actor, id)` calls this with
-     * the live `state` + `id` to produce the bound methods. Methods record
-     * events via `recordThat`, which the framework collects after the method
-     * returns. Methods may also return a value to the caller.
-     *
-     * `null` for classic / schema-bound-object actors.
+     * Per-use binder. `ctx.actor(Actor, id)` calls it with the live `state` + `id`
+     * to re-invoke the closure and produce methods bound over that instance;
+     * methods record events via `recordThat`, collected from `recorded` after each
+     * call. (Methods come from the closure's returned object, not options.)
      */
     readonly closureBinder?: (state: z.output<TSchema>, id: string) => {
         methods: Record<string, (...args: unknown[]) => unknown>;
-        /** Events emitted by the most recent method call. Cleared each call. */
         recorded: ReadonlyArray<{
             eventName: string;
             payload: unknown;
         }>;
     };
-    /** Where the actor was declared. Studio uses this for IDE-open links. */
-    readonly $source?: SourceLocation;
 }
 /**
- * The shape returned by `ctx.use(Actor, id)`: the loaded `state` plus every
- * method from the actor definition, pre-bound to that state.
+ * The shape returned by `ctx.actor(Actor, id)`: the loaded `state` plus every
+ * method, pre-bound to that state.
  */
 export type ActorInstanceView<TActor> = TActor extends ActorDefinition<infer TSchema, infer TMethods> ? {
     readonly state: Readonly<z.output<TSchema>>;
     readonly key: string;
     readonly stateName: string;
 } & {
-    readonly [K in keyof TMethods]: TMethods[K] extends (state: z.output<TSchema>, ...args: infer A) => infer R ? (...args: A) => R : never;
+    readonly [K in keyof TMethods]: TMethods[K] extends (...args: infer A) => infer R ? (...args: A) => R : never;
 } : never;
 /**
- * Schema-bound form: the actor borrows `key`, `initial`, and the set of valid
- * state names from a `SchemaDefinition`. Per-state `on`/`after` transitions are
- * still declared here, but only for states declared in the schema. States the
- * schema marks `final: true` cannot have `on:` reactions.
+ * Define an actor — one builder closure + a `defineSchema` for the shape.
  *
- *   const Submission = defineActor({
- *     schema: SubmissionData,           // SchemaDefinition
- *     states: {
- *       submitted:      { on: { ... } },
- *       "under-review": { on: { ... }, after: { ... } },
- *       // graded is final in the schema — omit it
- *     },
- *     methods: { ... },
- *   });
- */
-export interface ActorOptionsBound<TFields extends Readonly<Record<string, ZodTypeAny>>, TMethods extends Readonly<Record<string, ActorMethod<z.output<z.ZodObject<TFields>>>>> = Readonly<Record<string, ActorMethod<z.output<z.ZodObject<TFields>>>>>> {
-    /** Optional — defaults to `schema.name`. */
-    readonly name?: string;
-    readonly schema: SchemaDefinition<TFields>;
-    /** Per-state transition tables. Only states declared in the schema are valid. */
-    readonly states?: Readonly<Record<string, ActorStateConfig<z.output<z.ZodObject<TFields>>>>>;
-    readonly methods?: TMethods;
-    readonly stuckThresholds?: ActorStuckThresholds;
-    readonly slas?: ActorSlas;
-}
-/**
- * Closure form options — what `defineActor(schema, fn, options?)` accepts
- * for stuckThresholds + slas + name override. The transitions + methods
- * live in the closure body.
- */
-export interface ActorOptionsClosure {
-    readonly name?: string;
-    readonly stuckThresholds?: ActorStuckThresholds;
-    readonly slas?: ActorSlas;
-}
-export declare function defineActor<TSchema extends ZodTypeAny, TMethods extends Readonly<Record<string, ActorMethod<z.output<TSchema>>>> = Readonly<Record<string, ActorMethod<z.output<TSchema>>>>>(name: string, options: ActorOptions<TSchema, TMethods>): ActorDefinition<TSchema, TMethods>;
-export declare function defineActor<TFields extends Readonly<Record<string, ZodTypeAny>>, TMethods extends Readonly<Record<string, ActorMethod<z.output<z.ZodObject<TFields>>>>> = Readonly<Record<string, ActorMethod<z.output<z.ZodObject<TFields>>>>>>(options: ActorOptionsBound<TFields, TMethods>): ActorDefinition<z.ZodObject<TFields>, TMethods>;
-/**
- * Closure form:
- *
- *   const Station = defineActor(StationData,
- *     ({ data, id, validate, recordThat, states, when, methods }) => {
- *       const { active, decommissioned } = states
- *       const create = (input) => { validate(...); recordThat(Created({...})); }
- *       when(Created, (e, { assign }) => { assign({...}) })
- *       when(Deleted, (e, { assign }) => { assign({...}); return decommissioned })
- *       return methods({ create })
- *     },
- *     { stuckThresholds: { ... } },
- *   )
- *
- * The closure runs once at define time to register transitions + capture
- * method names; the runtime re-runs it per `use(Actor, id)` call to produce
- * bound methods over the live state.
- */
-export declare function defineActor<TFields extends Readonly<Record<string, ZodTypeAny>>>(schema: SchemaDefinition<TFields>, body: (ctx: ActorClosureContext<z.output<z.ZodObject<TFields>>>) => Record<string, (...args: never[]) => unknown> | void, options?: ActorOptionsClosure): ActorDefinition<z.ZodObject<TFields>, any>;
-/**
- * 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.
- */
+ * 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).
+ */
+export declare function defineActor<TFields extends Readonly<Record<string, ZodTypeAny>>, TMethods extends Readonly<Record<string, (...args: any[]) => unknown>> = Record<string, never>>(name: string, body: (ctx: ActorBuilderContext<z.output<z.ZodObject<TFields>>>) => TMethods, options: ActorOptions<TFields>): ActorDefinition<z.ZodObject<TFields>, TMethods>;
+/** Helper: `Event.name` as a string. Reads as `eventKey(Event)` at call sites. */
 export declare function eventKey(event: EventDefinition): string;