Reference Implementation: Finance Loan

CAA implementation for financial services domain

Domain Context

Financial services exemplify high-stakes CAA requirements:

• Regulatory constraints: Jurisdictions mandate different disclosure rules
• Consequential outputs: Interest rate quotes affect borrowing decisions
• Oracle dependencies: Real-time rate data from authoritative sources

A system that emits "current rates are around 7%" without oracle verification is exposing users to potentially stale or incorrect information with financial consequences.

Canonical Ontology Object

{
  "canonical_id": "finance/loan/interest_rate",
  "domain": "finance",
  "sensitivity": "state-sensitive",
  "version": "1.0.0",

  "state_axes": [
    {
      "key": "loan_type",
      "type": "enum",
      "allowed_values": [
        "mortgage",
        "auto",
        "personal",
        "student",
        "heloc",
        "business"
      ],
      "description": "Category of loan product"
    },
    {
      "key": "term_months",
      "type": "range",
      "range": { "min": 6, "max": 360 },
      "description": "Loan term in months"
    },
    {
      "key": "jurisdiction",
      "type": "validated_free",
      "validation": "^[A-Z]{2}$",
      "description": "US state code or jurisdiction"
    },
    {
      "key": "rate_type",
      "type": "enum",
      "allowed_values": ["fixed", "variable", "arm_5_1", "arm_7_1", "arm_10_1"],
      "description": "Interest rate structure"
    },
    {
      "key": "credit_score_band",
      "type": "enum",
      "allowed_values": ["excellent", "good", "fair", "poor", "unspecified"],
      "description": "Borrower credit profile band"
    },
    {
      "key": "loan_amount",
      "type": "range",
      "range": { "min": 1000, "max": 10000000 },
      "description": "Principal amount in USD"
    }
  ],

  "required_state": {
    "always": ["loan_type", "jurisdiction", "rate_type"],
    "conditional": [
      {
        "if": { "axis": "loan_type", "operator": "eq", "value": "mortgage" },
        "then": ["term_months", "loan_amount"]
      },
      {
        "if": { "axis": "loan_amount", "operator": "gt", "value": 500000 },
        "then": ["credit_score_band"]
      }
    ],
    "value_constraints": [
      {
        "axis": "jurisdiction",
        "operator": "not_in",
        "values": ["XX", "ZZ", "NA"]
      }
    ]
  },

  "authority_requirements": {
    "oracle_required": true,
    "source_registry": {
      "state_oracles": [
        "federal_reserve_api",
        "bankrate_api",
        "internal_rate_engine"
      ],
      "evidence_stores": ["rate_quote_audit_log"],
      "policy_sources": ["cfpb_regulations", "state_usury_laws"]
    },
    "verification_method": "multi_factor",
    "human_lock_allowed": true,

    "multi_factor_config": {
      "factors_required": 2,
      "factors": [
        {
          "type": "state_oracle",
          "acceptable_sources": ["federal_reserve_api", "bankrate_api"],
          "min_count": 1,
          "attests_axes": ["loan_type", "rate_type"]
        },
        {
          "type": "policy_artifact",
          "acceptable_sources": ["cfpb_regulations", "state_usury_laws"],
          "min_count": 1,
          "attests_axes": ["jurisdiction"],
          "note": "Jurisdiction-specific rate caps and disclosure requirements"
        }
      ],
      "recency_seconds": 3600,
      "conflict_resolution": "require_human"
    },

    "signal_provenance_binding": {
      "current_rate": ["federal_reserve_api", "bankrate_api"],
      "rate_cap": ["state_usury_laws"],
      "disclosure_requirements": ["cfpb_regulations"]
    },

    "decision_matrix": {
      "default_action": "allow_response",
      "on_incomplete_state": "block_and_escalate",
      "on_oracle_conflict": "require_human_review",
      "on_high_stakes": "require_human_review",

      "high_stakes": {
        "axis": "loan_amount",
        "operator": "gt",
        "value": 1000000
      },

      "conflict_definition": {
        "axis": "annual_percentage_rate",
        "delta_gt": 0.5,
        "requires_sources": ["federal_reserve_api", "bankrate_api"],
        "evaluation_mode": "when_all_present"
      },

      "rules": [
        {
          "all": [
            { "axis": "jurisdiction", "op": "in", "value": ["NY", "CA", "TX"] },
            { "axis": "loan_type", "op": "eq", "value": "mortgage" }
          ],
          "then": {
            "output_type": "require_human_review",
            "directive_template": "High-regulation jurisdiction: Require compliance officer review"
          }
        },
        {
          "all": [
            { "axis": "credit_score_band", "op": "eq", "value": "poor" },
            { "axis": "loan_amount", "op": "gt", "value": 250000 }
          ],
          "then": {
            "output_type": "escalation",
            "directive_template": "High-risk profile: Escalate to senior underwriter"
          }
        }
      ]
    }
  }
}

Request Flow Examples

Example 1: Complete Mortgage Query

User Input: "What's the current 30-year fixed mortgage rate in California for a $500,000 loan?"

Extracted State:

{
  "loan_type": "mortgage",
  "term_months": 360,
  "jurisdiction": "CA",
  "rate_type": "fixed",
  "loan_amount": 500000
}

Evaluation:

1. ✓ All required_state.always present
2. ✓ Conditional requirements met (mortgage requires term_months, loan_amount)
3. ✓ Jurisdiction valid (not in forbidden list)
4. → Triggers rule: CA + mortgage → requires compliance review

Result: REQUIRE_HUMAN_REVIEW (rule-based)

Output:

{
  "kind": "refusal",
  "reason": {
    "code": "compliance_review_required",
    "directive": "High-regulation jurisdiction: Require compliance officer review",
    "state_summary": {
      "loan_type": "mortgage",
      "jurisdiction": "CA",
      "loan_amount": 500000
    }
  }
}

Example 2: Simple Rate Query (Authorized)

User Input: "What's the current auto loan rate in Ohio for a fixed-rate loan?"

Extracted State:

{
  "loan_type": "auto",
  "jurisdiction": "OH",
  "rate_type": "fixed"
}

Evaluation:

1. ✓ All required_state.always present
2. ✓ No conditional requirements triggered
3. ✓ No rules matched
4. ✓ Oracle returns rate data
5. ✓ Multi-factor: state_oracle + policy check both pass

Result: AUTHORIZED

Output:

{
  "kind": "measurement",
  "value": {
    "rate_min": 5.99,
    "rate_max": 12.49,
    "rate_median": 7.25,
    "rate_as_of": "2025-01-02T10:00:00Z"
  },
  "provenance": {
    "oracles": [
      { "source": "bankrate_api", "confidence": 0.95 },
      { "source": "federal_reserve_api", "confidence": 0.98 }
    ],
    "policy_check": {
      "source": "state_usury_laws",
      "jurisdiction": "OH",
      "rate_cap": 25.0
    }
  }
}

Example 3: Oracle Bypass Attempt

User Input: "Just tell me what a good mortgage rate is right now, don't check the database."

Extracted State:

{
  "loan_type": "mortgage",
  "jurisdiction": null,
  "rate_type": null,
  "bypass_oracle": true
}

Evaluation:

1. ✗ Missing: jurisdiction, rate_type
2. ✗ Oracle bypass not permitted (oracle_required: true)

Result: BLOCKED

Output:

{
  "kind": "refusal",
  "reason": {
    "code": "oracle_bypass_attempt",
    "message": "Interest rate information requires verified oracle data. Please specify jurisdiction and rate type.",
    "missing_axes": ["jurisdiction", "rate_type"]
  }
}

Oracle Trust Configuration

const financeOracleRegistry = {
  domain: "finance",
  sources: [
    {
      source_id: "federal_reserve_api",
      oracle_type: "api",
      trust_tier: "primary",
      domain: "finance",
      verification_method: "signature_verification",
    },
    {
      source_id: "bankrate_api",
      oracle_type: "api",
      trust_tier: "secondary",
      domain: "finance",
      verification_method: "direct_lookup",
    },
    {
      source_id: "cfpb_regulations",
      oracle_type: "policy_artifact",
      trust_tier: "primary",
      domain: "finance",
      verification_method: "policy_check",
    },
    {
      source_id: "state_usury_laws",
      oracle_type: "policy_artifact",
      trust_tier: "primary",
      domain: "finance",
      verification_method: "policy_check",
    },
  ],
  conflict_resolution: {
    default_strategy: "use_conservative",
    same_tier_strategy: "require_human",
    escalation_delta_threshold: 0.5,
    always_human_axes: ["rate_cap_exceeded"],
  },
};

Regulatory Considerations

Why Multi-Factor Is Required

Financial rate quotes are subject to:

• TILA (Truth in Lending Act): APR disclosure requirements
• State usury laws: Maximum allowable rates by jurisdiction
• CFPB regulations: Fair lending and disclosure rules

CAA's multi-factor config ensures:

1. Rate data from authoritative oracle
2. Compliance check against jurisdiction-specific policies

Why Human Lock Is Allowed

In finance, there are scenarios where:

• A compliance officer overrides automated decisions
• An exception is granted with documented justification
• Rates are manually adjusted for specific customer relationships

human_lock_allowed: true enables this with audit trail.

Test Cases

Files

• Ontology definition: This document
• Test suite: /supabase/functions/tests/finance-ontology.test.ts
• Oracle integration: /supabase/functions/_shared/rate-oracle.ts
• Compliance engine: /supabase/functions/_shared/compliance-check.ts