docs/security.md

# Security design

Trace2MCP separates three decisions: what was observed, what was compiled, and what is
authorized to execute. Trace labels and aliases never override trusted runtime contracts.

The default policy allows `pure` and `read`, requires approval for `write` and
`external_side_effect`, and denies `delete` and `unknown`. Contract hashes detect drift.
Workflow hashes detect artifact changes. Generated adapters start as inert stubs;
generated contracts start unreviewed and are preserved during regeneration.

All supported capability paths converge on `RuntimeDispatcher.dispatch`. The dispatcher
captures the exact handler/contract pair, checks policy and approvals, detects registry
mutation, validates arguments, optionally asks a `RuntimeGuard`, invokes the same bound
handler, and validates its output. Managed nested calls return through the same boundary.
Unknown, uncontracted, unreviewed, malformed, changed, guard-denied, or guard-error
capabilities are rejected before their handler begins.

Threats considered include malicious trace data, effect-label spoofing, ambiguous value
matches, secret leakage, JSON parser abuse, path/symlink overwrite, contract drift,
unbounded parallelism, unsafe retries, and orphaned tasks. See `SECURITY.md` for the
operational boundary and reporting guidance.