Guardrails Contract Patterns

Guide for implementing validation contracts that enforce data quality, risk limits, and compliance.

When to Use

Apply when:

• Adding validation rules for domain resources
• Implementing signal bounds, dataset schema checks
• Creating portfolio constraints (weights, leverage)
• Enforcing PIT correctness on datasets
• Building custom validators
• Embedding contracts in Definition resources

Law vs Police Architecture

┌────────────────────────────────────────────────────────────┐
│           DEFINITION RESOURCE (The Law)                     │
│  ├── interface_spec        # Abstract interface             │
│  ├── input_schema          # Expected inputs                │
│  ├── output_schema         # Expected outputs               │
│  ├── compatibility_rules   # Connection rules               │
│  └── guardrail_contracts   # Validation rules               │
│      ├── signal.bounds: {min: -1, max: 1}                  │
│      ├── pit.policy: {knowledge_date_required: true}       │
│      └── dataset.schema: {columns: [...]}                  │
└────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌────────────────────────────────────────────────────────────┐
│           GUARDRAILS ENGINE (The Police)                    │
│  Reads contracts FROM Definitions, enforces at gates:       │
│  ├── Gate 1: Instance Creation (validate config)           │
│  ├── Gate 2: Run Execution (validate inputs)               │
│  ├── Gate 3: Data Write (validate outputs in real-time)    │
│  └── Gate 4: Promotion/Merge (all must pass)               │
└────────────────────────────────────────────────────────────┘

Key Insight: Contracts live IN Definition resources. The Guardrails Engine reads and enforces them—no manual attachment needed.

Core Concepts

ContractRef: Identifies contract kind + JSON schema ContractInstance: Bound contract with config + enforcement hint ContractBundle: Collection of contracts for a resource ValidationReport: Results with issues, enforcement decision

Implementation Workflow

1. Define Contract Kind

Use namespaced naming: <domain>.<aspect>

signal.bounds       # Value range [-1, 1]
signal.schema       # Arrow schema conformance
dataset.pit         # Point-in-time correctness
dataset.freshness   # Data staleness SLA
portfolio.weights   # Sum-to-one, min/max weight
portfolio.leverage  # Gross/net exposure limits

2. Create JSON Schema

Location: optaic/guardrails/contracts/<domain>.py

See references/contract-schemas.md.

3. Implement Validator

Location: optaic/guardrails/validators/<domain>.py

Validators must be pure and deterministic. See references/validators.md.

4. Register Contract

ContractRegistry.register(
    kind="signal.bounds",
    schema=SIGNAL_BOUNDS_SCHEMA,
    validator=SignalBoundsValidator,
    version="1.0"
)

5. Write Tests

Test cases:

• Valid config + valid data → Pass
• Invalid config → Schema validation fail
• Valid config + invalid data → Business validation fail

Enforcement Policy

# official subspace → BLOCK on errors
# staging subspace → WARN on errors (unless elevated)

if subspace == "official":
    return EnforcementLevel.BLOCK
return EnforcementLevel.WARN

Lifecycle Gates

Guardrails validate at:

• resource.create / resource.update
• promotion.request / promotion.merge
• run.submit / run.start

Reference Files

• Contract Schemas - JSON schema patterns
• Validators - Validator implementation
• Quant Contracts - Domain-specific examples