FR-032 — Canonical fully-qualified references (YAML-only relative paths) #21

Status: implemented (5 ports), pre-1.0. Tracked here for the roadmap; delivered in PR #20.

Problem

A metadata reference (extends/super, @objectRef, @references, origin @from/@of/@via, @parameterRef, @payloadRef/@responseRef, the dotted Entity.child) resolved against a package context, and the bare-name rule was a silent-shadowing footgun (a bare Apple present in both the current package and at root could never deterministically reference the root one) — the exact ambiguity Python 3 removed (PEP 328) and Rust makes a hard error. The four loaders also disagreed on what ::X meant.

Decision (ADR-0032)

Canonical JSON references are fully-qualified and self-contained. Relative forms are a YAML-authoring affordance only, expanded to FQN by the desugar:

• bare Name → current package only (no root fallback — kills the footgun)
• qualified a::b::C → absolute
• leading ::Rest → root-absolute escape
• ..::Rest → parent-relative (drop one package segment per ..::)

A relative ref surviving into canonical JSON is rejected with ERR_RELATIVE_REF_IN_CANONICAL.

Delivered (PR #20)

• TS reference: expandRef + YAML desugar FQN expansion + reject-relative-in-canonical guard + the conformance corpus sweep (every ref → FQN, goldens regenerated).
• Cross-port fan-out — all 5 ports green (TS / Java / Kotlin / C# / Python): FQN resolution (origin/template/@parameterRef) + desugar expandRef + the ERR_RELATIVE_REF_IN_CANONICAL guard, gated by the shared error-relative-ref-in-canonical fixture.
• The FQN corpus flushed out (and fixed) real codegen bugs in TS, C#, and Python (generators emitting a raw FQN ref as a code type name).

Notes

• Developed under the working number "FR-026" (collided with FR-026 = Forms); renumbered to FR-032.
• Design: docs/superpowers/specs/2026-06-13-fr-032-canonical-fqn-refs-design.md, ADR-0032.

🤖 Generated with Claude Code