---
title: Decision records
description: Thirteen architecture decisions, each with its context, alternatives and accepted consequences.
label: Overview
---

An ADR records a decision that was genuinely contested — where a reasonable
engineer would have chosen differently, and where the reasoning matters more
than the outcome.

Each one has the same four sections:

| | |
| --- | --- |
| **Context** | What problem forced a choice |
| **Decision** | What was chosen |
| **Alternatives** | What was rejected, and why |
| **Consequences** | What this costs, stated plainly |

The last section is the one worth reading. A decision record that lists only
benefits is marketing.

## The records

| | Decision |
| --- | --- |
| [0001](/architecture/adr/0001-scope-boundaries) | Scope boundaries — what Veefore deliberately is not |
| [0002](/architecture/adr/0002-gateway-architecture) | Two planes, one image |
| [0003](/architecture/adr/0003-policy-engine) | A TypeScript policy IR, not OPA |
| [0004](/architecture/adr/0004-delegation-semantics) | Refuse escalation rather than clamp it |
| [0005](/architecture/adr/0005-identity-model) | Per-agent key pairs, not API keys |
| [0006](/architecture/adr/0006-passport-format) | A signed snapshot that is never the decision |
| [0007](/architecture/adr/0007-trust-evidence) | Expiring typed evidence, not a reputation score |
| [0008](/architecture/adr/0008-credential-broker) | Short-lived leases to the runtime, never to the agent |
| [0009](/architecture/adr/0009-mcp-architecture) | Discovery and authorization as separate steps |
| [0010](/architecture/adr/0010-a2a-architecture) | A2A through the gateway, not as a direct API |
| [0011](/architecture/adr/0011-tenant-isolation) | Two independent isolation layers |
| [0012](/architecture/adr/0012-audit-architecture) | A keyed hash chain in PostgreSQL |
| [0013](/architecture/adr/0013-deployment-model) | Stateless planes, forward-only migrations |

## The thread running through them

Most of these resolve the same way, for the same reason: **prefer a guarantee
that is structural over one that is configured.**

- An agent belongs to one environment, so a staging identity cannot act in production. Not a rule — an absence.
- The broker runs after every refusal, so `BLOCK` means the secret did not go out.
- The SDK depends only on `types`, so it is structurally incapable of deciding anything.
- No table may have a `balance` column, so a wallet cannot be written without the audit noticing.

Configuration drifts. Structure does not.