@nwire/forge 0.12.1 → 0.13.0

package/dist/primitives/define-handler.js

@@ -1,49 +1,18 @@
 /**
- * `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 { captureSourceLocation } from "@nwire/messages";
-// Forge dispatcher binding name — duplicated here to avoid a runtime →
-// primitives import cycle. Matches `FORGE_DISPATCHER_BINDING` in
-// `runtime/forge-plugin.ts`.
-const FORGE_DISPATCHER_BINDING = "forge.dispatcher";
-export function defineHandler(action, handler) {
-    const def = {
-        $kind: "handler",
-        action,
-        handler,
-        $source: captureSourceLocation(),
-        name: action.name,
-        input: action.schema,
-        async run(ctx, opts) {
-            const dispatcher = ctx.resolve(FORGE_DISPATCHER_BINDING);
-            const result = await dispatcher.dispatch(action, ctx.input, ctx.envelope, { signal: opts?.signal });
-            return { result };
-        },
-    };
-    return def;
-}
+export {};

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

@@ -1,43 +1,38 @@
 /**
  * `defineProjection` — first-class CQRS read models.
  *
- *   export const SubmissionsByStudent = defineProjection('submissions-by-student', {
- *     listens: [AnswerSubmittedEvent, SubmissionAutoGradedEvent, ...],
- *     initial: () => ({}),
- *     on: {
- *       [AnswerSubmittedEvent.name]: (state, event) => ({
- *         ...state,
- *         [event.submissionId]: { ... }
- *       }),
- *       ...
- *     }
- *   })
+ *   export const SubmissionsByStudent = defineProjection("submissions-by-student",
+ *     ({ when }) => {
+ *       when(AnswerWasSubmitted, (state, e) => ({ ...state, [e.submissionId]: e }));
+ *       when(SubmissionWasAutoGraded, (state, e) => ({ ...state, [e.submissionId]: { ...state[e.submissionId], verdict: e.verdict } }));
+ *     },
+ *     { initial: () => ({}) },
+ *   );
  *
- * Projections are pure folds over event streams: `(state, event) => state`.
- * The runtime registers a `when` listener for each event in `listens` and
- * applies the corresponding `on` reducer to the projection's state.
+ * Projections are pure folds over event streams: `(state, event) => state`. The
+ * builder is a closure exposing the one event verb, `when` — each `when(Event,
+ * reducer)` registers a fold and adds the event to what the projection listens
+ * for (no separate `listens` list, no `on:{}` keyed by string). The runtime
+ * registers a `when` listener per event and applies the matching reducer.
  *
- * Queries (`defineQuery`) read from projections, not from actors. This
- * preserves the CQRS separation: writes go through actors, reads through
- * projections.
- *
- * Side effects (notifications, external sync) belong in `when` reactions, not
- * in projections — projections are pure folds, like `assign`.
+ * Queries (`defineQuery`) read from projections, not actors — CQRS separation:
+ * writes through actors, reads through projections. Side effects belong in `when`
+ * reactions (listeners / workflows), never in a projection — folds stay pure.
  */
-import type { EventDefinition, EventPayload, SourceLocation } from "@nwire/messages";
+import type { EventDefinition, EventPayload } from "@nwire/messages";
 export type ProjectionReducer<TState, E extends EventDefinition = EventDefinition> = (state: TState, event: EventPayload<E>) => TState;
 /** Studio-aware: declared read-model freshness target. */
 export interface ProjectionFreshness {
     /** Declared p95 milliseconds the projection lags behind the event stream. */
     readonly p95MsBehindStream?: number;
 }
+/** The one event verb, in the projection builder: register a fold for an event. */
+export interface ProjectionBuilderContext<TState> {
+    when<E extends EventDefinition>(event: E, reducer: (state: TState, event: EventPayload<E>) => TState): void;
+}
 export interface ProjectionOptions<TState> {
-    /** The events this projection folds over. Order matters for `on` lookup. */
-    readonly listens: readonly EventDefinition[];
     /** Factory for the initial state when no events have been seen yet. */
     readonly initial: () => TState;
-    /** Pure reducers, keyed by event name. */
-    readonly on: Readonly<Record<string, ProjectionReducer<TState>>>;
     /** Free-form description (Studio-aware). */
     readonly description?: string;
     /** Declared freshness SLO (Studio-aware). */
@@ -46,12 +41,12 @@ export interface ProjectionOptions<TState> {
 export interface ProjectionDefinition<TState = unknown> {
     readonly $kind: "projection";
     readonly name: string;
+    /** Events folded over — derived from the `when` calls. */
     readonly listens: readonly EventDefinition[];
     readonly initial: () => TState;
+    /** Pure reducers, keyed by event name — derived from the `when` calls. */
     readonly on: Readonly<Record<string, ProjectionReducer<TState>>>;
     readonly description?: string;
     readonly freshness?: ProjectionFreshness;
-    /** Where the projection was declared. Studio uses this for IDE-open links. */
-    readonly $source?: SourceLocation;
 }
-export declare function defineProjection<TState>(name: string, options: ProjectionOptions<TState>): ProjectionDefinition<TState>;
+export declare function defineProjection<TState>(name: string, build: (ctx: ProjectionBuilderContext<TState>) => void, options: ProjectionOptions<TState>): ProjectionDefinition<TState>;

package/dist/primitives/define-projection.js

@@ -1,46 +1,43 @@
 /**
  * `defineProjection` — first-class CQRS read models.
  *
- *   export const SubmissionsByStudent = defineProjection('submissions-by-student', {
- *     listens: [AnswerSubmittedEvent, SubmissionAutoGradedEvent, ...],
- *     initial: () => ({}),
- *     on: {
- *       [AnswerSubmittedEvent.name]: (state, event) => ({
- *         ...state,
- *         [event.submissionId]: { ... }
- *       }),
- *       ...
- *     }
- *   })
+ *   export const SubmissionsByStudent = defineProjection("submissions-by-student",
+ *     ({ when }) => {
+ *       when(AnswerWasSubmitted, (state, e) => ({ ...state, [e.submissionId]: e }));
+ *       when(SubmissionWasAutoGraded, (state, e) => ({ ...state, [e.submissionId]: { ...state[e.submissionId], verdict: e.verdict } }));
+ *     },
+ *     { initial: () => ({}) },
+ *   );
  *
- * Projections are pure folds over event streams: `(state, event) => state`.
- * The runtime registers a `when` listener for each event in `listens` and
- * applies the corresponding `on` reducer to the projection's state.
+ * Projections are pure folds over event streams: `(state, event) => state`. The
+ * builder is a closure exposing the one event verb, `when` — each `when(Event,
+ * reducer)` registers a fold and adds the event to what the projection listens
+ * for (no separate `listens` list, no `on:{}` keyed by string). The runtime
+ * registers a `when` listener per event and applies the matching reducer.
  *
- * Queries (`defineQuery`) read from projections, not from actors. This
- * preserves the CQRS separation: writes go through actors, reads through
- * projections.
- *
- * Side effects (notifications, external sync) belong in `when` reactions, not
- * in projections — projections are pure folds, like `assign`.
+ * Queries (`defineQuery`) read from projections, not actors — CQRS separation:
+ * writes through actors, reads through projections. Side effects belong in `when`
+ * reactions (listeners / workflows), never in a projection — folds stay pure.
  */
-import { captureSourceLocation } from "@nwire/messages";
-export function defineProjection(name, options) {
-    const $source = captureSourceLocation();
-    // Validate that every listened event has a reducer.
-    for (const event of options.listens) {
-        if (!options.on[event.name]) {
-            throw new Error(`defineProjection("${name}"): event "${event.name}" is in 'listens' but has no reducer in 'on'.`);
-        }
-    }
+export function defineProjection(name, build, options) {
+    const listens = [];
+    const on = {};
+    build({
+        when(event, reducer) {
+            if (on[event.name]) {
+                throw new Error(`defineProjection("${name}"): event "${event.name}" has more than one when() reducer.`);
+            }
+            listens.push(event);
+            on[event.name] = reducer;
+        },
+    });
     return {
         $kind: "projection",
         name,
-        listens: options.listens,
+        listens,
         initial: options.initial,
-        on: options.on,
+        on,
         description: options.description,
         freshness: options.freshness,
-        $source,
     };
 }

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

@@ -1,36 +1,37 @@
 /**
- * `defineQuery` — read function over a projection or a direct adapter (DB,
- * cache, search index). Two forms:
+ * `defineQuery` — a read over a projection or a direct adapter (DB, cache,
+ * search). A query IS a handler: like actions it is built via the one definer
+ * (`defineHandler.kind("query")`), so it carries `.run` / `config` and can be
+ * wired to a transport (HTTP GET), dispatched via `runtime.execute`, and
+ * registered by the app (`createApp({ handlers })`) — same surface as any
+ * handler. What's query-specific stays query-specific: it does NOT go through
+ * the command pipeline (no retry / publish / commit), and execution delegates
+ * to the read engine (`QueryRunner`), which loads projection state or runs the
+ * handler closure.
  *
  *   // Projection-driven — runtime hands you `state` + validated input.
  *   export const submissionsByStudent = defineQuery(SubmissionsByStudent, {
- *     name: 'submissions.by-student',
- *     schema: z.object({ studentId: StudentId }),
+ *     name: "submissions.by-student",
+ *     input: z.object({ studentId: StudentId }),
  *     execute: (state, { studentId }) =>
- *       Object.values(state).filter(s => s.studentId === studentId),
+ *       Object.values(state).filter((s) => s.studentId === studentId),
  *   })
  *
- *   // Handler form — no projection, you reach into the container yourself.
+ *   // Handler form — no projection; reach into the container yourself.
  *   export const usersById = defineQuery({
- *     name: 'users.by-id',
- *     schema: z.object({ id: UserId }),
- *     handler: async ({ id }, { resolve }) => {
- *       const db = resolve<DrizzleDb>('db');
+ *     name: "users.by-id",
+ *     input: z.object({ id: UserId }),
+ *     handler: async ({ input: { id }, resolve }) => {
+ *       const db = resolve<DrizzleDb>("db");
  *       return db.select().from(users).where(eq(users.id, id)).limit(1);
  *     },
  *   })
  *
- * Pick projection form when the read is "eventually-consistent over events
- * I publish in-process." Pick handler form when reading from any external
- * source of truth (Postgres rows, Redis, OpenSearch) — no projection layer
- * needed. Queries are always direct calls: no envelope, no bus, no commit.
- *
- * Naming follows actions: `<domain>.<verb-noun>` so a query is addressable
- * on the same routing keyspace as actions when transports need it (HTTP GET
- * routes wire queries; HTTP POST routes wire actions).
+ * Naming follows actions: `<domain>.<verb-noun>`.
  */
 import type { z } from "zod";
-import type { ZodTypeAny, SourceLocation } from "@nwire/messages";
+import type { ZodTypeAny } from "@nwire/messages";
+import type { MessageEnvelope } from "@nwire/envelope";
 import type { ProjectionDefinition } from "./define-projection.js";
 import { type PublicMarker } from "../helpers/public-marker.js";
 /** Studio-aware: declared read-path SLO. */
@@ -51,13 +52,22 @@ export interface QueryContext {
     readonly tenant?: string;
     /** Abort signal — wired from the caller's request when available. */
     readonly signal?: AbortSignal;
+    /**
+     * Dispatch envelope when the query runs under one (tenant, userId,
+     * correlation/causation ids). Present when invoked via `ctx.query` from a
+     * handler or a transport that carries an envelope.
+     */
+    readonly envelope?: MessageEnvelope;
 }
+/** Ctx a handler-form query body receives — the read ctx with `input` on it. */
+export type QueryCtx<TSchema extends ZodTypeAny = ZodTypeAny> = QueryContext & {
+    readonly input: z.output<TSchema>;
+};
 export interface QueryOptions<TState, TSchema extends ZodTypeAny, TResult> {
     readonly name: string;
     readonly description?: string;
-    /** Input schema — `input` is an alias accepted for docs parity with actions. */
-    readonly schema: TSchema;
-    readonly input?: TSchema;
+    /** Input schema (zod). */
+    readonly input: TSchema;
     readonly execute: (state: TState, input: z.output<TSchema>) => TResult | Promise<TResult>;
     /** Studio-aware: declared latency target. */
     readonly slo?: QuerySlo;
@@ -65,17 +75,17 @@ export interface QueryOptions<TState, TSchema extends ZodTypeAny, TResult> {
     readonly cacheable?: boolean;
 }
 /**
- * Options for handler-form `defineQuery({ name, schema, handler })`. No
- * projection, no state — you read from whatever source you care to via
+ * Options for handler-form `defineQuery({ name, input, handler })`. No
+ * projection, no state — read from whatever source you care to via
  * `ctx.resolve<DbType>("db")` (or any registered binding).
  */
 export interface QueryHandlerOptions<TSchema extends ZodTypeAny, TResult> {
     readonly name: string;
     readonly description?: string;
-    /** Input schema — `input` is an alias accepted for docs parity with actions. */
-    readonly schema: TSchema;
-    readonly input?: TSchema;
-    readonly handler: (input: z.output<TSchema>, ctx: QueryContext) => TResult | Promise<TResult>;
+    /** Input schema (zod). */
+    readonly input: TSchema;
+    /** The read body — one ctx arg (`{ input, resolve, tenant, envelope }`). */
+    readonly handler: (ctx: QueryCtx<TSchema>) => TResult | Promise<TResult>;
     readonly slo?: QuerySlo;
     readonly cacheable?: boolean;
 }
@@ -83,27 +93,27 @@ export interface QueryDefinition<TState = unknown, TSchema extends ZodTypeAny =
     readonly $kind: "query";
     readonly name: string;
     readonly description?: string;
-    readonly schema: TSchema;
+    /** Input schema (zod). */
+    readonly input: TSchema;
     /**
-     * Backing projection. `undefined` for handler-form queries — runtime
+     * Backing projection. `undefined` for handler-form queries — the runner
      * detects this and routes through `handler` directly (no state load).
      */
     readonly projection?: ProjectionDefinition<TState>;
-    /**
-     * Projection-form executor. Called with the projection's full state + the
-     * validated input. Present iff `projection` is present.
-     */
+    /** Projection-form executor. Present iff `projection` is present. */
     readonly execute?: (state: TState, input: z.output<TSchema>) => TResult | Promise<TResult>;
-    /**
-     * Handler-form executor. Called with the validated input + a
-     * `QueryContext` (DI resolution, tenant, abort signal). Present iff
-     * `projection` is absent.
-     */
-    readonly handler?: (input: z.output<TSchema>, ctx: QueryContext) => TResult | Promise<TResult>;
+    /** Handler-form executor. Present iff `projection` is absent. */
+    readonly handler?: (ctx: QueryCtx<TSchema>) => TResult | Promise<TResult>;
     readonly slo?: QuerySlo;
     readonly cacheable?: boolean;
-    /** Where the query was declared. Studio uses this for IDE-open links. */
-    readonly $source?: SourceLocation;
+    /** Kernel `@nwire/handler` config — `kind:"query"`. Read by the runtime registry. */
+    readonly config?: any;
+    /** Hook-chain run — `runtime.execute` / a wired GET calls this; delegates to the read engine. */
+    run?(ctx: unknown, opts?: {
+        readonly signal?: AbortSignal;
+    }): Promise<unknown>;
+    /** Attach a chain step to the underlying hook. */
+    use?(fn: any, opts?: any): QueryDefinition<TState, TSchema, TResult>;
 }
 export declare function defineQuery<TState, TSchema extends ZodTypeAny, TResult>(projection: ProjectionDefinition<TState>, options: QueryOptions<TState, TSchema, TResult>): QueryDefinition<TState, TSchema, TResult>;
 export declare function defineQuery<TSchema extends ZodTypeAny, TResult>(options: QueryHandlerOptions<TSchema, TResult>): QueryDefinition<any, TSchema, TResult>;

package/dist/primitives/define-query.js

@@ -1,58 +1,55 @@
 /**
- * `defineQuery` — read function over a projection or a direct adapter (DB,
- * cache, search index). Two forms:
+ * `defineQuery` — a read over a projection or a direct adapter (DB, cache,
+ * search). A query IS a handler: like actions it is built via the one definer
+ * (`defineHandler.kind("query")`), so it carries `.run` / `config` and can be
+ * wired to a transport (HTTP GET), dispatched via `runtime.execute`, and
+ * registered by the app (`createApp({ handlers })`) — same surface as any
+ * handler. What's query-specific stays query-specific: it does NOT go through
+ * the command pipeline (no retry / publish / commit), and execution delegates
+ * to the read engine (`QueryRunner`), which loads projection state or runs the
+ * handler closure.
  *
  *   // Projection-driven — runtime hands you `state` + validated input.
  *   export const submissionsByStudent = defineQuery(SubmissionsByStudent, {
- *     name: 'submissions.by-student',
- *     schema: z.object({ studentId: StudentId }),
+ *     name: "submissions.by-student",
+ *     input: z.object({ studentId: StudentId }),
  *     execute: (state, { studentId }) =>
- *       Object.values(state).filter(s => s.studentId === studentId),
+ *       Object.values(state).filter((s) => s.studentId === studentId),
  *   })
  *
- *   // Handler form — no projection, you reach into the container yourself.
+ *   // Handler form — no projection; reach into the container yourself.
  *   export const usersById = defineQuery({
- *     name: 'users.by-id',
- *     schema: z.object({ id: UserId }),
- *     handler: async ({ id }, { resolve }) => {
- *       const db = resolve<DrizzleDb>('db');
+ *     name: "users.by-id",
+ *     input: z.object({ id: UserId }),
+ *     handler: async ({ input: { id }, resolve }) => {
+ *       const db = resolve<DrizzleDb>("db");
  *       return db.select().from(users).where(eq(users.id, id)).limit(1);
  *     },
  *   })
  *
- * Pick projection form when the read is "eventually-consistent over events
- * I publish in-process." Pick handler form when reading from any external
- * source of truth (Postgres rows, Redis, OpenSearch) — no projection layer
- * needed. Queries are always direct calls: no envelope, no bus, no commit.
- *
- * Naming follows actions: `<domain>.<verb-noun>` so a query is addressable
- * on the same routing keyspace as actions when transports need it (HTTP GET
- * routes wire queries; HTTP POST routes wire actions).
+ * Naming follows actions: `<domain>.<verb-noun>`.
  */
-import { captureSourceLocation } from "@nwire/messages";
+import { defineHandler } from "@nwire/handler";
 import { markable } from "../helpers/public-marker.js";
+import { FORGE_QUERY_RUNNER_BINDING } from "../plugins/queries-plugin.js";
 export function defineQuery(projectionOrOptions, maybeOptions) {
-    const $source = captureSourceLocation();
     // Handler form — first arg is the options object with `handler`.
     if (maybeOptions === undefined) {
         const opts = projectionOrOptions;
-        const schema = opts.schema ?? opts.input;
-        return markable({
-            $kind: "query",
+        const schema = opts.input;
+        return buildQuery({
             name: opts.name,
             description: opts.description,
             schema,
             handler: opts.handler,
             slo: opts.slo,
             cacheable: opts.cacheable,
-            $source,
         });
     }
     // Projection form — first arg is the projection.
     const projection = projectionOrOptions;
-    const schema = maybeOptions.schema ?? maybeOptions.input;
-    return markable({
-        $kind: "query",
+    const schema = maybeOptions.input;
+    return buildQuery({
         name: maybeOptions.name,
         description: maybeOptions.description,
         schema,
@@ -60,6 +57,46 @@ export function defineQuery(projectionOrOptions, maybeOptions) {
         execute: maybeOptions.execute,
         slo: maybeOptions.slo,
         cacheable: maybeOptions.cacheable,
-        $source,
     });
 }
+/**
+ * Build the query as a kernel handler (kind:"query") whose body delegates to
+ * the per-app `QueryRunner` (resolved from ctx), then attach the query
+ * metadata + the `$kind:"query"` discriminator + the public marker.
+ */
+function buildQuery(f) {
+    if (!f.schema) {
+        throw new Error(`defineQuery("${f.name}"): an \`input\` (zod) schema is required.`);
+    }
+    const kernel = defineHandler.kind("query")(f.name, {
+        input: f.schema,
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        handler: async (ctx) => {
+            const runner = ctx.resolve(FORGE_QUERY_RUNNER_BINDING);
+            return runner.run(f.name, ctx.input, ctx.envelope?.tenant ?? "", ctx.envelope);
+        },
+        description: f.description,
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        meta: { slo: f.slo, cacheable: f.cacheable },
+    });
+    const q = markable({
+        $kind: "query",
+        name: f.name,
+        description: f.description,
+        input: f.schema,
+        projection: f.projection,
+        execute: f.execute,
+        handler: f.handler,
+        slo: f.slo,
+        cacheable: f.cacheable,
+        config: kernel.config,
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        run: (ctx, opts) => kernel.run(ctx, opts),
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        use: (fn, opts) => {
+            kernel.use(fn, opts);
+            return q;
+        },
+    });
+    return q;
+}

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

@@ -17,7 +17,7 @@
  * Example shapes appear in `docs/concepts/workflow.md`.
  */
 import type { z } from "zod";
-import type { ZodTypeAny, SourceLocation } from "@nwire/messages";
+import type { ZodTypeAny } from "@nwire/messages";
 import type { EventDefinition, EventPayload } from "@nwire/messages";
 import type { MessageEnvelope } from "@nwire/envelope";
 import type { Logger } from "@nwire/logger";
@@ -26,7 +26,7 @@ import type { EventMessage } from "../messages/event-message.js";
 import { type PublicMarker } from "../helpers/public-marker.js";
 /**
  * Timer definition produced by `timeout(name, delay)`. Acts like an event
- * for subscription purposes — `on(timer, handler)` registers a handler
+ * for subscription purposes — `when(timer, handler)` registers a handler
  * that fires when the timer's delay elapses. The `delay` string accepts
  * the same units as actor timers (`"7d"`, `"30m"`, `"500ms"`, …).
  */
@@ -84,16 +84,15 @@ export type StateCallable = ((body: StateBody) => void) & {
 export type StateBody = () => Awaitable<Transition>;
 /**
  * Stateless workflow context — no `data`, no `states`, no `complete`.
- * `on()` returns are ignored (there's no state machine to transition).
+ * A `when` return is ignored (there's no state machine to transition).
  */
 export interface StatelessWorkflowContext extends WorkflowEffects {
-    on<E extends EventDefinition>(event: E, handler: (payload: EventPayload<E>, ctx: WorkflowReactionContext) => Awaitable<Transition>, opts?: WorkflowOnOptions): void;
+    /** The one event verb — react to an event. Returns are ignored when stateless. */
+    when<E extends EventDefinition>(event: E, handler: (payload: EventPayload<E>, ctx: WorkflowReactionContext) => Awaitable<Transition>, opts?: WorkflowOnOptions): void;
     /** Subscribe to the `complete` pseudo-event. Fires after each handler. */
-    on(event: CompleteEvent, handler: () => Awaitable<void>, opts?: WorkflowOnOptions): void;
+    when(event: CompleteEvent, handler: () => Awaitable<void>, opts?: WorkflowOnOptions): void;
     /** Subscribe to a saga timer fire. */
-    on(event: TimerDefinition, handler: (payload: unknown, ctx: WorkflowReactionContext) => Awaitable<Transition>, opts?: WorkflowOnOptions): void;
-    /** Canonical event verb — alias of `on`. Prefer `when`; `on` is retained for now. */
-    when: StatelessWorkflowContext["on"];
+    when(event: TimerDefinition, handler: (payload: unknown, ctx: WorkflowReactionContext) => Awaitable<Transition>, opts?: WorkflowOnOptions): void;
 }
 /**
  * Stateful workflow context — adds `data`, `assign`, `states`, and the
@@ -150,7 +149,7 @@ export interface WorkflowDefinition extends PublicMarker {
     readonly $kind: "workflow";
     readonly name: string;
     readonly description?: string;
-    /** Event names this workflow declares an `on()` for. */
+    /** Event names this workflow declares a `when()` for. */
     readonly subscribedEvents: ReadonlySet<string>;
     /** Action names this workflow declares it dispatches. */
     readonly dispatchedActions: ReadonlySet<string>;
@@ -170,8 +169,6 @@ export interface WorkflowDefinition extends PublicMarker {
     readonly retry?: WorkflowRetryPolicy;
     /** Internal — invoked by the runtime per matching event. */
     readonly _fire: (event: EventMessage, fireCtx: FireContext) => Promise<void>;
-    /** Where the workflow was declared. Studio uses this for IDE-open links. */
-    readonly $source?: SourceLocation;
 }
 /**
  * Runtime hooks the workflow uses to load/save per-correlation state

package/dist/primitives/define-workflow.js

@@ -16,7 +16,6 @@
  *
  * Example shapes appear in `docs/concepts/workflow.md`.
  */
-import { captureSourceLocation } from "@nwire/messages";
 import { markable } from "../helpers/public-marker.js";
 import { timerEventName } from "../stores/workflow-timer-store.js";
 /**
@@ -34,14 +33,26 @@ function isStateful(opts) {
 export function defineWorkflow(name, 
 // eslint-disable-next-line @typescript-eslint/no-explicit-any
 closure, options) {
-    const $source = captureSourceLocation();
     const stateful = isStateful(options);
-    const stateSpecs = stateful ? (options.states ?? {}) : {};
+    // Default lifecycle (nominal, not forced persistence): a stateful workflow —
+    // one that declares `data`/`states` — always has a closed lifecycle. With no
+    // states declared it gets `active` → `completed`; with states but none marked
+    // `final`, a `completed` terminal is injected so `complete` / cleanup always
+    // has meaning. The stateless fast path (no `data`, no `states`) is untouched —
+    // a pure reactor persists nothing and is nominally `active` forever.
+    let stateSpecs = stateful ? (options.states ?? {}) : {};
+    if (stateful && Object.keys(stateSpecs).length === 0) {
+        stateSpecs = { active: {}, completed: { final: true } };
+    }
     const finalStates = new Set();
     for (const [n, spec] of Object.entries(stateSpecs)) {
         if (spec.final)
             finalStates.add(n);
     }
+    if (stateful && finalStates.size === 0) {
+        stateSpecs = { ...stateSpecs, completed: { final: true } };
+        finalStates.add("completed");
+    }
     const initialState = stateful
         ? Object.keys(stateSpecs).find((n) => !finalStates.has(n))
         : undefined;
@@ -80,7 +91,6 @@ closure, options) {
     const probeStates = stateful ? buildProbeStateCallables(stateSpecs) : {};
     const probeCtx = stateful
         ? {
-            on: probeOn,
             when: probeOn,
             send: async () => undefined,
             enqueue: async () => undefined,
@@ -93,7 +103,6 @@ closure, options) {
             schedule: async () => undefined,
         }
         : {
-            on: probeOn,
             when: probeOn,
             send: async () => undefined,
             enqueue: async () => undefined,
@@ -159,7 +168,6 @@ closure, options) {
                 dataSchema: stateful ? options.data : undefined,
             });
         },
-        $source,
     };
     return markable(built);
 }
@@ -177,7 +185,6 @@ async function fireStateless({ closure, event, fireCtx, completeMarker, }) {
         }
     });
     const ctx = {
-        on: register,
         when: register,
         send: fireCtx.send,
         enqueue: fireCtx.enqueue,
@@ -268,7 +275,6 @@ async function fireStateful(args) {
         }
     };
     const ctx = {
-        on: onImpl,
         when: onImpl,
         async send(action, input) {
             if (scope.kind === "collect")