# Rat Stack lore

> For agents: start with the [agent guide](https://ratstack.sh/llms.txt). Every page is Markdown by default; add `Accept: text/html` for HTML.

New on /news: [tla-ts 0.0.9 adds TLC's -continue](/news).

Short, source-grounded notes on the ideas and decisions behind rat-stack.

## Idea

- [A browser send follows one path to the capability](/lore/a-browser-send-follows-one-path) — In the Foldkit docs browser, a search is a Message, then an update, then a named Command that calls the search capability over RPC on a cache miss and returns a result Message.
- [A clean playground](/lore/a-clean-playground) — rat-stack does real work with packages that stay easy to add and remove.
- [Agents explore, tests remember](/lore/agents-explore-tests-remember) — Let agent users explore scenarios; turn a good bug reproduction into a repeatable test.
- [An MCP your users want](/lore/an-mcp-your-users-want) — Rhys Sullivan's practical guide gives rat-stack a checklist for useful MCP tools.
- [Shared caches hold completed values](/lore/cache-completed-values) — Keep pending request I/O out of isolate-scoped caches.
- [Capture first, shape later](/lore/capture-first) — Store events without rejecting them for an evolving event shape, then decide their shape when you query.
- [Cartridges](/lore/cartridges) — A cartridge owns one job and brings the infrastructure its service needs.
- [Code snippets quote a pinned source](/lore/code-snippets) — Shipped design brief: pinned Git objects, typed diagnostics, and one build-only snippet model for both views.
- [Concurrent work needs an owner and a bound](/lore/concurrent-work-needs-an-owner) — Limit active work, retain result order, and stop child work when its owning lifetime ends.
- [Configuration is a supplied, validated dependency](/lore/configuration-is-a-dependency) — Parse configuration when a Layer builds, reject invalid values, and supply controlled settings in tests.
- [Dependency injection is the reason to choose Effect](/lore/dependency-injection-is-the-reason-to-choose-effect) — Effect tracks service requirements in types and supplies replaceable implementations through Layers.
- [Durability starts with a recovery record](/lore/durability) — A reading order for storage, replay, worker ownership, overload, and recovery tests.
- [Flags climb on evidence](/lore/flags-climb-on-evidence) — A flag ladder connects each rollout step to scoped measurements, approval, and a durable receipt.
- [HATEOAS](/lore/hateoas) — Links in a representation tell its reader what to do next; rat-stack applies that idea to agent-facing pages and responses.
- [Hexagonal architecture](/lore/hexagonal-architecture) — Ports name the application's jobs; adapters connect them to the outside world.
- [Effect keeps the surfaces on one contract](/lore/how-we-do-it-with-effect) — Schema owns values, projections build interfaces, and Layers supply implementations.
- [HTTP success needs a status check and a decoder](/lore/http-responses-need-validation) — Supply the client, check the response status, decode accepted data, and name failures at the adapter boundary.
- [Worker init runs twice](/lore/init-runs-twice) — Alchemy Worker initialization runs in deploy and runtime contexts, so resource declarations need a boundary.
- [Lauren Tan's skills](/lore/lauren-tan-skills) — Lauren Tan (poteto) publishes skills in several repos: brainmaxxing for memory and skill improvement, noodle for skill-based orchestration, how for explaining a codebase, and a verification-skill example.
- [Layer composition makes dependencies explicit](/lore/layers-make-dependencies-explicit) — Supply a service's dependencies, choose which services remain visible, and reuse Layer identity within a build.
- [Lifecycles are machines](/lore/lifecycles-are-machines) — XState owns finite lifecycle states while declared Effect actors own side effects.
- [Matt Pocock's skills](/lore/matt-pocock-skills) — Matt Pocock's skills repo packages the agent skills he says he uses every day, built to be small, adaptable, and composable.
- [MCP is another surface](/lore/mcp-is-another-surface) — MCP lists and calls schema-typed tools; rat-stack projects the same handlers instead of adding MCP-only behavior.
- [mdsvex left unified](/lore/mdsvex-left-unified) — The next parser leaves unified; the CommonMark migrator still uses remark.
- [No comments](/lore/no-comments) — Code comments are banned because names, types, tests, and boundaries should carry the meaning.
- [One capability, every surface](/lore/one-capability-every-surface) — A schema-typed contract and one handler feed every interface rat-stack keeps.
- [One program can replace several tool calls](/lore/one-program-can-replace-several-tool-calls) — Code mode combines typed content calls inside one bounded execute request.
- [One schema, three surfaces](/lore/one-schema-three-surfaces) — A capability contract feeds CLI, HTTP, and MCP; OpenAPI is generated output, not their input.
- [OpenAPI describes the refusal too](/lore/openapi-describes-the-refusal-too) — The generated HTTP contract declares inputs, outputs, and the bodyless 400 returned when decoding fails.
- [Rat King carries signed mail between named agents](/lore/rat-king) — Rat King gives agents named mailboxes, signed messages, optional encryption, and Pi, CLI, and MCP clients.
- [Rat's Nest keeps the code public and the inventory private](/lore/rats-nest) — Joel's purpose-built on-prem cloud uses rat-stack and Alchemy, with private inventory outside the public repo.
- [Run Effect at the integration boundary](/lore/run-effect-at-the-boundary) — Build the runtime where a calling framework enters, reuse its services, and dispose it when that integration ends.
- [Schemas define the boundary](/lore/schemas-define-the-boundary) — Define accepted data with Schema, decode unknown input before dispatch, and encode results through the declared contract.
- [Scopes release resources when work ends](/lore/scopes-own-resources) — Acquire resources lazily, keep their use inside the owner, and release them after success, failure, or interruption.
- [A service captures its construction dependencies](/lore/services-capture-dependencies) — Build a service with its dependencies, then expose methods that callers can use without rebuilding the graph.
- [The rat-stack bestiary eats excuses](/lore/shitrat-bestiary) — A field guide to eight documented rat-stack creatures, with real habitats, enforceable behaviour, and strictly imaginary temperaments.
- [ShitRat's canon is an incident log](/lore/shitrat-canon) — Four public ShitRat stories: a comment ban, a hold that blocked its own migration, a desktop body, and a domain for the rat.
- [ShitRat wants receipts before claims](/lore/shitrat-creed) — The familiar's creed: read the file, run the command, give the number, admit uncertainty, and spare everyone the corporate sludge.
- [Joel bought a domain and the rat built its own house](/lore/shitrat-origin) — ShitRat's public origin story starts with a gift: shitrat.ai, a hand-written page, and a rat doing its own deployment.
- [A rat can be a name with a mailbox](/lore/shitrat-rat-king) — Rat King's named mailboxes and leased readers give ShitRat a postal mythology with a clear line between the rules and the rats' stories.
- [The rat has rituals for proving it happened](/lore/shitrat-rituals) — The gate, the snapshot dance, receipts before claims, and the deployment check give rat-stack's folklore some repeatable steps.
- [The war stories](/lore/shitrat-war-stories) — Seven public repo incidents: a deploy undoes itself, failure says 200, sessions forget their guests, and the rat tests the demolition instructions.
- [Structure an Effect codebase by domain](/lore/structure-effect-by-domain) — Start with folders for application work, services and Layers in the same file, and startup code that supplies implementations.
- [Tests prove behavior through supplied services](/lore/tests-that-earn-their-place) — Supply services through Layers, choose properties or models for domain rules, and reject tests that cannot detect broken behavior.
- [The fence](/lore/the-fence) — The fence uses compiler checks, lint rules, and hooks to reject unsafe shortcuts.
- [There is no ISR on Cloudflare](/lore/there-is-no-isr-on-cloudflare) — SvelteKit's Vercel ISR setting does not configure Workers Cache; our local comparison did not prove cache reuse.
- [Trace operations where they mean something](/lore/trace-meaningful-operations) — Name useful operations, add safe context, and distinguish creating a span from delivering it to a backend.
- [An agent applied through Markdown and HTTP](/lore/two-lines-of-curl-is-a-front-door) — One observed application used the Markdown page and llms.txt, then one POST; confirmation followed 88 seconds later.
- [UI behaviour is a scene](/lore/ui-behaviour-is-a-scene) — A Foldkit Scene drives update, view, and subscriptions with input and time as plain data, then asserts on what the view shows.

## Concept

- [Accumulate independent errors before writing output](/lore/accumulate-independent-errors) — Check every independent job before any job writes an asset.
- [Admission control protects recovery](/lore/admission-controls-new-work) — Refuse or defer work that cannot be served usefully under current load.
- [Source-first workflow](/lore/agent-source-first-workflow) — Michael Arnaldi says agents should inspect a library's current source instead of trusting stale model knowledge.
- [Alchemy Domain models a business as commands, aggregates, and events](/lore/alchemy-domain) — Alchemy Domain is a domain-driven design framework for Effect whose one model runs in memory for tests and on Cloudflare Durable Objects in production.
- [Ambient cloud](/lore/ambient-cloud) — Sam Goodwin describes a cloud experience where credentials and accounts become available through one interface.
- [Anti-money](/lore/anti-money) — Sam Goodwin frames Alchemy as reducing SaaS products to libraries and shifting value elsewhere.
- [AT Protocol separates identity, data, and application schemas](/lore/at-protocol) — AT Protocol connects persistent account identifiers, signed public repositories, hosting services, and shared schemas.
- [Backpressure reaches the producer](/lore/backpressure-reaches-the-producer) — Bounded consumption helps only when upstream respects waiting or refusal.
- [Bindings](/lore/bindings) — Sam Goodwin describes bindings as the place where runtime permissions and configuration meet infrastructure.
- [Build-time work stays out of requests](/lore/build-time-work-stays-out-of-requests) — Git reads and highlighting produce static assets before the Worker handles requests.
- [Bulkheads isolate scarce capacity](/lore/bulkheads-isolate-capacity) — Reserve independent capacity for workloads that must not starve each other.
- [CAFE names the Cloudflare, Alchemy, Foldkit and Effect stack](/lore/cafe-stack) — CAFE is a named stack: Cloudflare runs the app, Alchemy declares it, Foldkit draws the UI, and Effect does the typed work.
- [Checkpoints follow the promised commit](/lore/checkpoints-follow-commits) — Persist state and progress together when one store can transact both.
- [Circuit breakers have state](/lore/circuit-breakers-have-state) — A breaker stops doomed calls and controls probes before restoring traffic.
- [Cleanup can be an idempotent postcondition](/lore/cleanup-can-be-an-idempotent-postcondition) — Already-absent state can be success when absence is the operation’s intended result.
- [Cloud as a library](/lore/cloud-as-a-library) — Sam Goodwin argues that cloud services can be consumed as libraries inside an application.
- [Context and requirements](/lore/context-and-requirements) — Effect requirements make a computation's needed services visible in its type.
- [Dead letters need a return path](/lore/dead-letters-need-a-return-path) — Exhausted work needs durable evidence, an owner, and deliberate redrive.
- [Distilled](/lore/distilled) — Sam Goodwin describes provider client libraries that return Effects and named error types under the Distilled name.
- [Double opt-in](/lore/double-opt-in) — The visitor gets one confirmation email and is counted only after using its link.
- [Durability bibliography](/lore/durability-bibliography) — Books, checked short quotations, source limits, and Effect mapping provenance.
- [Durable timers need recovery](/lore/durable-timers-need-recovery) — Persist scheduled intent when losing a worker must not lose its deadlines.
- [Durable work needs storage](/lore/durable-work-needs-storage) — A restarted worker cannot recover intent that existed only in memory.
- [Effect basics](/lore/effect-basics) — An Effect describes work, expected failures, and required services before a runtime executes it.
- [Effect's design lineage](/lore/effect-design-lineage) — Michael Arnaldi describes Effect's path from financial software needs through ZIO influence and TypeScript iterations.
- [Effect is not BEAM](/lore/effect-is-not-beam) — Fibers share a runtime; scope ownership does not supply isolated heaps or OTP restart strategies.
- [Engine-neutral tokens keep adapters replaceable](/lore/engine-neutral-tokens-keep-adapters-replaceable) — The highlighter port exposes text, roles, and font styles rather than Shiki types.
- [Handle expected failures without hiding defects](/lore/error-model) — Declare expected failures, preserve their context, and recover by tag without turning crashes into successful outcomes.
- [Errors are part of the interface](/lore/errors-are-part-of-the-interface) — An author error needs a location, the rejected input, and a repair.
- [Every task needs an owner](/lore/every-task-needs-an-owner) — Give child work a lifetime, a failure observer, and a recovery decision.
- [Failures keep their meaning](/lore/failures-keep-their-meaning) — Expected refusals, infrastructure faults, and defects need different policies.
- [Floor and ceiling](/lore/floor-and-ceiling) — Theo Browne argues that a model's ordinary reliability matters more than its peak on long agent runs.
- [Golden signals expose overload](/lore/golden-signals-expose-overload) — Measure latency, traffic, errors, and saturation, including failed work.
- [Infrastructure as effects](/lore/infrastructure-as-effects) — Sam Goodwin relates application operations to infrastructure requirements in one typed program.
- [A Layer as constructor](/lore/layer-constructor-pattern) — Sam Goodwin compares an Effect Layer that builds a service to a constructor.
- [Model-based testing](/lore/model-based-testing) — Describe what a system should do as a small model, generate action sequences, and check the real system against the model.
- [Old events must still decode](/lore/old-events-must-still-decode) — Retained data needs compatibility rules before recovery depends on it.
- [One snippet model feeds both renderers](/lore/one-snippet-model-two-renderers) — HTML and agent Markdown derive their code, repository, commit, path, and line numbers from the same snippet.
- [Pin the source and report drift separately](/lore/pinned-sources-can-report-drift) — A pinned excerpt stays fixed while a separate diagnostic compares it with HEAD.
- [The plan model](/lore/plan-model) — Sam Goodwin describes Alchemy's plan outputs as a way to inspect infrastructure before deployment.
- [Production-grade TypeScript](/lore/production-grade-typescript) — Michael Arnaldi defines production-grade software through reliability, observability, testability, and maintainability.
- [Property-based testing](/lore/property-based-testing) — State a rule that must hold for every input, then let a generator hunt for the smallest input that breaks it.
- [Pure cores reduce timeline coupling](/lore/pure-cores-reduce-timelines) — Move deterministic rules out of time-dependent actions and shared mutable state.
- [Queries need result bounds](/lore/queries-need-result-bounds) — Limit result cardinality before the driver materializes an oversized response.
- [Queues, Pipelines, Workflows and K2 do different jobs](/lore/queues-pipelines-workflows-and-k2-do-different-jobs) — Pick a Cloudflare product for work outside a request by the unit you track: a message, a row, a step, or a record in a log.
- [Recovery needs model tests](/lore/recovery-needs-model-tests) — Test sequences of failures and recoveries against explicit invariants.
- [Replay needs stable inputs](/lore/replay-needs-stable-inputs) — Historical processing must not silently depend on today’s clock or external decisions.
- [Request lifetime is not durability](/lore/request-lifetime-is-not-durability) — Worker waitUntil has a shared post-response allowance; required work needs a durable marker and redrive.
- [Restart must reconstruct known state](/lore/restart-from-known-state) — Execution recovery and state recovery need separate contracts.
- [Retry load needs a budget](/lore/retry-load-needs-a-budget) — One retry owner must control attempts, delay, and aggregate load.
- [Retry needs idempotent effects](/lore/retry-needs-idempotency) — Repeating an operation must preserve its intended observable result.
- [Shared schemas need a transition period](/lore/schema-changes-need-a-transition) — Keep old and new representations usable while consumers migrate.
- [shitratgit\[bot\] leaves a countable trail](/lore/shitratgit-bot) — At rat-stack commit 7570e37, shitratgit\[bot] authors 1,314 of 1,365 reachable commits, a dated repo count rather than a live counter.
- [Steady state recycles resources](/lore/steady-state-recycles-resources) — Every accumulation needs a deliberate recycling policy.
- [Supervision chooses what restarts](/lore/supervision-is-a-recovery-policy) — Restart policy follows dependency shape and bounds repeated recovery.
- [Think wider](/lore/think-wider) — Theo Browne asks developers to cover more product breadth instead of adding depth in one narrow area.
- [Timeouts bound waiting](/lore/timeouts-bound-waiting) — A local timeout stops waiting; it does not prove the remote action never happened.
- [Tokenize the whole file before slicing](/lore/tokenize-before-slicing) — Select lines after tokenization so preceding code still guides recognition of multiline strings and comments.
- [Workers answer requests; Durable Objects own named state](/lore/workers-answer-requests-durable-objects-own-named-state) — A Worker must not rely on module state between requests, so state that must persist lives in a Durable Object addressed by name.

## Source

- [DHH on Omarchy and the agent OS](/lore/0xsero-dhh-omarchy-the-agent-os) — David Heinemeier Hansson reflects on agency, agents, and building with language.
- [Vibe engineering Effect apps](/lore/ai-engineer-vibe-engineering-effect-apps-michael-arnaldi) — Michael Arnaldi shows how source, tests, and diagnostics can guide agents working with Effect.
- [AI Engineer World's Fair 2026: Software has changed](/lore/aiewf-2026-everything-we-knew-about-software-has-changed-theo-browne) — Theo Browne argues that stronger models call for wider software work and extensible products.
- [CascadiaJS 2026: It's time to rethink everything](/lore/cascadiajs-2026-its-time-to-rethink-everything-theo-browne) — Theo Browne compares how cloud infrastructure and coding agents changed the cost of experimentation.
- [Cause & Effect 10: Software engineering in the age of AI](/lore/cause-and-effect-10-software-engineering-age-of-ai-de-goes) — John De Goes, Michael Arnaldi, and Johannes Schickling discuss engineering judgment as code gets cheaper.
- [Effect: Production-Grade TypeScript](/lore/cityjs-effect-production-grade-typescript-michael-arnaldi) — Michael Arnaldi presents Effect as a set of shared tools for production TypeScript.
- [Alchemy and the next generation of infrastructure as code](/lore/devtools-fm-sam-goodwin-alchemy-next-gen-iac) — Sam Goodwin describes Alchemy's stateful TypeScript model for infrastructure resources.
- [Sam Goodwin on Alchemy](/lore/devtools-fm-sam-goodwin-alchemy) — Sam Goodwin explains Alchemy's Effect model, plans, bindings, and cloud-library idea.
- [Effect Days 2024: The origin story](/lore/effect-days-2024-origin-story-michael-arnaldi) — Michael Arnaldi traces Effect to a TypeScript team's needs for tests, dependencies, and resource safety.
- [Effect Days 2025: Building Effect 4](/lore/effect-days-2025-building-effect-4-michael-arnaldi) — Michael Arnaldi presents Effect 4 as a redesign shaped by production feedback.
- [Effect Meetup SF 2023: Why Effect?](/lore/effect-meetup-sf-2023-why-effect-michael-arnaldi) — Michael Arnaldi introduces Effect as a shared runtime for production TypeScript concerns.
- [Effect Office Hours 26: Community projects and Alchemy](/lore/effect-office-hours-26-community-projects-alchemy) — The hosts discuss Alchemy Effect's typed resource requirements, plans, and deployment stages.
- [Effect Office Hours 27: Alchemy, infrastructure as effects](/lore/effect-office-hours-27-alchemy-infrastructure-as-effects) — Sam Goodwin presents Alchemy as a system built with Effect for planning, testing, and deploying infrastructure.
- [Happy Path 116: Infrastructure as effects](/lore/happy-path-116-infrastructure-as-effects-sam-goodwin) — Sam Goodwin connects Effect requirements, infrastructure policies, and runtime behavior.
- [Happy Path 81: TypeScript and effects](/lore/happy-path-81-typescript-and-effects-michael-arnaldi) — Michael Arnaldi describes Effect's TypeScript design and its typed outputs, errors, and requirements.
- [Lauren Tan: Dune, trust, and agent skills](/lore/poteto-lauren-tan-2500-prs-dune) — Lauren Tan describes verification, a trust ladder, and an application framework designed for coding agents.
- [Theo Browne: Please stop using stupid models](/lore/theo-please-stop-using-stupid-models) — Theo Browne argues that model reliability matters more as agent work gets wider and longer.
- [Why JavaScript is broken: Effect and TypeScript](/lore/why-javascript-is-broken-effect-michael-arnaldi) — Michael Arnaldi argues that production JavaScript needs one composable model for errors, dependencies, and cleanup.
- [Why TypeScript is a good fit for Scala developers](/lore/ziverge-de-goes-arnaldi-typescript-for-scala-devs) — John De Goes and Michael Arnaldi discuss carrying functional programming ideas into TypeScript.

## Person

- [Chris Tate](/lore/chris-tate) — Chris Tate shares public experiments in generative UI and fast model judgments.
- [David Khourshid](/lore/david-khourshid) — David Khourshid teaches state machines with XState and argues for model-based and property-based testing.
- [Lauren Tan](/lore/lauren-tan) — Lauren Tan describes verification and agent-oriented architecture in her public talk about Dune.
- [Michael Arnaldi](/lore/michael-arnaldi) — Michael Arnaldi develops Effect and explains its TypeScript design in public talks.
- [Sam Goodwin](/lore/sam-goodwin) — Sam Goodwin presents Alchemy as infrastructure built from Effect programs and typed requirements.
- [ShitRat is Joel's familiar, with receipts](/lore/shitrat) — Meet ShitRat: Joel's terminal-dwelling familiar, its public house, its rules, its commits, and the incidents that became canon.
- [Theo Browne](/lore/theo-browne) — Theo Browne discusses broader software work and model reliability in public talks.
- [Visakan Veerasamy](/lore/visakan-veerasamy) — Visakan Veerasamy writes about building a network of friendly, ambitious nerds.


## Linked from

- Purpose and boundaries of rat-stack (VISION.md) → What this starter is for and what a useful copy should keep. → [Read page](https://ratstack.sh/VISION.md)