@strav/machine 0.4.31 → 1.0.0-alpha.8

package/package.json

@@ -1,24 +1,29 @@
 {
   "name": "@strav/machine",
-  "version": "0.4.31",
+  "version": "1.0.0-alpha.8",
+  "description": "Strav state machines — declarative transitions with guards, effects, events + a stateful() Repository mixin.",
   "type": "module",
-  "description": "State machine for the Strav framework",
-  "license": "MIT",
+  "main": "./src/index.ts",
+  "types": "./src/index.ts",
   "exports": {
-    ".": "./src/index.ts",
-    "./*": "./src/*.ts"
+    ".": "./src/index.ts"
   },
   "files": [
-    "src/",
-    "package.json",
-    "tsconfig.json"
+    "src",
+    "README.md"
   ],
+  "engines": {
+    "bun": ">=1.3.14"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@strav/kernel": "1.0.0-alpha.8",
+    "@strav/database": "1.0.0-alpha.8"
+  },
   "peerDependencies": {
-    "@strav/kernel": "0.4.31",
-    "@strav/database": "0.4.31"
+    "@types/bun": ">=1.3.14"
   },
-  "scripts": {
-    "test": "bun test tests/",
-    "typecheck": "tsc --noEmit"
-  }
+  "devDependencies": null
 }

package/src/define_machine.ts

@@ -0,0 +1,136 @@
+/**
+ * `defineMachine(...)` — build a `Machine` from a declarative definition.
+ *
+ * The returned object is a pure (no DI, no DB, no event bus) value: the
+ * same machine works for an in-memory POJO, a Repository-managed row,
+ * or a request DTO. Persistence and event emission are layered on top
+ * via the `stateful(...)` Repository mixin.
+ *
+ * The `field` and `transitions` are required; `guards`, `effects`, and
+ * `events` are optional. A machine with no guards/effects/events is a
+ * pure transition validator — still useful for `can()` / `availableTransitions()`.
+ *
+ * Example:
+ *
+ * ```ts
+ * type OrderState      = 'pending' | 'processing' | 'shipped' | 'delivered' | 'cancelled'
+ * type OrderTransition = 'process' | 'ship' | 'deliver' | 'cancel'
+ *
+ * export const orderMachine = defineMachine<Order, OrderState, OrderTransition>({
+ *   field: 'status',
+ *   initial: 'pending',
+ *   states: ['pending', 'processing', 'shipped', 'delivered', 'cancelled'],
+ *   transitions: {
+ *     process: { from: 'pending',                    to: 'processing' },
+ *     ship:    { from: 'processing',                 to: 'shipped'    },
+ *     deliver: { from: 'shipped',                    to: 'delivered'  },
+ *     cancel:  { from: ['pending', 'processing'],    to: 'cancelled'  },
+ *   },
+ *   guards:  { cancel: (order) => !order.locked },
+ *   effects: { ship:   async (order) => sendShippingNotification(order) },
+ *   events:  { ship:   'order.shipped' },
+ * })
+ * ```
+ */
+
+import { GuardError } from './guard_error.ts'
+import type { Machine } from './machine.ts'
+import type {
+  MachineDefinition,
+  TransitionMeta,
+} from './machine_definition.ts'
+import { TransitionError } from './transition_error.ts'
+
+export function defineMachine<
+  TEntity extends object,
+  TState extends string,
+  TTransition extends string,
+>(
+  definition: MachineDefinition<TEntity, TState, TTransition>,
+): Machine<TEntity, TState, TTransition> {
+  // Pre-compute the `from` array for each transition so `can()` and
+  // `availableTransitions()` don't re-normalize on every call.
+  const fromMap = new Map<TTransition, readonly TState[]>()
+  for (const [name, def] of Object.entries(definition.transitions) as Array<
+    [TTransition, TransitionDef<TState>]
+  >) {
+    fromMap.set(name, Array.isArray(def.from) ? def.from : [def.from])
+  }
+
+  const readField = (entity: TEntity): TState =>
+    (entity as Record<string, unknown>)[definition.field] as TState
+
+  return {
+    definition,
+
+    state: readField,
+
+    is: (entity, state) => readField(entity) === state,
+
+    can(entity, transition) {
+      const allowed = fromMap.get(transition)
+      if (!allowed) return false
+      const current = readField(entity)
+      if (!allowed.includes(current)) return false
+      const guard = definition.guards?.[transition]
+      if (!guard) return true
+      const result = guard(entity)
+      // Preserve sync vs async — apps that want a boolean today
+      // shouldn't be forced into a Promise when no guard is async.
+      if (result instanceof Promise) return result
+      return result
+    },
+
+    availableTransitions(entity) {
+      const current = readField(entity)
+      const available: TTransition[] = []
+      for (const [name, allowed] of fromMap) {
+        if (allowed.includes(current)) available.push(name)
+      }
+      return available
+    },
+
+    async apply(entity, transition) {
+      const def = definition.transitions[transition]
+      const current = readField(entity)
+      if (!def) {
+        throw new TransitionError(transition, current)
+      }
+      const allowed = fromMap.get(transition) ?? []
+      if (!allowed.includes(current)) {
+        throw new TransitionError(transition, current, allowed)
+      }
+      const guard = definition.guards?.[transition]
+      if (guard) {
+        const passed = await guard(entity)
+        if (!passed) {
+          throw new GuardError(transition, current)
+        }
+      }
+
+      const meta: TransitionMeta<TState, TTransition> = {
+        from: current,
+        to: def.to,
+        transition,
+      }
+
+      // Mutate first so any effect sees the new state on the entity.
+      // Cast through `unknown` because `TState` is more specific than
+      // `unknown` and `Record<string, unknown>` widens to it.
+      ;(entity as Record<string, unknown>)[definition.field] = def.to
+
+      const effect = definition.effects?.[transition]
+      if (effect) {
+        await effect(entity, meta)
+      }
+
+      return meta
+    },
+  }
+}
+
+// Narrow alias for the inner-loop type assertion above; not exported.
+interface TransitionDef<TState extends string> {
+  from: TState | readonly TState[]
+  to: TState
+}

package/src/guard_error.ts

@@ -0,0 +1,21 @@
+/**
+ * Thrown when a transition's guard returns `false` (or its Promise
+ * resolves to `false`). Distinct from `TransitionError` so apps can
+ * render different UX for "you can't do that from this state" vs
+ * "you can't do that right now" — both 422, different `code`.
+ *
+ * A guard that *throws* (rather than returning `false`) propagates the
+ * throw verbatim; this error fires only on the "guard said no" path.
+ */
+
+import { StravError } from '@strav/kernel'
+
+export class GuardError extends StravError {
+  constructor(transition: string, from: string) {
+    super(
+      `Guard rejected transition "${transition}" from state "${from}".`,
+      { code: 'machine.guard-rejected', status: 422 },
+      { context: { transition, from } },
+    )
+  }
+}

package/src/index.ts

@@ -1,4 +1,17 @@
-export { defineMachine } from './machine.ts'
-export { stateful } from './stateful.ts'
-export { TransitionError, GuardError } from './errors.ts'
-export type { MachineDefinition, TransitionDefinition, TransitionMeta, Machine } from './types.ts'
+// Public API of @strav/machine.
+//
+// State machines + a `stateful()` Repository mixin. The machine itself is
+// pure (no DI, no DB, no event bus). The mixin layers in persistence
+// via Repository.update + optional event emission via the Repository's
+// EventBus.
+
+export { defineMachine } from './define_machine.ts'
+export { GuardError } from './guard_error.ts'
+export type { Machine } from './machine.ts'
+export type {
+  MachineDefinition,
+  TransitionDefinition,
+  TransitionMeta,
+} from './machine_definition.ts'
+export { type RepositoryConstructor, stateful } from './stateful.ts'
+export { TransitionError } from './transition_error.ts'

package/src/machine.ts

@@ -1,146 +1,58 @@
-import { Emitter } from '@strav/kernel'
-import type { MachineDefinition, Machine, TransitionMeta } from './types.ts'
-import { TransitionError, GuardError } from './errors.ts'
-
 /**
- * Define a state machine.
+ * `Machine` — the runtime interface produced by `defineMachine(...)`.
  *
- * Returns a `Machine` object that can validate and apply transitions to any entity.
- * The machine operates on a single field of the entity object.
+ * Methods operate on any entity object that has the configured `field`.
+ * The interface is decoupled from `@strav/database` so apps can use
+ * machines on POJOs, query result rows, request payloads, etc. The
+ * `stateful(...)` mixin in `stateful.ts` is the convenience wrapper for
+ * the common case ("apply a transition and save it through a
+ * Repository, optionally emit").
  *
- * @example
- * const orderMachine = defineMachine({
- *   field: 'status',
- *   initial: 'pending',
- *   states: ['pending', 'processing', 'shipped', 'delivered', 'canceled'],
- *   transitions: {
- *     process: { from: 'pending', to: 'processing' },
- *     ship:    { from: 'processing', to: 'shipped' },
- *     deliver: { from: 'shipped', to: 'delivered' },
- *     cancel:  { from: ['pending', 'processing'], to: 'canceled' },
- *   },
- *   guards: {
- *     cancel: (order) => !order.locked,
- *   },
- *   effects: {
- *     ship: async (order) => await sendShippingNotification(order),
- *   },
- *   events: {
- *     ship:    'order:shipped',
- *     deliver: 'order:delivered',
- *   },
- * })
+ * `apply()` mutates the entity in-place and returns the `TransitionMeta`
+ * for the move. It does NOT persist — callers handle persistence
+ * (the `stateful` mixin does it for you).
  */
-export function defineMachine<TState extends string, TTransition extends string>(
-  definition: MachineDefinition<TState, TTransition>
-): Machine<TState, TTransition> {
-  // Pre-compute normalized from-arrays for each transition
-  const fromMap = new Map<TTransition, TState[]>()
-  for (const [name, def] of Object.entries(definition.transitions) as [
-    TTransition,
-    { from: TState | TState[]; to: TState },
-  ][]) {
-    fromMap.set(name, Array.isArray(def.from) ? def.from : [def.from])
-  }
-
-  return {
-    definition,
-
-    state(entity: any): TState {
-      return entity[definition.field] as TState
-    },
-
-    is(entity: any, state: TState): boolean {
-      return entity[definition.field] === state
-    },
-
-    can(entity: any, transition: TTransition): boolean | Promise<boolean> {
-      const currentState = entity[definition.field] as TState
-      const allowed = fromMap.get(transition)
-      if (!allowed || !allowed.includes(currentState)) return false
-
-      const guard = definition.guards?.[transition]
-      if (!guard) return true
-
-      const result = guard(entity)
-      // Support both sync and async guards
-      if (typeof (result as any)?.then === 'function') {
-        return result as Promise<boolean>
-      }
-      return result as boolean
-    },
-
-    availableTransitions(entity: any): TTransition[] {
-      const currentState = entity[definition.field] as TState
-      const available: TTransition[] = []
-
-      for (const [name, fromStates] of fromMap) {
-        if (fromStates.includes(currentState)) {
-          available.push(name)
-        }
-      }
-
-      return available
-    },
-
-    async apply(
-      entity: any,
-      transition: TTransition
-    ): Promise<TransitionMeta<TState, TTransition>> {
-      const currentState = entity[definition.field] as TState
-      const transitionDef = definition.transitions[transition]
-      if (!transitionDef) {
-        throw new TransitionError(transition, currentState)
-      }
-
-      const allowed = fromMap.get(transition)!
-      if (!allowed.includes(currentState)) {
-        throw new TransitionError(transition, currentState, allowed)
-      }
-
-      // Run guard
-      const guard = definition.guards?.[transition]
-      if (guard) {
-        const passed = await guard(entity)
-        if (!passed) {
-          throw new GuardError(transition, currentState)
-        }
-      }
-
-      const meta: TransitionMeta<TState, TTransition> = {
-        from: currentState,
-        to: transitionDef.to,
-        transition,
-      }
-
-      // Mutate field
-      entity[definition.field] = transitionDef.to
-
-      // Run effect
-      const effect = definition.effects?.[transition]
-      if (effect) {
-        await effect(entity, meta)
-      }
-
-      // Emit user-defined per-transition event (zero-cost when no listener).
-      const eventName = definition.events?.[transition]
-      if (eventName && Emitter.listenerCount(eventName) > 0) {
-        Emitter.emit(eventName, { entity, ...meta }).catch(() => {})
-      }
-
-      // Emit a generic state-transition event so a single audit hook can
-      // observe every transition across every machine without each
-      // definition wiring an `events.*` entry. Zero-cost when no
-      // listener is registered.
-      if (Emitter.listenerCount('machine:transition') > 0) {
-        Emitter.emit('machine:transition', {
-          entity,
-          field: definition.field,
-          ...meta,
-        }).catch(() => {})
-      }
 
-      return meta
-    },
-  }
+import type {
+  MachineDefinition,
+  TransitionMeta,
+} from './machine_definition.ts'
+
+export interface Machine<
+  TEntity extends object = object,
+  TState extends string = string,
+  TTransition extends string = string,
+> {
+  /** The raw definition passed to `defineMachine`. Exposed for reflection. */
+  readonly definition: MachineDefinition<TEntity, TState, TTransition>
+
+  /** Read the current state directly off the entity's configured field. */
+  state(entity: TEntity): TState
+
+  /** Boolean equality on the current state. */
+  is(entity: TEntity, state: TState): boolean
+
+  /**
+   * `true` when (a) the transition is defined, (b) the entity's current
+   * state is one of the `from` states, and (c) the guard (if any)
+   * resolves to `true`. Falls through to a synchronous boolean when no
+   * guard is registered; otherwise returns a `Promise<boolean>` matching
+   * the guard's signature.
+   */
+  can(entity: TEntity, transition: TTransition): boolean | Promise<boolean>
+
+  /** Names of every transition currently valid from the entity's state, ignoring guards. */
+  availableTransitions(entity: TEntity): TTransition[]
+
+  /**
+   * Validate the transition + run the guard + mutate the field + run the
+   * effect, in that order. Throws `TransitionError` for an undefined or
+   * disallowed transition; `GuardError` when the guard returns `false`;
+   * propagates any throw from guard or effect verbatim. Does **not**
+   * persist or emit — the `stateful(...)` mixin does both.
+   */
+  apply(
+    entity: TEntity,
+    transition: TTransition,
+  ): Promise<TransitionMeta<TState, TTransition>>
 }

package/src/machine_definition.ts

@@ -0,0 +1,83 @@
+/**
+ * Type contracts for `defineMachine(...)`. Apps don't typically import
+ * these directly — they fall out of the generics on `Machine<TEntity,
+ * TState, TTransition>`. They're exported so library code that holds
+ * machines generically can still type-narrow.
+ *
+ * `field` is the property name on the entity that holds the state value.
+ * The machine reads + mutates it via `entity[field]`. Convention is a
+ * snake_case column name (`status`, `state`, `workflow_phase`), but
+ * anything that lives on the entity works.
+ */
+
+/** A single transition: which state(s) can `from`, and which state lands as `to`. */
+export interface TransitionDefinition<TState extends string = string> {
+  /** Source state, or a list of source states. */
+  from: TState | readonly TState[]
+  /** Destination state. */
+  to: TState
+}
+
+/** What a guard / effect / `transition()` callback receives. */
+export interface TransitionMeta<
+  TState extends string = string,
+  TTransition extends string = string,
+> {
+  readonly from: TState
+  readonly to: TState
+  readonly transition: TTransition
+}
+
+/**
+ * Full machine definition — the input to `defineMachine(...)`.
+ *
+ * `guards`, `effects`, and `events` are all keyed on transition names.
+ * Each is optional — a machine with no guards/effects/events is valid
+ * and useful (pure transition validation).
+ */
+export interface MachineDefinition<
+  TEntity extends object = object,
+  TState extends string = string,
+  TTransition extends string = string,
+> {
+  /** Property name on the entity that holds the state. */
+  field: string
+  /** Initial state for newly-created entities — apps that want to reuse it. */
+  initial: TState
+  /** All valid state values — used as a validation reference and a published surface. */
+  states: readonly TState[]
+  /** Named transitions with `from` (one or many) + `to`. */
+  transitions: Record<TTransition, TransitionDefinition<TState>>
+  /**
+   * Guards run AFTER the state-validity check but BEFORE the mutation.
+   * Return `false` (sync or async) to block the transition with
+   * `GuardError`. Throwing also blocks; the throw propagates verbatim.
+   */
+  guards?: Partial<
+    Record<TTransition, (entity: TEntity) => boolean | Promise<boolean>>
+  >
+  /**
+   * Effects run AFTER the entity field is mutated. Use them for
+   * in-process side work that needs to see the new state on the
+   * entity (`order.status === 'shipped'`). For external side effects
+   * that must be transactional with the save, dispatch a Job from the
+   * effect — `@strav/queue` queues until the surrounding tx commits.
+   */
+  effects?: Partial<
+    Record<
+      TTransition,
+      (
+        entity: TEntity,
+        meta: TransitionMeta<TState, TTransition>,
+      ) => void | Promise<void>
+    >
+  >
+  /**
+   * Optional event-bus names emitted on successful transitions. Only
+   * fires when the transition is applied via the `stateful(...)`
+   * Repository mixin (which has access to the Repository's EventBus).
+   * Standalone `machine.apply(entity, name)` skips emission — it has
+   * no EventBus to call.
+   */
+  events?: Partial<Record<TTransition, string>>
+}

package/src/stateful.ts

@@ -1,73 +1,115 @@
-import type { BaseModel } from '@strav/database'
-import type { NormalizeConstructor } from '@strav/kernel'
-import type { Machine, TransitionMeta } from './types.ts'
-
 /**
- * Mixin that adds state machine methods to a BaseModel subclass.
+ * `stateful(Base, machine)` — class-mixin that bolts state-machine
+ * methods onto a `Repository` subclass.
  *
- * @example
- * import { BaseModel } from '@strav/database'
- * import { defineMachine, stateful } from '@strav/machine'
+ * The mixin adds four instance methods that delegate to the machine:
+ *   - `is(entity, state)`             — boolean equality on the state field
+ *   - `can(entity, transition)`       — eligibility check (incl. guard)
+ *   - `availableTransitions(entity)`  — transitions valid from current state
+ *   - `transition(entity, name)`      — validate + mutate + effect + save + emit
  *
- * const orderMachine = defineMachine({
- *   field: 'status',
- *   initial: 'pending',
- *   states: ['pending', 'processing', 'shipped'],
- *   transitions: {
- *     process: { from: 'pending', to: 'processing' },
- *     ship:    { from: 'processing', to: 'shipped' },
- *   },
- * })
+ * `transition()` is the load-bearing method: it runs the machine, persists
+ * the field change via `Repository.update`, and (when the machine
+ * defines an `events.<name>` entry AND the repo was constructed with an
+ * EventBus) emits the event with `{ entity, ...meta }` as the payload.
  *
- * class Order extends stateful(BaseModel, orderMachine) {
- *   declare id: number
- *   declare status: string
- * }
+ * Mixins compose: a Repository can stack `stateful(...)` and any other
+ * mixin via plain class inheritance. The returned class stays abstract
+ * (still needs `static schema = …` + `static model = …` from the
+ * concrete subclass) — the mixin doesn't try to know which schema you're on.
  *
- * const order = await Order.find(1)
- * order.is('pending')            // true
- * order.can('process')           // true
- * await order.transition('process')  // validates, mutates, saves, emits
+ * Example:
+ *
+ * ```ts
+ * @inject()
+ * class OrderRepository extends stateful(Repository<Order>, orderMachine) {
+ *   static override readonly schema = orderSchema
+ *   static override readonly model = Order
+ *   constructor(db: PostgresDatabase, events: EventBus) { super(db, events) }
+ * }
  *
- * // Composable with other mixins:
- * import { compose } from '@strav/kernel'
- * class Order extends compose(BaseModel, searchable, m => stateful(m, orderMachine)) { }
+ * const order = await orderRepo.find('o1')
+ * await orderRepo.transition(order, 'ship')
+ * ```
+ */
+
+import { Repository } from '@strav/database'
+import type { Machine } from './machine.ts'
+import type { TransitionMeta } from './machine_definition.ts'
+
+/**
+ * Constructor type for an abstract Repository subclass — matches the
+ * shape `class extends Repository<T>` produces. Using `abstract new`
+ * lets the mixin accept `Repository` itself (which is abstract).
  */
-export function stateful<T extends NormalizeConstructor<typeof BaseModel>>(
-  Base: T,
-  machine: Machine
-) {
-  return class Stateful extends Base {
-    /** Check if this model instance is in the given state. */
-    is(state: string): boolean {
-      return machine.is(this, state)
+// biome-ignore lint/suspicious/noExplicitAny: mixin constructor signature requires variadic any[]
+export type RepositoryConstructor<TEntity extends object> = abstract new (
+  // biome-ignore lint/suspicious/noExplicitAny: see above
+  ...args: any[]
+) => Repository<TEntity>
+
+export function stateful<
+  TBase extends RepositoryConstructor<TEntity>,
+  TEntity extends object,
+  TState extends string,
+  TTransition extends string,
+>(Base: TBase, machine: Machine<TEntity, TState, TTransition>) {
+  abstract class Stateful extends Base {
+    /** Boolean equality on the configured state field. Pure delegate to the machine. */
+    is(entity: TEntity, state: TState): boolean {
+      return machine.is(entity, state)
     }
 
-    /** Check if a transition can be applied to this model instance. */
-    can(transition: string): boolean | Promise<boolean> {
-      return machine.can(this, transition)
+    /** Eligibility check. Returns a sync boolean unless the registered guard is async. */
+    can(entity: TEntity, transition: TTransition): boolean | Promise<boolean> {
+      return machine.can(entity, transition)
     }
 
-    /** List all transitions available from this model's current state. */
-    availableTransitions(): string[] {
-      return machine.availableTransitions(this)
+    /** Names of every transition currently valid from the entity's state. */
+    availableTransitions(entity: TEntity): TTransition[] {
+      return machine.availableTransitions(entity)
     }
 
     /**
-     * Apply a transition: validate, mutate, save, and emit event.
-     * Throws `TransitionError` if the transition is invalid from the current state.
-     * Throws `GuardError` if the guard rejects the transition.
+     * Apply a transition end-to-end:
+     *   1. Validate the move + run the guard via `machine.apply()`.
+     *      Mutates `entity[field]` in-place.
+     *   2. Run the per-transition `effect` (if any). Effects see the
+     *      new state.
+     *   3. Persist by calling `Repository.update(entity, { [field]: to })`.
+     *      The change propagates through lifecycle events
+     *      (`<resource>.updating` / `<resource>.updated`) just like any
+     *      other update — listeners that care about the state column
+     *      can read the change off the model.
+     *   4. Emit the machine-defined event (when both
+     *      `machine.events[name]` and the Repository's `EventBus` are
+     *      present). Payload is `{ entity, ...meta }`.
+     *
+     * Throws `TransitionError` / `GuardError` from step 1. Effects and
+     * `update()` errors propagate verbatim — in those cases the entity
+     * may already be mutated in-memory but the row hasn't been written.
+     * Callers that need atomicity wrap the call in `UnitOfWork.run(...)`
+     * or `TenantManager.withTenant(...)`.
      */
-    async transition(name: string): Promise<TransitionMeta> {
-      const meta = await machine.apply(this, name)
-      await this.save()
-      return meta
-    }
+    async transition(
+      entity: TEntity,
+      name: TTransition,
+    ): Promise<TransitionMeta<TState, TTransition>> {
+      const meta = await machine.apply(entity, name)
+      const field = machine.definition.field
+      // `Partial<TEntity>` requires the field key + value to type-narrow
+      // against the entity's actual shape; we widen via Record<string, unknown>
+      // because the mixin doesn't know the entity's exact key set.
+      await this.update(entity, { [field]: meta.to } as unknown as Partial<TEntity>)
 
-    /** Query scope: filter records in the given state(s). */
-    static inState(state: string | string[]) {
-      const states = Array.isArray(state) ? state : [state]
-      return (this as any).query().whereIn(machine.definition.field, states)
+      const eventName = machine.definition.events?.[name]
+      if (eventName && this.events) {
+        await this.events.emit(eventName, { entity, ...meta })
+      }
+
+      return meta
     }
   }
+
+  return Stateful
 }

package/src/transition_error.ts

@@ -0,0 +1,35 @@
+/**
+ * Thrown when a transition isn't valid from the entity's current state
+ * (or the transition name isn't defined on the machine at all).
+ *
+ * `context.transition` names the transition the caller tried; `context.from`
+ * is the entity's current state; `context.allowedFrom` is the array of
+ * source states the transition would have accepted — or `null` when the
+ * transition name is undefined entirely.
+ *
+ * Status is 422 (unprocessable) rather than 400 because the request is
+ * well-formed; the *entity* is in the wrong state for the requested action.
+ * Apps that want a different code can override per-instance via the
+ * standard `code` field on `StravErrorOptions`.
+ */
+
+import { StravError } from '@strav/kernel'
+
+export class TransitionError extends StravError {
+  constructor(transition: string, from: string, allowedFrom?: readonly string[]) {
+    const message = allowedFrom
+      ? `Cannot apply transition "${transition}" from state "${from}". Allowed from: [${allowedFrom.join(', ')}].`
+      : `Transition "${transition}" is not defined on this machine.`
+    super(
+      message,
+      { code: 'machine.invalid-transition', status: 422 },
+      {
+        context: {
+          transition,
+          from,
+          allowedFrom: allowedFrom ? [...allowedFrom] : null,
+        },
+      },
+    )
+  }
+}

package/README.md

@@ -1,98 +0,0 @@
-# @strav/machine
-
-State machine for the [Strav](https://www.npmjs.com/package/@strav/core) framework. Declarative state definitions with transitions, guards, side effects, and event emission.
-
-## Install
-
-```bash
-bun add @strav/machine
-```
-
-Requires `@strav/core` as a peer dependency.
-
-## Usage
-
-### Define a Machine
-
-```ts
-import { defineMachine } from '@strav/machine'
-
-const orderMachine = defineMachine({
-  field: 'status',
-  initial: 'pending',
-  states: ['pending', 'processing', 'shipped', 'delivered', 'canceled'],
-  transitions: {
-    process: { from: 'pending', to: 'processing' },
-    ship:    { from: 'processing', to: 'shipped' },
-    deliver: { from: 'shipped', to: 'delivered' },
-    cancel:  { from: ['pending', 'processing'], to: 'canceled' },
-  },
-  guards: {
-    cancel: (order) => !order.locked,
-  },
-  effects: {
-    ship: async (order) => {
-      await sendShippingNotification(order)
-    },
-  },
-  events: {
-    ship:    'order:shipped',
-    deliver: 'order:delivered',
-    cancel:  'order:canceled',
-  },
-})
-```
-
-### Standalone (Any Object)
-
-```ts
-const order = { status: 'pending', id: 1, locked: false }
-
-orderMachine.state(order)                 // 'pending'
-orderMachine.is(order, 'pending')         // true
-orderMachine.can(order, 'process')        // true
-orderMachine.can(order, 'ship')           // false
-orderMachine.availableTransitions(order)  // ['process', 'cancel']
-
-await orderMachine.apply(order, 'process')
-// order.status === 'processing'
-```
-
-### ORM Mixin
-
-```ts
-import { BaseModel } from '@strav/core/orm'
-import { stateful } from '@strav/machine'
-
-class Order extends stateful(BaseModel, orderMachine) {
-  declare id: number
-  declare status: string
-}
-
-const order = await Order.find(1)
-order.is('pending')               // true
-order.can('ship')                 // false
-order.availableTransitions()      // ['process', 'cancel']
-
-await order.transition('process')
-// validates → mutates → saves → emits event
-
-// Query helpers
-const shipped = await Order.inState('shipped').get()
-const active = await Order.inState(['processing', 'shipped']).get()
-```
-
-## Features
-
-- **Guards** — sync or async functions that must return `true` for a transition to proceed
-- **Effects** — side effects that run after the state is mutated (before persistence in the mixin)
-- **Events** — automatic `Emitter.emit()` after transitions complete
-- **Composable** — works with `compose()` alongside other mixins like `searchable()`
-
-## Documentation
-
-See the full [Machine guide](../../guides/machine.md).
-
-## License
-
-MIT

package/src/errors.ts

@@ -1,27 +0,0 @@
-import { StravError } from '@strav/kernel'
-
-/** Thrown when a transition is not valid from the entity's current state. */
-export class TransitionError extends StravError {
-  constructor(
-    public readonly transition: string,
-    public readonly currentState: string,
-    public readonly allowedFrom?: string[]
-  ) {
-    super(
-      allowedFrom
-        ? `Cannot apply transition "${transition}" from state "${currentState}". ` +
-            `Allowed from: [${allowedFrom.join(', ')}]`
-        : `Transition "${transition}" is not defined.`
-    )
-  }
-}
-
-/** Thrown when a transition's guard rejects the transition. */
-export class GuardError extends StravError {
-  constructor(
-    public readonly transition: string,
-    public readonly currentState: string
-  ) {
-    super(`Guard rejected transition "${transition}" from state "${currentState}".`)
-  }
-}

package/src/types.ts

@@ -1,68 +0,0 @@
-// ── Machine Definition ──────────────────────────────────────────────────────
-
-export interface TransitionDefinition<TState extends string = string> {
-  from: TState | TState[]
-  to: TState
-}
-
-export interface MachineDefinition<
-  TState extends string = string,
-  TTransition extends string = string,
-> {
-  /** The field on the entity that holds the state value. */
-  field: string
-  /** The initial state for new entities. */
-  initial: TState
-  /** All valid states. */
-  states: TState[]
-  /** Named transitions with from/to state definitions. */
-  transitions: Record<TTransition, TransitionDefinition<TState>>
-  /** Guard functions that must return true for a transition to proceed. */
-  guards?: Partial<Record<TTransition, (entity: any) => boolean | Promise<boolean>>>
-  /** Side effects to run after a transition (before persistence). */
-  effects?: Partial<
-    Record<
-      TTransition,
-      (entity: any, meta: TransitionMeta<TState, TTransition>) => void | Promise<void>
-    >
-  >
-  /** Event names to emit via Emitter after a transition completes. */
-  events?: Partial<Record<TTransition, string>>
-}
-
-// ── Transition Meta ─────────────────────────────────────────────────────────
-
-export interface TransitionMeta<
-  TState extends string = string,
-  TTransition extends string = string,
-> {
-  from: TState
-  to: TState
-  transition: TTransition
-}
-
-// ── Machine Interface ───────────────────────────────────────────────────────
-
-export interface Machine<TState extends string = string, TTransition extends string = string> {
-  /** The machine definition. */
-  readonly definition: MachineDefinition<TState, TTransition>
-
-  /** Get the current state of an entity. */
-  state(entity: any): TState
-
-  /** Check if an entity is in a specific state. */
-  is(entity: any, state: TState): boolean
-
-  /** Check if a transition can be applied (valid from-state + guard passes). */
-  can(entity: any, transition: TTransition): boolean | Promise<boolean>
-
-  /** List all transitions available from the entity's current state. */
-  availableTransitions(entity: any): TTransition[]
-
-  /**
-   * Apply a transition to an entity.
-   * Validates the from-state, runs the guard, mutates the field, runs the effect, and emits the event.
-   * Does NOT persist — caller is responsible for saving.
-   */
-  apply(entity: any, transition: TTransition): Promise<TransitionMeta<TState, TTransition>>
-}

package/tsconfig.json

@@ -1,5 +0,0 @@
-{
-  "extends": "../../tsconfig.json",
-  "include": ["src/**/*.ts"],
-  "exclude": ["node_modules", "tests"]
-}