fix(relay): enforce scalar-only claims and surface untracked privacy budget (#632)

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

Author: jeremi

crates/registry-relay/CHANGELOG.md

@@ -21,6 +21,26 @@
   the unresolved reference instead fails every record at request time, so SP DCI
   generic search, details, and support answer `500 internal.unhandled` for any
   non-empty result.
+- BREAKING: Attribute-release claim values are scalar-only: a string, a
+  number, or a boolean. The stable v0.15.0 contract accepted arbitrary JSON
+  claim values; a claim whose projected or computed value is an object or an
+  array is now treated as unavailable instead of being released, so a
+  required claim of that shape denies the release and an optional one is
+  omitted, with a value-free warning naming the profile, version, and claim.
+  A claim expression that always produces a list or map (a top-level literal
+  or a `map()`/`filter()` comprehension) is rejected at configuration
+  validation and by `registryctl check`. Profiles that need structured
+  values should model them in Registry Evidence, whose signed,
+  minimum-disclosure assertions carry explicit output schemas and limits.
+  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. The warning may be
+  left active as an accepted-limitation signal or acknowledged with a
+  deployment waiver naming the finding.
 
 ## 0.16.3 - 2026-08-01
 

crates/registry-relay/docs/api.md

@@ -508,6 +508,20 @@ registry row, never a raw or hashed subject value. A `source` block
 only when the profile sets `response.include_source_metadata: true`; it is
 absent by default.
 
+Claim values are scalar-only: a string, a number, or a boolean. A claim whose
+projected or computed value is an object or an array is unavailable — an
+optional claim is omitted and a required claim denies the release through the
+collapsed `release.subject_denied` below — and the structured content never
+reaches the body. A claim expression that always produces a structured value
+(a top-level list or map literal, or a `map()`/`filter()` comprehension) is
+rejected at configuration validation and by `registryctl check`, before the
+route ever serves. A shape only some rows produce is caught at resolve time
+and logged once per profile version and claim as
+`attribute_release.claim.non_scalar_value`, a value-free operator signal
+carrying the profile id, version, claim name, and JSON type tag. Structured
+claim values belong to Registry Evidence, whose signed, minimum-disclosure
+assertions carry explicit output schemas and limits.
+
 Every denial after profile resolution collapses to one public code, so a
 caller cannot distinguish "no such subject" from "subject exists but was
 denied":

crates/registry-relay/docs/configuration.md

@@ -1407,16 +1407,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 minimum cell-size 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. Leaving the finding active is a legitimate steady state that keeps the posture honest; a deployment waiver naming the finding records a dated operator acknowledgement instead, at the cost of re-issuing the waiver whenever it expires. 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.
 
@@ -1735,6 +1738,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 minimum cell-size 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/openapi/registry-relay.openapi.json

@@ -1184,7 +1184,7 @@
             "type": "array"
           },
           "claim_names": {
-            "description": "Names of all claims that may be returned by this profile.",
+            "description": "Top-level names of all claims that may be returned by this profile. Every released value is a scalar (string, number, or boolean).",
             "items": {
               "type": "string"
             },
@@ -1268,7 +1268,7 @@
         "description": "Request body for resolving an attribute release profile against one subject.",
         "properties": {
           "claims": {
-            "description": "Optional subset of claim names to return. Absent means the profile default set; an empty array is rejected (400); duplicate or over-bound arrays are rejected (400); any explicit subset must include every required claim; any unknown claim name is denied.",
+            "description": "Optional subset of claim names to return. Entries are whole top-level claim names; there is no sub-selection inside a claim value. Absent means the profile default set; an empty array is rejected (400); duplicate or over-bound arrays are rejected (400); any explicit subset must include every required claim; any unknown claim name is denied.",
             "items": {
               "type": "string"
             },
@@ -1314,8 +1314,14 @@
         "description": "Resolved attribute release claim bundle. Contains only the approved, minimised claims for the matched subject. Never includes raw source rows, subject identifiers outside released claims, or private source internals.",
         "properties": {
           "claims": {
-            "additionalProperties": true,
-            "description": "Released claim bundle. Keys are claim names; values are the projected or computed claim values.",
+            "additionalProperties": {
+              "type": [
+                "string",
+                "number",
+                "boolean"
+              ]
+            },
+            "description": "Released claim bundle. Keys are top-level claim names; values are scalar-only in v1 (string, number, or boolean). Structured object or array values are never released: a claim whose projected or computed value is not a scalar is treated as unavailable, so a required claim of that shape denies the release and an optional one is omitted. Claim selection is by top-level claim name only; there is no sub-selection inside a claim value.",
             "type": "object"
           },
           "profile_id": {

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