EvoFirewall/docs/policy-rollouts.md

Policy snapshots and staged rollout

Migration 017_policy_snapshots.sql adds immutable compiled effective-policy snapshots, rollouts, materialized targets and per-agent pins. These are control-plane desired policies. Applied hashes and revisions still come exclusively from telemetry acknowledgements.

API

All paths below have the /api/v1 prefix. Snapshot/rollout routes require policies read/write permissions; pin release follows agents write permissions.

• POST /policies/snapshots {source_agent_id,name} captures a staging/source agent's effective compiled policy. It rejects pinned sources and active temporary overrides. Permanent overrides are included. Duplicate complete payloads return the existing snapshot and original metadata.
• GET /policies/snapshots?limit=20&offset=0 returns metadata only; maximum page size 50. GET /policies/snapshots/:id returns one payload. DELETE rejects referenced snapshots.
• POST /policies/snapshots/:id/diff {agent_ids} compares at most 100 unique targets, with counts, default/port-rule changes, generation preconditions, admission conflicts and at most 100 membership examples across the whole response.
• POST /policies/rollouts {snapshot_id,targets:[{agent_id,expected_generation}],canary_ids} validates every target, freezes each previous desired policy, then activates only canaries in one transaction. Canary IDs must be a nonempty subset of targets. Unselected agents retain their previous behavior.
• GET /policies/rollouts lists bounded metadata; GET /policies/rollouts/:id includes at most 100 target states and current acknowledgement evidence.
• POST /policies/rollouts/:id/confirm {expected_version} requires fresh successful exact hash/revision acknowledgements from every canary received strictly after activation. The freshness window is three sync intervals, minimum 180 seconds, maximum one hour. Failures and changed pending generations block confirmation. All remaining pins publish atomically.
• POST /policies/rollouts/:id/rollback {expected_version} restores still-owned activated targets' captured previous desired policies at new, higher revisions. Pending and manually released targets remain unchanged. Even when every activated target was already released, rollback terminates the rollout and permits history cleanup. The rollback result is not an applied-success claim. Rollback pins stay active until explicitly released.
• POST /agents/:id/policy-pin/release {rollout_id,expected_generation} validates and recompiles the current live policy before removing the pin; invalid/unsupported live policies retain the pin transactionally. Release can abandon a canary; subsequent confirmation fails, while rollback preserves the manual release and terminates the remaining rollout safely.
• DELETE /policies/rollouts/:id removes terminal history only after every pin is released. This lets operators subsequently delete unreferenced snapshots and reclaim capacity.

Safety and bounds

Every rollout validates all targets' temporary overrides, approval status, telemetry-v2 support and reported policy capabilities. RouterOS Port ACL, missing IPv6 support and legacy/unknown capabilities reject admission. A rollout freezes full effective source policy; target-specific permanent overrides are replaced, and the diff exposes that replacement.

While pinned, direct default-action, override, port-rule, set-assignment and clone mutations return 409 POLICY_PINNED. Shared source/list/DNS edits can proceed, but their generation bumps skip pinned agents. Pin reads use the existing bounded policy cache; source witnesses for explain derive decisions from the frozen memberships and explicitly mark original attribution unavailable.

Snapshots have an 8 MiB payload limit, a global 256 MiB stored-payload byte limit, and a 200-row limit. Capacity sums actual UTF-8 payload bytes in SQL. Content deduplication includes frozen explanatory metadata. Rollouts have at most 100 targets, 20 active canary rollouts and 200 retained history rows. Capacity/admission failures roll back previous-snapshot capture and every pin. Rollout lists and target hashes do not load payload JSON.

Captured previous desired snapshots, prior delivered metadata and prior reported applied metadata are distinct fields. Pin changes update desired hash/revision and clear the delivery timestamp; only a subsequent policy delivery marks delivery, and only telemetry changes applied state. Mutation CAS checks and state changes share SQLite transactions.

Observed validation

Service/HTTP lifecycle tests cover source mutation after capture, canary isolation, TTL rejection for source and all target baselines, unsupported targets, exact/fresh/revision/error ACK gates, pending-target CAS conflict, monotonic rollback, explicit release failure preservation, global-capacity admission, bounded diff examples, source explain after pinning and endpoint schema/pin-conflict handling. Windows tests do not establish real Linux/RouterOS apply behavior or production-volume readiness.