RFC-010: AIGP Runtime Governance Protocol — 5. Governance Modes

AIGP Specification › RFC-010: AIGP Runtime Governance Protocol › 5. Governance Modes

← 4A. Cryptographic Algorithm Agility · Section index · 5A. Enforceable Surface Area →

5. Governance Modes

Mode	Behavior	Use Case
REPORT	Log all invocations, allow all	Development, initial rollout
REPORT-TRACE	Log all invocations with stage-level trace spans	Performance analysis, security optimization, observability
ENFORCE	Check policies, block violations, apply provider controls	Production governance

5.1 REPORT Mode

In REPORT mode, AIGP logs every invocation but does not block. All REQUEST checks return ALLOW. RECORD messages are still sent. This mode is intended for onboarding, shadow testing, and development environments.

If no decision is obtained (authority unreachable, non-2xx, missing decision or unparseable response), the application proceeds and the client records the result as UNCHECKED. The client MUST NOT report or cache it as ALLOW.

5.2 ENFORCE Mode

In ENFORCE mode, AIGP actively enforces policies at two layers:

Protocol Layer The governance authority evaluates REQUEST messages against configured policies and returns ALLOW, ALLOW_WITH_CONSTRAINTS, or DENY.
Provider Layer The governance authority configures the cloud provider’s native controls to enforce guardrails, model access, quotas, and content policies directly at the service level.

If no decision is obtained in ENFORCE mode — the governance authority is unreachable, or returns a non-2xx, missing decision or unparseable response — the application MUST block the invocation (fail-closed). A RATE_LIMITED decision also blocks.

5.3 REPORT-TRACE Mode

REPORT-TRACE extends REPORT mode with stage-level distributed tracing. In this mode, the application emits trace spans for each governance stage traversed during an AI invocation. The governance authority collects these spans to provide end-to-end performance analysis, security optimization insights, and latency attribution across the 17 governance stages.

Like REPORT mode, REPORT-TRACE does not block invocations. All REQUEST checks return ALLOW. The additional trace payload is sent alongside or within RECORD messages.

5.3.1 Trace Message

POST /api/v1/trace
Headers:
  X-AIGP-Signature: hmac-sha256={signature}
  X-AIGP-Timestamp: {iso_timestamp}
  X-AIGP-App-Id: {app_id}
  Content-Type: application/json

Body:
{
  "protocol_version": "2.0",
  "message_type": "TRACE",
  "app_id": "my-app",
  "trace_id": "trc-a1b2c3d4e5f6",
  "request_id": "req-1714500000000",
  "use_case": "policy_review",
  "model_id": "us.anthropic.claude-sonnet-4-5-20250929-v1:0",
  "user_id": "[email protected]",
  "timestamp": "2026-05-12T12:00:00Z",
  "spans": [
    {
      "stage": 1,
      "stage_name": "identity_session_initiation",
      "start_time": "2026-05-12T12:00:00.000Z",
      "end_time": "2026-05-12T12:00:00.012Z",
      "duration_ms": 12,
      "status": "OK",
      "attributes": {
        "session_id": "sess-abc123",
        "auth_method": "oidc"
      }
    },
    {
      "stage": 4,
      "stage_name": "prompt_submission",
      "start_time": "2026-05-12T12:00:00.012Z",
      "end_time": "2026-05-12T12:00:00.015Z",
      "duration_ms": 3,
      "status": "OK",
      "attributes": {
        "prompt_source": "managed",
        "prompt_arn": "arn:aws:bedrock:us-east-1:123456789:prompt/XYZ"
      }
    },
    {
      "stage": 6,
      "stage_name": "context_authorization",
      "start_time": "2026-05-12T12:00:00.015Z",
      "end_time": "2026-05-12T12:00:00.045Z",
      "duration_ms": 30,
      "status": "OK",
      "attributes": {
        "kb_id": "kb-prod-001",
        "documents_retrieved": 5
      }
    },
    {
      "stage": 9,
      "stage_name": "runtime_invocation",
      "start_time": "2026-05-12T12:00:00.045Z",
      "end_time": "2026-05-12T12:00:03.245Z",
      "duration_ms": 3200,
      "status": "OK",
      "attributes": {
        "input_tokens": 1850,
        "output_tokens": 620,
        "model_latency_ms": 3100
      }
    },
    {
      "stage": 14,
      "stage_name": "post_invocation_record",
      "start_time": "2026-05-12T12:00:03.245Z",
      "end_time": "2026-05-12T12:00:03.260Z",
      "duration_ms": 15,
      "status": "OK",
      "attributes": {}
    }
  ],
  "summary": {
    "total_duration_ms": 3260,
    "stages_traversed": 5,
    "stages_skipped": 12,
    "slowest_stage": 9,
    "error_stages": []
  }
}

5.3.2 Trace Span Schema

Each span in the spans array MUST contain:

Field	Type	Required	Description
`stage`	integer	YES	Stage number (1–17) per AIGP Governance Stages
`stage_name`	string	YES	Machine-readable stage identifier
`start_time`	ISO 8601	YES	Span start (millisecond precision)
`end_time`	ISO 8601	YES	Span end (millisecond precision)
`duration_ms`	integer	YES	Computed duration in milliseconds
`status`	string	YES	`OK`, `ERROR`, `SKIPPED`, `TIMEOUT`
`attributes`	object	NO	Stage-specific key-value metadata
`error`	object	NO	Present when status is `ERROR` — contains `code` and `message`
`parent_span`	string	NO	For nested spans (e.g., multi-step agent reasoning)

5.3.3 Stage Name Registry

Stage	`stage_name` value
1	`identity_session_initiation`
2	`consent_policy_determination`
3	`request_registration`
4	`prompt_submission`
5	`prompt_assembly`
6	`context_authorization`
7	`context_retrieval`
8	`model_selection`
9	`runtime_invocation`
10	`tool_agent_authorization`
11	`intermediate_reasoning`
12	`output_generation`
13	`output_release`
14	`post_invocation_record`
15	`persistence_memory`
16	`observation_audit`
17	`reflection_optimization`

5.3.4 Summary Object

The summary object provides pre-computed analytics:

Field	Type	Description
`total_duration_ms`	integer	End-to-end latency across all spans
`stages_traversed`	integer	Number of stages with spans
`stages_skipped`	integer	Stages not traversed (17 − traversed)
`slowest_stage`	integer	Stage number with highest duration_ms
`error_stages`	array[int]	Stage numbers where status was ERROR

5.3.5 Governance Authority Behavior

When operating in REPORT-TRACE mode, the governance authority:

Accepts TRACE messages and stores spans indexed by trace_id
Computes per-stage latency percentiles (p50, p95, p99) across applications
Identifies security-sensitive stages with anomalous durations (potential exfiltration, injection)
Generates optimization recommendations (e.g., “Stage 7 context retrieval averages 450ms — consider caching”)
Correlates trace data with RECORD telemetry for cost-per-stage attribution

5.3.6 Inline Trace (Alternative)

Applications MAY embed trace spans directly in RECORD messages instead of sending a separate TRACE message. This is useful for simpler integrations:

{
  "protocol_version": "2.0",
  "message_type": "RECORD",
  "app_id": "my-app",
  "request_id": "req-1714500000000",
  "use_case": "chat_support",
  "trace": {
    "trace_id": "trc-a1b2c3d4e5f6",
    "spans": [ ... ]
  }
}

5.4 AIGP Context

{
  "mode": "ENFORCE",
  "region": "US",
  "provider": "aws",
  "consent_required": true,
  "allowed_models": [
    "us.anthropic.claude-opus-4-7",
    "us.anthropic.claude-sonnet-4-5-20250929-v1:0"
  ]
}

5.5 Mode Behavior

class AigpContext:
    mode: str = "REPORT"        # REPORT | REPORT-TRACE | ENFORCE
    provider: str = "aws"       # aws | azure | gcp
    region: str = "US"
    consent_required: bool = True
    allowed_models: list[str] = []

    def check_model(self, model_id: str) -> tuple[bool, str]:
        if not self.allowed_models:
            return True, ""
        if model_id in self.allowed_models:
            return True, ""
        if self.mode == "ENFORCE":
            return False, f"Model {model_id} not in allowed list"
        return True, f"REPORT: Model {model_id} not in allowed list (logged)"

← 4A. Cryptographic Algorithm Agility · Section index · 5A. Enforceable Surface Area →