Skip to content

refactor: make invalid config states unrepresentable, one loading layer, generated examples #311

Description

@jeremi

Context

The 2026-07-07 architecture review found that configuration is the de-facto architecture of both products, and that several recurring bug classes are generated by its current shape: interacting fields admit degenerate combinations that are compensated with runtime warnings (the auth failure-throttle fix chain), validation stops at the first error, each surface loads YAML with its own parser settings and unknown-key strictness (the generator behind #249, #250, #251, #259), and example/template configs are hand-copied across five surfaces (the drift class behind #253, #254, registrystack/solmara-lab#5, registrystack/solmara-lab#6, #263).

Scope

  1. Make invalid states unrepresentable where fix-chains recur: constructors/newtypes for interacting field groups, starting with the areas that have documented fix chains (auth failure throttle first). Where a constructor can refuse to build, delete the compensating warning taxonomy.
  2. Aggregate validation errors: report all config errors in one pass instead of failing on the first.
  3. One shared config-loading layer for both products: single YAML parser, uniform unknown-key strictness, shared source resolution.
  4. Generate example/template configs by round-tripping through the real Config types in a test, so committed examples cannot drift from the schema.
  5. Move config types out of registry-notary-core so the client SDK stops inheriting the server deployment schema (coordinate with the refactor: split security-critical god files and make audit emission structural #304 split).

Out of scope: knob reduction that falls out of the standards roster decision (#305), and the governed-config delivery redesign (#314), though the shared loading layer should be designed with it in mind.

Acceptance

  • A config with multiple errors reports all of them in one run.
  • Both products parse YAML through the same loader with the same unknown-key strictness.
  • Committed example/template configs are asserted equal to generated ones in CI.
  • Throttle-class invalid combinations fail construction instead of warning at runtime.
  • The notary client crate builds without server deployment config types.

Security note

Config loading and validation gate authentication and deployment posture; changes here are security-sensitive per AGENTS.md and need explicit 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