Design notes

Eight documents, one per area. Each says what the area does, why it is built that way, and what fails under the alternative somebody reaches for first.

They are copied from docs/design-notes/ in the repository and reviewed with the code that makes them true. The order of precedence is unchanged: DESIGN.md decides what gets built, and a design note that contradicts it is the thing that is wrong.

Read the relevant one before changing a component. Read any of them to decide whether you agree with the runtime enough to depend on it.

• Durability and leases: why supervision and execution are separate loops, why a lease and a deadline are two mechanisms rather than one, and what happens to a tool call nobody finished.
• The record log and its reducer: the append-only log, the pure fold over it, and why a contradictory log is failed loudly instead of repaired.
• Spec versioning and tool access: content hashing, the canonicalisation rules chosen rather than inherited, and the three-plane narrowing that access passes through.
• Tool disclosure and the prompt budget: what reaches the model each turn, and what a large MCP catalogue would otherwise cost on every call.
• Metering and telemetry: usage split by cache state, why an unknown price is None, and the span schema.
• Subagents and delegation: the roster an author writes, the envelope a model composes within, and why a parent suspends rather than holding its lease.
• Code execution and sandboxing: why in-process sandboxing is rejected outright, and what each backend can honestly promise about the network.
• MCP 2026-07-28: the protocol version Psych implements, and the decisions its spec leaves to a client.