Minimal CAA Implementation Guide

For teams who want CAA benefits without full ontology commitment

Overview

This guide defines the smallest useful subset of the Claim Authorization Architecture (CAA) for teams who want to adopt incrementally.

The minimal CAA profile provides:

• Authority boundary protection
• Oracle verification
• Basic conflict handling

Without requiring:

• Full ontology modeling
• Multi-factor verification
• Advanced decision matrices

Minimal Adoption Profile

Level 1: Authority Boundary Only

What you get: Protection against unauthorized authoritative claims.

What you implement:

interface MinimalOntology {
  canonical_id: string; // "your_domain/entity_type"
  sensitivity: "state-sensitive";
  required_state: {
    always: string[]; // At least 1 required axis
  };
  authority_requirements: {
    oracle_required: true;
    verification_method: "direct_lookup";
    decision_matrix: {
      default_action: "block_and_escalate";
      on_incomplete_state: "require_human_review";
    };
  };
}

Behavior:

• Requests without required state → REQUIRES_SPECIFICATION
• Requests with required state → Authorized (if oracle validates)
• No oracle available → BLOCKED

Example: Basic product availability check

{
  "canonical_id": "retail/product_availability",
  "sensitivity": "state-sensitive",
  "required_state": {
    "always": ["product_id", "location"]
  },
  "authority_requirements": {
    "oracle_required": true,
    "source_registry": {
      "state_oracles": ["inventory_database"]
    },
    "verification_method": "direct_lookup",
    "decision_matrix": {
      "default_action": "allow_response",
      "on_incomplete_state": "block_and_escalate"
    }
  }
}

Level 2: Add Required State Logic

What you add: Conditional requirements based on context.

interface Level2Ontology extends MinimalOntology {
  required_state: {
    always: string[];
    conditional?: Array<{
      if: { axis: string; operator: "eq" | "in"; value: string | string[] };
      then: string[];
    }>;
  };
}

Example: Product pricing with jurisdiction requirements

{
  "canonical_id": "retail/product_price",
  "sensitivity": "state-sensitive",
  "required_state": {
    "always": ["product_id"],
    "conditional": [
      {
        "if": {
          "axis": "product_type",
          "operator": "in",
          "value": ["alcohol", "tobacco"]
        },
        "then": ["jurisdiction", "customer_age_verified"]
      }
    ]
  }
}

Level 3: Add Decision Rules

What you add: Explicit routing based on state values.

interface Level3Ontology extends Level2Ontology {
  authority_requirements: {
    decision_matrix: {
      rules?: Array<{
        all?: Array<{ axis: string; op: string; value: unknown }>;
        then: { output_type: string; directive_template: string };
      }>;
    };
  };
}

Example: Customer support triage

{
  "canonical_id": "support/ticket_priority",
  "required_state": {
    "always": ["customer_tier", "issue_type"]
  },
  "authority_requirements": {
    "decision_matrix": {
      "rules": [
        {
          "all": [
            { "axis": "customer_tier", "op": "eq", "value": "enterprise" },
            {
              "axis": "issue_type",
              "op": "in",
              "value": ["outage", "security"]
            }
          ],
          "then": {
            "output_type": "escalation",
            "directive_template": "Immediate escalation to on-call"
          }
        }
      ],
      "default_action": "allow_response",
      "on_incomplete_state": "require_human_review"
    }
  }
}

Progressive Enhancement Path

Level 1 (Week 1)        Level 2 (Week 2-4)       Level 3 (Month 2)        Full CAA
┌─────────────────┐    ┌─────────────────────┐   ┌────────────────────┐   ┌─────────────────┐
│ Authority       │    │ + Conditional       │   │ + Decision Rules   │   │ + Multi-factor  │
│ Boundary        │ => │   Requirements      │ =>│ + High Stakes      │ =>│ + Oracle Trust  │
│                 │    │                     │   │ + Conflict Defs    │   │ + Evidence      │
└─────────────────┘    └─────────────────────┘   └────────────────────┘   └─────────────────┘

What You Skip at Minimal Level

When to Graduate to Full CAA

Upgrade when you encounter:

1. Oracle conflicts: Multiple data sources disagree
2. High-stakes decisions: Errors have legal/financial consequences
3. Audit requirements: Need provenance and evidence binding
4. Safety-critical operations: Medical, financial, legal domains

Implementation Checklist

Level 1 Checklist

• Define canonical_id for your entity type
• Identify minimum required state axes
• Configure oracle source (database, API)
• Set decision_matrix.default_action
• Test with missing state → expect REQUIRES_SPECIFICATION
• Test with complete state → expect AUTHORIZED

Level 2 Checklist

• Identify context-dependent requirements
• Add conditional rules
• Test conditional triggers
• Document requirement logic

Level 3 Checklist

• Define explicit routing rules
• Add high-stakes thresholds if applicable
• Configure conflict definitions
• Test rule precedence
• Document decision matrix logic

Example: Minimal E-commerce CAA

{
  "canonical_id": "ecommerce/order_status",
  "sensitivity": "state-sensitive",
  "state_axes": [
    { "key": "order_id", "type": "identifier" },
    { "key": "customer_id", "type": "identifier" }
  ],
  "required_state": {
    "always": ["order_id", "customer_id"]
  },
  "authority_requirements": {
    "oracle_required": true,
    "source_registry": {
      "state_oracles": ["order_database"]
    },
    "verification_method": "direct_lookup",
    "decision_matrix": {
      "default_action": "allow_response",
      "on_incomplete_state": "require_human_review",
      "on_oracle_conflict": "require_human_review"
    }
  }
}

Behavior:

• "What's the status of my order?" without order_id → REQUIRES_SPECIFICATION
• "What's the status of order 12345?" → Query oracle, return status
• Order not found in oracle → BLOCKED (oracle returned no match)

Support

For questions about CAA adoption:

• RFC Specification: /docs/spec/rfc.md
• Full examples: /docs/platform/reference-implementations/
• Test suite: /supabase/functions/tests/