# ADR-0001: Production registry and contract authority

- **Status:** Accepted
- **Date:** 2026-08-28
- **Decision owners:** MARS production ecosystem

## Context

The ecosystem currently contains overlapping registry implementations, protocol
types, MAP integration code, and consumers with hand-maintained assumptions.
That overlap makes migrations ambiguous and allows wire contracts to drift.
Sigil anchoring also changes the authority of registry writes, so it cannot be
enabled globally without staged evidence and an explicit governance decision.

## Decision

1. `mars-server` is the sole production MARS registry implementation and the
   only service authorized to own production registry persistence and v1 HTTP
   behavior.
2. `mars-protocol` is the canonical MARS wire model. JSON Schemas, OpenAPI, and
   downstream clients are derived from its Rust types and the server handlers;
   hand-maintained parallel type models are non-authoritative.
3. The separate `mars-registry` implementation is migration-only and is
   deprecated after its data and consumers move to `mars-server`. It receives
   no new production contract surface after migration.
4. MAP's `mars-lib` becomes an adapter to the canonical MARS v1 contract. It
   does not own registry business logic, storage, or a competing wire model.
5. OAS remains vendor-neutral. OAS crates and specifications do not import MARS
   product code or encode MARS deployment assumptions; MARS consumes OAS
   identity contracts through adapters.
6. Sigil asset anchoring activates in three governed stages:
   **shadow**, then **private canary**, then **governed activation**. Shadow
   mode submits or simulates anchors without making them authoritative and
   compares receipts against registry state. Private canary limits authority
   to explicitly admitted tenants and assets with monitored rollback.
   Production authority changes only after governance reviews evidence for
   correctness, replay protection, failure recovery, latency, cost, and
   rollback, and records an activation decision.

## Consequences

- Contract changes start in Rust and fail CI when committed artifacts drift.
- Consumers generate clients from `docs/api/openapi.v1.json` or consume the
  versioned JSON Schemas under `schemas/v1`.
- Compatibility routes may be additive, but `/v1/federation/peers` remains the
  canonical federation peer path and no unauthenticated legacy write API is
  introduced.
- Arsenal ACT is not advertised as an active MARS auth profile until an
  enforcing adapter is implemented and governed. The current production entry
  write profile is Sign-In-With-Sigil session authentication.
- A failed shadow or canary gate leaves existing registry authority unchanged;
  rollback disables the candidate anchor path without rewriting MARS history.