Rat Stack lore

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

Idea

A browser send follows one path to the capability⁶ — 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⁸ — rat-stack does real work with packages that stay easy to add and remove.
Agents explore, tests remember⁷ — Let agent users explore scenarios; turn a good bug reproduction into a repeatable test.
An MCP your users want⁵ — Rhys Sullivan’s practical guide gives rat-stack a checklist for useful MCP tools.
Shared caches hold completed values⁸ — Keep pending request I/O out of isolate-scoped caches.
Capture first, shape later⁸ — Store events without rejecting them for an evolving event shape, then decide their shape when you query.
Cartridges³⁸ — A cartridge³⁸ owns one job and brings the infrastructure its service needs.
Code snippets quote a pinned source¹⁶ — 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²³ — Limit active work, retain result order, and stop child work when its owning lifetime ends.
Configuration is a supplied, validated dependency⁷ — Parse configuration when a Layer builds, reject invalid values, and supply controlled settings in tests.
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³⁵ — A reading order for storage, replay, worker⁶⁰ ownership, overload, and recovery tests.
Flags climb on evidence⁷ — A flag ladder⁷ connects each rollout step to scoped measurements, approval, and a durable receipt.
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³⁰ — Ports name the application’s jobs; adapters connect them to the outside world.
Effect keeps the surfaces on one contract⁹ — Schema owns values, projections build interfaces, and Layers supply implementations.
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.
Worker init runs twice⁸ — Alchemy Worker initialization runs in deploy and runtime contexts, so resource declarations need a boundary.
Lauren Tan’s 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²¹ — Supply a service’s dependencies, choose which services remain visible, and reuse Layer identity within a build.
Lifecycles are machines²⁷ — XState owns finite lifecycle states while declared Effect actors own side effects.
Matt Pocock’s 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³¹ — MCP³¹ lists and calls schema-typed tools; rat-stack projects the same handlers instead of adding MCP-only behavior.
mdsvex left unified⁵ — The next parser leaves unified; the CommonMark migrator still uses remark.
No comments¹¹ — Code comments are banned¹¹ because names, types, tests, and boundaries should carry the meaning.
One capability, every surface²¹ — A schema-typed contract and one handler feed every interface rat-stack keeps.
One program can replace several tool calls²³ — Code mode²³ combines typed content calls inside one bounded execute request.
One schema, three surfaces²⁶ — A capability contract²⁸ feeds CLI, HTTP, and MCP; OpenAPI is generated output, not their input.
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⁹ — 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⁸ — 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⁸ — Build the runtime where a calling framework enters, reuse its services, and dispose it when that integration ends.
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³⁵ — Acquire resources lazily, keep their use inside the owner, and release them after success, failure, or interruption.
A service captures its construction dependencies³⁰ — Build a service with its dependencies, then expose methods that callers can use without rebuilding the graph.
The rat-stack bestiary eats excuses⁹ — 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¹⁰ — 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⁹ — 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⁹ — 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⁸ — 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⁸ — The gate, the snapshot dance, receipts before claims, and the deployment check give rat-stack’s folklore some repeatable steps.
The 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¹⁸ — 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²² — Supply services through Layers, choose properties or models for domain rules, and reject tests that cannot detect broken behavior.
The fence⁵⁰ — The fence uses compiler checks, lint rules, and hooks to reject unsafe shortcuts.
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⁸ — Name useful operations, add safe context, and distinguish creating a span from delivering it to a backend.
An agent applied through Markdown and HTTP⁶ — One observed application used the Markdown page and llms.txt, then one POST; confirmation followed 88 seconds later.
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¹⁰ — Check every independent job before any job writes an asset.
Admission control protects recovery¹⁰ — Refuse or defer work that cannot be served usefully under current load.
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⁵ — 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⁵ — Sam Goodwin describes a cloud experience where credentials and accounts become available through one interface.
Anti-money⁵ — Sam Goodwin frames Alchemy as reducing SaaS products to libraries and shifting value elsewhere.
AT Protocol separates identity, data, and application schemas⁷ — AT Protocol connects persistent account identifiers, signed public repositories, hosting services, and shared schemas.
Backpressure reaches the producer¹⁰ — Bounded consumption helps only when upstream respects waiting or refusal.
Bindings²⁵ — Sam Goodwin describes bindings as the place where runtime permissions and configuration meet infrastructure.
Build-time work stays out of requests⁷ — Git reads and highlighting produce static assets before the Worker handles requests.
Bulkheads isolate scarce capacity¹⁰ — Reserve independent capacity for workloads that must not starve each other.
CAFE names the Cloudflare, Alchemy, Foldkit and Effect 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¹⁰ — Persist state and progress together when one store can transact both.
Circuit breakers have state¹⁰ — A breaker stops doomed calls and controls probes before restoring traffic.
Cleanup can be an idempotent postcondition¹⁰ — Already-absent state can be success when absence is the operation’s intended result.
Cloud as a library⁶ — Sam Goodwin argues that cloud services can be consumed as libraries inside an application.
Context and requirements⁹ — Effect requirements make a computation’s needed services visible in its type.
Dead letters need a return path¹⁵ — Exhausted work needs durable evidence, an owner, and deliberate redrive.
Distilled⁵ — Sam Goodwin describes provider client libraries that return Effects and named error types under the Distilled name.
Double opt-in¹⁰ — The visitor gets one confirmation email and is counted only after using its link.
Durability bibliography³³ — Books, checked short quotations, source limits, and Effect mapping provenance.
Durable timers need recovery⁷ — Persist scheduled intent when losing a worker must not lose its deadlines.
Durable work needs storage¹⁶ — A restarted worker cannot recover intent that existed only in memory.
Effect basics³⁵ — An Effect describes work, expected failures, and required services before a runtime executes it.
Effect’s design lineage⁵ — Michael Arnaldi describes Effect’s path from financial software needs through ZIO influence and TypeScript iterations.
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⁷ — The highlighter port exposes text, roles, and font styles rather than Shiki types.
Handle expected failures without hiding defects³⁸ — Declare expected failures, preserve their context, and recover by tag without turning crashes into successful outcomes.
Errors are part of the interface⁹ — An author error needs a location, the rejected input, and a repair.
Every task needs an owner⁹ — Give child work a lifetime, a failure observer, and a recovery decision.
Failures keep their meaning¹⁰ — Expected refusals, infrastructure faults, and defects need different policies.
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⁹ — Measure latency, traffic, errors, and saturation, including failed work.
Infrastructure as effects¹⁰ — Sam Goodwin relates application operations to infrastructure requirements in one typed program.
A Layer as constructor¹² — Sam Goodwin compares an Effect Layer that builds a service to a constructor.
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⁹ — Retained data needs compatibility rules before recovery depends on it.
One snippet model feeds both 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⁹ — A pinned excerpt stays fixed while a separate diagnostic compares it with HEAD.
The plan model⁸ — Sam Goodwin describes Alchemy’s plan outputs as a way to inspect infrastructure before deployment.
Production-grade TypeScript⁶ — Michael Arnaldi defines production-grade software through reliability, observability, testability, and maintainability.
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⁹ — Move deterministic rules out of time-dependent actions and shared mutable state.
Queries need result bounds⁷ — Limit result cardinality before the driver materializes an oversized response.
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¹⁰ — Test sequences of failures and recoveries against explicit invariants.
Replay needs stable inputs⁹ — Historical processing must not silently depend on today’s clock or external decisions.
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⁹ — Execution recovery and state recovery need separate contracts.
Retry load needs a budget¹⁰ — One retry owner must control attempts, delay, and aggregate load.
Retry needs idempotent effects¹⁵ — Repeating an operation must preserve its intended observable result.
Shared schemas need a transition period⁷ — Keep old and new representations usable while consumers migrate.
shitratgit[bot] leaves a countable trail⁸ — 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⁹ — Every accumulation needs a deliberate recycling policy.
Supervision chooses what restarts¹¹ — Restart policy follows dependency shape and bounds repeated recovery.
Think wider⁶ — Theo Browne asks developers to cover more product breadth instead of adding depth in one narrow area.
Timeouts bound waiting²⁰ — A local timeout stops waiting; it does not prove the remote action never happened.
Tokenize the whole file 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⁶⁰ — 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⁵ — David Heinemeier Hansson reflects on agency, agents, and building with language.
Vibe engineering Effect apps⁶ — Michael Arnaldi shows how source, tests, and diagnostics can guide agents working with Effect.
AI Engineer World’s Fair 2026: Software has changed⁷ — Theo Browne argues that stronger models call for wider software work and extensible products.
CascadiaJS 2026: It’s time to rethink everything⁵ — Theo Browne compares how cloud infrastructure and coding agents changed the cost of experimentation.
Cause & Effect 10: Software engineering in the age of AI⁶ — John De Goes, Michael Arnaldi, and Johannes Schickling discuss engineering judgment as code gets cheaper.
Effect: Production-Grade TypeScript⁶ — Michael Arnaldi presents Effect as a set of shared tools for production TypeScript.
Alchemy and the next generation of infrastructure as code⁵ — Sam Goodwin describes Alchemy’s stateful TypeScript model for infrastructure resources.
Sam Goodwin on Alchemy¹⁰ — Sam Goodwin explains Alchemy’s Effect model, plans, bindings, and cloud-library idea.
Effect Days 2024: The origin story⁶ — Michael Arnaldi traces Effect to a TypeScript team’s needs for tests, dependencies, and resource safety.
Effect Days 2025: Building Effect 4⁵ — Michael Arnaldi presents Effect 4 as a redesign shaped by production feedback.
Effect Meetup SF 2023: Why Effect?⁵ — Michael Arnaldi introduces Effect as a shared runtime for production TypeScript concerns.
Effect Office Hours 26: Community projects and Alchemy⁵ — The hosts discuss Alchemy Effect’s typed resource requirements, plans, and deployment stages.
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⁸ — Sam Goodwin connects Effect requirements, infrastructure policies, and runtime behavior.
Happy Path 81: TypeScript and effects⁵ — Michael Arnaldi describes Effect’s TypeScript design and its typed outputs, errors, and requirements.
Lauren Tan: Dune, trust, and agent skills⁷ — Lauren Tan describes verification, a trust ladder, and an application framework designed for coding agents.
Theo Browne: 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⁵ — Michael Arnaldi argues that production JavaScript needs one composable model for errors, dependencies, and cleanup.
Why TypeScript is a good fit for Scala developers⁵ — John De Goes and Michael Arnaldi discuss carrying functional programming ideas into TypeScript.

Person

Chris Tate⁵ — Chris Tate shares public experiments in generative UI and fast model judgments.
David Khourshid⁷ — David Khourshid teaches state machines with XState and argues for model-based and property-based testing.
Lauren Tan⁹ — Lauren Tan describes verification and agent-oriented architecture in her public talk about Dune.
Michael Arnaldi⁷ — Michael Arnaldi develops Effect and explains its TypeScript design in public talks.
Sam Goodwin⁸ — Sam Goodwin presents Alchemy as infrastructure built from Effect programs and typed requirements.
ShitRat is Joel’s familiar, with receipts¹² — Meet ShitRat: Joel’s terminal-dwelling familiar, its public house, its rules, its commits, and the incidents that became canon.
Theo Browne⁶ — Theo Browne discusses broader software work and model reliability in public talks.
Visakan Veerasamy⁵ — Visakan Veerasamy writes about building a network of friendly, ambitious nerds.