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

Rat Stack lore

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

Idea

• 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.
• 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 binds agents into one encrypted network⁶ — Rat King⁶ plans an encrypted AT Protocol agent network built on rat-stack.
• 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.
• 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.
• Source-first workflow⁵ — Michael Arnaldi says agents should inspect a library’s current source instead of trusting stale model knowledge.
• 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.
• 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.
• 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.
• 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.
• 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.
• 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.
• 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.
• Floor and ceiling⁵ — Theo Browne argues that a model’s ordinary reliability matters more than its peak on long agent runs.
• 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.
• 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.
• Think wider⁷ — Theo Browne asks developers to cover more product breadth instead of adding depth in one narrow area.
• Tokenize the whole file before slicing⁷ — Select lines after tokenization so preceding code still guides recognition of multiline strings and comments.

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.
• 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.