registrystack / registrystack/registry-stack

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

Aperta
#583 0 commenti 0 reazioni 0 assegnatari Vedi su GitHub
1.0-blocker area:docs area:manifest criticality:p2 documentation needs-jeremi-decision
Lingua principale
Rust
Stelle
2
Fork
0
Merge medio
2h 55m
PR unite (30g)
130

Descrizione

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

Guida per i contributori

Apri la guida per i contributori

Direzione di ricerca

Inizia da REQ-PR-NOTARY-025 in docs/site/src/content/docs/spec/rs-pr-notary.mdx e dalla riga max_source_observed_age_seconds in products/manifest/docs/reference.md, quindi esamina i file di provenienza, configurazione e manifest citati. Controlla il test federation_rejects_removed_source_named_fields e i controlli interessati della documentazione e del crate. Il lavoro è completato quando la formulazione, la documentazione delle capacità e delle limitazioni e il trattamento del campo del manifest corrispondono alla decisione registrata, senza modifiche al runtime non pianificate.

Scritto dal modello di indicizzazione a partire dal testo della issue.

Valutazione

Stack tecnologico
rust
Ambito
documentation
Tipo di issue
Documentazione
Difficoltà
4/5
Tempo stimato
3-5 giorni
Stato di attività
Tranquilla
Chiarezza
Abbastanza chiara
Idoneità per principianti
48/100

Ricevi le nuove issue nella tua casella

Un breve riepilogo di issue GitHub adatte ai principianti.