rune/docs/surface-parity.md

Surface Parity

Sixth orchestration plan (after foundation, cognitive strata, resource authority, memory and synthesis, Gitea delegation and outbox): the entry-path parity layer, per design "Entry-path and surface parity".

Components (src/rune/orchestration/)

• surface.py — Capability + SurfaceRegistry (bidirectional external/internal ids, stable binding)
• capability.py — CapabilityNegotiator (baseline parity + structured absence)
• mapping.py — MappingStore (durable bidirectional conversation mapping)
• gateway.py — SurfaceGateway (enter: resolve + peer-check + negotiate + map)
• surface_gateway.py — build_surface_parity() composition

Contracts

• Every production entry path enters through the same gateway and composition root (S4 doctrine: Rune contains the model; surfaces do not fork the spine).
• Capability-set parity is mandatory; exceptions require structured absence (owner, reason, expiry, restoration canary). Honest absence is NOT parity.
• External-to-internal mappings are bidirectional and durable: responses can return to the originating room, device, or peer.
• Transport identity and portable agent identity remain distinct; configured peer keys are pinned and checked before events enter the spine.
• The SurfaceRegistry is itself persisted (AtomicStore JSON at <paths_root>/surface_registry/state/registry.json) and reloaded on composition, so surfaces and pinned peer keys survive restart.

Run

PYTHONPATH=src:. python3 -m pytest tests/ -k orchestration --ignore=tests/test_message_widgets.py -q
PYTHONPATH=src:. python3 src/rune/canary_surface_parity.py