fix(sdk, collector): apply role-keyed top-level constraints, widen revocation staleness

[guillaume-hexamind]

Two independent changes on one branch

1. fix(sdk) — a role-keyed policy's top-level constraints: was silently dropped

load_policy_set_from_dict validated only the values under roles:, so every other top-level key parsed and was discarded. An author wrote a role-wide fence, got no fence, and no error. The flat shape was never affected — there the whole payload validates as one AgentPolicy — so the same key meant two different things depending on whether the document declared roles.

• A file-level constraints: block now unions into every role. Union, not replace: a role dropping the file's fence would be fail-open, the same reason constraints union across inherits.
• Any other unrecognised sibling of roles: is now a PolicySetError naming the key. That closes the defect class rather than this one instance, and matches composed module policies, which are already extra="forbid" at every scope.
• The block's own shape is checked before the hoist — a bare string would otherwise splat into single characters, each a valid str.

Verified past the unit tests: the fence compiles into the Rego bundle per role, so this holds on the WASM engine and not only the pydantic path; and the resolve → build round-trip still loads, since hexgate policy resolve emits {"roles": …, "_resolved": true} for a multi-role result.

Upgrade note — anyone who wrote such a fence speculatively starts denying on upgrade, and the policy's compiled source_hash moves with it. Documented in docs/policy/constraints.mdx, alongside the note #155 wrote for the flat shape.

Found by a code review of #155 (already merged), then reproduced before being fixed.

2. feat(collector) — revocation max_staleness 2m → 1h, both knobs env-tunable

2m sat under the length of routine control-plane maintenance (minor-version upgrade, volume resize, slow restart), so a Postgres blip meant total ingest rejection — silently, because the deploy healthcheck is a TCP-connect probe that stays green while every request 401s, and refused spans never reach the Redpanda buffer that exists to absorb this.

• poll_interval stays 20s, so steady-state revocation latency is unchanged. The widened window applies only while refreshes are failing.
• Both knobs override via HEXGATE_COLLECTOR_REVOCATION_POLL_INTERVAL / _MAX_STALENESS, per stage, no image rebuild.
• The env default applies only when a variable is unset, so the deploy stack passes them with non-empty fallbacks: a blank value arrives as 0s and the collector refuses to boot (verified against the built binary).

collector-check gained an accepted and a refused override case. The refusal is the load-bearing one — it can only fail if the env values actually reached the config struct, so a typo in either variable name fails the build instead of shipping a dead override.

Testing

make check-all green: SDK 2570 passed, platform-api 638, dashboard 218, collector ok plus the three validate cases. The platform-api run matters here specifically — it compiles signed bundles through the same policy loader, so the new strict rejection could have broken bundle compilation. It didn't.

Not in scope

Three further findings from the same review of #155, none addressed here:

• a named-export import (caps.yaml#export) drops the imported file's own top-level boundary: while a whole-file import of that same file raises — same fail-open class, reproduced;
• agent.run admission is audited outside run_scope on the LangChain / LangGraph / OpenAI paths but inside it on Google, so the row admitting a run has no run_id to join on;
• the CLI's constraint localization doesn't reach the file-level block, so a malformed expression there reports as a schema error rather than default → <policy>.

[codecov]

Codecov Report

❌ Patch coverage is 87.50000% with 5 lines in your changes missing coverage. Please review.

Files with missing lines	Patch %	Lines
hexgate/security/policy_set.py	84.61%	2 Missing and 2 partials ⚠️
platform/api/hexgate_api/features/agents/router.py	92.30%	0 Missing and 1 partial ⚠️

📢 Thoughts on this report? Let us know!