Ref-022: OPA Policy Migration Guide

Purpose

This guide defines how to update and roll out OPA policy changes safely in the SEA-Forge runtime.

Policy Versioning

• Each policy file must include a header: # Policy Version: X.Y.Z.
• Increment the version when policy logic changes.
• Store the active version in the PolicyConfig entity as policyVersion.

Rollout Steps

1. Update policy files in infra/opa/policies/ and bump the version header.
2. Run policy tests:
   • just opa-test
3. Validate integration:
   • just ai-stack-up
   • AI_STACK_INTEGRATION=1 just ai-stack-test
4. Deploy:
   • Roll out OPA bundle changes
   • Confirm Policy Gateway reports the new policyVersion

Backward Compatibility

• Avoid removing policy rules without a deprecation window.
• When renaming a rule, keep a compatibility alias for at least one release.

Audit Requirements

• Record the deployed policyVersion in change logs or deployment notes.
• Keep policy test results for audit review.