For agents: start with the agent guide. Every page is Markdown by default; add Accept: text/html for HTML.

Uncomplect rat-stack

Uncomplect means separate responsibilities that currently change together. Preserve behavior proved by tests or runtime observations. Replace structure that combines unrelated responsibilities. Make the separation hold under the next change.¶

Rich Hickey’s Simple Made Easy (2011) distinguishes simplicity from familiarity.¶

Greg Young’s The Art of Destroying Software argues for replaceable programs. Optimise for deletion.¶

Read first

Read AGENTS.md, VISION.md, and the relevant .brain/ decisions. Inspect the design’s source, tests, and recorded runtime results. Check library APIs against matching pinned sources before changing Effect, XState, or Alchemy code. Every recommendation must name its source file, preserved behavior, deleted complexity, and enforced check.¶

A held connection, a request, and a provider call in one scope³⁴ is a braid. Separate them with durability.¶

Terms used here

• Capability: One named action with a contract and a server-side handler.¶
• Contract: The shared name, input, output, failures, metadata, and approval setting.¶
• Projection: An interface built from capabilities: a command, API, or agent tool.¶
• Cartridge³⁸: A package that owns one job and its resources. It must pass the add-and-remove test below.¶
• Fence⁴⁵: Types, lint rules, tests, and hooks that reject prohibited changes. Project rules cover remaining gaps.¶
• Effect: The library for describing work with typed failures³⁹ and required services.¶
• Service: A named interface for one job. A service tag identifies the service requested by a caller.¶
• Schema: A definition of accepted values that provides TypeScript types and runtime checks.¶
• Layer: A description of how to construct services and supply their dependencies.¶
• Alchemy Stack: The infrastructure program that declares cloud resources and their connections.¶
• Binding²³: A connection that gives runtime code access to a resource.¶
• Machine: Named states, events, and legal transitions for one lifecycle, defined with XState.¶
• Actor: A running unit of work used by a machine.¶
• Feature: A thin route and view that read client state and call named commands.¶
• Client: The module that owns queries, commands, and a local copy of server data.¶
• Port: An interface for an application job, independent of a provider.¶
• Adapter: An implementation of a port for a particular provider.¶

CLI means command-line interface. MCP lets agents discover and call tools. RPC lets a client call named server operations.¶

Atoms hold observable client values. A property test²³ checks a rule across generated inputs. A model test checks stateful rules across generated command sequences.¶

Find combined responsibilities

Behavior in a projection

• Look for domain decisions inside packages/capability/src/to-*.ts, or separate handlers for HTTP, MCP²⁸, CLI, and RPC.¶
• Put behavior in a capability handler. Copy packages/core/src/inspect-file.ts and its contract in packages/core/src/contracts.ts.¶
• rat-stack-boundaries/no-cross-layer-imports blocks capability-package imports of core. rat-stack-boundaries/no-hand-rolled-surface restricts interface constructors. Neither detects every misplaced decision. No fence yet proving that interfaces behave alike; candidate: a property test that compares one capability’s results across interfaces.¶

Network calls and retries in a feature

• Look for fetch, RPC construction, or retries inside apps/web/src/features/**.¶
• Move network calls and retries into a client under apps/web/src/client/. Copy apps/web/src/client/docs.ts; features read atoms and call named commands.¶
• rat-stack-boundaries/no-feature-transport blocks network calls in features. rat-stack-boundaries/no-browser-server-imports keeps handler imports outside browser modules.¶

Provider code in a caller

• Look for Drizzle queries, SQL dialects, or provider SDK calls outside their cartridge.¶
• Call the application’s port. Copy packages/database/src/run-log.ts and the provider Layer in packages/database/src/d1.ts. Subscriber adapters live in packages/subscriber-delivery/, outside core.¶
• rat-stack-boundaries/no-core-adapters blocks provider adapters in core. No fence yet for all callers; candidate: a rule that restricts provider imports.¶

Resources separate from the code that uses them

• Look for a database or queue declared separately from the Layer that consumes its binding.¶
• Let the cartridge declare resources and bindings. Copy packages/database/src/d1.ts; provide its Layer where the application selects and connects service implementations.¶
• Alchemy binding requirements let types check resource dependencies. No fence yet proving safe removal; candidate: a cartridge-removal compile check.¶

Infrastructure setup in runtime code

• Look for runtime imports of apps/infra, or resource work triggered by importing apps/infra/alchemy.run.ts.¶
• Keep Alchemy Stack setup in apps/infra/alchemy.run.ts. Keep runtime behavior in capabilities and cartridge Layers.¶
• rat-stack-boundaries/no-cross-layer-imports rejects imports of apps/infra from elsewhere. No fence yet proving that imports do not deploy resources; candidate: an import-without-deployment test.¶

Approval and retry rules inside handlers

• Look for approval checks repeated inside handlers, or retry rules mixed with domain refusal.¶
• Set needsApproval on the contract. Copy the gate in packages/capability/src/implement.ts. Put rules for retrying temporary failures in the service that handles external calls, or in the machine.¶
• The capability type adds Approval and ApprovalDenied. packages/capability/test/to-rpc.test.ts checks the gate and reserves its failure. No fence yet for arbitrary retry policy; candidate: a retry-history model test.¶

Lifecycle encoded in scattered flags

• Look for status strings and booleans that encode modes, retries, cancellation, or legal event sequences.¶
• Use a machine under packages/core/src/. Copy packages/core/src/inspect-machine.ts. Declare createEffectLogic actors; start only with createEffectActor.¶
• xstate-effect/no-inline-effect and rat-stack-patterns/watch-effect-actors check how actors are declared and observed. packages/core/test/inspect-machine.model.test.ts checks histories. No fence yet banning ordinary actor startup; candidate: an Effect-machine startup rule.¶

Two places approving writes

• Look for a cache or local copy of server data that decides a mutation independently of the Durable Object or database cartridge.¶
• Keep the server authoritative. Clients in apps/web/src/client/ update their local copies through reactivityKeys. Copy the contract-derived client in apps/web/src/client/docs.ts for reads. In domain-driven design (DDD), a read model is derived data arranged for queries. A rat-stack projection instead exposes capabilities through an interface.¶
• No fence yet proving that local copies update correctly or that only the server approves writes. Candidate: a model test over command sequences with an outdated local copy.¶

Service wrapper that hides nothing

• Look for a Context.Service and Layer that hide one implementation, no dependencies, and no replacement implementation for tests.¶
• Use a plain function; copy summarizeText in packages/core/src/stats.ts. Use a service when it hides dependencies or replaceable behavior. Copy packages/core/src/file-inspector.ts when it must capture dependencies.¶
• No fence yet checking whether a service hides useful dependencies or behavior. Candidate: a project rule requiring hidden dependencies or replaceable behavior.¶

Unchecked external input

• Look for unknown, JSON.parse, or assertions that carry untrusted external values into domain code.¶
• Decode with Effect Schema at the boundary. Copy the schemas in packages/core/src/contracts.ts; give handlers parsed inputs.¶
• anti-slop/no-unknown-parameters, anti-slop/no-unknown-returns, and anti-slop/require-safety-comment-for-type-assertion restrict ways to bypass type checks. They do not prove decoding. No fence yet for every raw parse; candidate: a boundary-decode property over malformed inputs.¶

Crash folded into an outcome

• Look for onError, catchAll, or cause recovery that erases the distinction between refusal and broken execution. Check what each handler catches.¶
• Keep expected outcomes in declared types. Propagate defects: unexpected execution failures. Copy packages/core/src/join-delivery-machine.ts; the machine leaves crashed delivery pending.¶
• packages/core/test/join-delivery-machine.model.test.ts checks crash histories. The integration property in packages/core/test/join-interest.test.ts keeps crashed contacts ready for another delivery attempt. No fence yet for other machines; candidate: lint onError transitions targeting final states.¶

PR #9 (37b8ba9) removed onError: { target: "settled" }. A first-attempt crash had stored refused permanently. The fix propagates the crash and leaves contact delivery pending.¶

Duplicated API definitions

• Look for a hand-written route, tool, command, or schema that repeats a capability’s input, output, or failure definitions.¶
• Define one contract in the capability owner’s package. Copy packages/core/src/contracts.ts; use the projections in packages/capability/src/to-*.ts.¶
• rat-stack-boundaries/no-hand-rolled-surface restricts constructors. rat-stack-patterns/contract-binding-matches-name keeps contract bindings aligned with names.¶

Deployment configuration or live flag

• Look for deploy-only values in callers, or a switch that requires immediate changes but needs a deployment.¶
• Put deploy-only values in AppConfig, using packages/core/src/config-service.ts, packages/core/src/app-config.ts, and .env.schema. A live switch needs a flag: a value that controls whether behavior is enabled. Rat-stack has no flags cartridge yet.¶
• packages/core/test/app-config.test.ts checks config parsing. No fence yet for flags; candidate: reject flag reads outside their Layer when the cartridge arrives.¶

Undeclared deployment inputs

• Look for resource deletes caused by configuration missing from the shell that runs deployment with unchanged code.¶
• Declare deployment inputs in .env.schema; run pnpm env:check. Keep resource use in cartridge Layers, as in packages/events/src/basin.ts.¶
• AGENTS requires sign-off for plan deletions and replacements. No fence yet proving that plans do not depend on undeclared shell values; candidate: compare resource actions with required deploy configuration present and absent.¶

On 2026-10-04, missing EVENTS_* deployment configuration produced three analytics deletes without a code change. Schema validation alone cannot prove the intended set of resources. Read the plan before applying it.¶

Hide implementation details behind the interface

A capability hides schemas, behavior, approval, and projections. A cartridge hides its provider implementation and resources.¶

For each proposed service tag, Layer, or state, name what it removes. For consequential changes, compare two function signatures: their inputs, outputs, failures, and required services. Choose the one requiring less caller knowledge while preserving failures and behavior.¶

Run the cartridge test

Apply VISION.md’s cartridge test:¶

• The package has one named job.¶
• Add or remove one package and its Layer or Alchemy Stack line.¶
• The package owns its job and resources.¶
• The package is easy to delete and replace.¶

1. In an isolated checkout, remove the package and the line that provides its Layer or adds its resources to the Alchemy Stack. Run pnpm turbo run check test build.¶
2. Check that callers use its public interface, not internal implementation details.¶
3. Ask whether its schemas, tests, and recorded runtime results support replacement within about one week.¶

Use the week to pressure-test replacement. Keep each service responsible for its named job.¶

Enforce the separation

Use the strongest available check: types and APIs first, then lint and behavior tests, then project rules.¶

1. Follow gardener: add a rule before cleaning up the pattern. Plant a bug before trusting a new property.¶
2. Verify existing names in oxlint.config.ts, scripts/oxlint-plugin-*.ts, and packages/*/test/.¶
3. Mark missing coverage No fence yet. Label candidates; do not present them as shipped rules.¶

Output

Lead with More complicated locally, simpler overall or More machinery, no net simplification. Give each combined responsibility’s source, preserved behavior, smallest interface, deleted complexity, and existing check or proposed check. Include the signature, any machine, cartridge-test result, deletion list, and one material question. State what becomes impossible, what becomes obvious, and what disappears.¶

Last changed 2026-10-24 in abefe39. Source on GitHub. Change log.