What's consequential — what to seal
A capsule is for consequential actions, not every log line. The rule, in one sentence: seal what changes the world, plus reads of sensitive data; everything else is observability.
Two signals
| Signal | Seal it when… |
|---|---|
| 1 · Command vs. query | the action changes state or has a side effect — places an order, moves money, sends a message, writes a record. Pure reads (list / get / search) are queries — not sealed by default. |
| 2 · Privileged read | the action reads sensitive data (PII/PHI/cardholder data) even though it's a "read." This signal is evaluated engine-side, where data is classified — not at the gateway. |
Fail-safe by default
When a tool's nature is unknown, it is sealed — the safe default is to record, not to skip. An adapter only skips a call when it is explicitly marked a read (e.g. action_type="fyi", or seal_reads=False for tools so annotated). You opt out of sealing deliberately; you never silently lose a consequential action.
Grey areas
Some reads matter (exporting a customer list); some "writes" are trivial (a cache warm). Signal 2 is exactly for the first case. For the rest, when in doubt, seal — a few extra capsules cost little; a missing one is the gap that matters.
Why this isn't a private invention
The command-vs-query distinction is decades-old accepted vocabulary. We stand on it deliberately:
| Prior art | What we take from it |
|---|---|
| Command–Query Separation — Bertrand Meyer (1988) | the foundational command-vs-query split: commands change state, queries don't. |
| RFC 9110 — HTTP Semantics (safe methods) | the web's codification of "safe" (read) vs. unsafe (state-changing) methods. |
| Model Context Protocol tool annotations (Anthropic / AAIF) | tool-level read-only / destructive hints — the per-tool signal an adapter reads. |
| HIPAA §164.312(b) + PCI DSS | why a privileged read of regulated data is itself an auditable event (Signal 2). |
seal_reads knob, gateway vs. decorator patterns) lives in the producer's docs: capsule-emit/docs.