Governance Epic

User Journey

The Governance bounded context provides policy-based access control and audit capabilities for the SEA platform. It enables declarative security policies using Open Policy Agent (OPA) and Rego, ensuring that all access to sensitive resources (including policies themselves) is evaluated against explicit rules, with default-deny semantics for fail-safe security. The context serves as the security and compliance enforcer, sitting between query services and data stores to enforce authorization at retrieval boundaries.

Jobs to be Done & EARS Requirements

Job: Evaluate Policy Access Request

User Story: As a policy administrator, I want all policy access to be governed by declarative rules, so that only authorized users can query sensitive governance policies.

EARS Requirement:

• While the system is operational, when an access request is received with user context (subject_id, roles, attributes), resource context (resource_id, type, owner, attributes), and action (read, write, delete), the governance context shall:
  1. Route the request to the OPA policy engine with Rego evaluation
  2. Return an AccessDecision containing:
     • decision: “allow” or “deny”
     • reason: Explanation of the policy evaluation result
     • policy_id: Which policy rule was evaluated
     • timestamp: When the decision was made
  3. Enforce DefaultDeny policy: Return “deny” if no explicit allow rule matches
  4. Enqueue an AuditEvent for compliance tracking (async, outside the decision path)
  5. Complete evaluation in <5ms (p95) for simple policy rules (decision path only)
  6. Return 403 Forbidden for unauthorized access attempts

Job: Record Access Decision

User Story: As a security/compliance officer, I want all policy decisions to be logged with full context, so that I can audit system access for compliance review.

EARS Requirement:

• While the system is operational, when a policy decision is made (allow or deny), the governance context shall:
  1. Create an AccessDecision entity with:
     • subject_id: Who requested access
     • resource_id: What resource was accessed
     • action: Action performed (read, write, delete)
     • decision: Allow or deny result
     • reason: Policy evaluation explanation
     • policy_id: Policy rule that was evaluated
     • timestamp: When the decision occurred
  2. Enforce AuditAllDecisions policy: Log 100% of decisions
  3. Store the audit record in tamper-evident storage
  4. Include IP address and actor_id for security forensics

Job: Query Audit Log

User Story: As a security/compliance officer, I want to retrieve audit logs for a specific time range, so that I can review access patterns and verify compliance.

EARS Requirement:

• While the system is operational, when a GetAuditLog query is received with date range (from_date, to_date), the governance context shall:
  1. Retrieve AuditEvent records within the specified time range
  2. Return events containing:
     • event_type: Type of event (policy_decision, access_attempt, etc.)
     • actor_id: Who performed the action
     • target_id: What was affected
     • details: Additional event data as JSON object
     • ip_address: Source IP for security auditing
     • occurred_at: When the event occurred
  3. Enforce access control on audit log queries (only authorized personnel)
  4. Return results with eventual consistency from primary database

Job: Reload Policy Rules

User Story: As a policy administrator, I want to update Rego policy files without restarting services, so that I can modify security rules in production without downtime.

EARS Requirement:

• While the system is operational, when Rego policy files are modified in the policies directory, the governance context shall:
  1. Detect file system changes to policy directory
  2. Validate new Rego syntax and semantics
  3. Reload policies into OPA engine
  4. Complete reload in <100ms
  5. Maintain service availability during reload (no restart required)
  6. Log policy version changes for audit trail

Job: Enforce Query Pipeline Policy Check

User Story: As the RAG orchestrator, I want to inject policy checks before memory/context data retrieval, so that unauthorized queries are blocked before accessing sensitive data.

EARS Requirement:

• While processing a query request, before accessing memory or context services, the governance context shall:
  1. Extract user and resource context from the query
  2. Call the PolicyEnginePort.evaluatePolicy() method
  3. Await allow/deny decision from OPA
  4. Block request with 403 if decision is “deny”
  5. Include decision transparency in query response metadata
  6. Emit OpenTelemetry metrics for decision latency and deny rate

Domain Entities Summary

Root Aggregates

• AccessDecision: Records the result of policy evaluations with full context
• PolicyRule: Stores declarative policy definitions in Rego format
• AuditEvent: Creates tamper-evident audit trails for compliance

Policy Rules

• DefaultDeny: All requests denied unless explicitly allowed (fail-safe)
• AuditAllDecisions: 100% of policy decisions must be logged

Integration Points

• Memory Context: Governance sits between Query and Memory services, performing policy checks before allowing data access
• Query Context: RAG orchestrator injects policy checks into query pipeline via PolicyEnginePort interface
• Ingest Context: Policies can be ingested and stored as documents with special access rules
• Cognitive Extension Context: Runtime AI governance extends policy patterns to prompt filtering and output validation

Non-Functional Requirements

• NFR-001.1: Fail-safe (default deny when uncertain)
• NFR-001.2: Auditable (structured logs, tamper-evident)
• NFR-001.3: Declarative (Rego policy-as-code, version control)
• NFR-001.4: Observable (emit decision metrics via OpenTelemetry)