docs: migrate jobs model docs

Co-authored-by: Cursor <cursoragent@cursor.com>

Author: 0xgleb

AGENTS.md

@@ -28,7 +28,7 @@ the limit:
 **Read when relevant** to your task:
 
 - [docs/cqrs.md](docs/cqrs.md) - Event sourcing patterns: the `EventSourced`
-  trait, `Lifecycle` adapter, projections, services, schema registry.
+  trait, `Lifecycle` adapter, projections, jobs, schema registry.
 - [docs/sqlx.md](docs/sqlx.md) - `SQLX_OFFLINE`, `query!` vs runtime queries,
   regenerating the `.sqlx/` cache, common pitfalls.
 - [docs/ttdd.md](docs/ttdd.md) - Type-driven TDD workflow: scientific method
@@ -219,7 +219,7 @@ workspace has two crates and no application binaries:
   repository traits. Standalone; usable wherever a `cqrs-es` backend is needed.
 - **`crates/event-sorcery`** — higher-level ergonomics on top of `sqlite-es`:
   the `EventSourced` trait, `Lifecycle` adapter, typed `Store`, projections,
-  schema registry, reactor.
+  schema registry, reactor, and apalis-backed jobs.
 
 The `migrations/` directory at the workspace root holds the canonical SQLite
 schema (events + snapshots tables) that `sqlite_es::testing::create_test_pool`

README.md

@@ -35,7 +35,7 @@ explaining what it covers. Run any of them with
 - [`docs/domain.md`](docs/domain.md) — domain terminology and naming
   conventions.
 - [`docs/cqrs.md`](docs/cqrs.md) — event-sourcing patterns, the `EventSourced`
-  trait, projections, services, schema registry.
+  trait, projections, jobs, schema registry.
 - [`docs/sqlx.md`](docs/sqlx.md) — `SQLX_OFFLINE`, `query!` vs runtime queries,
   regenerating the query cache.
 - [`docs/ttdd.md`](docs/ttdd.md) — type-driven TDD methodology used in this

SPEC.md

@@ -86,7 +86,8 @@ everything needed to event-source the type:
 - `Event` — domain event type (must implement `DomainEvent`)
 - `Command` — input that drives state transitions
 - `Error` — domain failure type (`Never` if everything is infallible)
-- `Services` — external dependencies passed into command handlers
+- `Jobs` — type-level list (`JobList`) of durable job types this entity's
+  handlers may enqueue; `Nil` when none
 - `Materialized` — `Table` if the entity has a SQLite-backed projection, `Nil`
   otherwise
 - `AGGREGATE_TYPE` — stable string identifier used in the event store
@@ -98,7 +99,11 @@ It splits behavior across two pairs:
   derives new state from subsequent events. Both are fallible.
 - Command-side: `initialize` handles a command when no state exists yet;
   `transition` handles a command against existing state. The split prevents
-  accidentally reading "current state" while bootstrapping.
+  accidentally reading "current state" while bootstrapping. Both are synchronous
+  and pure — they compute `Vec<Event>` and may enqueue durable jobs through a
+  `&mut JobQueue<Self::Jobs>`, but perform no I/O. External reads a handler once
+  did through `Services` (clock, config, idempotency keys) are now supplied
+  through the `Command`.
 
 ### `Lifecycle` adapter
 
@@ -138,6 +143,32 @@ Side-effect handler keyed off events. Used for cross-aggregate orchestration
 (e.g., one aggregate's event triggers a command on another). Has automatic
 retry-with-backoff on optimistic-lock conflicts.
 
+### Jobs
+
+Durable, retryable side-effect work. Handlers stay pure by enqueuing jobs
+instead of calling external systems directly:
+
+- `Job` — a serializable unit of work. Declares its dependency bundle (`Input`),
+  `Output`, and `Error`, a `perform(&self, &Input)` body, and constants for
+  worker naming, kind, and terminal-failure logging.
+- `JobList` / `HasJob<J>` — a type-level list (`Cons` / `Nil`) of the job types
+  an entity may dispatch. `JobQueue::push::<J>` is bounded
+  `where Jobs:
+  HasJob<J>`, so a handler can enqueue only the jobs its entity
+  declares — checked at compile time. `jobs![A, B]` is sugar for the list.
+- `JobQueue<Jobs>` — the handler-facing handle. `push` / `push_with_delay` are
+  synchronous and buffer onto the handle; the framework drains the buffer inside
+  the event-commit transaction (see "Job dispatch").
+- `JobBackend<J>` — apalis-backed `SqliteStorage` for one job type, built once
+  at startup and owned by the worker side.
+- `build_supervised_worker!` — wires a worker with the shared retry policy,
+  exponential backoff, circuit breaker, and terminal-failure notifier, so every
+  consumer gets identical execution semantics.
+
+apalis (`apalis`, `apalis-sqlite`, `apalis-core`, `apalis-codec`) is the
+non-negotiable queue backend; it is part of event-sorcery's public surface, not
+a feature flag.
+
 ### `SchemaRegistry`
 
 Tracks `(aggregate_type, schema_version)` tuples in a `schema_registry` table.
@@ -166,12 +197,31 @@ projection becomes a type error, not silent data staleness.
 2. `Store` looks up the aggregate, loads its `Lifecycle`, applies any relevant
    snapshot, replays uncached events.
 3. `Lifecycle::handle` routes to `EventSourced::initialize` (no state) or
-   `EventSourced::transition` (has state) and produces events.
-4. `cqrs-es::CqrsFramework` persists events with monotonic sequence numbers in
-   the same SQL transaction as any side-effects implemented via cqrs-es
-   `Service`s.
+   `EventSourced::transition` (has state) and produces events. The handler also
+   buffers any job pushes onto its `JobQueue` handle.
+4. `cqrs-es::CqrsFramework` persists events with monotonic sequence numbers, and
+   the framework drains the buffered `JobQueue` into the apalis `Jobs` table —
+   both in the same SQL transaction, so events and their jobs commit or roll
+   back together.
 5. Reactors registered on this aggregate are notified.
 
+### Job dispatch
+
+Command handlers never touch external systems. They enqueue work onto the
+`JobQueue<Self::Jobs>` handle the framework hands them; `push` is synchronous
+and only buffers. The framework flushes the buffer with a transaction-bound
+`INSERT` into the apalis `Jobs` table inside the same transaction that persists
+the events (write-path step 4). A crash before commit loses both the events and
+the jobs; a crash after commit leaves a durable job row the worker will pick up.
+This closes the window where a side effect fires but no event records it.
+Because the push is buffered, a queued row is never observable mid-handler.
+
+A separate apalis worker — wired with `build_supervised_worker!` — polls the
+table, runs each `Job::perform`, retries with exponential backoff, and trips a
+circuit breaker on sustained failure. Because the worker retries on failure and
+re-runs a job after a crash, jobs are delivered at-least-once: `Job::perform`
+must be idempotent, with any dedup key carried in the job payload or `Input`.
+
 ### Read path
 
 Consumers query via `Projection::load(...)`, never by replaying events

docs/cqrs.md

@@ -69,13 +69,12 @@ pub enum MyEntityCommand {
 ### 3. Implement EventSourced
 
 ```rust
-#[async_trait]
 impl EventSourced for MyEntity {
     type Id = MyEntityId;       // strongly-typed, Display + FromStr
     type Event = MyEntityEvent;
     type Command = MyEntityCommand;
     type Error = Never;         // or a thiserror type
-    type Services = ();         // or Arc<dyn SomeService>
+    type Jobs = Nil;            // or jobs![SendEmail, ChargeCard]
     type Materialized = Table;  // Table for projected, Nil for non-projected
 
     const AGGREGATE_TYPE: &'static str = "MyEntity";
@@ -87,10 +86,10 @@ impl EventSourced for MyEntity {
     fn evolve(entity: &Self, event: &Self::Event)
         -> Result<Option<Self>, Self::Error> { /* ... */ }
 
-    // Command-side: process commands to produce events
-    async fn initialize(command: Self::Command, services: &Self::Services)
+    // Command-side: sync, pure -- produce events, enqueue jobs
+    fn initialize(command: Self::Command, jobs: &mut JobQueue<Self::Jobs>)
         -> Result<Vec<Self::Event>, Self::Error> { /* ... */ }
-    async fn transition(&self, command: Self::Command, services: &Self::Services)
+    fn transition(&self, command: Self::Command, jobs: &mut JobQueue<Self::Jobs>)
         -> Result<Vec<Self::Event>, Self::Error> { /* ... */ }
 }
 ```
@@ -243,32 +242,73 @@ receives `(error, id, event)` and can reprocess the event from the errored state
 
 Wire reactors via `Unwired` + `StoreBuilder::wire()`.
 
-## Services Pattern
+## Jobs Pattern
+
+Handlers are sync and pure: they must not call external systems. Side-effecting
+work is enqueued as a durable job and runs in a separate worker. The enqueue
+commits in the same SQLite transaction as the events that triggered it, so a job
+exists iff its events do.
+
+The worker retries `perform` on failure and re-runs it after a crash, so jobs
+are delivered **at-least-once** -- `perform` must be idempotent. Carry any dedup
+key in the job payload or `Input`.
+
+Declare a job and the entity's job list:
+
+```rust
+#[derive(Serialize, Deserialize)]
+struct PlaceOrder { order_id: OrderId, quantity: u32 }
+
+impl Job for PlaceOrder {
+    type Input = Arc<dyn OrderPlacer>;   // dependency bundle, injected by the worker
+    type Output = ();
+    type Error = PlaceOrderError;
 
-Inject external dependencies into command handlers:
+    const WORKER_NAME: &'static str = "place-order";
+    const KIND: &'static str = "PlaceOrder";
+
+    fn label(&self) -> Label { Label(format!("place-order:{}", self.order_id)) }
+
+    async fn perform(&self, placer: &Self::Input) -> Result<(), Self::Error> {
+        placer.place_order(self.order_id, self.quantity).await
+    }
+}
+```
 
 ```rust
-type Services = Arc<dyn OrderPlacer>;
+type Jobs = jobs![PlaceOrder];   // Nil if the entity dispatches none
+```
 
-async fn transition(
+Enqueue from a handler through the `jobs` handle. `push` is synchronous and
+buffers; the framework flushes the buffer at commit. `push::<J>` only compiles
+when `J` is in the entity's `Jobs` list (`HasJob<J>`):
+
+```rust
+fn transition(
     &self,
     command: Self::Command,
-    services: &Self::Services,
+    jobs: &mut JobQueue<Self::Jobs>,
 ) -> Result<Vec<Self::Event>, Self::Error> {
-    let result = services.place_order(/* ... */).await?;
-    Ok(vec![MyEvent::OrderPlaced { /* ... */ }])
+    jobs.push(PlaceOrder { order_id: self.id, quantity: command.quantity });
+    Ok(vec![MyEvent::OrderRequested { /* ... */ }])
 }
 ```
 
-Pass services when building the `Store`:
+A queued row is never observable mid-handler -- the push is buffered, not a live
+`INSERT`. Reads a handler once did via `Services` (clock, config, idempotency
+keys) move into the `Command`; the caller supplies them at dispatch time.
+
+Run the jobs in a worker, wired with the shared retry/backoff/circuit-breaker
+policy. `Input` is the only context handed in:
 
 ```rust
-let store = StoreBuilder::<MyEntity>::new(pool)
-    .build(services)
-    .await?;
-```
+let placer: Arc<dyn OrderPlacer> = Arc::new(/* ... */);
+let backend = JobBackend::<PlaceOrder>::new(&pool);
 
-For entities that don't need services, use `type Services = ()`.
+Monitor::new().register(build_supervised_worker!(
+    ::<PlaceOrder>, 0, backend.into_storage(), placer, fail_stop, failure_notify,
+));
+```
 
 ## Schema Versioning
 
@@ -640,38 +680,31 @@ the same result.
 **Call replay at startup** to ensure views are up-to-date with any schema
 changes.
 
-## Services Pattern
+## Jobs and Crash Safety
 
-Domain types can depend on external services (APIs, blockchain, etc.) via the
-`Services` associated type on `EventSourced`:
+The reason handlers enqueue jobs instead of calling out directly: a job's
+enqueue and its triggering events commit in one SQLite transaction. There is no
+window where a side effect fires but no event records it, and none where an
+event commits but the follow-up work is lost.
 
 ```rust
-#[async_trait]
-impl EventSourced for MyEntity {
-    type Services = Arc<dyn MyService>;  // or () if none needed
-
-    async fn transition(
-        &self,
-        command: Self::Command,
-        services: &Self::Services,
-    ) -> Result<Vec<Self::Event>, Self::Error> {
-        let result = services.do_something().await?;
-        Ok(vec![MyEvent::SomethingDone { result }])
-    }
-    // ...
+fn transition(
+    &self,
+    command: Self::Command,
+    jobs: &mut JobQueue<Self::Jobs>,
+) -> Result<Vec<Self::Event>, Self::Error> {
+    jobs.push(SettlePayment { id: self.id });   // buffered, not yet persisted
+    Ok(vec![MyEvent::PaymentRequested { /* ... */ }])
 }
 ```
 
-Pass services when building the `Store`:
-
-```rust
-let services: Arc<dyn MyService> = Arc::new(MyServiceImpl::new());
-let store = StoreBuilder::<MyEntity>::new(pool)
-    .build(services)
-    .await?;
-```
+`push` only buffers; the framework drains the buffer with a transaction-bound
+`INSERT` into the apalis `Jobs` table alongside the event write. On rollback,
+neither is visible. A worker (`build_supervised_worker!`) then polls the table
+and runs `Job::perform` with retries and a circuit breaker. See
+[Jobs Pattern](#jobs-pattern) for the full `Job` impl and worker wiring.
 
-For entities that don't need services, use `type Services = ()`.
+For entities that dispatch no jobs, use `type Jobs = Nil`.
 
 ## Testing Aggregates
 

docs/domain.md

@@ -57,11 +57,14 @@ never mutate state directly.
 
 `event-sorcery` splits command handling into two methods:
 
-- `EventSourced::initialize(command, services)` — for aggregates that don't yet
+- `EventSourced::initialize(command, jobs)` — for aggregates that don't yet
   exist. No `&self`, so handlers can't accidentally read state during creation.
-- `EventSourced::transition(&self, command, services)` — for live aggregates.
+- `EventSourced::transition(&self, command, jobs)` — for live aggregates.
   Receives the domain type, never the wrapping `Lifecycle`.
 
+Both handlers are synchronous and pure: they compute events and may enqueue jobs
+through the `jobs` handle, but perform no I/O.
+
 ### Event Application
 
 The pure function that derives new aggregate state from old state plus an event.
@@ -124,11 +127,20 @@ of state, events, or projections changes. Compared against the persisted version
 in the `schema_registry` table on startup; mismatches clear stale snapshots and
 trigger view rebuilds.
 
-### Service
+### Job
+
+A durable, retryable unit of side-effect work (`trait Job`). Command handlers
+enqueue jobs instead of calling external systems directly, which keeps handlers
+pure. Each job declares its dependency bundle (`Input`), `Output`, and `Error`,
+plus a `perform` body. An entity lists the job types its handlers may dispatch
+via `EventSourced::Jobs` (a `JobList`; `Nil` when none).
+
+### Job Queue
 
-External dependency injected into command handlers (`EventSourced::Services`).
-Used so a handler can produce side-effects (e.g., enqueue work) atomically with
-event persistence. `()` when no services are needed.
+The handler-facing handle (`JobQueue<Jobs>`) passed to `initialize` /
+`transition`. `push` is synchronous and buffers the job; the framework flushes
+the buffer into the apalis `Jobs` table in the same transaction that persists
+the triggering events, so a job is enqueued iff its events commit.
 
 ### Lifecycle
 
@@ -180,18 +192,19 @@ Error variants store domain types, not opaque strings. Prefer
 `InvalidSymbol(Symbol)` over `InvalidSymbol(String)`. The compiler then prevents
 the caller from accidentally formatting the symbol away too early.
 
-### CQRS Aggregate Services
+### Job naming
 
-When an aggregate needs to perform side-effects atomically with persistence, the
-cqrs-es Service pattern applies. Naming convention used across consumer code:
+When an aggregate needs a side-effect, it enqueues a job rather than calling out
+from the handler. Naming convention:
 
-- **`{Action}er`** — the trait describing the capability (`OrderPlacer`).
-- **`{Domain}Service`** — the implementation (`OrderPlacementService`).
-- **`{Domain}Manager`** — the orchestration layer that drives commands through
-  the framework (`OrderManager`).
+- **`{Action}`** — the job type, named for the work it performs (`SendWelcome`,
+  `ChargeCard`). No generic `...Job` suffix.
+- **`{Job}Input`** — the dependency bundle the worker injects into `perform`
+  (HTTP clients, config, connection handles), exposed as `Job::Input`.
 
-This convention is library-imposed, not framework-enforced, but the `cqrs-es`
-`Service` parameter on aggregate `handle` is what makes it work.
+Jobs declared by an entity are listed in `EventSourced::Jobs` via `jobs![..]`.
+The framework enqueues them atomically with the triggering events; the
+consumer's worker wiring (`build_supervised_worker!`) runs them.
 
 ### Refactoring completeness