Lifecycles are machines

Use an XState machine for the application’s named states, retries, cancellation, or a lifecycle you need to resume or inspect. Model the states and the events that move between them instead of accumulating booleans whose combinations have no meaning.¶

An actor is a running unit that performs declared work. A side effect is work outside the state description, such as reading a file. A scope²⁰ owns cleanup when that work ends.¶

setupEffect declares actors. fromEffect defines an Effect-backed side effect with an input schema. createEffectActor starts the machine inside Effect’s scope.¶

The machine chooses transitions and records its outcome. The invoked actor performs the file read.¶

join waits for the final outcome. Effect.orDie treats a machine-level failure as a programming error. The domain read failure remains an explicit machine state.¶

packages/core/src/inspect-machine.ts is the working example. watchActor makes the run visible to devtools. The rule in scripts/oxlint-plugin-xstate-effect.ts enforces declared actors by catching inline Effects in machine actions and actors.¶

See one capability, every surface¹⁸ for how a capability can own a machine and the fence³⁹ for the rule that protects it.¶

Sources

rat-stack/AGENTS.md at main · joelhooks/rat-stack · GitHub. GitHub joelhooks/rat-stack. Lifecycle rule; used for declared Effect actors and explicit states. Accessed 2026-10-01.
rat-stack/packages/core/src/inspect-machine.ts at main · joelhooks/rat-stack · GitHub. GitHub joelhooks/rat-stack. Inspection machine; used as the working actor and scope example. Accessed 2026-10-01.
rat-stack/packages/core/test/inspect-machine.test.ts at main · joelhooks/rat-stack · GitHub. GitHub joelhooks/rat-stack. Machine tests; used for the inspection lifecycle's behavior. Accessed 2026-10-01.

Last changed 2026-10-07 in f1a00f2. Source on GitHub. Change log.

Linked from

add-a-capability. Learn how one contract and its handler become a command, HTTP route, MCP tool, browser RPC, and sandbox call.
Keep it small; put real work in a service or lifecycle machine.¶
add-a-lifecycle-machine. Learn how XState owns a lifecycle while Effect owns its work, errors, and services.
A lifecycle machine defines named states and the events that permit movement between them.
Agent guide. An Effect stack so pure (aspirational) Kit Langton will blush.
Lifecycles are machines — XState owns finite lifecycle states while declared Effect actors own side effects.
Agent rules for rat-stack (AGENTS.md). What you may change, which commands to run, and which changes need approval.
Build and run rat-stack (README.md). What is in the repo, how the example works, and how to run it.
Change log. What changed in the files served here, newest first.
Lifecycles are machines — edited: feat(learn): teach cards 43 to 62 with plain lines, diagrams and snippets
Code snippets quote a pinned source. Shipped design brief: pinned Git objects, typed diagnostics, and one build-only snippet model for both views.
Lifecycles are machines applies when remote acquisition adds retries, cancellation, or resumability.
Concurrent work needs an owner and a bound. Limit active work, retain result order, and stop child work when its owning lifetime ends.
In rat-stack, machines own finite domain retries and cancellation.
Effect 4 study: September 2026. Dated Effect 4 source studies from September 2026; current versions live in pins.md.
ts, and lifecycles are machines.
Full agent guide. An Effect stack so pure (aspirational) Kit Langton will blush.
Handle expected failures without hiding defects. Declare expected failures, preserve their context, and recover by tag without turning crashes into successful outcomes.
Link context
The inspection machine uses it where the machine’s result is handed back to Effect because its expected file failure already travels through the Unreadable outcome.
HTTP success needs a status check and a decoder. Supply the client, check the response status, decode accepted data, and name failures at the adapter boundary.
In rat-stack, machines own finite retry lifecycles.
Infrastructure as effects. Sam Goodwin relates application operations to infrastructure requirements in one typed program.
Use an XState machine for named states, retries, cancellation, or a lifecycle to resume or inspect.
Model-based testing. Describe what a system should do as a small model, generate action sequences, and check the real system against the model.
Machines in this repo are lifecycles, so each one is a ready-made test model.
One capability, every surface. A schema-typed contract and one handler feed every interface rat-stack keeps.
See lifecycles are machines for stateful handlers and cartridges for the infrastructure boundary.
Rat Stack lore | rat-stack. Short, source-grounded notes on the ideas and decisions behind rat-stack.
Lifecycles are machines — XState owns finite lifecycle states while declared Effect actors own side effects.
Schema projections: 2026-09-18 history. Historical Effect rc.115 proposal and implementation receipts from 2026-09-18; use the one-capability-every-surface lore page for the current pattern.
packages/core: FileStats became a Schema; inspectFile is the first capability; the lifecycle machine moved here from the CLI so every surface runs it.
Scopes release resources when work ends. Acquire resources lazily, keep their use inside the owner, and release them after success, failure, or interruption.
In rat-stack, machines own finite business lifecycles.
Source change history (log.md). The generated change log as Markdown.
Lifecycles are machines — edited: feat(learn): teach cards 43 to 62 with plain lines, diagrams and snippets
Structure an Effect codebase by domain. Start with folders for application work, services and Layers in the same file, and startup code that supplies implementations.
In rat-stack, a machine owns finite modes, cancellation, or legal event sequences.

Unlinked mentions (21)

add-a-lifecycle-machine → An actor is a running unit that processes events or performs work for a machine.
Agent rules for rat-stack (AGENTS.md) → Only actions and actors declared in setupEffect contribute to the actor’s requirements; the xstate-effect/no-inline-effect lint rule enforces the inline cases.
Build and run rat-stack (README.md) → 7: the official XState v6 to Effect 4 bridge: createEffectActor runs a machine as a scoped Effect, fromEffect makes Effects into actors with typed failures and requirements.
Code snippets quote a pinned source → There is no state machine yet.
David Khourshid → It explains how to generate tests from a state machine instead of writing each case by hand.¶
Devtools → An actor is a running unit that processes events or performs work for a machine.
Effect + Alchemy peer patterns → Its enabled Layer owns the inspector, and attach acquires an actor subscription whose finalizer unsubscribes.
Effect + Alchemy peers → Targeted discovery also checks XState 6 alpha and @xstate/effect independently of Alchemy; single-line peers qualify when their machine or runtime seam is relevant.
Effect 4 study: September 2026 → sleep on the Effect Clock so TestClock drives after, declared Effect actions fork in the actor scope, and R is collected from declared actions and actors via RequirementsFrom.
Handle expected failures without hiding defects → An unexpected actor failure or missing outcome is a programming failure at that boundary.¶
learn → It stays on the machine.¶
Learn mode presents concepts at useful depths → XState owns the learning lifecycle as a state machine: named states and the events that permit movement between them.
Learn rat-stack from your own agent → Progress stays on your machine in ~/.rat-learn/.
learn-rat-stack → A declared fromEffect actor calls FileInspector.¶
Model-based testing → XState builds it into xstate/graph: createTestModel wraps a machine, and getShortestPaths turns it into test paths.
Oxlint rule limits → A two-actor/one-watch probe against base 8da815d produced no watch-rule diagnostic; the current fixture requires the unwatched second actor to be reported.
Rat's Nest keeps the code public and the inventory private → Hostnames, IPs, sites, ports, and machine inventory live outside the repo.¶
ship → The release machine tracks deployment states and transitions.
test-behaviour → The inspection lifecycle replays generated histories against the real actor:¶
Trace operations where they mean something → Devtools records capability calls and watched actor lifecycles.
uncomplect → No fence yet banning ordinary actor startup; candidate: an Effect-machine startup rule.¶