@rikalabs/akter 0.2.2 → 0.3.0-next.40953534015.1.ge41bf251cdeb

package/CHANGELOG.md

@@ -1,5 +1,27 @@
 # Changelog
 
+## 0.3.0 (2026-10-29)
+
+The framework and CLI release together at `0.3.0` on the `latest` npm dist-tag. Akter now uses domain-driven names: a caller's request is a **command** and a live, never-stored value is a **broadcast**. Stores written by 0.2 open unchanged: every spelling written to a store, an audit record or the `/rpc` wire keeps its 0.2 form.
+
+### Breaking changes
+
+- `Actor.action` is `Actor.command`, the `actions` option is `commands`, and `ActionContext`, `ActionHandler` and `ActionDefect` are `CommandContext`, `CommandHandler` and `CommandDefect`. A defect reaches a client named `CommandDefect`.
+- `Actor.event` is `Actor.broadcast`, the `events` option is `broadcasts`, `ctx.emit` in commands and jobs is `ctx.broadcast`, and the `Event` type is `Broadcast`. `Transport.event` is `Transport.broadcast`.
+- `access` sees request kinds `"command"` and `"broadcast"` instead of `"action"` and `"event"`; `classifyRpc` returns `"command"` instead of `"action"`.
+- `Actor.job` no longer takes `retry` or `timeout`. Attach them as policies: `Actor.job({ ... }).pipe(Job.retry({ times, schedule }), Job.timeout("30 seconds"))`. `times` counts retries after the first attempt, so 0.2's `attempts: 3` is `times: 2`; `schedule` is an Effect `Schedule` for the delay before each retry. `Retry` is `{ times, schedule? }`.
+- None of the 0.2 spellings is kept as an alias.
+- The `effect`, `@effect/platform-bun` and `@effect/platform-node` peers are `~4.0.3`: Effect 4.0 patch releases only. Effect 4.1.0 removed `Crypto` from the `effect` root entry, which Akter imports, so 0.3.0 does not support Effect 4.1.
+
+### New
+
+- `Actor.job({ onSuccess })` names an internal command that receives the job's success value. The value is journaled before it is delivered, under an id derived from the job, so a crash or a retry delivers it exactly once. A job without `onSuccess` behaves as in 0.2.
+- Each retry delay is computed from the job's `Schedule` when the failure is journaled and replayed from the log, never recomputed. A schedule that ends stops the retries early.
+- `Story` in `@rikalabs/akter/testing` runs one actor's command and view handlers with no engine and no store. A story gives a state and a command and checks the reply or failure, the new state and every staged send, timer, job start and broadcast; `Story.effect` runs the same steps as an Effect.
+- `Job` is exported from `@rikalabs/akter` as both the type and the policy namespace.
+- `App.make` names the actor its layer leaves unimplemented and the `toLayer` call to add.
+- The naming guide documents imperative commands and jobs, past-tense results (`succeeded<Job>`, `failed<Job>`) and broadcasts, and dotted actor names such as `Billing.Invoice`.
+
 ## 0.2.2 (2026-10-15)
 
 The framework and CLI release together at `0.2.2` on the `latest` npm dist-tag. Stores written by 0.2.0 and 0.2.1 open unchanged.

package/README.md

@@ -24,7 +24,7 @@ export const Counter = Actor.make("Counter", {
       by: "id",
     }),
   }),
-  actions: { add: Actor.action(Schema.Finite, { success: Schema.Finite }) },
+  commands: { add: Actor.command(Schema.Finite, { success: Schema.Finite }) },
 })
 
 export const CounterLive = Counter.toLayer({
@@ -35,7 +35,7 @@ export const CounterLive = Counter.toLayer({
 })
 ```
 
-Actions are synchronous and deterministic. They publish no reply, event, send, timer or job until their bucket-log segment is durable. Jobs are the only place for I/O.
+Commands are synchronous and deterministic. They publish no reply, broadcast, send, timer or job until their bucket-log segment is durable. Jobs are the only place for I/O.
 
 ## Client and server
 
@@ -46,7 +46,7 @@ const app = App.make({ actors: [Counter], layer: CounterLive })
 const server = Akter.serve({ app, auth: Auth.none })
 ```
 
-Provide `Store.fileSystem(".akter/store")` for local development or `Store.s3({ bucket, credentials })` for an S3-compatible store. The single Effect client is `Counter.client(id)`. Its actions are Effects, state and views are Streams, lists expose `range` and watch, and static `Counter.find({ where, orderBy, limit })` returns ids only.
+Provide `Store.fileSystem(".akter/store")` for local development or `Store.s3({ bucket, credentials })` for an S3-compatible store. The single Effect client is `Counter.client(id)`. Its commands are Effects, state and views are Streams, lists expose `range` and watch, and static `Counter.find({ where, orderBy, limit })` returns ids only.
 
 The one RPC group is `/rpc`: WebSocket JSON and HTTP NDJSON. The server can opt into `/metrics` with `prometheus: true`; `Telemetry.layer` composes OTLP traces/metrics and Effect DevTools without an OTLP logs exporter.
 

package/dist/client/transport.d.ts

@@ -26,7 +26,7 @@ export interface ClientOptions {
     readonly reauthenticateEvery?: Duration.Input;
 }
 /**
- * The `Client` every handle calls through, over `/rpc`. Each action mints a command id from the
+ * The `Client` every handle calls through, over `/rpc`. Each command mints a command id from the
  * client's clock and retries with that same id after a lost connection or a retryable refusal;
  * each stream resubscribes after a lost connection and starts again from a full value. A WebSocket
  * session that lapses at its reauthorization bound is replaced by reconnecting.

package/dist/client/transport.js

@@ -9,7 +9,7 @@ import { ActionFailed, ErrorEnvelope, FindCodec, groupOf, SPAN_PREFIX, Tags } fr
 const isClientError = (error) => Predicate.isTagged(error, "RpcClientError");
 /**
  * A response that never arrived as a valid envelope. A lost connection is safe to retry: an
- * action resends its command id, so the server runs it at most once, and a read resubscribes.
+ * command resends its command id, so the server runs it at most once, and a read resubscribes.
  */
 const transportError = (error) => ActorError.make({
     reason: Predicate.isTagged(error.reason, "RpcClientDefect")
@@ -84,7 +84,7 @@ const makeTransport = (options, connection) => Effect.gen(function* () {
             id: request.id,
             params: request.params,
         })),
-        event: (request) => streamed(Tags.event(request.actor.name, request.member), { id: request.id }),
+        broadcast: (request) => streamed(Tags.event(request.actor.name, request.member), { id: request.id }),
         range: (request) => retrying(unary(Tags.range(request.actor.name, request.member), {
             id: request.id,
             ...request.range,
@@ -169,7 +169,7 @@ const connected = (options, connection) => isSocket(options.url)
         transformClient: (client) => refusalsAsExits(HttpClient.mapRequestEffect(client, (request) => Effect.map(headersOf(options), (headers) => HttpClientRequest.setHeaders(request, headers)))),
     }).pipe(Layer.provide([FetchHttpClient.layer, RpcSerialization.layerNdjson]));
 /**
- * The `Client` every handle calls through, over `/rpc`. Each action mints a command id from the
+ * The `Client` every handle calls through, over `/rpc`. Each command mints a command id from the
  * client's clock and retries with that same id after a lost connection or a retryable refusal;
  * each stream resubscribes after a lost connection and starts again from a full value. A WebSocket
  * session that lapses at its reauthorization bound is replaced by reconnecting.

package/dist/contract/actor.d.ts

@@ -1,16 +1,16 @@
 import type { Actor as ActorContract, Def } from "./make.ts";
 import { JobFailure } from "./members.ts";
 /**
- * Declares actors: `Actor.make(name, { state, actions, ... })` for the contract and the member
+ * Declares actors: `Actor.make(name, { state, commands, ... })` for the contract and the member
  * constructors, schema first and options second.
  */
 export declare const Actor: {
-    make: <const Name extends string, S extends import("./make.ts").State, A extends Record<string, import("./members.ts").Action>, K extends import("./members.ts").MemberSchema = import("effect/Schema").String, V extends Record<string, import("./members.ts").View> = {}, E extends Record<string, import("./members.ts").Event> = {}, J extends Record<string, import("./members.ts").Job> = {}, P extends import("./members.ts").OptionalSchema = undefined, Acc extends (caller: import("./caller.ts").Caller, request: import("./make.ts").AccessRequest) => boolean = (caller: import("./caller.ts").Caller) => caller is import("./caller.ts").User | import("./caller.ts").System>(name: Name, options: import("./make.ts").MakeOptions<K, S, A, V, E, J, P, Acc> & ([(keyof A & (keyof E | keyof J | keyof V | import("./context.ts").ListKeys<S["fields"]> | ("connect" | "disconnect" | "join" | "state"))) | (keyof E & (keyof J | import("./context.ts").ListKeys<S["fields"]> | ("connect" | "disconnect" | "join" | "state"))) | (keyof J & (import("./context.ts").ListKeys<S["fields"]> | ("connect" | "disconnect" | "join" | "state"))) | (keyof V & (keyof E | keyof J | import("./context.ts").ListKeys<S["fields"]> | ("connect" | "disconnect" | "join" | "state"))) | (import("./context.ts").ListKeys<S["fields"]> & ("connect" | "disconnect" | "join" | "state"))] extends [never] ? unknown : import("./make.ts").TypeError<`member name '${keyof A & "connect"}' is used twice or reserved (state, join, connect, disconnect)` | `member name '${keyof A & "disconnect"}' is used twice or reserved (state, join, connect, disconnect)` | `member name '${keyof A & "join"}' is used twice or reserved (state, join, connect, disconnect)` | `member name '${keyof A & "state"}' is used twice or reserved (state, join, connect, disconnect)` | `member name '${keyof E & "connect"}' is used twice or reserved (state, join, connect, disconnect)` | `member name '${keyof E & "disconnect"}' is used twice or reserved (state, join, connect, disconnect)` | `member name '${keyof E & "join"}' is used twice or reserved (state, join, connect, disconnect)` | `member name '${keyof E & "state"}' is used twice or reserved (state, join, connect, disconnect)` | `member name '${keyof J & "connect"}' is used twice or reserved (state, join, connect, disconnect)` | `member name '${keyof J & "disconnect"}' is used twice or reserved (state, join, connect, disconnect)` | `member name '${keyof J & "join"}' is used twice or reserved (state, join, connect, disconnect)` | `member name '${keyof J & "state"}' is used twice or reserved (state, join, connect, disconnect)` | `member name '${keyof V & "connect"}' is used twice or reserved (state, join, connect, disconnect)` | `member name '${keyof V & "disconnect"}' is used twice or reserved (state, join, connect, disconnect)` | `member name '${keyof V & "join"}' is used twice or reserved (state, join, connect, disconnect)` | `member name '${keyof V & "state"}' is used twice or reserved (state, join, connect, disconnect)` | `member name '${import("./context.ts").ListKeys<S["fields"]> & "connect"}' is used twice or reserved (state, join, connect, disconnect)` | `member name '${import("./context.ts").ListKeys<S["fields"]> & "disconnect"}' is used twice or reserved (state, join, connect, disconnect)` | `member name '${import("./context.ts").ListKeys<S["fields"]> & "join"}' is used twice or reserved (state, join, connect, disconnect)` | `member name '${import("./context.ts").ListKeys<S["fields"]> & "state"}' is used twice or reserved (state, join, connect, disconnect)` | `member name '${keyof A & keyof E & string}' is used twice or reserved (state, join, connect, disconnect)` | `member name '${keyof A & keyof J & string}' is used twice or reserved (state, join, connect, disconnect)` | `member name '${keyof A & keyof V & string}' is used twice or reserved (state, join, connect, disconnect)` | `member name '${keyof A & import("./context.ts").ListKeys<S["fields"]> & string}' is used twice or reserved (state, join, connect, disconnect)` | `member name '${keyof E & keyof J & string}' is used twice or reserved (state, join, connect, disconnect)` | `member name '${keyof E & import("./context.ts").ListKeys<S["fields"]> & string}' is used twice or reserved (state, join, connect, disconnect)` | `member name '${keyof J & import("./context.ts").ListKeys<S["fields"]> & string}' is used twice or reserved (state, join, connect, disconnect)` | `member name '${keyof V & keyof E & string}' is used twice or reserved (state, join, connect, disconnect)` | `member name '${keyof V & keyof J & string}' is used twice or reserved (state, join, connect, disconnect)` | `member name '${keyof V & import("./context.ts").ListKeys<S["fields"]> & string}' is used twice or reserved (state, join, connect, disconnect)`>)) => ActorContract<Name, {
+    make: <const Name extends string, S extends import("./make.ts").State, A extends Record<string, import("./members.ts").Command>, K extends import("./members.ts").MemberSchema = import("effect/Schema").String, V extends Record<string, import("./members.ts").View> = {}, E extends Record<string, import("./members.ts").Broadcast> = {}, J extends Record<string, import("./members.ts").Job> = {}, P extends import("./members.ts").OptionalSchema = undefined, Acc extends (caller: import("./caller.ts").Caller, request: import("./make.ts").AccessRequest) => boolean = (caller: import("./caller.ts").Caller) => caller is import("./caller.ts").User | import("./caller.ts").System>(name: Name, options: import("./make.ts").MakeOptions<K, S, A, V, E, J, P, Acc> & ([(keyof A & (keyof E | keyof J | keyof V | import("./context.ts").ListKeys<S["fields"]> | ("connect" | "disconnect" | "join" | "state"))) | (keyof E & (keyof J | import("./context.ts").ListKeys<S["fields"]> | ("connect" | "disconnect" | "join" | "state"))) | (keyof J & (import("./context.ts").ListKeys<S["fields"]> | ("connect" | "disconnect" | "join" | "state"))) | (keyof V & (keyof E | keyof J | import("./context.ts").ListKeys<S["fields"]> | ("connect" | "disconnect" | "join" | "state"))) | (import("./context.ts").ListKeys<S["fields"]> & ("connect" | "disconnect" | "join" | "state"))] extends [never] ? unknown : import("./make.ts").TypeError<`member name '${keyof A & "connect"}' is used twice or reserved (state, join, connect, disconnect)` | `member name '${keyof A & "disconnect"}' is used twice or reserved (state, join, connect, disconnect)` | `member name '${keyof A & "join"}' is used twice or reserved (state, join, connect, disconnect)` | `member name '${keyof A & "state"}' is used twice or reserved (state, join, connect, disconnect)` | `member name '${keyof E & "connect"}' is used twice or reserved (state, join, connect, disconnect)` | `member name '${keyof E & "disconnect"}' is used twice or reserved (state, join, connect, disconnect)` | `member name '${keyof E & "join"}' is used twice or reserved (state, join, connect, disconnect)` | `member name '${keyof E & "state"}' is used twice or reserved (state, join, connect, disconnect)` | `member name '${keyof J & "connect"}' is used twice or reserved (state, join, connect, disconnect)` | `member name '${keyof J & "disconnect"}' is used twice or reserved (state, join, connect, disconnect)` | `member name '${keyof J & "join"}' is used twice or reserved (state, join, connect, disconnect)` | `member name '${keyof J & "state"}' is used twice or reserved (state, join, connect, disconnect)` | `member name '${keyof V & "connect"}' is used twice or reserved (state, join, connect, disconnect)` | `member name '${keyof V & "disconnect"}' is used twice or reserved (state, join, connect, disconnect)` | `member name '${keyof V & "join"}' is used twice or reserved (state, join, connect, disconnect)` | `member name '${keyof V & "state"}' is used twice or reserved (state, join, connect, disconnect)` | `member name '${import("./context.ts").ListKeys<S["fields"]> & "connect"}' is used twice or reserved (state, join, connect, disconnect)` | `member name '${import("./context.ts").ListKeys<S["fields"]> & "disconnect"}' is used twice or reserved (state, join, connect, disconnect)` | `member name '${import("./context.ts").ListKeys<S["fields"]> & "join"}' is used twice or reserved (state, join, connect, disconnect)` | `member name '${import("./context.ts").ListKeys<S["fields"]> & "state"}' is used twice or reserved (state, join, connect, disconnect)` | `member name '${keyof A & keyof E & string}' is used twice or reserved (state, join, connect, disconnect)` | `member name '${keyof A & keyof J & string}' is used twice or reserved (state, join, connect, disconnect)` | `member name '${keyof A & keyof V & string}' is used twice or reserved (state, join, connect, disconnect)` | `member name '${keyof A & import("./context.ts").ListKeys<S["fields"]> & string}' is used twice or reserved (state, join, connect, disconnect)` | `member name '${keyof E & keyof J & string}' is used twice or reserved (state, join, connect, disconnect)` | `member name '${keyof E & import("./context.ts").ListKeys<S["fields"]> & string}' is used twice or reserved (state, join, connect, disconnect)` | `member name '${keyof J & import("./context.ts").ListKeys<S["fields"]> & string}' is used twice or reserved (state, join, connect, disconnect)` | `member name '${keyof V & keyof E & string}' is used twice or reserved (state, join, connect, disconnect)` | `member name '${keyof V & keyof J & string}' is used twice or reserved (state, join, connect, disconnect)` | `member name '${keyof V & import("./context.ts").ListKeys<S["fields"]> & string}' is used twice or reserved (state, join, connect, disconnect)`>)) => ActorContract<Name, {
         readonly key: K;
         readonly state: S;
-        readonly actions: A;
+        readonly commands: A;
         readonly views: V;
-        readonly events: E;
+        readonly broadcasts: E;
         readonly jobs: J;
         readonly presence: P;
         readonly caller: Acc extends (caller: any, ...rest: Array<any>) => caller is infer C ? Extract<C, {
@@ -37,9 +37,9 @@ export declare const Actor: {
             readonly subject: string;
         };
     }>;
-    action: {
-        (): import("./members.ts").Action<undefined, undefined, undefined, false>;
-        <P extends import("./members.ts").MemberSchema, const O extends import("./members.ts").PayloadActionOptions = {}>(payload: P, options?: O): import("./members.ts").Action<P, O extends {
+    command: {
+        (): import("./members.ts").Command<undefined, undefined, undefined, false>;
+        <P extends import("./members.ts").MemberSchema, const O extends import("./members.ts").PayloadCommandOptions = {}>(payload: P, options?: O): import("./members.ts").Command<P, O extends {
             readonly success: infer S extends import("./members.ts").MemberSchema;
         } ? S : undefined, O extends {
             readonly fails: infer E extends import("./members.ts").DeclaredError;
@@ -48,7 +48,7 @@ export declare const Actor: {
         } ? true : O extends {
             readonly internal: true;
         } ? true : false>;
-        <const O extends import("./members.ts").ActionOptions>(options: O): import("./members.ts").Action<undefined, O extends {
+        <const O extends import("./members.ts").CommandOptions>(options: O): import("./members.ts").Command<undefined, O extends {
             readonly success: infer S extends import("./members.ts").MemberSchema;
         } ? S : undefined, O extends {
             readonly fails: infer E extends import("./members.ts").DeclaredError;
@@ -61,14 +61,13 @@ export declare const Actor: {
     view: <A extends import("./members.ts").MemberSchema, P extends import("./members.ts").MemberSchema | undefined = undefined>(success: A, options?: {
         readonly params?: P;
     }) => import("./members.ts").View<A, NoInfer<P>>;
-    event: <A extends import("./members.ts").MemberSchema>(schema: A) => import("./members.ts").Event<A>;
-    job: <P extends import("./members.ts").MemberSchema | undefined = undefined, const F extends string = string>(options: {
+    broadcast: <A extends import("./members.ts").MemberSchema>(schema: A) => import("./members.ts").Broadcast<A>;
+    job: <P extends import("./members.ts").MemberSchema | undefined = undefined, const F extends string = string, const S extends string | undefined = undefined>(options: {
         readonly payload?: P;
-        readonly retry?: import("./members.ts").Retry;
-        readonly timeout?: import("effect/Duration").Input;
         readonly concurrency?: number;
+        readonly onSuccess?: S;
         readonly onFailure: F;
-    }) => import("./members.ts").Job<NoInfer<P>, NoInfer<F>>;
+    }) => import("./members.ts").Job<NoInfer<P>, NoInfer<F>, NoInfer<S>>;
     list: <I extends import("./members.ts").MemberSchema, const B extends import("./members.ts").KeyField<I["Type"]>, const K extends import("./members.ts").KeyField<I["Type"]> = B>(item: I, options: {
         readonly key?: K;
         readonly by: B;

package/dist/contract/actor.js

@@ -1,14 +1,14 @@
 import { Contract } from "./make.js";
 import { JobFailure, Members } from "./members.js";
 /**
- * Declares actors: `Actor.make(name, { state, actions, ... })` for the contract and the member
+ * Declares actors: `Actor.make(name, { state, commands, ... })` for the contract and the member
  * constructors, schema first and options second.
  */
 export const Actor = {
     make: Contract.make,
-    action: Members.action,
+    command: Members.command,
     view: Members.view,
-    event: Members.event,
+    broadcast: Members.broadcast,
     job: Members.job,
     list: Members.list,
     JobFailure,

package/dist/contract/caller.d.ts

@@ -14,7 +14,7 @@ export type Anonymous = typeof Anonymous.Type;
  * `cron`, `job`, `operator`, `process`), `subject` names the origin (`actor:<Type>/<id>`,
  * `job:<jobId>`, `cron:<Type>`, `operator:<id>`) so that `caller.subject` types for every caller
  * an actor admits once `access` excludes `Anonymous`, `ref` is the originating actor's address and
- * `onBehalfOf` the principal of the action that caused the call.
+ * `onBehalfOf` the principal of the command that caused the call.
  */
 export declare const System: Schema.TaggedStruct<"System", {
     readonly source: Schema.Literals<readonly ["send", "timer", "cron", "job", "operator", "process"]>;

package/dist/contract/caller.js

@@ -8,7 +8,7 @@ export const Anonymous = Schema.TaggedStruct("Anonymous", {});
  * `cron`, `job`, `operator`, `process`), `subject` names the origin (`actor:<Type>/<id>`,
  * `job:<jobId>`, `cron:<Type>`, `operator:<id>`) so that `caller.subject` types for every caller
  * an actor admits once `access` excludes `Anonymous`, `ref` is the originating actor's address and
- * `onBehalfOf` the principal of the action that caused the call.
+ * `onBehalfOf` the principal of the command that caused the call.
  */
 export const System = Schema.TaggedStruct("System", {
     source: Schema.Literals(["send", "timer", "cron", "job", "operator", "process"]),

package/dist/contract/context.d.ts

@@ -2,7 +2,7 @@ import type { DateTime, Duration, Effect, Schema, Types } from "effect";
 import type { Caller, System } from "./caller.ts";
 import type { SelfHandle } from "./handle.ts";
 import type { Actor, AnyActor, Def, DefOf } from "./make.ts";
-import type { Action, Event, Job, List, ListDraft, ListReader, MemberSchema, OptionalSchema, View } from "./members.ts";
+import type { Broadcast, Command, Job, List, ListDraft, ListReader, MemberSchema, OptionalSchema, View } from "./members.ts";
 /** The state struct's fields. */
 export type Fields = {
     readonly [name: string]: MemberSchema;
@@ -33,7 +33,7 @@ export type ListKeys<F extends Fields> = {
 type DraftField<S> = S extends List ? ListDraft<ItemOf<S>, ListKey<S>, ListBy<S>> : S extends Schema.Top ? Types.DeepMutable<S["Type"]> : never;
 type ReadField<S> = S extends List ? ListReader<ItemOf<S>, ListKey<S>, ListBy<S>> : S extends Schema.Top ? S["Type"] : never;
 /**
- * The state an action handler changes: deep-mutable fields, each list as its draft API.
+ * The state a command handler changes: deep-mutable fields, each list as its draft API.
  * `Schema.optional` fields are optional keys, so `delete draft.field` compiles for them only.
  */
 export type Draft<F extends Fields> = {
@@ -57,9 +57,9 @@ export type ClientState<F extends Fields> = {
 export type FullState<F extends Fields> = ClientState<F> & {
     readonly [K in ListKeys<F>]: F[K] extends List ? ReadonlyArray<ItemOf<F[K]>> : never;
 };
-/** The staged-call surface of `send` and `schedule`: one method per target action, fire-and-forget. */
+/** The staged-call surface of `send` and `schedule`: one method per target command, fire-and-forget. */
 export type Sender<X> = {
-    readonly [A in keyof DefOf<X>["actions"]]: (...args: Args<DefOf<X>["actions"][A]["payload"]>) => void;
+    readonly [A in keyof DefOf<X>["commands"]]: (...args: Args<DefOf<X>["commands"][A]["payload"]>) => void;
 };
 /** `ctx.start`: one method per job, staging a start. */
 export type Starters<J extends Record<string, Job>> = {
@@ -67,20 +67,20 @@ export type Starters<J extends Record<string, Job>> = {
         readonly key?: string;
     }]) => void;
 };
-/** `ctx.emit` in actions: stages an event for publication after durability. */
-export type Emitters<E extends Record<string, Event>> = {
+/** `ctx.broadcast` in commands: stages a broadcast for publication after durability. */
+export type Broadcasters<E extends Record<string, Broadcast>> = {
     readonly [K in keyof E]: (value: E[K]["schema"]["Type"]) => void;
 };
-/** `emit` in jobs: publishes at once. */
-export type JobEmitters<E extends Record<string, Event>> = {
+/** `broadcast` in jobs: publishes at once. */
+export type JobBroadcasters<E extends Record<string, Broadcast>> = {
     readonly [K in keyof E]: (value: E[K]["schema"]["Type"]) => Effect.Effect<void>;
 };
-/** When a scheduled action runs: after a delay, or at an epoch-millisecond instant. */
+/** When a scheduled command runs: after a delay, or at an epoch-millisecond instant. */
 export type When = Duration.Input | {
     readonly at: number;
 };
-/** The capabilities of an action handler; nothing else is reachable from an action. */
-export interface ActionContext<Name extends string, D extends Def, C extends Caller> {
+/** The capabilities of a command handler; nothing else is reachable from a command. */
+export interface CommandContext<Name extends string, D extends Def, C extends Caller> {
     readonly caller: C;
     readonly self: D["key"]["Type"];
     readonly id: () => string;
@@ -89,10 +89,10 @@ export interface ActionContext<Name extends string, D extends Def, C extends Cal
     readonly send: <X extends AnyActor>(target: X, id: DefOf<X>["key"]["Type"]) => Sender<X>;
     readonly schedule: (when: When) => Sender<Actor<Name, D>>;
     readonly start: Starters<D["jobs"]>;
-    readonly emit: Emitters<D["events"]>;
+    readonly broadcast: Broadcasters<D["broadcasts"]>;
 }
-/** The context of `connect` and `disconnect`: an action context with the connection id. */
-export interface PresenceContext<Name extends string, D extends Def> extends ActionContext<Name, D, D["caller"] | System> {
+/** The context of `connect` and `disconnect`: a command context with the connection id. */
+export interface PresenceContext<Name extends string, D extends Def> extends CommandContext<Name, D, D["caller"] | System> {
     readonly connection: string;
 }
 /** A view handler reads durable state only and stages nothing. */
@@ -113,27 +113,32 @@ export interface JobContext<Name extends string, D extends Def> {
     readonly self: SelfHandle<Name, D>;
     readonly id: () => string;
     readonly attempt: number;
-    readonly emit: JobEmitters<D["events"]>;
+    readonly broadcast: JobBroadcasters<D["broadcasts"]>;
     readonly step: Step;
 }
-type SuccessType<A extends Action> = A["success"] extends Schema.Top ? A["success"]["Type"] : undefined;
-type FailsType<A extends Action> = A["fails"] extends Schema.Top ? A["fails"]["Type"] : never;
-/** The caller an action handler sees: internal actions are reached by the engine only. */
-export type CallerFor<D extends Def, A extends Action> = A["internal"] extends true ? System : D["caller"] | System;
+type SuccessType<A extends Command> = A["success"] extends Schema.Top ? A["success"]["Type"] : undefined;
+type FailsType<A extends Command> = A["fails"] extends Schema.Top ? A["fails"]["Type"] : never;
+/** The caller a command handler sees: internal commands are reached by the engine only. */
+export type CallerFor<D extends Def, A extends Command> = A["internal"] extends true ? System : D["caller"] | System;
 /**
- * An action handler: synchronous, over a copy-on-write draft. Returning the declared failure
+ * A command handler: synchronous, over a copy-on-write draft. Returning the declared failure
  * discards the draft and every staged effect; returning a value is the reply.
  */
-export type ActionHandler<Name extends string, D extends Def, A extends Action> = (draft: Draft<D["state"]["fields"]>, payload: PayloadOf<A["payload"]>, ctx: ActionContext<Name, D, CallerFor<D, A>>) => SuccessType<A> | FailsType<A>;
+export type CommandHandler<Name extends string, D extends Def, A extends Command> = (draft: Draft<D["state"]["fields"]>, payload: PayloadOf<A["payload"]>, ctx: CommandContext<Name, D, CallerFor<D, A>>) => SuccessType<A> | FailsType<A>;
 /** A view handler: a pure, synchronous function of durable state and its parameters. */
 export type ViewHandler<D extends Def, V extends View> = (state: ReadState<D["state"]["fields"]>, params: PayloadOf<V["params"]>, ctx: ViewContext<D>) => V["success"]["Type"];
+/**
+ * What a job's Effect succeeds with: the payload of its `onSuccess` command, which receives it, or
+ * `void` when that command takes none; anything when the job has no `onSuccess`.
+ */
+export type JobSuccess<D extends Def, J extends Job> = J["onSuccess"] extends keyof D["commands"] ? D["commands"][J["onSuccess"]]["payload"] extends Schema.Top ? PayloadOf<D["commands"][J["onSuccess"]]["payload"]> : void : unknown;
 /** A job handler: the only place for I/O. Its requirements flow into the layer type. */
-export type JobHandler<Name extends string, D extends Def, J extends Job> = (payload: PayloadOf<J["payload"]>, ctx: JobContext<Name, D>) => Effect.Effect<unknown, unknown, any>;
-/** `connect` or `disconnect`: an action over the draft receiving the presence value. */
+export type JobHandler<Name extends string, D extends Def, J extends Job> = (payload: PayloadOf<J["payload"]>, ctx: JobContext<Name, D>) => Effect.Effect<JobSuccess<D, J>, unknown, any>;
+/** `connect` or `disconnect`: a command over the draft receiving the presence value. */
 export type PresenceHandler<Name extends string, D extends Def> = (draft: Draft<D["state"]["fields"]>, presence: PayloadOf<D["presence"]>, ctx: PresenceContext<Name, D>) => undefined;
-/** Every handler `X.toLayer` takes: actions, views, jobs and, with presence, `connect`/`disconnect`. */
+/** Every handler `X.toLayer` takes: commands, views, jobs and, with presence, `connect`/`disconnect`. */
 export type Handlers<Name extends string, D extends Def> = {
-    readonly [A in keyof D["actions"]]: ActionHandler<Name, D, D["actions"][A]>;
+    readonly [A in keyof D["commands"]]: CommandHandler<Name, D, D["commands"][A]>;
 } & {
     readonly [V in keyof D["views"]]: ViewHandler<D, D["views"][V]>;
 } & {

package/dist/contract/cron.d.ts

@@ -9,7 +9,7 @@ export interface CronSchedule {
  * and unknown zones are refused. Throws on anything else.
  */
 declare const parse: (expression: string) => CronSchedule;
-/** Cron schedules of `cron` actions. */
+/** Cron schedules of `cron` commands. */
 export declare const Crons: {
     parse: typeof parse;
 };

package/dist/contract/cron.js

@@ -72,5 +72,5 @@ const nextInZone = (zone, cron) => (after) => {
             return instant;
     }
 };
-/** Cron schedules of `cron` actions. */
+/** Cron schedules of `cron` commands. */
 export const Crons = { parse };

package/dist/contract/errors.d.ts

@@ -29,11 +29,11 @@ export declare const InvalidCommandId: Schema.TaggedStruct<"InvalidCommandId", {
     readonly code: Schema.Literals<readonly ["malformed", "version", "future", "window", "conflict"]>;
     readonly now: Schema.optionalKey<Schema.Finite>;
 }>;
-/** The owner could not run the action now; retry with the same command id. */
+/** The owner could not run the command now; retry with the same command id. */
 export declare const ActorUnavailable: Schema.TaggedStruct<"ActorUnavailable", {}>;
 /** The shard is draining or was lost by its owner; retry with the same command id. */
 export declare const ShardMoved: Schema.TaggedStruct<"ShardMoved", {}>;
-/** The caller stopped waiting; the action may still become durable. */
+/** The caller stopped waiting; the command may still become durable. */
 export declare const Timeout: Schema.TaggedStruct<"Timeout", {
     readonly commandId: Schema.optionalKey<Schema.String>;
 }>;
@@ -126,21 +126,21 @@ export declare class ActorError extends ActorError_base {
     /** The base wait before a retry in milliseconds, before the client's jitter. */
     get retryAfter(): number | undefined;
 }
-/** Which defect ended an action: its staged work is discarded and the defect is its outcome. */
+/** Which defect ended a command: its staged work is discarded and the defect is its outcome. */
 export declare const DefectKind: Schema.Literals<readonly ["SynchronousActionViolation", "StateTooLarge", "ReplayMismatch", "DecodeFailure", "Thrown"]>;
-/** Which defect ended an action. */
+/** Which defect ended a command. */
 export type DefectKind = typeof DefectKind.Type;
-declare const ActionDefect_base: Schema.Class<ActionDefect, Schema.TaggedStruct<"ActionDefect", {
+declare const CommandDefect_base: Schema.Class<CommandDefect, Schema.TaggedStruct<"CommandDefect", {
     readonly kind: Schema.Literals<readonly ["SynchronousActionViolation", "StateTooLarge", "ReplayMismatch", "DecodeFailure", "Thrown"]>;
     readonly actor: Schema.String;
     readonly member: Schema.String;
     readonly detail: Schema.String;
 }>, import("effect/Cause").YieldableError>;
 /**
- * A defect a caller observes as the outcome of its action. It is never an `ActorError` reason:
+ * A defect a caller observes as the outcome of its command. It is never an `ActorError` reason:
  * nothing it staged survived, and retrying the same command id returns the same defect.
  */
-export declare class ActionDefect extends ActionDefect_base {
+export declare class CommandDefect extends CommandDefect_base {
     get message(): string;
 }
 export {};

package/dist/contract/errors.js

@@ -28,11 +28,11 @@ export const InvalidCommandId = Schema.TaggedStruct("InvalidCommandId", {
     code: Schema.Literals(["malformed", "version", "future", "window", "conflict"]),
     now: Schema.optionalKey(Schema.Finite),
 });
-/** The owner could not run the action now; retry with the same command id. */
+/** The owner could not run the command now; retry with the same command id. */
 export const ActorUnavailable = Schema.TaggedStruct("ActorUnavailable", {});
 /** The shard is draining or was lost by its owner; retry with the same command id. */
 export const ShardMoved = Schema.TaggedStruct("ShardMoved", {});
-/** The caller stopped waiting; the action may still become durable. */
+/** The caller stopped waiting; the command may still become durable. */
 export const Timeout = Schema.TaggedStruct("Timeout", {
     commandId: Schema.optionalKey(Schema.String),
 });
@@ -114,7 +114,7 @@ export class ActorError extends Schema.TaggedError()("ActorError", {
         return retryAfterMillis[this.reason._tag];
     }
 }
-/** Which defect ended an action: its staged work is discarded and the defect is its outcome. */
+/** Which defect ended a command: its staged work is discarded and the defect is its outcome. */
 export const DefectKind = Schema.Literals([
     "SynchronousActionViolation",
     "StateTooLarge",
@@ -123,10 +123,10 @@ export const DefectKind = Schema.Literals([
     "Thrown",
 ]);
 /**
- * A defect a caller observes as the outcome of its action. It is never an `ActorError` reason:
+ * A defect a caller observes as the outcome of its command. It is never an `ActorError` reason:
  * nothing it staged survived, and retrying the same command id returns the same defect.
  */
-export class ActionDefect extends Schema.TaggedError()("ActionDefect", {
+export class CommandDefect extends Schema.TaggedError()("CommandDefect", {
     kind: DefectKind,
     actor: Schema.String,
     member: Schema.String,

package/dist/contract/handle.d.ts

@@ -3,7 +3,7 @@ import type { Scope } from "effect";
 import { ActorError } from "./errors.ts";
 import type { Args, ClientState, FindQuery, Fields, ListKeys, ListTypes } from "./context.ts";
 import type { AnyActor, Def } from "./make.ts";
-import type { Action, List, MemberSchema, OptionalSchema, RangeOptions } from "./members.ts";
+import type { Command, List, MemberSchema, OptionalSchema, RangeOptions } from "./members.ts";
 /** A call's reply as the transport carries it: the encoded success value or declared failure. */
 export type Reply = {
     readonly kind: "Success";
@@ -27,12 +27,12 @@ export interface Target {
     readonly actor: AnyActor;
     readonly id: Schema.Json;
 }
-/** A call to one action. */
+/** A call to one command. */
 export interface CallRequest extends Target {
     readonly member: string;
     readonly payload: Schema.Json;
 }
-/** A read of one member (a view, an event or a list). */
+/** A read of one member (a view, a broadcast or a list). */
 export interface MemberRequest extends Target {
     readonly member: string;
     readonly params: Schema.Json;
@@ -57,13 +57,13 @@ export interface FindRequest {
 }
 /**
  * What a handle is derived from, in encoded values. The engine implements it in process; the
- * `/rpc` client implements it over the wire. A defect reaches the caller as an `ActionDefect`.
+ * `/rpc` client implements it over the wire. A defect reaches the caller as a `CommandDefect`.
  */
 export interface Transport {
     call(request: CallRequest): Effect.Effect<Reply, ActorError>;
     state(request: Target): Stream.Stream<StateFrame, ActorError>;
     view(request: MemberRequest): Stream.Stream<Schema.Json, ActorError>;
-    event(request: MemberRequest): Stream.Stream<Schema.Json, ActorError>;
+    broadcast(request: MemberRequest): Stream.Stream<Schema.Json, ActorError>;
     range(request: RangeRequest): Effect.Effect<ReadonlyArray<Schema.Json>, ActorError>;
     watch(request: RangeRequest): Stream.Stream<ReadonlyArray<Schema.Json>, ActorError>;
     join(request: JoinRequest): Effect.Effect<void, ActorError, Scope.Scope>;
@@ -73,13 +73,13 @@ declare const Client_base: Context.ServiceClass<Client, "@rikalabs/akter/contrac
 /** The connection handles talk through: the in-process engine, a job, or the `/rpc` client. */
 export declare class Client extends Client_base {
 }
-type SuccessType<A extends Action> = A["success"] extends MemberSchema ? A["success"]["Type"] : void;
-type FailsType<A extends Action> = A["fails"] extends MemberSchema ? A["fails"]["Type"] : never;
-type PublicActions<D extends Def> = {
-    [A in keyof D["actions"]]: D["actions"][A]["internal"] extends true ? never : A;
-}[keyof D["actions"]];
-type ActionMethods<D extends Def, Keys extends keyof D["actions"]> = {
-    readonly [A in Keys]: (...args: Args<D["actions"][A]["payload"]>) => Effect.Effect<SuccessType<D["actions"][A]>, FailsType<D["actions"][A]> | ActorError>;
+type SuccessType<A extends Command> = A["success"] extends MemberSchema ? A["success"]["Type"] : void;
+type FailsType<A extends Command> = A["fails"] extends MemberSchema ? A["fails"]["Type"] : never;
+type PublicCommands<D extends Def> = {
+    [A in keyof D["commands"]]: D["commands"][A]["internal"] extends true ? never : A;
+}[keyof D["commands"]];
+type CommandMethods<D extends Def, Keys extends keyof D["commands"]> = {
+    readonly [A in Keys]: (...args: Args<D["commands"][A]["payload"]>) => Effect.Effect<SuccessType<D["commands"][A]>, FailsType<D["commands"][A]> | ActorError>;
 };
 /** A list on a client handle: a one-shot window and a watched one. */
 export interface ListHandle<Item, By> {
@@ -91,18 +91,18 @@ type Reads<D extends Def> = {
 } & {
     readonly [V in keyof D["views"]]: (...args: Args<D["views"][V]["params"]>) => Stream.Stream<D["views"][V]["success"]["Type"], ActorError>;
 } & {
-    readonly [E in keyof D["events"]]: Stream.Stream<D["events"][E]["schema"]["Type"], ActorError>;
+    readonly [E in keyof D["broadcasts"]]: Stream.Stream<D["broadcasts"][E]["schema"]["Type"], ActorError>;
 } & {
     readonly state: Stream.Stream<ClientState<D["state"]["fields"]>, ActorError>;
 } & (D["presence"] extends MemberSchema ? {
     join(presence: D["presence"]["Type"]): Effect.Effect<void, ActorError, Scope.Scope>;
 } : {});
-/** The client handle of one actor instance: public actions, lists, views, events, state, `join`. */
-export type Handle<Name extends string, D extends Def> = ActionMethods<D, PublicActions<D>> & Reads<D> & {
+/** The client handle of one actor instance: public commands, lists, views, broadcasts, state, `join`. */
+export type Handle<Name extends string, D extends Def> = CommandMethods<D, PublicCommands<D>> & Reads<D> & {
     readonly "~name"?: Name;
 };
-/** A job's `self`: the handle with internal actions included. */
-export type SelfHandle<Name extends string, D extends Def> = ActionMethods<D, keyof D["actions"]> & Reads<D> & {
+/** A job's `self`: the handle with internal commands included. */
+export type SelfHandle<Name extends string, D extends Def> = CommandMethods<D, keyof D["commands"]> & Reads<D> & {
     readonly "~name"?: Name;
 };
 /** The JSON codec of any member schema. */
@@ -120,7 +120,7 @@ export declare const MemberCodec: {
 };
 /** The client's `state` frame schema: every state field except lists. */
 export declare const clientStateSchema: (actor: AnyActor) => MemberSchema;
-/** Derives one handle; `self` includes internal actions. A new owner's full state frame resets its version clock before schema-equivalent values are suppressed. */
+/** Derives one handle; `self` includes internal commands. A new owner's full state frame resets its version clock before schema-equivalent values are suppressed. */
 declare const derive: <H>(target: Target & {
     readonly self: boolean;
 }, transport: Transport) => H;

package/dist/contract/handle.js

@@ -1,5 +1,5 @@
 import { Context, Effect, JsonPatch, Result, Schema, Stream } from "effect";
-import { ActionDefect, ActorError, InvalidInput } from "./errors.js";
+import { ActorError, CommandDefect, InvalidInput } from "./errors.js";
 import { isList } from "./members.js";
 /** A value a list orders by. */
 export const ByValue = Schema.Union([Schema.String, Schema.Finite]);
@@ -42,7 +42,7 @@ export const MemberCodec = {
         const decode = Schema.decodeResult(json(schema));
         return (value) => Result.match(decode(value), {
             onSuccess: Effect.succeed,
-            onFailure: (error) => Effect.die(ActionDefect.make({ kind: "DecodeFailure", actor, member, detail: error.message })),
+            onFailure: (error) => Effect.die(CommandDefect.make({ kind: "DecodeFailure", actor, member, detail: error.message })),
         });
     },
 };
@@ -62,15 +62,15 @@ export const clientStateSchema = (actor) => {
     clientStateSchemas.set(actor, schema);
     return schema;
 };
-/** Derives one handle; `self` includes internal actions. A new owner's full state frame resets its version clock before schema-equivalent values are suppressed. */
+/** Derives one handle; `self` includes internal commands. A new owner's full state frame resets its version clock before schema-equivalent values are suppressed. */
 const derive = (target, transport) => {
     const { actor, id } = target;
     const handle = new Map();
-    const actions = actor.actions;
+    const commands = actor.commands;
     const fields = actor.state.fields;
     const views = actor.views;
-    const events = actor.events;
-    for (const [member, declaration] of Object.entries(actions)) {
+    const broadcasts = actor.broadcasts;
+    for (const [member, declaration] of Object.entries(commands)) {
         if (declaration.internal && !target.self)
             continue;
         const encode = MemberCodec.encode(declaration.payload);
@@ -103,9 +103,9 @@ const derive = (target, transport) => {
         const decode = MemberCodec.decode(declaration.success, actor.name, member);
         handle.set(member, (params) => Stream.unwrap(Effect.map(encode(params), (encoded) => transport.view({ actor, id, member, params: encoded }).pipe(Stream.mapEffect(decode)))));
     }
-    for (const [member, declaration] of Object.entries(events)) {
+    for (const [member, declaration] of Object.entries(broadcasts)) {
         const decode = MemberCodec.decode(declaration.schema, actor.name, member);
-        handle.set(member, transport.event({ actor, id, member, params: null }).pipe(Stream.mapEffect(decode)));
+        handle.set(member, transport.broadcast({ actor, id, member, params: null }).pipe(Stream.mapEffect(decode)));
     }
     const decodeState = MemberCodec.decode(clientStateSchema(actor), actor.name, "state");
     handle.set("state", Stream.suspend(() => {