feat(relay): surface untracked privacy budget on sensitive aggregates

A dataset classified personal, confidential, or secret that declares a
dataset-level access.aggregate_only_execution aggregate now raises the
relay.aggregates.privacy_budget_untracked deployment finding, bound
finding_warn under hosted_lab, production, and evidence_grade. Only
dataset-level declarations count: the aggregate query routes resolve
aggregates through dataset.aggregates alone, so table-level and
entity-level declarations have no runtime route and raise no finding.
Aggregate routes apply per-result k-anonymity suppression but track no
longitudinal query budget; this is the documented accepted limitation
from the known-limitations page, so the gate warns everywhere rather
than blocking startup or readiness, and a deployment waiver naming the
finding records the operator's acknowledgement. Boot is loud: an
active finding emits a dedicated deployment.privacy_budget_untracked
warn line pointing at the waiver remediation; a waived one reports
through the existing deployment.gate_waived line. The finding reaches
the posture endpoint and registryctl doctor through the existing
catalog plumbing.

Security note (deployment defaults): adds a deployment gate finding;
no runtime behavior or API surface changes.

Closes #585

Signed-off-by: Jeremi Joslin <jeremi@joslin.fr>

Author: jeremi

crates/registry-relay/CHANGELOG.md

@@ -8,6 +8,12 @@
   that shape denies the release and an optional one is omitted. The OpenAPI
   contract documents the scalar-only claim bundle and top-level-only claim
   selection.
+- A dataset classified `personal`, `confidential`, or `secret` with a
+  dataset-level `access.aggregate_only_execution` aggregate now raises the
+  `relay.aggregates.privacy_budget_untracked` deployment finding (warn at
+  every bound profile) and a dedicated boot-log warning, surfacing that
+  aggregate routes track no longitudinal privacy budget. A deployment waiver
+  naming the finding records the operator's acknowledgement.
 
 ## 0.16.2 - 2026-08-01
 

crates/registry-relay/docs/configuration.md

@@ -1403,16 +1403,19 @@ Waiver references and summaries are visible only in the restricted posture tier;
 | `relay.audit.retention_local_only` | (not bound) | warn | startup_fail |
 | `relay.audit.shipping_unverified` | (not bound) | warn | startup_fail |
 | `relay.audit.shipping_stale` | (not bound) | error | readiness_fail |
+| `relay.aggregates.privacy_budget_untracked` | warn | warn | warn |
 
 `relay.audit.retention_local_only` fires when the audit sink is a local rotating `file` sink and `evidence.audit_offhost_shipping` is not declared: a local rotating file caps retention, and an attacker with host access can destroy the audit trail. `stdout` sinks are exempt (retention is the orchestrator's log pipeline's concern) and `syslog` sinks are exempt (forwarding is the syslog daemon's own surface).
 
 `relay.audit.shipping_unverified` and `relay.audit.shipping_stale` read the ack cursor's observed health. `shipping_unverified` fires when any shipping target (`stdout`, `syslog`, or an attested local `file` sink) lacks `evidence.audit_ack_cursor_path`. It warns under `production` and refuses startup under `evidence_grade`, because a missing observation capability cannot heal at runtime. `shipping_stale` fires when a cursor is configured but is missing, unreadable, malformed, too old, too slow to read, or names a `last_acked_hash` other than the live keyed audit-chain tail. It fails readiness under `evidence_grade` and recovers when the trusted shipper advances a fresh cursor to the current tail. Neither hard gate is waivable. Runtime tail equality establishes that the claimed watermark belongs to this chain and the local backlog is zero; the unsigned local cursor is not cryptographic proof of remote receipt. Offline `doctor` cannot bind to a live chain and therefore reports a fresh cursor as `unverified`, never `ok`; an evidence-grade offline check consequently reports the hard shipping gate. The signed-bundle acceptance audit advances the tail before Relay serves requests, so the shipper must run independently of application readiness and acknowledge that boot record before `/ready` can return 200. Remediation: configure the cursor maintained by the off-host shipper, restore shipping, adjust `evidence.audit_ack_max_age_secs` if the cadence is legitimately slower, or repair a path or watermark mismatch. Removing the cursor does not satisfy `evidence_grade`.
 
+`relay.aggregates.privacy_budget_untracked` fires when a dataset classified `personal`, `confidential`, or `secret` has a dataset-level aggregate with `access.aggregate_only_execution: true`. Only dataset-level declarations count: they are the only ones the aggregate query routes serve, so table-level and entity-level declarations raise no finding. Aggregate routes apply per-result k-anonymity suppression (`disclosure_control.min_cell_size`), but track no longitudinal query budget: `query_budget.tracked` is always false. This is a documented, accepted limitation, not a fixable misconfiguration, so it warns at every bound profile, including `evidence_grade`, rather than blocking startup or readiness. A deployment waiver naming this finding records the operator's acknowledgement of the limitation. See "Aggregates are not privacy-budgeted" in [Known limitations and non-guarantees](https://docs.registrystack.org/explanation/known-limitations/).
+
 The current deployment profile, its findings, and active waivers are reported under `deployment` in the operations posture (`GET /admin/v1/posture`).
 
 ### Boot-time visibility
 
-Reduced posture is loud at boot, not only visible on the posture surface. Every config load warns once per waiver-suppressed finding (`deployment.gate_waived`, with the finding id, reference, optional summary, and expiry), once per expired waiver (`deployment.waiver_expired`), and once when the profile is undeclared (`deployment.profile_undeclared`). The serve path additionally writes one operational audit record per waived gate at boot, once the audit pipeline exists: event `deployment.gate_waived` at audit path `/__events/deployment.gate_waived`, with `error_code` set to the gate id. That minimized audit record does not copy waiver metadata.
+Reduced posture is loud at boot, not only visible on the posture surface. Every config load warns once per waiver-suppressed finding (`deployment.gate_waived`, with the finding id, reference, optional summary, and expiry), once per expired waiver (`deployment.waiver_expired`), and once when the profile is undeclared (`deployment.profile_undeclared`). A sensitive dataset's aggregate-only-execution aggregate additionally warns once per config load with `deployment.privacy_budget_untracked`, naming the finding id; a waived occurrence is reported through the generic `deployment.gate_waived` line instead, not a duplicate line. The serve path additionally writes one operational audit record per waived gate at boot, once the audit pipeline exists: event `deployment.gate_waived` at audit path `/__events/deployment.gate_waived`, with `error_code` set to the gate id. That minimized audit record does not copy waiver metadata.
 
 This boot-time audit write inherits `audit.write_policy` (see below). Under `fail_closed` (the default), a failed write aborts startup. Under `availability_first`, the failure is logged (`audit.operational_event_write_failed`) and startup continues, so the durable record is best-effort; the per-gate boot log warnings above remain the guaranteed floor.
 
@@ -1730,6 +1733,8 @@ aggregates:
 
 Supported aggregate functions include the configured V1 set used by tests and examples, such as `count`, `sum`, and `avg`. The runtime config key remains `indicators` for compatibility; public aggregate APIs expose these configured series as measures. `temporal_field` is optional; when present, native aggregate `temporal.from` and `temporal.to` are translated into the declared range-capable allowed filter for that source-entity field. Dataset measure and dimension discovery is derived from these aggregate declarations, so keep ids stable and labels consumer-friendly. Keep disclosure thresholds explicit and reviewable.
 
+`disclosure_control` and `access.aggregate_only_execution` bound per-result k-anonymity suppression on a single query; they do not track a longitudinal query budget across repeated aggregate queries. On a `personal`, `confidential`, or `secret` dataset, a dataset-level `aggregate_only_execution` aggregate raises the `relay.aggregates.privacy_budget_untracked` deployment finding described in the findings catalog under "Deployment profile" above; see "Aggregates are not privacy-budgeted" in [Known limitations and non-guarantees](https://docs.registrystack.org/explanation/known-limitations/) for the underlying limitation.
+
 ### Spatial EDR aggregates
 
 Spatial EDR exposure is opt-in. Requires `--features ogcapi-edr`.

crates/registry-relay/src/api/admin.rs

@@ -1153,6 +1153,62 @@ datasets: []
         assert!(ids.contains(&"relay.ingress.rate_limit_missing"));
     }
 
+    /// A sensitive dataset with an aggregate-only-execution aggregate surfaces
+    /// `relay.aggregates.privacy_budget_untracked` on the posture surface at
+    /// `finding_warn`, the same generic path every other catalog gate takes.
+    #[test]
+    fn deployment_summary_reports_untracked_privacy_budget_finding() {
+        let yaml = r#"
+server:
+  bind: "127.0.0.1:8080"
+catalog:
+  title: "Test Registry"
+  base_url: "https://data.example.test"
+  publisher: "Test Ministry"
+auth:
+  mode: api_key
+  api_keys: []
+audit:
+  sink: stdout
+datasets:
+  - id: sensitive_ds
+    title: "Sensitive Dataset"
+    description: "desc"
+    owner: "owner"
+    sensitivity: personal
+    access_rights: restricted
+    update_frequency: daily
+    tables:
+      - id: t1
+        source:
+          type: file
+          path: "data/t1.csv"
+        refresh:
+          mode: manual
+        schema:
+          fields: []
+    aggregates:
+      - id: agg1
+        description: "test aggregate"
+        source_entity: record
+        disclosure_control:
+          min_group_size: 2
+        access:
+          aggregate_only_execution: true
+"#;
+        let mut config = parse_minimal_config(yaml);
+        config.deployment.profile = Some(DeploymentProfile::HostedLab);
+        let summary = deployment_summary(&config, ConfigSource::LocalFile);
+        let finding = summary["findings"]
+            .as_array()
+            .expect("findings array")
+            .iter()
+            .find(|finding| finding["id"] == "relay.aggregates.privacy_budget_untracked")
+            .expect("privacy-budget finding is reported");
+        assert_eq!(finding["severity"], "finding_warn");
+        assert_eq!(finding["status"], "active");
+    }
+
     /// The full posture document is schema-valid for every declared profile and
     /// for the undeclared default. `evidence_grade` from a local file would
     /// trip a startup gate at load time, so its posture is exercised with a

crates/registry-relay/src/config/validate.rs

@@ -584,6 +584,13 @@ fn log_deployment_boot_findings(evaluation: &crate::deployment::GateEvaluation)
                 code = "deployment.profile_undeclared",
                 "deployment profile is undeclared; no profile gates bind"
             );
+        } else if finding.id == "relay.aggregates.privacy_budget_untracked" {
+            tracing::warn!(
+                code = "deployment.privacy_budget_untracked",
+                finding = %finding.id,
+                action = "record acknowledgement with a deployment waiver naming this finding; see explanation/known-limitations, \"Aggregates are not privacy-budgeted\"",
+                "aggregate routes on a sensitive dataset apply per-result k-anonymity suppression but track no longitudinal privacy budget"
+            );
         }
     }
 }
@@ -4726,6 +4733,96 @@ datasets: []
         serde_saphyr::from_str(&deployment_config_yaml(extra)).expect("config parses")
     }
 
+    /// A dataset with `sensitivity` classification carrying one dataset-level
+    /// aggregate with `access.aggregate_only_execution: true` (the only
+    /// aggregate level the query routes serve), plus `extra` (typically a
+    /// `deployment:` stanza) appended at the top level.
+    fn sensitive_aggregate_dataset_config_yaml(sensitivity: &str, extra: &str) -> String {
+        format!(
+            r#"
+server:
+  bind: "127.0.0.1:8080"
+catalog:
+  title: "Test Registry"
+  base_url: "https://data.example.test"
+  publisher: "Test Ministry"
+auth:
+  mode: api_key
+  api_keys: []
+audit:
+  sink: stdout
+datasets:
+  - id: sensitive_ds
+    title: "Sensitive Dataset"
+    description: "desc"
+    owner: "owner"
+    sensitivity: {sensitivity}
+    access_rights: restricted
+    update_frequency: daily
+    tables:
+      - id: t1
+        source:
+          type: file
+          path: "data/t1.csv"
+        refresh:
+          mode: manual
+        primary_key: record_id
+        schema:
+          strict: true
+          fields:
+            - name: record_id
+              type: string
+              nullable: false
+            - name: region_code
+              type: string
+              nullable: true
+    aggregates:
+      - id: agg1
+        title: "Records by region"
+        description: "test aggregate"
+        source_entity: record
+        default_group_by:
+          - region_code
+        dimensions:
+          - id: region_code
+            label: Region
+            field: region_code
+        indicators:
+          - id: record_count
+            label: Records
+            function: count
+            column: id
+            unit_measure: records
+        disclosure_control:
+          min_group_size: 2
+          suppression: omit
+        access:
+          aggregate_only_execution: true
+    entities:
+      - name: record
+        table: t1
+        fields:
+          - name: id
+            from: record_id
+          - name: region_code
+        access:
+          metadata_scope: "sensitive_ds:metadata"
+          aggregate_scope: "sensitive_ds:aggregate"
+          read_scope: "sensitive_ds:rows"
+        api:
+          default_limit: 10
+          max_limit: 100
+          require_purpose_header: true
+{extra}
+"#
+        )
+    }
+
+    fn parse_sensitive_aggregate_dataset_config(sensitivity: &str, extra: &str) -> Config {
+        serde_saphyr::from_str(&sensitive_aggregate_dataset_config_yaml(sensitivity, extra))
+            .expect("config parses")
+    }
+
     fn consultation_deployment_config_yaml(extra: &str) -> String {
         format!(
             r#"
@@ -5334,6 +5431,66 @@ deployment:
         );
     }
 
+    #[test]
+    fn sensitive_aggregate_only_execution_is_loud_in_the_boot_log() {
+        let config = parse_sensitive_aggregate_dataset_config(
+            "personal",
+            "deployment:\n  profile: production",
+        );
+        let (result, rendered) = run_with_captured_logs(&config);
+        result.expect(
+            "an aggregate-only-execution finding on a sensitive dataset must not block startup",
+        );
+        assert!(
+            rendered.contains("deployment.privacy_budget_untracked"),
+            "expected deployment.privacy_budget_untracked in boot log: {rendered}"
+        );
+        assert!(
+            rendered.contains("relay.aggregates.privacy_budget_untracked"),
+            "expected the finding id in boot log: {rendered}"
+        );
+        assert!(
+            rendered.contains("known-limitations"),
+            "expected a known-limitations reference in boot log: {rendered}"
+        );
+    }
+
+    #[test]
+    fn public_sensitivity_keeps_the_privacy_budget_boot_log_quiet() {
+        let config = parse_sensitive_aggregate_dataset_config(
+            "public",
+            "deployment:\n  profile: production",
+        );
+        let (result, rendered) = run_with_captured_logs(&config);
+        result.expect("a public-sensitivity dataset must not block startup");
+        assert!(
+            !rendered.contains("deployment.privacy_budget_untracked"),
+            "no privacy-budget line expected for a public-sensitivity dataset: {rendered}"
+        );
+    }
+
+    #[test]
+    fn waived_privacy_budget_finding_shows_the_generic_gate_waived_line_only() {
+        let config = parse_sensitive_aggregate_dataset_config(
+            "personal",
+            "deployment:\n  profile: production\n  waivers:\n    - finding: relay.aggregates.privacy_budget_untracked\n      reference: OPS-TEST-PRIVACY-BUDGET\n      expires: \"2999-01-01\"",
+        );
+        let (result, rendered) = run_with_captured_logs(&config);
+        result.expect("a waived privacy-budget finding must not block startup");
+        assert!(
+            rendered.contains("deployment.gate_waived"),
+            "expected deployment.gate_waived in boot log: {rendered}"
+        );
+        assert!(
+            rendered.contains("relay.aggregates.privacy_budget_untracked"),
+            "expected the waived finding id in boot log: {rendered}"
+        );
+        assert!(
+            !rendered.contains("deployment.privacy_budget_untracked"),
+            "the dedicated privacy-budget line must not appear once waived: {rendered}"
+        );
+    }
+
     #[test]
     fn evidence_grade_via_signed_bundle_source_boots() {
         // The same evidence_grade config that a local file rejects must validate