✅ Governance

Invariant enforcement for cognitive workflows.

Overview

The Validator/Governor ensures all agent contributions conform to semantic contracts before committing state updates.

Validation Pipeline

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37

┌─────────────────────────────────────────────────────────────┐
│ Aggregated Deltas from Specialists                           │
└──────────────┬──────────────────────────────────────────────┘
               │
               ▼
┌─────────────────────────────────────────────────────────────┐
│ Schema Validation                                            │
│ • All outputs match declared JSON schemas                    │
└──────────────┬──────────────────────────────────────────────┘
               │
               ▼
┌─────────────────────────────────────────────────────────────┐
│ Identity Invariants                                          │
│ • ConceptIds remain stable                                   │
│ • No identity drift                                          │
└──────────────┬──────────────────────────────────────────────┘
               │
               ▼
┌─────────────────────────────────────────────────────────────┐
│ Policy Limits                                                │
│ • SBVR business rules                                        │
│ • CALM architecture boundaries                               │
└──────────────┬──────────────────────────────────────────────┘
               │
               ▼
┌─────────────────────────────────────────────────────────────┐
│ State Bounds                                                 │
│ • Size limits                                                │
│ • Token budgets                                              │
└──────────────┬──────────────────────────────────────────────┘
               │
     ┌─────────┴─────────┐
     ▼                   ▼
┌─────────┐         ┌─────────┐
│  PASS   │         │  BLOCK  │
│ Commit  │         │ Reject  │
└─────────┘         └─────────┘

Validation Checks

Schema Conformance

1
2
3
4

checks:
  - type: "schema"
    description: "All outputs match declared shapes"
    action: "block"

ConceptId Persistence

1
2
3
4

checks:
  - type: "concept-id-persistence"
    description: "Identity invariants maintained"
    action: "block"

SBVR Rules

1
2
3
4

checks:
  - type: "sbvr-rules"
    description: "Business rules satisfied"
    action: "warn"  # or "block"

CALM Boundaries

1
2
3
4

checks:
  - type: "calm-boundaries"
    description: "Architecture constraints"
    action: "block"

State Size

1
2
3
4

checks:
  - type: "state-size"
    maxBytes: 50000
    action: "clip"

Violation Actions

Action Description When to Use
pass Commit update All checks pass
clip Remove invalid portion, commit rest Recoverable violations
block Reject entire update Critical violations
warn Log warning, commit anyway Non-critical issues

Configuration

1
2
3
4
5
6
7
8
9
10
11
12
13
14

validator:
  checks:
    - type: "schema"
    - type: "concept-id-persistence"
    - type: "sbvr-rules"
    - type: "calm-boundaries"
    - type: "state-size"
      maxBytes: 50000
  
  onViolation: "block-and-emit"
  
  events:
    violationTopic: "cognitive.violations"
    auditTopic: "cognitive.audit"

Violation Events

When violations occur, events are emitted:

1
2
3
4
5
6
7
8
9
10

{
  "eventType": "CognitiveViolation",
  "workflowId": "wf-123",
  "round": 3,
  "agentId": "custom-agent",
  "checkType": "schema",
  "message": "Output missing required field 'confidence'",
  "severity": "error",
  "timestamp": "2026-01-05T12:00:00Z"
}

Human-in-the-Loop Escalation

For high-risk decisions:

1
2
3
4
5
6
7
8
9

escalation:
  triggers:
    - checkType: "calm-boundaries"
      severity: "critical"
    - agentId: "high-risk-agent"
  
  handler: "hitl-approval"
  timeout: "5m"
  fallback: "block"

See: SDS-031: Authority & Ownership Boundaries

Audit Trail

All governance decisions are logged:

1
2
3
4
5
6
7
8
9
10
11
12

{
  "workflowId": "wf-123",
  "round": 3,
  "checksRun": ["schema", "concept-id", "sbvr"],
  "results": [
    { "check": "schema", "passed": true },
    { "check": "concept-id", "passed": true },
    { "check": "sbvr", "passed": false, "violations": [...] }
  ],
  "decision": "block",
  "timestamp": "2026-01-05T12:00:00Z"
}