One capability, every surface

A capability is one named action with a contract and a server-side handler. A contract defines the shared input, output, failures, and metadata. Effect Schema provides types and runtime checks for these values. defineContract owns the name, Effect schemas, annotations, and approval setting. implement binds that contract to its handler.¶

Here, a surface²³ is an interface for calling the action. A projection converts registered capabilities into an interface. The interfaces are command line, HTTP, MCP tools, browser RPC, and code mode²¹. Each interface derives its input and failure definitions from the same schemas.¶

The split replaced defineCapability, which bundled contract data and its handler in one definition. The RPC client needed the contract without importing server implementation. toRpcGroup now projects contracts alone; toRpc connects those same contracts to implemented capabilities. The browser docs client imports only the shared contracts and RPC group. Commit 9a7bea5 records the split.¶

To add a capability, define its contract and implement it beside the data or infrastructure it owns. Register it in capabilities²¹, then check each interface you keep. packages/capability/test/ exercises projections; apps/site/src/capabilities/index.ts shows the hosted registry.¶

Michael Arnaldi⁶ demonstrates Schema decoding¹⁷ request input and encoding a frontend-safe result while preserving its output type. Effect Meetup SF, 27:17. In another conversation, the speakers discuss generated schemas and migrations as work agents can maintain, and a rule that rejects ad hoc JSON parsing. Cause & Effect 10, 63:49 67:53.¶

Analytics¹⁸ shows a separate infrastructure cartridge³⁶; interest signup¹² shows core ports with a delivery adapter outside core. Neither turns static pages or protocol discovery into domain capabilities.¶

See lifecycles are machines²⁰ for stateful handlers and cartridges³⁶ for the infrastructure boundary. HATEOAS⁹ covers links that guide an agent’s next action; hexagonal architecture¹⁹ names the ports-and-adapters principle.¶

Sources

rat-stack/AGENTS.md at main · joelhooks/rat-stack · GitHub. GitHub joelhooks/rat-stack. Projection law; used for one contract across every interface. Accessed 2026-10-01.
rat-stack/packages/capability/src/implement.ts at main · joelhooks/rat-stack · GitHub. GitHub joelhooks/rat-stack. Handler binding; used for separating contracts from implementations. Accessed 2026-10-01.
rat-stack/packages/capability/src/to-rpc-group.ts at main · joelhooks/rat-stack · GitHub. GitHub joelhooks/rat-stack. Client RPC projection; used for contracts without server handlers. Accessed 2026-10-01.

Last changed 2026-10-10 in 978dccc. Source on GitHub. Change log.

Linked from

Agent guide. An Effect stack so pure (aspirational) Kit Langton will blush.
One capability, every surface — A schema-typed contract and one handler feed every interface rat-stack keeps.
An MCP your users want. Rhys Sullivan's practical guide gives rat-stack a checklist for useful MCP tools.
See one capability, every surface and the cartridges page for the contracts and auth boundary.¶
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.
See one capability, every surface and infrastructure as effects.¶
Capabilities. Named application actions exposed through generated interfaces share one definition and one server-side implementation.
See one capability, every surface for why.¶
Cartridges. A cartridge owns one job and brings the infrastructure its service needs.
See one capability, every surface for the shared contract and a clean playground for the house rule behind these boundaries.¶
Change log. What changed in the files served here, newest first.
One capability, every surface — edited: docs: point live docs, skills and Brain pages at apps/site
Effect keeps the surfaces on one contract. Schema owns values, projections build interfaces, and Layers supply implementations.
One capability, every surface states the house rule.
Full agent guide. An Effect stack so pure (aspirational) Kit Langton will blush.
HATEOAS. Links in a representation tell its reader what to do next; rat-stack applies that idea to agent-facing pages and responses.
One capability, every surface describes the existing projections.
Hexagonal architecture. Ports name the application's jobs; adapters connect them to the outside world.
One capability, every surface starts with a contract, binds a handler, and projects CLI, HTTP, MCP, RPC, and code mode.
Infrastructure as effects. Sam Goodwin relates application operations to infrastructure requirements in one typed program.
A contract defines shared input, output, failures, and metadata.
learn-rat-stack. Trace a capability through Effect, XState, five projections, the CLI, and Alchemy. Try hosted search and read.
A projection builds a callable interface from capabilities.¶
Lifecycles are machines. XState owns finite lifecycle states while declared Effect actors own side effects.
See one capability, every surface for how a capability can own a machine and the fence for the rule that protects it.¶
Rat Stack lore | rat-stack. Short, source-grounded notes on the ideas and decisions behind rat-stack.
One capability, every surface — A schema-typed contract and one handler feed every interface rat-stack keeps.
rat-stack. An Effect stack so pure (aspirational) Kit Langton will blush.
Run Effect at the integration boundary. Build the runtime where a calling framework enters, reuse its services, and dispose it when that integration ends.
In rat-stack, capabilities remain the shared interface for application actions.
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.
Read One capability, every surface for today’s defineContract → implement pattern, including browser RPC, and current pins.
Source change history (log.md). The generated change log as Markdown.
One capability, every surface — edited: docs: point live docs, skills and Brain pages at apps/site

Unlinked mentions (18)

add-a-capability → A projection builds a callable interface from capabilities.¶
Agent rules for rat-stack (AGENTS.md) → File-level overrides exist only at projection boundaries (packages/capability/src/to-toolkit.ts, packages/capability/src/to-code-mode.ts, packages/capability/src/to-rpc.ts) and in process-spawning test files.
Analytics → Local tests prove projection and archive writes; they do not prove Cloudflare delivery.¶
Build and run rat-stack (README.md) → Code mode is the fourth projection.
Capabilities → A projection builds a callable interface from a capability.
Effect + Alchemy peer patterns → Keep capability schemas in packages/core, the toRpc projection in packages/capability, and UI atoms in the web app.
Effect keeps the surfaces on one contract → A projection builds an interface from a capability, a named action with a contract and handler.
Hexagonal architecture → The no-hand-rolled-surface rule keeps interface construction in the projection package.¶
keep-or-cut → A projection builds a callable interface from capabilities.¶
learn-rat-stack → A projection takes a registry and reuses its domain handlers.¶
One prompt serves people and agents → A projection builds a callable interface from capabilities.¶
One schema, three surfaces → A projection builds an interface from a capability.¶
OpenAPI describes the refusal too → ts builds the /api projection.
rat-stack → Each projection calls the same handler through the same contract.
Schema projections: 2026-09-18 history → Code mode is a fourth projection: serialize the catalog (Executor IR shape: JSON Schema per type, path per capability), emit .d.ts from the JSON Schema, expose search and execute as two ordinary Tools whose execute handler runs model code in a sandbox that can only call capabilities by path.
Schemas define the boundary → In rat-stack, one capability contract supplies schemas to every interface projection.¶
Tests prove behavior through supplied services → A capability is a named action; a projection converts it into an interface.¶
uncomplect → A rat-stack projection instead exposes capabilities through an interface.¶