SDS-046: GovernedSpeed™ Integration Service

Document Type

Software Design Specification (SDS)

Status

Proposed

Implements

• ADR-031: GovernedSpeed™ Integration Strategy
• PRD-021: GovernedSpeed™ Platform Integration

1. System Overview

This specification details the technical integration of GovernedSpeed™ services into the SEA-Forge™ runtime. It maps SEA-DSL Governance entities to GovernedSpeed™ configuration and defines the deployment topology for the Policy Gateway and Risk & Evidence Service.

2. Architecture Mapping

@namespace "system.sea.governance"
@version "1.0.0"

// ENTITIES: Map to GovernedSpeed™ implementations
Entity "PolicyGateway" in system.sea.governance
@rationale "Implemented by GovernedSpeed™ apps/policy-gateway"
@implementation "policy_gateway.application.services.PolicyDecisionService"

Entity "EvidenceLedger" in system.sea.governance
@rationale "Implemented by GovernedSpeed™ apps/risk-evidence-service"
@implementation "risk_evidence.domain.models.GovernanceEvent"

Entity "PolicyCompiler" in system.sea.governance
@rationale "Compiles SEA-DSL policies to GovernedSpeed™ YAML"
@implementation "tools/sea-compiler/plugins/gov_compiler.py"

// RESOURCES
Resource "GovernedSpeed™Config" in system.sea.governance
@rationale "The runtime configuration file (adr-006.yaml)"
@format "yaml"

// FLOWS
Flow "EnforceRequest" from "AI-Agent" to "PolicyGateway"
@rationale "Intercepts LLM requests for policy validation"
@cqrs { "kind": "command", "synchronous": true }

Flow "LogDecision" from "PolicyGateway" to "EvidenceLedger"
@rationale "Asynchronously logs decision evidence"
@cqrs { "kind": "event", "outbox": "required" }

Flow "CompilePolicy" from "SEACore" to "GovernedSpeed™Config"
@rationale "Transforms semantic policy definitions to runtime config"
@cqrs { "kind": "command" }

3. Component Integration

3.1 Policy Gateway (apps/policy-gateway)

Role: The primary enforcement point.

Configuration Mapping:

• Env PAC_CONFIG: Path to the compiled adr-006.embedded-governance.yaml.
• Env PAC_LLM_PROVIDER: litellm or http (default).

Deployment:

• Local: Runs via uvicorn on port 8081.
• Production: Deployed as a K8s sidecar to the application container.

Interface:

• POST /proxy/completion: OpenAI-compatible endpoint that wraps filter/prompt and filter/output checks.

3.2 Risk & Evidence Service (apps/risk-evidence-service)

Role: The immutable audit log.

Storage Backend:

• PostgreSQL: For centralized aggregation (Production).
• libSQL: For local journaling and edge deployment.

Schema (SDS-001):

• Uses governance_event, risk_snapshot, incident tables as defined in GovernedSpeed™ SDS-001.

3.3 Semantic Compiler Plugin (tools/sea-compiler)

Role: Translates human-authored SEA-DSL into machine-executable YAML.

Transformation Logic:

1. Input: SEA-DSL Policy entity.
2. Processing:
   • Extract thresholds (Quality, Fairness, Safety).
   • Extract rules (Conditionals, Actions).
   • Map roles to owners.
3. Output: adr-006.embedded-governance.yaml.

Example Mapping:

SEA-DSL:

Policy "NoPII" per Obligation priority 10
as: context.contains_pii == true implies action.block()

GovernedSpeed™ YAML:

1
2
3
4
rules:
  - id: "NoPII"
    when: "context.contains_pii == true"
    action: "block"

4. Operational Workflows

4.1 Development Workflow

1. Developer updates specs/governance.sea.
2. Runs just gov-compile -> Generates libs/governance/policies/active.yaml.
3. Runs just gov-start -> Starts Policy Gateway with new config.
4. Tests against localhost:8081.

4.2 CI/CD Gates

1. Pipeline runs just gov-ci-check.
2. Script loads active.yaml.
3. Evaluates test artifacts against thresholds.
4. Pass/Fail decision logs to Evidence Ledger.

5. Migration Guide

1. Reference Existing policies: Import current libs/governance/policies into SEA-DSL format.
2. Switch Runtime: Update AI-Agent clients to point to Policy Gateway URL instead of direct LLM URL.
3. Enable Logging: Configure Gateway to persist events to the Evidence Service.

6. Dependencies

• SDS-047: GovernedSpeed™ Governance Runtime — Unified specification for Policy Gateway and Risk & Evidence Service
• GovernedSpeed™ SDS-001 (Reference)

[!NOTE] SDS-047 (Policy Gateway) and SDS-047 (Risk & Evidence) have been superseded by the unified SDS-047.