sprig and prose docs classic docs
Reference› ADRs› ADR003 EndpointDimensionPairs

ADR003 EndpointDimensionPairs

Title: Endpoint dimension relationship pairs

  • Status: Accepted
  • Decided: D2026-08-21
  • Revised by: ADR007 RelatesEndpointDimensionPairs
  • Introduces: SP023 RelationshipPairConflictError
  • Affects: Dimension, Parser, Relationship, Relationships
  • Pairings:
    • ADR007 RelatesEndpointDimensionPairs — the relates exception

Context

A relationship pair is declared once, often on a dimension:

dimension abbreviation {
  relationship standsFor and isRepresentedBy { }
}

August 2026 taught the compiler to resolve an authored edge against the subject's dimension first, then ancestor scopes, then the target concept. That is the right rule for "which vocabulary is this concept speaking." It does not notice that the target is also a typed thing. Asserting the inverse from the other side failed with SP015 whenever that side's dimension did not repeat the pair, even though the pair was already known.

The finalizer already mirrors the inverse onto the other concept in the manifest after a successful assert. Authors could write one side and read both, but they could not write the inverse unless their own dimension declared it.

Decision

When a concept asserts an edge toward a target, look the edge up on both resolved dimensions.

  • One dimension defines the pair and the other does not: that pair is the definition.
  • Both define the same two names: the pair is unambiguous. Prefer the subject's definition, matching August.
  • Both define the same edge with different partners, or one-way against paired: SP023. Do not silently prefer the subject.
  • Neither dimension defines it: keep the August fallback (subject and ancestors, then the target concept). Relates are unchanged; they have no dimension of their own. (The relates exception is revised by ADR 007.)

Consequences

Cost. A universe that compiled by letting the subject's dimension win over a conflicting pair on the target will now error. That is the point of SP023.

Authoring. The inverse may be written from the side that does not own the declaration. ApplicationName may say isRepresentedBy { CommonAbbreviations.App } when abbreviation declared standsFor and isRepresentedBy, even if application is empty.

What this does not do. It does not require a particular side of the pair on a particular concept. If the pair is in reach, either name may be written. It does not search ancestor dimensions beyond each concept's resolved dimension.

Alternatives considered

Subject dimension always wins. That is what August shipped. Rejected for the conflicting-pair case: if abbreviation says standsFor and isRepresentedBy and application says isRepresentedBy and listedAs, there is no honest inverse to rehydrate. Preferring the subject would hide that.

Require the pair on both dimensions. Rejected. One declaration is enough; that is already the "declare one side" rule for authored edges, and repeating the pair is busywork.

Evidence

The failing universe that asserted isRepresentedBy from an empty application toward an abbreviation was SP015 under August, and is the case this decision is for. Real universes measured during the August work bound zero authored edges via target concepts; this change consults the target dimension, which that measurement did not cover.