ADR-031: GovernedSpeed™ Integration Strategy

Status: Proposed Version: 1.0 Date: 2025-12-27 Supersedes: ADR-005 (extends implementation details), ADR-028 (GovernedSpeed™ LLMOps) Related ADRs: ADR-030 (VibesPro™ Integration), ADR-012 (Delivery Pipeline) Related PRDs: PRD-010, PRD-004 Related SDSs: SDS-047 (Unified Governance Runtime), SDS-046, SDS-002 (GovernedSpeed™)

Context

SEA-Forge™ requires a “Continuous Governance” substrate to enforce policies at runtime and build time. We previously identified GovernedSpeed™ as the pillar for this (ADR-028), but we need to formally define how its specific architecture (Policy Gateway, Risk & Evidence Service, YAML policies) integrates with SEA™’s semantic core.

GovernedSpeed™ is an existing, functional “Operating System for Trustworthy AI” in the SEA™ root, featuring:

1. Policy Gateway: Sidecar for runtime enforcement (FastAPI).
2. Risk & Evidence Service: Tamper-proof logging (PostgreSQL/libSQL).
3. Embedded Governance: YAML-based policy definitions (adr-006).

Decision

We formally adopt GovernedSpeed™ as the runtime governance implementation for SEA-Forge™, with the following architectural commitments:

1. Unified Policy Definition (SEA-DSL → GovernedSpeed™ YAML)

We will use SEA-DSL as the authoring language for governance policies, which will be compiled into GovernedSpeed™’s YAML format for execution.

• Authoring: System.Governance.Policy entities in SEA-DSL.
• Compilation: SEA™ Compiler → adr-006.embedded-governance.yaml.
• Execution: Policy Gateway loads component-specific YAML configurations.

2. Runtime Enforcement via Policy Gateway

The GovernedSpeed™ Policy Gateway (apps/policy-gateway) becomes the canonical implementation of the SEA™ Policy Gateway Service (SDS-047).

• Role: Inference Sidecar / API Gateway Middleware.
• Mechanism: Intercepts POST /v1/chat/completions, runs decide_prompt/decide_output against loaded policies.
• Fail-Safe: Configured to “Fail-Closed” (Block if policy check fails or errors).

3. Evidence Ledger via Risk & Evidence Service

The GovernedSpeed™ Risk & Evidence Service (apps/risk-evidence-service) becomes the implementation of the SEA™ Risk & Evidence Service (SDS-047).

• Role: Audit Trail & Compliance Ledger.
• Schema: Adopts SDS-001 (GovernedSpeed™) for governance_event, risk_snapshot, incident.
• Storage: PostgreSQL (Production) / libSQL (Local/Edge).

4. CI/CD Governance Gates

We adopt GovernedSpeed™’s CI scripts (pac_ci.py) as the enforcement mechanism for SEA™ CI Semantic Gates (SDS-020).

• Pipeline Step: just gov-ci-check invoked during SEA™ delivery pipeline.
• Inputs: Artifacts JSON (evaluation results).
• Logic: Validates against thresholds defined in consolidated policy YAML.

Rationale

1. Separation of Concerns: SEA-DSL handles definition and semantics; GovernedSpeed™ handles enforcement and evidence.
2. Proven Runtime: Policy Gateway is already an implemented FastAPI service with specific logic for LLM caching, filtering, and sidecar patterns.
3. Audit Readiness: Risk & Evidence Service already implements tamper-evident hashing and immutable logs, a strict requirement for SEA™.
4. Isomorphism: Using SEA-DSL as the source maintains the “Semantics as Source of Truth” principle, while compiling to YAML allows utilizing GovernedSpeed™’s existing, optimized runtime.

Constraints

MUST

• MUST NOT manually edit adr-006.embedded-governance.yaml in SEA™ projects; it is a build artifact.
• MUST ensure Policy Gateway is running for any AI-Agent/LLM interaction in SEA™.
• MUST use Risk & Evidence Service schemas (SDS-001) for all audit logging.

SHOULD

• SHOULD co-locate Policy Gateway as a sidecar to the primary application in Kubernetes deployments to minimize latency.

Consequences

Positive

• Immediate runtime governance capability for SEA™ projects.
• Tamper-proof audit trails out-of-the-box.
• Unified policy language (SEA-DSL) with optimized runtime execution.

Negative

• Introduction of a compilation step for policies (SEA-DSL -> YAML).
• Dependency on GovernedSpeed™ release cycle.

Implementation Plan

1. Map SEA-DSL Policies to YAML: Create a compiler plugin in tools/sea-compiler.
2. Integrate Gateway: Add apps/policy-gateway to SEA™’s just start-all.
3. Connect Evidence: Configure SEA™ services to emit events to Risk & Evidence Service.