effect-cqrs 0.1.0 → 0.2.0

package/src/EventStore.ts

@@ -25,14 +25,24 @@ export const StoredEvent = Schema.Struct({
   aggregateId: Schema.String,
   version: Schema.Int,
   type: Schema.String,
+  /** The version of the event's schema the payload was written with. Events from before versions existed are `1`. */
+  schemaVersion: Schema.Int,
   payload: Schema.Json,
-  timestamp: Schema.DateTimeUtcFromMillis
+  timestamp: Schema.DateTimeUtcFromMillis,
+  /** Shared by everything that follows from one original request. */
+  correlationId: Schema.NullOr(Schema.String),
+  /** What directly caused the command that recorded the event: a request, a command or another event. */
+  causationId: Schema.NullOr(Schema.String),
+  /** What the command carried beside its payload, see `Metadata`. Events from before metadata existed have `{}`. */
+  metadata: Schema.JsonObject
 })
 export type StoredEvent = typeof StoredEvent.Type
 
 export interface NewEvent {
   readonly type: string
   readonly payload: Schema.Json
+  /** Defaults to `1`. */
+  readonly schemaVersion?: number | undefined
 }
 
 export interface AppendInput {
@@ -41,8 +51,41 @@ export interface AppendInput {
   /** The stream version the writer based its decision on, `0` for a new stream. */
   readonly expectedVersion: number
   readonly events: ReadonlyArray<NewEvent>
+  readonly correlationId?: string | undefined
+  readonly causationId?: string | undefined
+  /** Recorded on every event of the append. Defaults to `{}`. */
+  readonly metadata?: Schema.JsonObject | undefined
 }
 
+/**
+ * Identifies an event wherever it is stored, as the `causationId` of what it causes:
+ * `account/alice@4`. Name and id are URI-encoded, so a `/` or `@` inside one can't
+ * make two events look alike.
+ */
+export const eventId = (event: Pick<StoredEvent, "aggregateName" | "aggregateId" | "version">): string =>
+  `${encodeURIComponent(event.aggregateName)}/${encodeURIComponent(event.aggregateId)}@${event.version}`
+
+/** The columns every adapter stores for a new event, with the defaults filled in. */
+export const toStored = (
+  input: AppendInput,
+  event: NewEvent,
+  index: number,
+  position: number,
+  timestamp: DateTime.Utc
+): StoredEvent => ({
+  position,
+  aggregateName: input.aggregateName,
+  aggregateId: input.aggregateId,
+  version: input.expectedVersion + index + 1,
+  type: event.type,
+  schemaVersion: event.schemaVersion ?? 1,
+  payload: event.payload,
+  timestamp,
+  correlationId: input.correlationId ?? null,
+  causationId: input.causationId ?? null,
+  metadata: input.metadata ?? {}
+})
+
 /**
  * Selects events by stream, type and time. Omitted fields match everything.
  * `startTime` is inclusive and `finishTime` is exclusive, so adding one
@@ -199,15 +242,9 @@ export const makeMemory: Effect.Effect<EventStore["Service"], EventStoreError> =
           expectedVersion: input.expectedVersion
         })
       }
-      const stored = input.events.map((event, index): StoredEvent => ({
-        position: events.length + index + 1,
-        aggregateName: input.aggregateName,
-        aggregateId: input.aggregateId,
-        version: version + index + 1,
-        type: event.type,
-        payload: event.payload,
-        timestamp
-      }))
+      const stored = input.events.map((event, index) =>
+        toStored(input, event, index, events.length + index + 1, timestamp)
+      )
       for (const event of stored) {
         events.push(event)
         stream.push(event)

package/src/EventVersions.ts

@@ -0,0 +1,104 @@
+/**
+ * The older shapes of one event, so that events stored long ago still reach
+ * projections and view models in today's shape. The log is never rewritten:
+ * old payloads are upcast as they are read.
+ *
+ * ```ts
+ * const AccountOpenedV1 = Schema.Struct({ owner: Schema.String })
+ *
+ * const Account = Aggregate.make<State>()({
+ *   name: "account",
+ *   events: AccountEvent,
+ *   initial,
+ *   projection,
+ *   versions: {
+ *     AccountOpened: EventVersions.from(AccountOpenedV1).next(
+ *       AccountEvent.cases.AccountOpened,
+ *       ({ owner }) => ({ owner, currency: "CHF" })
+ *     )
+ *   }
+ * })
+ * ```
+ *
+ * The first schema is version 1, the shape events had before the history was
+ * declared, and every `next` adds a version. The last one must be the event's
+ * current schema, which is what new events are written with.
+ */
+import { Schema, SchemaGetter } from "effect"
+
+/** A schema that decodes and encodes without services, as stored payloads need. */
+export type VersionSchema = Schema.Top & {
+  readonly DecodingServices: never
+  readonly EncodingServices: never
+}
+
+/** What an upcast returns: the next version, without the `_tag` the event's name already gives. */
+export type Untagged<T> = T extends { readonly _tag: string } ? Omit<T, "_tag"> : T
+
+type Last<Schemas extends ReadonlyArray<VersionSchema>> = Schemas extends readonly [...any, infer L extends VersionSchema]
+  ? L
+  : VersionSchema
+
+export interface EventVersions<Schemas extends ReadonlyArray<VersionSchema>, Latest> {
+  /** Oldest first: `schemas[0]` is version 1. */
+  readonly schemas: Schemas
+  /** `upcasts[i]` turns version `i + 1` into version `i + 2`. */
+  readonly upcasts: ReadonlyArray<(previous: any) => unknown>
+  /** The type of the last version, which an aggregate checks against its event. */
+  readonly "~latest"?: Latest
+  /** Adds a version, with the function that turns the previous one into it. */
+  next<Next extends VersionSchema>(
+    schema: Next,
+    upcast: (previous: Latest) => Untagged<Next["Type"]>
+  ): EventVersions<readonly [...Schemas, Next], Next["Type"]>
+}
+
+/** Any history whose last version is `Latest`. */
+export type Any<Latest = any> = EventVersions<ReadonlyArray<VersionSchema>, Latest>
+
+/** The schema of one version, or `never` when the history has no such version. */
+export type SchemaAt<H extends Any, V extends number> = H extends EventVersions<infer Schemas, any>
+  ? [never, ...Schemas][V] extends infer S extends VersionSchema ? S : never
+  : never
+
+const build = <Schemas extends ReadonlyArray<VersionSchema>>(
+  schemas: Schemas,
+  upcasts: ReadonlyArray<(previous: any) => unknown>
+): EventVersions<Schemas, Last<Schemas>["Type"]> => ({
+  schemas,
+  upcasts,
+  next: (schema, upcast) => build([...schemas, schema] as const, [...upcasts, upcast]) as any
+})
+
+/** Starts a history at version 1. */
+export const from = <V1 extends VersionSchema>(schema: V1): EventVersions<readonly [V1], V1["Type"]> =>
+  build([schema] as const, [])
+
+/** The version new events of this kind are written with. */
+export const current = (versions: Any | undefined): number => versions?.schemas.length ?? 1
+
+/**
+ * Builds one decoder per old version, each going all the way to the current one.
+ * The chains are composed once with `Schema.decodeTo`, so reading an old event
+ * costs one decode however many versions it is behind.
+ *
+ * `decoders[v - 1]` decodes a JSON payload stored at version `v`. The current
+ * version has none, as the aggregate's own schema reads it.
+ */
+export const decoders = (tag: string, versions: Any): ReadonlyArray<Schema.Decoder<unknown>> =>
+  versions.schemas.slice(0, -1).map((schema, index) =>
+    versions.schemas.slice(index + 1).reduce<Schema.Top>(
+      (chain, next, step) =>
+        chain.pipe(Schema.decodeTo(Schema.toType(next), {
+          // Adding the tag lets the last step decode into the tagged event, and a
+          // schema in between without one drops it again.
+          decode: SchemaGetter.transform((previous) => ({
+            ...(versions.upcasts[index + step]!(previous) as object),
+            _tag: tag
+          })),
+          // A payload is only ever written in its current version.
+          encode: SchemaGetter.forbidden(() => `${tag} can only be written in its current version`)
+        })),
+      Schema.toCodecJson(schema)
+    ) as Schema.Decoder<unknown>
+  )

package/src/Fixture.ts

@@ -13,9 +13,13 @@
  *
  * Commands run through the real {@link AggregateService} on an in-memory store,
  * so payload validation and event encoding are exercised too.
+ *
+ * The history can include events stored in older versions of their schema, made
+ * with `Aggregate.historical`, which then go through the same upcasting as events
+ * read from a real store.
  */
-import { Effect, Effectable, Schema } from "effect"
-import type * as Aggregate from "./Aggregate.ts"
+import { Arbitrary, Effect, Effectable, Schema } from "effect"
+import * as Aggregate from "./Aggregate.ts"
 import * as AggregateService from "./AggregateService.ts"
 import { EventStore, makeMemory } from "./EventStore.ts"
 
@@ -37,6 +41,30 @@ export interface Outcome<A extends Aggregate.Any> {
 /** An event to compare with, or only its tag when the rest doesn't matter. */
 export type ExpectedEvent<A extends Aggregate.Any> = Aggregate.Event<A> | Aggregate.Event<A>["_tag"]
 
+/** An event in today's shape, or one stored in an older version of its schema. */
+export type GivenEvent<A extends Aggregate.Any> = Aggregate.Event<A> | Aggregate.Historical
+
+/** One generated step of {@link Fixture.checkInvariants}. */
+export type Step<A extends Aggregate.Any> = {
+  readonly [K in Aggregate.CommandName<A>]: { readonly command: K; readonly payload: Aggregate.Payload<A, K> }
+}[Aggregate.CommandName<A>]
+
+export interface InvariantOptions<A extends Aggregate.Any> {
+  /** Must hold for the given state and after every command that succeeds. */
+  readonly invariant: (state: Aggregate.State<A>) => boolean
+  /**
+   * How to generate each command's payload. By default it comes from the payload
+   * schema. `false` leaves a command out.
+   */
+  readonly commands?: {
+    readonly [K in Aggregate.CommandName<A>]?: Arbitrary.Arbitrary<Aggregate.Payload<A, K>> | false
+  } | undefined
+  /** The longest sequence of commands to try. Defaults to 20. */
+  readonly maxCommands?: number | undefined
+  /** Passed on to `Arbitrary.checkEffect`, for the number of runs or a seed. */
+  readonly check?: Arbitrary.CheckOptions | undefined
+}
+
 /**
  * The steps so far. Nothing runs until it is yielded or run as an Effect, which
  * produces the {@link Outcome} of the last command.
@@ -62,9 +90,9 @@ export interface Scenario<A extends Aggregate.Any, E, R> extends Effect.Effect<O
 
 export interface Fixture<A extends Aggregate.Any> {
   /** Replaces the history the next command runs against. */
-  given(events: ReadonlyArray<Aggregate.Event<A>>): Fixture<A>
+  given(events: ReadonlyArray<GivenEvent<A>>): Fixture<A>
   /** Like `given`, starting from an empty history by default and optionally switching aggregate id. */
-  givenEvents(events?: ReadonlyArray<Aggregate.Event<A>>, aggregateId?: string): Fixture<A>
+  givenEvents(events?: ReadonlyArray<GivenEvent<A>>, aggregateId?: string): Fixture<A>
   /** The state after the given events, without running a command. */
   readonly state: Effect.Effect<Aggregate.State<A>, AggregateService.ReadError, Aggregate.Context<A>>
   /** Passes the state after the given events to a callback, which throws to fail the test. */
@@ -80,6 +108,13 @@ export interface Fixture<A extends Aggregate.Any> {
     command: K,
     payload: Aggregate.Payload<A, K>
   ): Effect.Effect<Aggregate.CommandError<A, K> | AggregateService.CommandFailure, never, Aggregate.Context<A>>
+  /**
+   * Runs random sequences of commands from the given history and checks that the
+   * invariant holds after each one that succeeds. Commands that fail are part of
+   * the game and are skipped. A violation dies with {@link ExpectationFailed},
+   * holding the shortest sequence found that breaks it.
+   */
+  checkInvariants(options: InvariantOptions<A>): Effect.Effect<void, never, Aggregate.Context<A>>
 }
 
 class ScenarioImpl<A extends Aggregate.Any, E, R> extends Effectable.Class<Outcome<A>, E, R>
@@ -145,12 +180,14 @@ export const make = <A extends Aggregate.Any>(
   aggregate: A,
   options?: {
     readonly aggregateId?: string
-    readonly events?: ReadonlyArray<Aggregate.Event<A>>
+    readonly events?: ReadonlyArray<GivenEvent<A>>
   }
 ): Fixture<A> => {
   const aggregateId = options?.aggregateId ?? "fixture-id"
   const history = options?.events ?? []
   const encodeEvent = AggregateService.makeEventEncoder(aggregate)
+  const encodeGiven = (event: GivenEvent<A>) =>
+    event instanceof Aggregate.Historical ? Effect.succeed(event) : encodeEvent(event)
 
   const seeded = Effect.gen(function*() {
     const store = yield* makeMemory
@@ -159,7 +196,7 @@ export const make = <A extends Aggregate.Any>(
         aggregateName: aggregate.name,
         aggregateId,
         expectedVersion: 0,
-        events: yield* Effect.forEach(history, encodeEvent)
+        events: yield* Effect.forEach(history, encodeGiven)
       })
     }
     const service = yield* AggregateService.make(aggregate).pipe(Effect.provideService(EventStore, store))
@@ -187,6 +224,53 @@ export const make = <A extends Aggregate.Any>(
       })
     )
 
+  const checkInvariants = (options: InvariantOptions<A>) =>
+    Effect.gen(function*() {
+      const commands = Object.entries(aggregate.commands).flatMap(([name, command]) => {
+        const given = options.commands?.[name as Aggregate.CommandName<A>] as
+          | Arbitrary.Arbitrary<unknown>
+          | false
+          | undefined
+        if (given === false) return []
+        const payload = given ?? Arbitrary.schema(Schema.toType(command.payload))
+        return [[name, Arbitrary.map(payload, (payload: unknown) => ({ command: name, payload }))] as const]
+      })
+      if (commands.length === 0) {
+        return yield* Effect.die(new Error("checkInvariants needs at least one command to run"))
+      }
+      const byName = new Map(commands)
+      const steps = Arbitrary.array(
+        Arbitrary.flatMap(Arbitrary.schema(Schema.Literals(commands.map(([name]) => name))), (name) => byName.get(name)!),
+        { maxLength: options.maxCommands ?? 20 }
+      ) as Arbitrary.Arbitrary<ReadonlyArray<Step<A>>>
+
+      // Each run starts from a fresh store with the given history.
+      const holds = (sequence: ReadonlyArray<Step<A>>) =>
+        Effect.gen(function*() {
+          const service = yield* seeded
+          if (!options.invariant(yield* service.readModel(aggregateId))) return false
+          for (const step of sequence) {
+            const succeeded = yield* service.commands[step.command](aggregateId, step.payload).pipe(
+              Effect.as(true),
+              Effect.catch(() => Effect.succeed(false))
+            )
+            if (succeeded && !options.invariant(yield* service.readModel(aggregateId))) return false
+          }
+          return true
+        }).pipe(Effect.orDie)
+
+      const result = yield* Arbitrary.checkEffect(steps, holds, options.check)
+      if (result._tag !== "Passed") {
+        return yield* Effect.die(
+          new ExpectationFailed({
+            message: Arbitrary.formatCheckFailure(result) ?? "The invariant does not hold",
+            expected: "the invariant to hold after every command",
+            actual: result._tag === "Falsified" ? result.shrunkInput : result
+          })
+        )
+      }
+    })
+
   const fixture: Fixture<A> = {
     given: (events) => make(aggregate, { aggregateId, events }),
     givenEvents: (events = [], id = aggregateId) => make(aggregate, { aggregateId: id, events }),
@@ -206,7 +290,8 @@ export const make = <A extends Aggregate.Any>(
       when(command, payload).pipe(
         Effect.flip,
         Effect.catch(() => Effect.die(new Error(`Expected command "${command}" to fail, but it succeeded`)))
-      )
+      ),
+    checkInvariants
   }
 
   return fixture

package/src/Metadata.ts

@@ -0,0 +1,52 @@
+/**
+ * Metadata: what a command carries beside its payload that the domain doesn't
+ * decide on, such as the version of the software that ran it, the user who sent
+ * it or the address it came from. It is a JSON object recorded on every event
+ * the command writes, and projections, view models and `history` can read it.
+ *
+ * Like `Causation`, it travels in the fiber's context rather than in payloads.
+ * A command records, key by key, from the lowest precedence:
+ *
+ * 1. the metadata where its aggregate service was built, such as the software
+ *    version provided once for the whole application with {@link layer};
+ * 2. the metadata where it runs, added with {@link withMetadata};
+ * 3. the `metadata` of a `dispatch` envelope.
+ *
+ * A view model or saga reacting to an event doesn't inherit that event's
+ * metadata: its commands record their own. The `causationId` leads back to the
+ * event, and from there to its metadata.
+ */
+import { Context, Effect, Function, Layer, Schema } from "effect"
+
+/** A JSON object. */
+export type Metadata = Schema.JsonObject
+
+export const Metadata: Schema.Codec<Metadata> = Schema.JsonObject
+
+/** The metadata commands run in this fiber record, `{}` outside any. */
+export const CurrentMetadata = Context.Reference<Metadata>("effect-cqrs/Metadata", {
+  defaultValue: () => ({})
+})
+
+/** Runs an effect whose commands record this metadata on top of the current one. */
+export const withMetadata: {
+  (metadata: Metadata): <A, E, R>(effect: Effect.Effect<A, E, R>) => Effect.Effect<A, E, R>
+  <A, E, R>(effect: Effect.Effect<A, E, R>, metadata: Metadata): Effect.Effect<A, E, R>
+} = Function.dual(
+  2,
+  <A, E, R>(effect: Effect.Effect<A, E, R>, metadata: Metadata) =>
+    CurrentMetadata.use((current) => Effect.provideService(effect, CurrentMetadata, { ...current, ...metadata }))
+)
+
+/**
+ * Provides metadata to everything built on top of this layer, for values that
+ * hold for the whole process such as the software version:
+ *
+ * ```ts
+ * AppLayer.pipe(Layer.provide(Metadata.layer({ appVersion: "1.4.0" })))
+ * ```
+ *
+ * Aggregate services remember it, so it is recorded even by commands run where
+ * the layer isn't visible.
+ */
+export const layer = (metadata: Metadata): Layer.Layer<never> => Layer.succeed(CurrentMetadata, metadata)

package/src/PostgresEventStore.ts

@@ -25,8 +25,8 @@ const storeError = (operation: string) => (cause: unknown) => new EventStore.Eve
 
 const isUniqueViolation = (error: SqlError.SqlError) => error.reason._tag === "UniqueViolation"
 
-// The client binds at most 32,767 parameters to a statement, and each row uses 7.
-const rowsPerInsert = 4_000
+// The client binds at most 32,767 parameters to a statement, and each row uses 11.
+const rowsPerInsert = 2_900
 
 export const make = Effect.fnUntraced(function*(options?: Options) {
   const sql = yield* SqlClient.SqlClient
@@ -42,11 +42,20 @@ export const make = Effect.fnUntraced(function*(options?: Options) {
         aggregate_id TEXT NOT NULL,
         version INTEGER NOT NULL,
         type TEXT NOT NULL,
+        schema_version INTEGER NOT NULL DEFAULT 1,
         payload JSONB NOT NULL,
         "timestamp" BIGINT NOT NULL,
+        correlation_id TEXT,
+        causation_id TEXT,
+        metadata JSONB NOT NULL DEFAULT '{}',
         UNIQUE (aggregate_name, aggregate_id, version)
       )
     `
+    // Tables created before these columns existed get them here.
+    yield* sql`ALTER TABLE ${events} ADD COLUMN IF NOT EXISTS schema_version INTEGER NOT NULL DEFAULT 1`
+    yield* sql`ALTER TABLE ${events} ADD COLUMN IF NOT EXISTS correlation_id TEXT`
+    yield* sql`ALTER TABLE ${events} ADD COLUMN IF NOT EXISTS causation_id TEXT`
+    yield* sql`ALTER TABLE ${events} ADD COLUMN IF NOT EXISTS metadata JSONB NOT NULL DEFAULT '{}'`
     yield* sql`CREATE INDEX IF NOT EXISTS ${sql(`${prefix}_type_idx`)} ON ${events} (type, position)`
     yield* sql`
       CREATE TABLE IF NOT EXISTS ${counter} (
@@ -64,8 +73,12 @@ export const make = Effect.fnUntraced(function*(options?: Options) {
     aggregate_id AS "aggregateId",
     version,
     type,
+    schema_version AS "schemaVersion",
     payload,
-    "timestamp"::float8 AS "timestamp"
+    "timestamp"::float8 AS "timestamp",
+    correlation_id AS "correlationId",
+    causation_id AS "causationId",
+    metadata
   `)
 
   const append = (input: EventStore.AppendInput) => {
@@ -87,23 +100,21 @@ export const make = Effect.fnUntraced(function*(options?: Options) {
         UPDATE ${counter} SET position = position + ${input.events.length} RETURNING position::float8 AS position
       `
       const first = head!.position - input.events.length + 1
-      const stored = input.events.map((event, index): EventStore.StoredEvent => ({
-        position: first + index,
-        aggregateName: input.aggregateName,
-        aggregateId: input.aggregateId,
-        version: input.expectedVersion + index + 1,
-        type: event.type,
-        payload: event.payload,
-        timestamp: DateTime.makeUnsafe(timestamp)
-      }))
+      const stored = input.events.map((event, index) =>
+        EventStore.toStored(input, event, index, first + index, DateTime.makeUnsafe(timestamp))
+      )
       const rows = stored.map((event) => ({
         position: event.position,
         aggregate_name: event.aggregateName,
         aggregate_id: event.aggregateId,
         version: event.version,
         type: event.type,
+        schema_version: event.schemaVersion,
         payload: JSON.stringify(event.payload),
-        timestamp
+        timestamp,
+        correlation_id: event.correlationId,
+        causation_id: event.causationId,
+        metadata: JSON.stringify(event.metadata)
       }))
       yield* Effect.forEach(
         Arr.chunksOf(rows, rowsPerInsert),

package/src/Saga.ts

@@ -0,0 +1,176 @@
+/**
+ * Sagas: reactions that span several aggregates and outlive one command, run as
+ * durable workflows from `effect/workflow`.
+ *
+ * A saga has two halves. Its trigger is a view model that follows the log from a
+ * checkpoint and starts a workflow for each event it cares about. The workflow is
+ * the process itself: each command it runs is an `Activity`, so when the engine
+ * replays the workflow after a restart it skips the commands that already
+ * finished, and `withCompensation` undoes earlier steps when a later one fails.
+ *
+ * Triggers see an event at least once, and the workflow's idempotency key turns
+ * a second start into a join of the first execution. That only holds while the
+ * engine remembers the execution, so pair `WorkflowEngine.layerMemory` with
+ * in-memory checkpoints, as for view models, and a durable engine such as
+ * `ClusterWorkflowEngine` from `effect/cluster` with durable ones.
+ *
+ * An activity that is cut off before its result is saved runs again, so the
+ * commands a saga runs should be idempotent, for instance by recording the id of
+ * the transfer they belong to.
+ */
+import { Effect, Layer, Schedule, Schema } from "effect"
+import { Activity, Workflow } from "effect/workflow"
+import type { WorkflowEngine } from "effect/workflow"
+import type * as Aggregate from "./Aggregate.ts"
+import type { CommandResult } from "./AggregateService.ts"
+import * as Causation from "./Causation.ts"
+import type { Checkpoints } from "./Checkpoints.ts"
+import type { EventStore, EventStoreError } from "./EventStore.ts"
+import * as ViewModel from "./ViewModel.ts"
+
+/**
+ * The causation a workflow carries in its payload. A workflow body runs in the
+ * engine's fibers, not in the trigger's, so this is how commands it runs learn
+ * which event caused them.
+ */
+export const CausationSchema = Schema.Struct({
+  correlationId: Schema.String,
+  causationId: Schema.String
+})
+
+/** A workflow whose payload carries the causation of the event that started it. */
+export type SagaWorkflow<
+  Tag extends string = string,
+  Fields extends Schema.Struct.Fields = Schema.Struct.Fields,
+  Success extends Schema.Top = Schema.Top,
+  Error extends Schema.Top = Schema.Top
+> = Workflow.Workflow<Tag, Schema.Struct<Fields & { readonly causation: typeof CausationSchema }>, Success, Error>
+
+/**
+ * Defines the workflow of a saga. It is `Workflow.make` with a `causation` field
+ * added to the payload, which {@link start} fills in and {@link toLayer} applies.
+ */
+export const workflow = <
+  const Tag extends string,
+  const Fields extends Schema.Struct.Fields,
+  Success extends Schema.Top = Schema.Void,
+  Error extends Schema.Top = Schema.Never
+>(tag: Tag, options: {
+  readonly payload: Fields
+  /** Identifies one run of the saga, such as a transfer id. Starting it again joins that run. */
+  readonly idempotencyKey: (payload: Schema.Struct.Type<Fields>) => string
+  readonly success?: Success
+  readonly error?: Error
+  readonly suspendedRetrySchedule?: Schedule.Schedule<any, unknown> | undefined
+}): SagaWorkflow<Tag, Fields, Success, Error> =>
+  Workflow.make(tag, {
+    ...options,
+    payload: { ...options.payload, causation: CausationSchema }
+  }) as any
+
+/**
+ * Registers the body of a saga's workflow with the engine. Commands the body
+ * runs record the event that started the saga as their cause.
+ */
+export const toLayer = <
+  Tag extends string,
+  Fields extends Schema.Struct.Fields,
+  Success extends Schema.Top,
+  Error extends Schema.Top,
+  R
+>(
+  self: SagaWorkflow<Tag, Fields, Success, Error>,
+  execute: (
+    payload: Schema.Struct.Type<Fields>,
+    executionId: string
+  ) => Effect.Effect<Success["Type"], Error["Type"], R>
+) =>
+  self.toLayer((payload, executionId) =>
+    Causation.withCausation(
+      execute(payload as Schema.Struct.Type<Fields>, executionId),
+      (payload as { readonly causation: Causation.Causation }).causation
+    )
+  )
+
+/**
+ * Starts a saga's workflow without waiting for it, and returns its execution id.
+ * Inside a trigger the event being handled becomes the saga's cause; elsewhere
+ * the current causation does, or a new correlation when there is none.
+ */
+export const start = <Tag extends string, Fields extends Schema.Struct.Fields, Success extends Schema.Top, Error extends Schema.Top>(
+  self: SagaWorkflow<Tag, Fields, Success, Error>,
+  payload: Schema.Struct.MakeIn<Fields>
+): Effect.Effect<string, never, WorkflowEngine.WorkflowEngine> =>
+  Causation.CurrentCausation.use((current) => {
+    const id = crypto.randomUUID()
+    const causation = current ?? { correlationId: id, causationId: id }
+    return self.execute({ ...payload, causation } as never, { discard: true })
+  }) as any
+
+/**
+ * The trigger of a saga: a view model whose handlers start workflows with
+ * {@link start}, so it keeps a checkpoint and retries like view models do. Run it
+ * with {@link layer}, or with `ViewModel.layer` next to the other view models,
+ * where replaying it starts every saga again and joins the executions the engine
+ * still remembers.
+ */
+export const make = <
+  const Name extends string,
+  const Aggregates extends ReadonlyArray<Aggregate.Any>,
+  const H extends ViewModel.Handlers<Aggregate.Event<Aggregates[number]>>
+>(options: {
+  readonly name: Name
+  readonly aggregates: Aggregates
+  readonly handlers: H
+}) => ViewModel.make({ ...options, dispose: Effect.void })
+
+/**
+ * Runs triggers in the background for as long as the layer lives, apart from
+ * the view models. Workflows usually run commands, so they sit on top of the
+ * command side, which view models are often provided to.
+ */
+export const layer = <const Sagas extends ReadonlyArray<ViewModel.Any>>(
+  sagas: Sagas
+): Layer.Layer<never, EventStoreError, EventStore | Checkpoints | ViewModel.Context<Sagas[number]>> =>
+  Layer.provide(Layer.empty, ViewModel.layer(sagas))
+
+/** What a saga keeps of a command it ran: enough to wait for view models to see it. */
+export const CommandOutcome = Schema.Struct({
+  aggregateId: Schema.String,
+  version: Schema.Int,
+  position: Schema.Int
+})
+
+// Losing a race or a store error usually passes, so try again before giving up.
+const transient = (error: unknown) =>
+  Schema.is(Schema.Struct({ _tag: Schema.Literals(["ConcurrencyConflict", "EventStoreError"]) }))(error)
+
+const transientRetry = Schedule.exponential("50 millis").pipe(Schedule.jittered)
+
+/**
+ * Runs a command as an activity of a saga's workflow, so a replay of the
+ * workflow returns the saved outcome instead of running it again.
+ *
+ * Failures matching `error`, such as a domain error the saga reacts to, are
+ * saved like a success. A lost race or a store error is retried a few times.
+ * Anything else ends the workflow as a defect, which runs its compensations.
+ */
+export const command = <Err extends Schema.Top = typeof Schema.Never, E = never, R = never>(
+  name: string,
+  options: {
+    readonly execute: Effect.Effect<CommandResult<unknown>, E, R>
+    readonly error?: Err | undefined
+  }
+): Activity.Activity<typeof CommandOutcome, Err, R> => {
+  const expected = options.error === undefined ? () => false : Schema.is(Schema.toType(options.error))
+  return Activity.make({
+    name,
+    success: CommandOutcome,
+    error: options.error,
+    execute: options.execute.pipe(
+      Effect.retry({ while: transient, schedule: transientRetry, times: 5 }),
+      Effect.map(({ aggregateId, position, version }) => ({ aggregateId, version, position })),
+      Effect.catch((error) => expected(error) ? Effect.fail(error as Err["Type"]) : Effect.die(error))
+    )
+  }) as any
+}