registrystack / registrystack/registry-stack

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

Offen
#583 0 Kommentare 0 Reaktionen 0 zugewiesene Personen Auf GitHub ansehen
1.0-blocker area:docs area:manifest criticality:p2 documentation needs-jeremi-decision
Vorherrschende Sprache
Rust
Sterne
2
Forks
0
Ø Merge
2 Std. 55 Min.
Gemergte PRs (30 T.)
130

Beschreibung

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

Beitragsleitfaden

Beitragsleitfaden öffnen

Rechercherichtung

Beginne mit REQ-PR-NOTARY-025 in docs/site/src/content/docs/spec/rs-pr-notary.mdx und der Zeile max_source_observed_age_seconds in products/manifest/docs/reference.md, und überprüfe anschließend die darin referenzierten Provenienz-, Konfigurations- und Manifestdateien. Prüfe den Test federation_rejects_removed_source_named_fields sowie die betroffenen Dokumentations- und crate-Prüfungen. Erledigt ist die Aufgabe, wenn die Formulierung, die Dokumentation der Fähigkeiten und Einschränkungen sowie die Behandlung des Manifestfelds mit der aufgezeichneten Entscheidung übereinstimmen, ohne ungeplante Laufzeitänderungen.

Vom Indexierungsmodell aus dem Issue-Text verfasst.

Bewertung

Tech-Stack
rust
Bereich
documentation
Issue-Typ
Dokumentation
Schwierigkeit
4/5
Geschätzter Aufwand
3-5 Tage
Aktivitätsstatus
Ruhig
Klarheit
Größtenteils klar
Anfängerfreundlichkeit
48/100

Neue Issues direkt in Ihr Postfach

Eine kurze Übersicht über anfängerfreundliche GitHub-Issues.