Skip to content

ADR-021 — UC Rust reference implementation and feedback loop

  • Status: accepted
  • Date: 2026-07-18
  • Related issues: nomed/uc-bok#9, nomed/uc-rust#38

Context

UC-BoK is a vendor-neutral executable knowledge platform. A concrete implementation can validate whether its ontology, schemas, business objects, relationships and principles are coherent and usable. Without a governed relationship, specification and implementation can drift or implementation-specific concerns can contaminate the normative model.

Decision

nomed/uc-bok is the normative Unified Commerce knowledge and specification repository. nomed/uc-rust is its reference implementation and implementation-feedback laboratory.

  • UC-BoK publishes stable identifiers and versioned normative material.
  • UC Rust maps executable artifacts and tests to those identifiers.
  • UC Rust may raise evidence-based feedback for ambiguity, contradiction, missing concepts, impractical constraints and generally useful extensions.
  • UC-BoK changes create explicit UC Rust impact-assessment and adoption work.
  • Implementation feedback does not automatically become normative; UC-BoK records a disposition.
  • Intentional divergence requires reciprocal accepted decisions and documented compatibility impact.

Feedback lifecycle

Cross-repository issues must carry reciprocal links, affected identifiers/artifacts, evidence, change classification, compatibility impact and acceptance criteria. Repeated findings use a stable fingerprint and update an existing issue rather than generating duplicates.

Consequences

  • UC-BoK remains vendor-neutral while benefiting from executable validation.
  • Every normative change must consider reference-implementation impact.
  • The implementation may reveal new general principles, but promotion into UC-BoK requires the normal governance process.
  • Alignment and drift become measurable and auditable.