Skip to content

Align source-observation freshness wording with the consultation-only enforcement model #583

Description

@jeremi

Context

An internal architecture review (2026-07-30) confirmed that Registry Notary validates but does not retain source_observed_at from Relay consultation results: RelayConsultationProvenance and stored issuance provenance carry only acquired_at (crates/registry-notary-server/src/relay_client.rs, crates/registry-notary-server/src/runtime/evaluation.rs). The only Notary freshness control is the federation-profile max_claim_result_age_seconds, which measures consultation-acquisition age, and Relay owns snapshot freshness through max_snapshot_age_ms (crates/registry-relay/src/consultation/executor.rs).

History shows this is the intended post-convergence model, not an accident: the 2026-07-14 consultation-only refactor removed the direct-connector source-observed-age PDP gate, renamed the federation field from max_source_observed_age_seconds to max_claim_result_age_seconds, and added a config test that rejects the old name (crates/registry-notary-core/src/config/tests/infrastructure.rs, federation_rejects_removed_source_named_fields).

Two documentation surfaces were not brought along:

  • docs/site/src/content/docs/spec/rs-pr-notary.mdx:128 (REQ-PR-NOTARY-025) says Notary derives freshness from "the verified Relay consultation provenance" and that stale required provenance must deny. A reader can take this as Notary-enforced source-observation age, which no runtime path provides.
  • products/manifest/docs/reference.md:171 says max_source_observed_age_seconds "runtime enforcement is in Registry Notary config". Notary config now rejects that exact field name, so the sentence is false. crates/registry-manifest-core/src/lib.rs still serializes the field on EvaluationProfileManifest although nothing enforces it.

Decision

Prefer narrowing the claims over building retention machinery, unless a 1.0 profile genuinely needs Notary-owned source-observation age (no current ticket or roadmap item requires it). Concretely:

  1. Reword REQ-PR-NOTARY-025 to state what ships: absent or malformed required provenance denies at consultation verification; acquisition-age staleness is enforced by federation max_claim_result_age_seconds where configured; source-observation and snapshot freshness are owned by Relay's pinned contract (max_snapshot_age_ms).
  2. Correct the manifest reference row for max_source_observed_age_seconds and decide the field's fate: remove it from EvaluationProfileManifest before 1.0, or re-document it as an informational public hint with no runtime enforcement. Removing is preferred; do not keep an unused slot.
  3. If instead source-observation freshness is declared load-bearing for 1.0, retain source_observed_at in the verified result and stored provenance and bind a maximum age into the pinned contract — but record that decision explicitly before implementing.

Definition of Done

  • REQ-PR-NOTARY-025 wording matches implemented behavior and names the Relay-owned freshness boundary.
  • products/manifest/docs/reference.md no longer claims Notary-config runtime enforcement for max_source_observed_age_seconds.
  • The manifest field is either removed (with schema/docs regeneration) or explicitly documented as non-enforced; the choice is recorded.
  • The capability matrix and known-limitations docs state that source-observation age is not a Notary-enforced quantity (or reflect the alternative decision).
  • Docs site checks and affected crate tests pass; no runtime behavior changes unless option 3 is chosen.

Metadata

Metadata

Assignees

No one assigned

    Labels

    1.0-blockerBlocks the 1.0 release intent.area:docsDocumentation site ownership.area:manifestRegistry Manifest ownership.criticality:p2Priority/criticality P2.documentationImprovements or additions to documentationneeds-jeremi-decisionMigrated issue that still needs Jeremi's product or release decision.

    Type

    No type

    Projects

    No projects

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions