registrystack / registrystack/registry-stack

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

Open
#583 0 comments 0 reactions 0 assignees View on GitHub
1.0-blocker area:docs area:manifest criticality:p2 documentation needs-jeremi-decision
Dominant language
Rust
Stars
2
Forks
0
Avg merge
2h 57m
Merged PRs (30d)
128

Description

## 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.

Contributor guide

Open the contributing guide

Research direction

Start with REQ-PR-NOTARY-025 in docs/site/src/content/docs/spec/rs-pr-notary.mdx and the max_source_observed_age_seconds row in products/manifest/docs/reference.md, then review the cited provenance, configuration, and manifest files. Check the federation_rejects_removed_source_named_fields test and affected docs and crate checks. Done means the wording, capability and limitations documentation, and manifest field treatment match the recorded decision without unplanned runtime changes.

Written by the indexing model from the issue text.

Assessment

Tech stack
rust
Domain
documentation
Issue type
Documentation
Difficulty
4/5
Estimated time
3-5 days
Activity status
Quiet
Clarity
Mostly clear
Newbie friendliness
48/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.