Skip to content

title: ADR-0005 — Envelope content shape: the v1 content payload is the client's shape doc_id: ADR-0005 formalises: UCCA-RULING-ENVELOPE-SHAPE-01 (Tim's ruling on UCCA-ENVELOPE-DRIFT-FINDING-01, which this closes) type: architecture decision record — canon series. Class G (ratified). layer: decisions (append-only) status: minted (G — ratified 2026-07-03 by Tim's ruling) ruled_by: Tim, 2026-07-03, verbatim: "Ruled: option 1 with the adapter rider." authored: 2026-07-03 NYC (Claude-web, formalising the ruling; minted as ADR-0005 per the standing division — layout call is Alex's, grant recorded in the ruling) relates_to: UCCA-ENVELOPE-DRIFT-FINDING-01 (closed by this) · ucca-content-payload-schema-v1.json (FROZEN — unchanged by this) · UCCA-CONTRACT-PACK-01 v1.0 · RTOPACKS-ACK-CONTRACT-PACK-01 · ADR-0002 (gate neutrality) · UCCA-NORTHSTAR-01 §2 · UCCA-FENCE-ADOPTION-01

Ruling — the v1 content shape is the client's shape

The ruling

Option 1, with the adapter rider.

The v1 content payload (ucca-content-payload-schema-v1.json, FROZEN, RTOpacks- acked) is the RTOpacks world's content shape, and its course-shaped fields (ucca_code, course_code, learning_outcomes, content_changelog, artifacts) are ruled ADAPTER, NOT GATE. The fossil is knowingly signed, as a client-shaped payload under a provenance-only seal.

The rider: option 3 of the finding — a domain-neutral inner engine artefact, distinct from any client's world shape, which client worlds adapt — is recorded as the named architectural direction. It triggers when the second client or the diagnosis build forces it, not before. It is direction, not debt: no work is scheduled against it and no gate waits on it.

Rationale (why this is doctrinally clean, not a concession)

  1. Client surfaces are permitted to be client-shaped. NORTHSTAR §2 and ADR-0002 require the gate to be neutral; specialisation lives in the adapter, on the client's side of the warranty line. The v1 schema was derived from the client's run, acked by the client, and describes the client's content object. The course-shape is located exactly where specialisation is allowed to live. The gate itself fired clean (no VET-only field).
  2. The seal attests provenance only. The signature says "this came through the throat," never "this content is domain-neutral." Signing a client-shaped payload therefore does not corrupt what a UCCO means.
  3. Option 2 is rejected, explicitly: it would burn a fence crossing (a contract revision requiring RTOpacks re-ack) to rename identifiers on a surface that is entitled to be client-shaped — jamming a fence that already has Phase-6 and the stamped-pack debt queued, to buy cosmetics. It also misreads doctrine: it tries to neutralise a client surface, when only the gate must be neutral.

The honest cost (recorded, not hidden)

Every v1 UCCO minted between this ruling and any future option-3 build carries the course-shaped fields immutably — that is the envelope working as designed. This is acceptable because the shape is frozen, acked, and derived from the client's own run: the client acked the shape it receives. If that ack is ever found not to have covered the shape, that is a fence matter, not an engine matter.

additionalProperties: true remains as frozen. The reasoner path drops non-contract fields (verified in step 2 / golden §8.1); the loose surface is a watch-item for any future mapping change, owned by the drift-checks already standing.

Consequences

  • UCCA-ENVELOPE-DRIFT-FINDING-01 is CLOSED by this ruling. Status flip on the finding, pointer to this doc.
  • The proof job is unblocked. The course-shape is no longer an open question at mint time; ADR-0002's mint language may state that the known course-shape is located outside the gate by this ruling.
  • No fence crossing is created. The frozen contract is untouched; RTOpacks is not contacted; nothing changes on their side.
  • The purpose drift-check is vindicated, not silenced. It fired on a real fossil; the fossil is now ruled, located, and ledgered rather than latent. Both drift-checks continue to be asked of every build decision.
  • Option-3 trigger conditions (second client onboarding, or the diagnosis build) are recorded here so the direction is findable when the trigger arrives.

Ruling record. The shape is the client's; the gate stayed neutral; the seal attests provenance; the pure architecture is named and parked with its trigger. Finding closed, proof job unblocked, fence untouched.