Skip to content

refactor(relay): single runtime metadata model, canonical manifest direction, manifest/notary contract test #312

Description

@jeremi

Context

The 2026-07-07 architecture review found the same domain concepts (dataset/entity/field metadata) modeled in up to four parallel hierarchies in Relay: the config hierarchy (config/mod.rs), CompiledMetadata (metadata/core_adapter.rs), the manifest-core mirror, and the catalog/OpenAPI hierarchy (metadata/catalog.rs plus openapi.rs admission), with conversion layers and diverged wire vocabulary between them. Relay both consumes external manifests and generates manifests from its own runtime config, so neither direction is canonical today. Notary and manifest fixtures are joined only by policy_id/policy_hash string equality, and that contract is undocumented.

Scope

  1. Make CompiledMetadata the single Relay runtime model: fold the catalog/OpenAPI hierarchy into it and resolve the diverged wire vocabulary once. Target state: two representations (config in, compiled out).
  2. Document the canonical direction: the manifest is the authoring/interchange format; Relay config holds connection and policy material. Fully inverting the generation direction may land after 1.0, but the documented contract must land before the formats freeze.
  3. Split manifest-core renderers into a separate crate so consumers of types/validate/compile stop compiling all renderers.
  4. Bless the Notary/manifest policy_id + policy_hash join as the documented contract, with a cross-fixture contract test: a manifest fixture and a notary config fixture that must agree, failing CI on divergence.

Acceptance

  • One runtime metadata hierarchy in Relay; the catalog/OpenAPI surfaces derive from it.
  • Docs state which artifact is authoritative for source descriptions.
  • manifest-core types are usable without compiling renderers.
  • A CI contract test fails when manifest and notary fixtures disagree on policy_id/policy_hash.

Security note

Metadata and policy joins feed disclosure policy wiring; treat as security-sensitive per AGENTS.md, with review notes. If work surfaces a suspected vulnerability, report it per SECURITY.md, not on this issue.

Metadata

Metadata

Assignees

No one assigned

    Labels

    area:notaryRegistry Notary ownership.area:relayRegistry Relay ownership.criticality:p2Priority/criticality P2.rustRust implementation work.

    Type

    No type

    Fields

    No fields configured for issues without a type.

    Projects

    No projects

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions