CARI Methodology and Scoring Framework

The Community Association Risk Index (CARI) is a deterministic, consent-gated index that summarizes attested governance, financial, and operational risk signals for community associations. This article documents the scoring methodology, signal sources, access controls, and integrity guarantees that govern how CARI scores are produced and consumed.

CARI is not a credit score. It does not make eligibility or lending decisions. It summarizes observable conditions from an authoritative system of record and presents them as a structured, verifiable index. For an introduction to what CARI is and why it exists, see What Is a Community Association Risk Index?.

Scoring Architecture

Every CARI Score is a weighted composite of five component sub-scores. Each component is computed independently from system-of-record signals, then combined using published weights.

Component Weights

Weights are stored in a versioned ScoreMethodology record. Only one methodology version is ACTIVE at any time. When weights change, a new version is created and the previous version is marked DEPRECATED. Historical scores always reference the methodology version that was active at computation time.

Financial Health (30%)

The largest component. Derived from signals that are already computed and stored by the platform's accounting engine:

Sub-signal weights within this component: reserve adequacy (40%), delinquency rate (35%), operating ratio (25%).

Governance (25%)

Captures the quality of board oversight and governance processes:

Vendor Risk (15%)

Measures the compliance posture of the HOA's vendor ecosystem:

Enforcement Integrity (15%)

Derived from the platform's own enforcement telemetry. This component measures how well the HOA's financial controls are operating:

This component has a non-linear relationship: a 0% block rate may indicate controls are not active, while a very high rate may indicate operational dysfunction. The scoring function assigns the highest scores to the 1-10% range.

Payment Behavior (15%)

Captures the HOA's payment patterns and dispute history:

Grade Thresholds

CARI Scores are mapped to letter grades using published thresholds:

Grade thresholds are defined in the active ScoreMethodology record and versioned alongside weights.

Confidence and Data Completeness

Every CARI Score includes a confidence assessment that reflects how much source data was available at computation time.

Data completeness is calculated as signals_available / signals_total * 100, where signals_total is the count of all signals defined in the active methodology and signals_available is the count of signals that returned non-null values for the HOA being scored.

A LOW confidence score is still a valid score — it reflects what is observable. The confidence tier tells the consumer how much evidence supports the number.

Consent Architecture

CARI enforces a strict consent model. No score data is accessible to any third party without an active consent record from the HOA.

Consent Model

The HOA controls who can access its CARI data. Consent is granted by an authorized HOA representative and recorded as an OracleConsent record.

Three consent scopes exist:

Each consent record specifies: - Permissions: What actions are authorized (score:read, report:lender, report:title, monitor) - Expiration: Optional expiry date after which consent automatically lapses - Revocation: HOA can revoke consent at any time. Revocation is immediate and retroactive — no new queries are served

Consent Enforcement

Every API request that accesses HOA data passes through a consent check. The check verifies: 1. An active (non-expired, non-revoked) consent record exists for this HOA 2. The consent covers the requesting subscriber (by identity, type, or ALL) 3. The consent includes the required permission for the requested operation

If any check fails, the request is rejected with a 403 Forbidden response. The rejection is logged but no score data is included in the response.

API Authentication

Third-party access to CARI data uses API key authentication designed for machine-to-machine integration.

Key Lifecycle

1. Creation: A raw API key is generated using secrets.token_urlsafe(32) with the prefix oracle_key_. The full key is shown to the subscriber once at creation
2. Storage: Only the SHA-256 hash of the key is stored. The raw key cannot be recovered
3. Authentication: On each request, the key is hashed and compared against stored hashes. Lookup uses the 12-character prefix for efficiency, then verifies the full hash
4. Expiration: Keys can have optional expiration dates. Expired keys are rejected at authentication time
5. Revocation: Keys can be revoked with a documented reason. Revocation is immediate

Scoped Permissions

Each API key carries a set of scoped permissions:

A key without score:read cannot retrieve scores. A key without report:generate cannot request reports. Permissions are checked on every request after authentication.

Rate Limiting

Rate limits are tier-based:

Individual API keys can override the tier default with a custom daily limit. Rate limit state is tracked per-subscriber and enforced via middleware.

Webhook Security

Subscribers can register webhook endpoints to receive real-time notifications when monitored HOA scores change. Webhook payloads are signed for integrity verification.

Signing Scheme

Every webhook delivery includes two headers:

The HMAC-SHA256 signature is computed over the string {timestamp}.{payload_json} using the subscriber's webhook secret as the key. Recipients should:

1. Extract the timestamp from the header
2. Construct the signed message: {timestamp}.{raw_body}
3. Compute HMAC-SHA256 with their stored secret
4. Compare the computed signature to the header value
5. Reject if the timestamp is more than 5 minutes old (replay protection)

Delivery Guarantees

Webhook deliveries use exponential backoff with 5 retry attempts:

After 5 failed attempts, the delivery is moved to DEAD_LETTER status. After 10 consecutive failures across any deliveries, the endpoint is automatically marked FAILING and delivery is paused until the subscriber re-enables it.

Score Immutability

CARI Scores are immutable after computation. The OracleScore model rejects any attempt to update an existing record. New scores do not replace old scores — they are appended to the time series.

Deterministic Hashing

Every score includes a calculation_hash — a SHA-256 digest computed from canonical JSON serialization of:

• HOA identifier
• As-of date
• Methodology version
• All signal values (sorted by key)
• All weights (sorted by key)

Canonical JSON uses sorted keys, minimal separators, and UTF-8 encoding. Given the same inputs and the same methodology version, the same hash is always produced. This allows independent verification that a score was computed correctly.

Version Chain

Each CARI Score references its previous_score (the most recent prior score for the same HOA). This creates an append-only chain that enables:

• Score delta computation (current vs. previous)
• Grade change detection
• Historical trend analysis without relying on query ordering

Audit Trail

Every score computation records: - All signal values at computation time (signals_snapshot) - The methodology version and weights used (weights_snapshot) - Per-component calculation details (component_details) - Computation timing (computation_ms) - What triggered the computation (triggered_by: scheduled, enforcement_event, manual, api_request, signal_change)

This snapshot is frozen at computation time. Even if the underlying data changes later, the score's evidence is preserved exactly as it was when the score was computed.

CARI Reports

Four report types provide context-appropriate views of CARI data for different institutional consumers. All reports are generated as InstitutionalPackets using BaseAttestationService, which provides:

• Canonical JSON serialization with deterministic SHA-256 content hashing
• Version chain management (each report references its predecessor's hash)
• Full audit trail via PacketEvent records
• PDF rendering

Each report type extends BaseAttestationService and implements its own evidence snapshot builder and scope determination logic. Reports inherit the same immutability and hash verification guarantees as all institutional packets.

Scheduled Operations

Three automated tasks maintain the CARI system: