ADR-0008: Realms as lightweight namespaces

Status

Accepted

Date

2026-06-24

Context

The pack defines 14 realms and makes them runtime boundaries: cross-realm links must be explicitly typed, cross-realm actions must declare affected realms, and authority composes per-realm policy fragments into one decision. That governance machinery exists to stop different teams / extension authors from each inventing their own permission model.

For a 2–3 person team (ADR-0014) that is the only author, that problem does not exist yet — but the ceremony tax is immediate and real. The proof loop touches only ~6 realms (core, geo, network, projects, evidence, workflow, integration, ops).

Decision

Keep the realm concept (it is a clean separation from Extension, Trait, and App), but at the start make realms naming namespaces + dependency declarations only:

Realms are prefixes (network., projects.) plus declared dependencies/imports.
Cross-realm links are allowed and lightly typed.
Defer the runtime governance — per-realm policy-fragment composition, affected-realm gating, cross-realm action-composition checks — until multiple extension authors actually exist.
Declare ~6 realms, not 14. Add market / signal / campus / security when their modules arrive.

Alternatives Considered

Full runtime boundary, all 14

Rejected: matches the spec exactly, but a heavy governance tax on a tiny single-author team solving a multi-author problem that doesn’t exist yet.

Drop realms early, one flat namespace

Just entity-type prefixes, introduce realms later.

Rejected: loses semantic-boundary discipline early and would force a messy retrofit when boundaries do matter.

Collapse realm into extension

One concept — a package is a namespace.

Rejected: muddies the clean Realm/Extension/Trait/App separation that the rest of the model relies on; the cost of keeping them distinct is just naming.

Consequences

The realm concept and naming are present from day one; only the runtime enforcement is deferred.
When the second author (or external extension team) arrives, runtime governance is added to an existing realm structure rather than introduced from scratch.
Authority (the policy engine) initially evaluates without per-realm fragment composition; that composition is the first thing added when multi-author governance is needed.