One capability, every surface

Goal: add one action and get a command, an HTTP route, an MCP31 tool, and a code-mode function from it. Browser RPC uses the same contracts; search and read show that side.

A capability is one named action with a contract28 and a server-side handler28. A contract defines the shared input, output, failures, and metadata. Effect35 Schema30 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 surface26 is an interface26 for calling the action. A projection is code that converts registered capabilities into an interface. The interfaces are command line, HTTP, MCP tools, browser RPC, and code mode23. Each interface derives its input and failure definitions from the same schemas.

Worked example: inspectFile

1. The contract

packages/core/src/contracts.ts · a3f5a148 · Name, schemas, failure, and annotations
export const inspectFileContract = defineContract("inspectFile", {
  annotations: { idempotent: true, readOnly: true },
  description: "Count bytes, characters, words, and lines in a file",
  failure: FileStatsError,
  input: Schema.Struct({
    path: Schema.String.annotate({ description: "File to inspect" }),
  }),
  output: FileStatsSchema,
});

The contract holds no handler. A browser can import it without server code.

2. The handler

packages/core/src/inspect-file.ts · a3f5a148 · implement binds the handler; capabilities registers it
export const inspectFile = implement(inspectFileContract, ({ path }) =>
  runInspectMachine(path)
);

export const capabilities = [
  inspectFile,

The handler runs the inspection machine27.

3. The projections

apps/cli/src/surfaces.ts · a3f5a148 · HTTP, MCP tools, and code mode from the same lists
export const http = toHttpApi("RatStack", capabilities);

export const tools = toToolkit(cliCapabilities);

export const codeMode = toCodeMode(cliCapabilities);
apps/cli/src/command.ts · a3f5a148 · The CLI command, with a stats alias
const capabilityCommands = commandCapabilities.map((capability) => {
  const command =
    capability === inspectFile
      ? toCommand(capability, {
          positional: ["path"],
          render: formatFileStats,
        }).pipe(Command.withAlias("stats"))

No projection repeats the schema. Each one reads the contract it was given.

Why one contract

A second hand-written route would need its own schema, and the two could drift. Here each surface derives its input and failure from one place.

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.

Michael Arnaldi7 demonstrates Schema decoding30 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.

Next

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

Use the add-a-capability skill for the steps.

Read A browser send follows one path to the capability6 to see search called over RPC.

Analytics18 shows a separate infrastructure cartridge38; interest signup14 shows core ports with a delivery adapter30 outside core. Neither turns static pages or protocol discovery into domain capabilities.

See lifecycles are machines27 for stateful handlers and cartridges38 for the infrastructure boundary. HATEOAS9 covers links that guide an agent’s next action; hexagonal architecture30 names the ports-and-adapters principle.

Sources

  1. 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.
  2. Shared contracts at a3f5a14. GitHub joelhooks/rat-stack. inspectFileContract declares the name, schemas, failure, and annotations. Accessed 2026-11-08.
  3. inspectFile capability at a3f5a14. GitHub joelhooks/rat-stack. implement binds inspectFileContract to runInspectMachine and registers it in capabilities. Accessed 2026-11-08.
  4. CLI projections at a3f5a14. GitHub joelhooks/rat-stack. toHttpApi, toToolkit, and toCodeMode project the same capability lists. Accessed 2026-11-08.
  5. CLI commands at a3f5a14. GitHub joelhooks/rat-stack. toCommand projects inspectFile with a positional path and the stats alias. Accessed 2026-11-08.
  6. 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.
  7. 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-11-08 in fa39fa0. Source on GitHub. Change log.

Linked from

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

    Its search box calls the search capability.¶

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

  3. 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.¶

  4. 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.¶

  5. Capabilities. Named application actions exposed through generated interfaces share one definition and one server-side implementation.

    See one capability, every surface for why.¶

  6. 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.¶

  7. Change log. What changed in the files served here, newest first.

    One capability, every surface — new page: Initial commit from joelhooks/rat-stack template

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

  9. Full agent guide. An Effect stack so pure (aspirational) Kit Langton will blush.
  10. 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.

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

  12. Infrastructure as effects. Sam Goodwin relates application operations to infrastructure requirements in one typed program.

    A contract defines shared input, output, failures, and metadata.

  13. 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.¶

  14. 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.¶

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

  16. rat-stack. An Effect stack so pure (aspirational) Kit Langton will blush.
  17. 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.

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

  19. Source change history (log.md). The generated change log as Markdown.

    One capability, every surface — new page: Initial commit from joelhooks/rat-stack template

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

    A generated-program test checks failure reporting across HTTP, MCP, RPC, and the CLI; restoring the false 200 makes it fail.¶

  21. Turbo remote cache. A separate Worker stores streamed Turbo artifacts in R2, with one credential per team and lifecycle expiry.

    The capability projection requires struct inputs, excludes HEAD, and does not describe raw upload streams with per-artifact response headers.

Unlinked mentions (24)