@nwire/forge 0.7.0

package/dist/define-action.d.ts

@@ -0,0 +1,148 @@
+/**
+ * `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.
+ *
+ *   export const submitAnswer = defineAction({
+ *     name: 'submissions.submit-answer',
+ *     description: 'Avi submits his answer to an exercise.',
+ *     schema: SubmitAnswerInput,
+ *   })
+ *
+ * An action carries a `name` (its routing key) and a `schema` (input type).
+ * Pass it by reference to `defineHandler(action, fn)`, `ctx.request(action, ...)`,
+ * or `ctx.send(action, ...)`. The name is the identity everywhere — Studio,
+ * telemetry, OpenAPI, and the event graph all key off it.
+ *
+ * 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`.
+ */
+import type { z } from "zod";
+import type { ZodTypeAny } from "@nwire/messages";
+import type { EventDefinition } from "@nwire/messages";
+import type { HandlerDefinition, HandlerReturn, HandlerContext } from "./define-handler.js";
+import { type PublicMarker } from "./public-marker.js";
+/**
+ * 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).
+ */
+export interface RetryPolicy {
+    /** Maximum retry attempts after the initial try. Default: 0 (no retry). */
+    readonly max: number;
+    /** Backoff strategy. Default: `'exponential'`. */
+    readonly backoff?: "exponential" | "fixed";
+    /** Base delay in ms for backoff (default 100ms). */
+    readonly baseDelayMs?: number;
+    /** Cap on the per-attempt delay (default 30s). */
+    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.
+ */
+export interface ActionSlo {
+    /** Declared p95 latency target in milliseconds. */
+    readonly p95LatencyMs?: number;
+    /** Declared success rate target (0–1). */
+    readonly successRate?: number;
+}
+export interface ActionDefinition<TSchema extends ZodTypeAny = ZodTypeAny> extends PublicMarker {
+    readonly $kind: "action";
+    readonly name: string;
+    readonly description?: string;
+    readonly schema: 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']`.
+     */
+    readonly policy?: string | readonly string[];
+    /**
+     * 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)'`.
+     */
+    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'`.
+     */
+    readonly journeyStep?: string;
+    /**
+     * High-level capability name (UDOO-framework concept). Groups actions
+     * by what they enable. Example: `'submit-answer'`, `'review-flagged'`.
+     */
+    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.).
+     */
+    readonly handler?: HandlerDefinition;
+    /**
+     * 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).
+     */
+    readonly emits?: readonly EventDefinition[];
+}
+export interface ActionMeta<TSchema extends ZodTypeAny = ZodTypeAny> {
+    readonly name: string;
+    readonly description?: string;
+    readonly schema: TSchema;
+    readonly retry?: RetryPolicy;
+    readonly policy?: string | readonly string[];
+    /** 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`. */
+    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.
+     */
+    readonly handler?: (input: z.output<TSchema>, ctx: HandlerContext) => Promise<HandlerReturn> | HandlerReturn;
+}
+export declare function defineAction<TSchema extends ZodTypeAny>(meta: ActionMeta<TSchema>): ActionDefinition<TSchema>;
+export declare function defineAction<TSchema extends ZodTypeAny>(name: string, meta: Omit<ActionMeta<TSchema>, "name">): ActionDefinition<TSchema>;
+export type ActionInput<A> = A extends ActionDefinition<infer S> ? z.output<S> : never;
+//# sourceMappingURL=define-action.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"define-action.d.ts","sourceRoot":"","sources":["../src/define-action.ts"],"names":[],"mappings":"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"}

package/dist/define-action.js

@@ -0,0 +1,52 @@
+/**
+ * `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.
+ *
+ *   export const submitAnswer = defineAction({
+ *     name: 'submissions.submit-answer',
+ *     description: 'Avi submits his answer to an exercise.',
+ *     schema: SubmitAnswerInput,
+ *   })
+ *
+ * An action carries a `name` (its routing key) and a `schema` (input type).
+ * Pass it by reference to `defineHandler(action, fn)`, `ctx.request(action, ...)`,
+ * or `ctx.send(action, ...)`. The name is the identity everywhere — Studio,
+ * telemetry, OpenAPI, and the event graph all key off it.
+ *
+ * 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`.
+ */
+import { markable } from "./public-marker.js";
+export function defineAction(nameOrMeta, maybeMeta) {
+    const meta = typeof nameOrMeta === "string"
+        ? { ...(maybeMeta ?? {}), name: nameOrMeta }
+        : nameOrMeta;
+    const action = {
+        $kind: "action",
+        name: meta.name,
+        description: meta.description,
+        schema: meta.schema,
+        retry: meta.retry,
+        policy: meta.policy,
+        persona: meta.persona,
+        journeyStep: meta.journeyStep,
+        capability: meta.capability,
+        slo: meta.slo,
+        tags: meta.tags,
+        emits: meta.emits,
+    };
+    if (meta.handler) {
+        const userFn = meta.handler;
+        const handler = {
+            $kind: "v3-handler",
+            action: action,
+            handler: userFn,
+        };
+        return markable({ ...action, handler });
+    }
+    return markable(action);
+}
+//# sourceMappingURL=define-action.js.map

package/dist/define-action.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"define-action.js","sourceRoot":"","sources":["../src/define-action.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAMH,OAAO,EAAE,QAAQ,EAAqB,MAAM,iBAAiB,CAAC;AA2I9D,MAAM,UAAU,YAAY,CAC1B,UAAwC,EACxC,SAA6C;IAE7C,MAAM,IAAI,GACR,OAAO,UAAU,KAAK,QAAQ;QAC5B,CAAC,CAAE,EAAE,GAAG,CAAC,SAAS,IAAI,EAAE,CAAC,EAAE,IAAI,EAAE,UAAU,EAA0B;QACrE,CAAC,CAAC,UAAU,CAAC;IAEjB,MAAM,MAAM,GAAG;QACb,KAAK,EAAE,QAAiB;QACxB,IAAI,EAAE,IAAI,CAAC,IAAI;QACf,WAAW,EAAE,IAAI,CAAC,WAAW;QAC7B,MAAM,EAAE,IAAI,CAAC,MAAM;QACnB,KAAK,EAAE,IAAI,CAAC,KAAK;QACjB,MAAM,EAAE,IAAI,CAAC,MAAM;QACnB,OAAO,EAAE,IAAI,CAAC,OAAO;QACrB,WAAW,EAAE,IAAI,CAAC,WAAW;QAC7B,UAAU,EAAE,IAAI,CAAC,UAAU;QAC3B,GAAG,EAAE,IAAI,CAAC,GAAG;QACb,IAAI,EAAE,IAAI,CAAC,IAAI;QACf,KAAK,EAAE,IAAI,CAAC,KAAK;KAClB,CAAC;IACF,IAAI,IAAI,CAAC,OAAO,EAAE,CAAC;QACjB,MAAM,MAAM,GAAG,IAAI,CAAC,OAAO,CAAC;QAC5B,MAAM,OAAO,GAAsB;YACjC,KAAK,EAAE,YAAY;YACnB,MAAM,EAAE,MAAmC;YAC3C,OAAO,EAAE,MAAsC;SAChD,CAAC;QACF,OAAO,QAAQ,CAAC,EAAE,GAAG,MAAM,EAAE,OAAO,EAAE,CAA8B,CAAC;IACvE,CAAC;IACD,OAAO,QAAQ,CAAC,MAAM,CAA8B,CAAC;AACvD,CAAC"}

package/dist/define-actor.d.ts

@@ -0,0 +1,302 @@
+/**
+ * `defineActor` — the primitive for entities that carry state, transitions,
+ * and timers. The actor is data + state machine in one declaration.
+ *
+ *   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 }
+ *     }
+ *   })
+ *
+ * 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
+ */
+import type { z } from "zod";
+import type { ZodTypeAny } from "@nwire/messages";
+import type { 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.
+ */
+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).
+ */
+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 }`.
+     */
+    readonly buildInput?: (ctx: unknown, key: string) => unknown;
+}
+/**
+ * Configuration for one state of an actor.
+ */
+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.
+     */
+    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
+ *       }
+ *   }
+ */
+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."
+ */
+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).
+ */
+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.
+ */
+export interface StateRef {
+    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;
+    readonly id: string;
+    readonly validate: <TIn>(input: TIn, predicates: ReadonlyArray<(input: TIn, state?: TState) => true | string>, state?: TState) => void;
+    readonly recordThat: (event: {
+        eventName: string;
+        payload: unknown;
+    }) => void;
+    readonly states: Record<string, StateRef>;
+    readonly 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;
+}
+/**
+ * `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>>>>> {
+    readonly $kind: "actor";
+    readonly name: string;
+    readonly schema: TSchema;
+    readonly key: string;
+    readonly initial: string;
+    readonly states: Readonly<Record<string, ActorStateConfig<z.output<TSchema>>>>;
+    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.
+     */
+    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.
+     */
+    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;
+        }>;
+    };
+}
+/**
+ * The shape returned by `ctx.use(Actor, id)`: the loaded `state` plus every
+ * method from the actor definition, 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;
+} : 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.
+ *
+ *   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.
+ */
+export declare function eventKey(event: EventDefinition): string;
+//# sourceMappingURL=define-actor.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"define-actor.d.ts","sourceRoot":"","sources":["../src/define-actor.ts"],"names":[],"mappings":"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"}