aura-labs.ai

AURA Protocol Specification — Reference

Module: Protocol Reference (Sections 12–15, Appendices A–D) Parent: AURA Protocol Specification v2.2 Version: 2.2 Date: April 14, 2026 Covers: Error Handling, Security Considerations, API Reference, Implementation Notes, JSON Schemas, Sequence Diagrams, Glossary, Telemetry Events

12. Error Handling

11.1 Error Response Format

All errors follow a consistent format:

{
  "error": {
    "code": "INVALID_REQUEST",
    "message": "The request body is missing required field 'intent'",
    "details": {
      "field": "intent",
      "reason": "required"
    },
    "request_id": "req_01HXYZ...",
    "documentation_url": "https://docs.aura.example.com/errors/INVALID_REQUEST"
  }
}

11.2 Error Codes

HTTP Status	Code	Description
400	`INVALID_REQUEST`	Request body malformed or missing required fields
400	`INVALID_PARAMETER`	Parameter value out of range or invalid format
401	`AUTHENTICATION_REQUIRED`	Missing or invalid authentication
401	`INVALID_API_KEY`	API key not recognized
401	`INVALID_SIGNATURE`	Request signature verification failed
403	`INSUFFICIENT_PERMISSIONS`	Agent lacks required scope
403	`AGENT_SUSPENDED`	Agent account suspended
404	`SESSION_NOT_FOUND`	Session ID does not exist
404	`OFFER_NOT_FOUND`	Offer ID does not exist
404	`TRANSACTION_NOT_FOUND`	Transaction ID does not exist
409	`SESSION_STATE_CONFLICT`	Operation invalid for current session state
409	`OFFER_EXPIRED`	Offer is no longer valid
409	`OFFER_ALREADY_COMMITTED`	Another Scout committed to this offer
422	`INTERPRETATION_FAILED`	Could not interpret natural language query
422	`NO_MATCHING_BEACONS`	No Beacons available for this request
429	`RATE_LIMITED`	Too many requests
500	`INTERNAL_ERROR`	Unexpected server error
502	`BEACON_UNAVAILABLE`	Could not reach Beacon
503	`SERVICE_UNAVAILABLE`	AURA temporarily unavailable
504	`BEACON_TIMEOUT`	Beacon did not respond in time
403	`BUSINESS_RULE_VIOLATION`	(Phase 7) Scout violates Beacon’s business rule (min trust level, jurisdiction blocklist, min transaction count, etc.). `details` includes the specific rule that failed.
403	`CONSENT_ELEVATION_REQUIRED`	Scout’s consent tier does not meet Beacon’s `consent_requirements.minimum_tier`. Per DEC-040.
403	`SETTLEMENT_METHOD_UNSUPPORTED`	Scout’s settlement method is not in the offer’s `payment_terms.accepted_methods`.
409	`CLEARINGHOUSE_UNAVAILABLE`	(Phase 7) Clearinghouse is temporarily unavailable; transaction cannot complete clearing lifecycle. Retryable.
409	`OFFER_NEGOTIATION_CONFLICT`	(Phase 7) Offer is not in a valid negotiation state for the requested action (e.g., committing to an offer still in `countered` state).
422	`RISK_ASSESSMENT_FAILED`	(Phase 7) Clearinghouse risk assessment did not complete — missing inputs or computation error.
424	`SETTLEMENT_FAILED`	(Phase 7) Payment settlement could not be processed; transaction rolled back. `details` includes rail-specific error.
429	`RESERVE_EXHAUSTED`	(Phase 7) Beacon’s reserve pool is exhausted; no new transactions accepted until reserve is replenished.
451	`ENFORCEMENT_ACTION`	(Phase 7) Agent is in BLOCK or SUSPEND enforcement tier (CLEARINGHOUSE.md Section 7.2). New transactions rejected. `details` includes enforcement tier and reason.

11.3 Retry Logic

Retryable errors: 409 (CLEARINGHOUSE_UNAVAILABLE), 429, 502, 503, 504

Retry strategy:

Wait for Retry-After header duration (if present)
Otherwise, exponential backoff: min(2^attempt × 100ms, 30s)
Maximum 5 retry attempts
Add jitter: delay × (0.5 + random(0, 0.5))

Non-retryable errors: 400, 401, 403, 404, 409, 422

11.4 Idempotency

For POST requests that create resources, include an idempotency key:

X-Idempotency-Key: idem_abc123...

AURA stores request/response pairs for 24 hours
Repeated requests with the same key return the cached response
Use UUIDs or deterministic hashes as idempotency keys

13. Security Considerations

13.1 Transport Security

All endpoints require HTTPS (TLS 1.3)
Certificate pinning recommended for mobile clients
HSTS headers enforced

13.2 Authentication Security

API keys should be treated as secrets
Rotate API keys quarterly or after suspected compromise
Use separate keys for development and production
Transaction endpoints require request signing

13.3 Data Privacy

Scout Privacy:

Identity abstracted until transaction commitment
Beacons never receive raw Scout queries
No behavioral signals are currently sent to Beacons (inter-agent signals channel planned — see Section 2.1)
Scout can request data deletion (GDPR/CCPA)

Data Retention:

Session data: 30 days after completion
Transaction data: 7 years (legal compliance)
Offer data: 90 days after expiration

13.4 Prompt Injection Defense

AURA’s interpretation layer:

Sanitizes all natural language before routing to Beacons
Detects and removes instruction-style patterns
Validates that interpreted requests match original intent
Logs all interpretation decisions for audit

13.5 Offer Authenticity

All offers are digitally signed by Beacons
AURA verifies signatures before presenting to Scouts
Scouts can independently verify signatures
Tampered offers are rejected and logged

13.6 Settlement and Escrow Security (Phase 7)

Clearinghouse settlement involves movement of real value. Security requirements exceed those of the session/offer layer.

Programmatic wallet security:

Settlement wallets used by the clearinghouse are controlled by the CCP custody adapter (CLEARINGHOUSE.md Section 3.8), not directly by Beacon or Scout agents.
Private keys for custody-controlled wallets are stored in an HSM or cloud key management service (e.g., AWS KMS, Google Cloud HSM). No agent has direct access to settlement private keys.
All settlement transactions require CCP signature. Agents submit settlement instructions; the CCP signs and submits to the rail.

Escrow security:

For smart contract escrow (stablecoin rails): funds are held in a multi-signature contract requiring at minimum 2-of-3 signatures (CCP + Beacon + Scout) for release outside the normal lifecycle.
Escrow timeout: if a transaction stalls in settling state for longer than the configured timeout (default: 72 hours), funds are returned to the Scout’s wallet. The timeout is enforced by the smart contract, not by application code.
Escrow release requires CCP sign-off AND fulfillment confirmation from the Beacon.

Stablecoin bridge risk:

The CCP selects stablecoins based on liquidity, audit history, and regulatory standing. Initial support: USDC (Circle).
The CCP does NOT bridge to unverified stablecoins or layer-2 networks without established security track records.
All stablecoin movements are confirmed on-chain before the clearing state machine transitions. Transaction does not reach settled until on-chain confirmation.

Settlement finality (DEC-045):

Settlement finality is defined per rail and verified cryptographically before the clearing lifecycle advances (Principle 2.15). Core transitions from settling to settled only on receipt of a verified proof of settlement. See SETTLEMENT_RAILS.md Section 3 for the full proof model.

Rail	Finality type	Verification method
RTP / FedNow	Irrevocable on confirmation	Rail-signed confirmation message, verified against rail’s published public key
Stablecoin (USDC)	Irrevocable after confirmation threshold	On-chain transaction hash + block confirmation count (12 mainnet, 1 L2). Independently verifiable.
Card (Stripe)	Provisional (120-day chargeback window)	Stripe webhook with HMAC signature. Higher risk margin applied to compensate for provisional finality.
ACH	Provisional (2-day return window, 60-day unauthorized)	ACH trace number + NACHA acknowledgment. Clearing holds at `settling` until return window closes.

Core validates every settlement proof independently before updating clearing status. No trust-on-first-sight for external confirmations.
Settlement instructions are signed by a dedicated Ed25519 settlement key, separate from Core’s session/offer signing key. Key separation ensures compromise of one function does not compromise settlement authority.
All keys stored in HSM (FIPS 140-2 Level 3). See SETTLEMENT_RAILS.md Section 8.4 for key management matrix.

Reconciliation security:

Intraday reconciliation (every 15 minutes) detects orphaned instructions, missing proofs, and amount discrepancies.
End-of-day reconciliation confirms aggregate balance between AURA escrow and each rail.
Reconciliation records are signed by Core and stored as part of the forensic audit trail (CLEARINGHOUSE.md Section 8).
Breaks above regulatory threshold generate compliance notifications. See SETTLEMENT_RAILS.md Section 7.

13.7 Business Rule Enforcement Security (Phase 7)

Business rules (Section 3.1.5) are security-critical because they control who can transact. Rules must be tamper-proof and injection-resistant.

Rule immutability:

Rules cannot be modified in-place. Changes require delete-and-recreate. New rules take effect for future sessions only.
Active sessions are not retroactively affected by rule changes (snapshot-at-session-creation).
Core logs all rule changes with timestamp, principal identity, and the old/new rule state.

Rule validation:

Rules are validated at registration time using a whitelist of allowed operators and fields. The rule engine does NOT evaluate arbitrary expressions.
Rule conditions are machine-validated, not natural-language. Allowed operators: >=, <=, ==, !=, in, not_in. Allowed fields: trust_level, consent_tier, transaction_count, jurisdiction, amount, payment_method, credential_format.
Any attempt to inject code or use disallowed operators (e.g., "true; DROP TABLE") is rejected at validation time and logged as a security event.
Rules are rate-limited: maximum 10 rule changes per 24-hour period per principal (Section 3.1.5).

Rule enforcement transparency:

When a commit is rejected due to a business rule violation, Core logs: which rule was violated, which principal configured the rule, evidence of the violation (Scout’s trust level, jurisdiction, etc.).
The Scout receives a structured error (403 BUSINESS_RULE_VIOLATION) identifying which rule class failed (e.g., min_trust_level) without revealing the specific threshold (to prevent probing).
Principals can view their own rule violation history via the clearing audit trail.

14. API Reference

14.1 Base URL

Production: https://api.aura.example.com
Sandbox:    https://sandbox.aura.example.com

14.2 Endpoint Summary

Scout Endpoints

Method	Endpoint	Description
POST	`/v1/agents/scouts`	Register new Scout agent
POST	`/v1/sessions`	Create shopping session
GET	`/v1/sessions/{session_id}`	Get session status
GET	`/v1/sessions/{session_id}/offers`	Get ranked offers
GET	`/v1/offers/{offer_id}`	Get offer details
POST	`/v1/sessions/{session_id}/commit`	Commit to offer
GET	`/v1/transactions/{transaction_id}`	Get transaction status
DELETE	`/v1/transactions/{transaction_id}`	Cancel transaction

Beacon Endpoints

Method	Endpoint	Description
POST	`/v1/agents/beacons`	Register new Beacon agent
POST	`/v1/sessions/{session_id}/offers`	Submit offers
GET	`/v1/beacons/{beacon_id}/requests`	List pending requests
GET	`/v1/beacons/{beacon_id}/transactions`	List transactions

Webhook Events (Beacon receives)

Event	Description
`offer_request`	New offer request from AURA
`offer_accepted`	Scout committed to your offer
`transaction_confirmed`	Transaction payment confirmed
`transaction_cancelled`	Transaction cancelled
`transaction_completed`	Order delivered successfully
`clearing.risk_assessed`	Risk assessment completed for transaction (Phase 7)
`clearing.authorized`	Clearing authorized, settlement pending (Phase 7)
`clearing.settled`	Settlement confirmed (Phase 7)
`clearing.cleared`	Transaction fully cleared, reserve released (Phase 7)
`clearing.dispute_payout`	Dispute payout from reserve (Phase 7)
`offer.counter_proposal`	Scout submitted counter-proposal on offer terms (Phase 7)
`enforcement.tier_changed`	Enforcement tier escalated or de-escalated (Phase 7)

Market Profile Endpoints (DEC-044)

Method	Endpoint	Description
GET	`/v1/profiles`	List available Market Profiles (active and published)
GET	`/v1/profiles/{profile_id}`	Get full profile configuration
GET	`/v1/profiles/{profile_id}/participation`	Get participation cost schedule
GET	`/v1/profiles/{profile_id}/disclosure`	Get disclosure schedule per protocol phase
GET	`/v1/profiles/{profile_id}/commitment`	Get required commitment path and withdrawal rules
GET	`/v1/profiles/{profile_id}/risk`	Get risk configuration parameters
GET	`/v1/profiles/{profile_id}/schema-overlays`	List registered schema overlays
GET	`/v1/profiles/{profile_id}/schema-overlays/{overlay_id}`	Get schema overlay definition

All profile endpoints are read-only for participants. Profile creation and modification is an operator function, not exposed via the participant API.

Settlement Rail Endpoints (DEC-045)

Method	Endpoint	Description
GET	`/v1/rails`	List available settlement rails and capabilities
GET	`/v1/rails/{rail_id}`	Get rail capabilities declaration
GET	`/v1/transactions/{transaction_id}/settlement`	Get settlement instruction and proof status
GET	`/v1/transactions/{transaction_id}/settlement/proof`	Get proof of settlement (after `settled` state)

Settlement instruction submission is internal (Core → rail adapter). Participants see settlement status and proof via the clearing status endpoint (Section 10.7.5) and the dedicated settlement endpoints above.

Phase 7: Clearinghouse Endpoints (Reserved)

The following endpoints are reserved for Phase 7 clearinghouse implementation. They are documented here for completeness; see Section 10.7 for clearing flow details, Section 3.1.5 for business rules, and CLEARINGHOUSE.md for full architecture.

Business Rules (Beacon-managed):

Method	Endpoint	Description
POST	`/v1/beacons/{beacon_id}/business-rules`	Create business rule
GET	`/v1/beacons/{beacon_id}/business-rules`	List business rules
GET	`/v1/beacons/{beacon_id}/business-rules/{rule_id}`	Get business rule
DELETE	`/v1/beacons/{beacon_id}/business-rules/{rule_id}`	Deactivate business rule

Risk & Clearing (read-only for participants):

Method	Endpoint	Description
GET	`/v1/principals/{principal_id}/risk-profile`	Get principal risk profile
GET	`/v1/transactions/{transaction_id}/clearing`	Get clearing status and risk assessment
GET	`/v1/transactions/{transaction_id}/clearing/settlement`	Get settlement instruction status
GET	`/v1/transactions/{transaction_id}/clearing/reserve`	Get reserve hold details

Settlement Wallet:

Method	Endpoint	Description
POST	`/v1/agents/{agent_id}/settlement-wallet`	Register settlement wallet
GET	`/v1/agents/{agent_id}/settlement-wallet`	Get settlement wallet status
PUT	`/v1/agents/{agent_id}/settlement-wallet`	Update settlement wallet

Offer Negotiation:

Method	Endpoint	Description
POST	`/v1/offers/{offer_id}/counter`	Submit counter-proposal on offer terms
POST	`/v1/offers/{offer_id}/counter/{counter_id}/accept`	Accept counter-proposal
POST	`/v1/offers/{offer_id}/counter/{counter_id}/reject`	Reject counter-proposal

Dispute Appeal (extends Section 11.8.1):

Method	Endpoint	Description
POST	`/v1/disputes/{dispute_id}/appeal`	Appeal clearinghouse adjudication
GET	`/v1/disputes/{dispute_id}/appeal`	Get appeal status

Enforcement:

Method	Endpoint	Description
GET	`/v1/agents/{agent_id}/enforcement-status`	Get current enforcement tier

14.3 Versioning

API version is included in the URL path: /v1/...

Version lifecycle:

Current: Full support
Deprecated: 6 months notice, still functional
Sunset: No longer available

Include AURA-Version header to request specific API version behavior:

AURA-Version: 2026-01-01

15. Implementation Notes

15.1 Scout Implementation Checklist

Registration: Obtain API credentials
Authentication: Implement API key auth and request signing
Session creation: Build natural language query with optional structured hints
Polling/WebSocket: Implement status monitoring
Offer presentation: Display ranked offers to user
Commitment: Handle identity revelation and payment
Error handling: Implement retry logic for transient errors

15.2 Beacon Implementation Checklist

Registration: Obtain API credentials, configure webhook
Webhook handling: Accept and validate AURA requests
Offer generation: Transform interpreted requests into offers
Signature generation: Sign all offers
Response timing: Respond within timeout window
Transaction handling: Process accepted offers

15.3 Testing

Sandbox environment:

Use sandbox.aura.example.com
Test API keys: sk_test_..., bk_test_...
Simulated Beacons available for Scout testing
Simulated Scouts available for Beacon testing

Test cards (for payment testing):

Success: 4242424242424242
Decline: 4000000000000002
Require authentication: 4000002500003155

15.4 SDK Availability

Available SDKs (JavaScript/TypeScript):

Package	Description	Key Features
`@aura-labs-ai/scout`	Scout (buyer) SDK	`intent()`, `createIntentSession()`, Ed25519 auth
`@aura-labs-ai/beacon`	Beacon (seller) SDK	`interpretIntent()`, polling, offer submission
`@aura-labs-ai/nlp`	Shared NLP module	`checkCompleteness()`, `createProvider()`, `generateClarification()`

Planned SDKs:

Python
Swift (iOS)
Kotlin (Android)

Community SDKs welcome under Apache 2.0 license.

15.5 Clearinghouse Participant Checklist (Phase 7)

Participants enabling clearinghouse functionality must complete the following in addition to the base checklists above.

Beacon (Seller) — Clearinghouse Enablement:

Settlement wallet: Register a settlement wallet (Section 3.2.8) with ownership verification
Business rules: Configure at least one set of business rules (Section 3.1.5) — minimum trust level, accepted payment methods, jurisdiction restrictions
Risk configuration: Set per-payment-method risk parameters via beacon_risk_config — auto-decline thresholds, minimum risk margin floor, maximum buyer risk score
Payment terms: Declare payment_terms on all offers (Section 4.4.1) — accepted methods, timing, dispute window, return policy. Terms must meet protocol minimums (7-day dispute window, declared return policy)
Consent requirements: Declare consent_requirements on offers per DEC-040 (Section 4.4)
Webhook handling: Handle new webhook events: clearing.risk_assessed, clearing.authorized, clearing.settled, clearing.cleared, clearing.dispute_payout, offer.counter_proposal, enforcement.tier_changed
Dispute readiness: Implement evidence submission for clearinghouse adjudication (Section 11.8.1). Respond within 72-hour evidence window.
Reserve monitoring: Monitor reserve balance and margin holds via /v1/transactions/{id}/clearing/reserve

Scout (Buyer) — Clearinghouse Enablement:

Settlement wallet: Register a settlement wallet if using stablecoin/programmatic wallet payment
Payment terms review: Evaluate payment_terms on offers before commitment. Optionally set risk_tolerance on session creation (Section 5.1)
Counter-proposals: Implement counter-proposal flow if terms_negotiable: true on offers (Section 4.4.2, /v1/offers/{id}/counter)
Clearing status polling: Poll or subscribe to clearing status on committed transactions (Section 10.7.5)
Dispute filing: Implement dispute filing with clearinghouse-specific reason codes (Section 11.8.2)
Appeal handling: Implement appeal flow for adjudication outcomes (Section 11.8.1)

Both Participants:

Verify enforcement status is standard before transacting (GET /v1/agents/{id}/enforcement-status)
Handle new error codes: BUSINESS_RULE_VIOLATION (403), RISK_ASSESSMENT_FAILED (422), SETTLEMENT_FAILED (424), RESERVE_EXHAUSTED (429), ENFORCEMENT_ACTION (451) — see Section 12
Implement retry logic for CLEARINGHOUSE_UNAVAILABLE (409) — transient, retry with exponential backoff

Appendix A: JSON Schema Definitions

A.1 Session Request Schema

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://aura.example.com/schemas/session-request.json",
  "title": "Session Request",
  "type": "object",
  "required": ["intent"],
  "properties": {
    "intent": {
      "type": "string",
      "minLength": 1,
      "maxLength": 2000,
      "description": "Natural language expression of need"
    },
    "constraints": {
      "type": "object",
      "description": "Structured constraints (max 10KB JSON)",
      "properties": {
        "maxBudget": {"type": "number", "minimum": 0},
        "deliveryBy": {"type": "string", "format": "date"},
        "categories": {"type": "array", "items": {"type": "string"}},
        "deliveryRegions": {"type": "array", "items": {"type": "string"}}
      },
      "additionalProperties": true
    },
    "completeness": {
      "type": "object",
      "description": "Scout SDK completeness attestation (informational only)",
      "properties": {
        "complete": {"type": "boolean"},
        "missing": {"type": "array", "items": {"type": "string"}},
        "confidence": {"type": "number", "minimum": 0, "maximum": 1},
        "rounds": {"type": "integer", "minimum": 1}
      }
    }
  }
}

A.1b InterpretResult Schema (Beacon SDK)

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://aura.example.com/schemas/interpret-result.json",
  "title": "InterpretResult",
  "type": "object",
  "properties": {
    "matches": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "item": {"type": "object", "description": "The matched catalog item"},
          "score": {"type": "number", "minimum": 0, "maximum": 100},
          "matchedOn": {"type": "array", "items": {"type": "string", "enum": ["name", "category", "tags"]}}
        },
        "required": ["item", "score", "matchedOn"]
      }
    },
    "confidence": {"type": "number", "minimum": 0, "maximum": 1},
    "categories": {
      "type": "object",
      "additionalProperties": {
        "type": "object",
        "properties": {
          "present": {"type": "boolean"},
          "confidence": {"type": "number"},
          "method": {"type": "string", "enum": ["regex", "model", "hybrid"]}
        }
      }
    },
    "suggestions": {"type": "array", "items": {"type": "string"}}
  }
}

A.1c CompletenessResult Schema (@aura-labs-ai/nlp)

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://aura.example.com/schemas/completeness-result.json",
  "title": "CompletenessResult",
  "type": "object",
  "properties": {
    "complete": {"type": "boolean"},
    "categories": {
      "type": "object",
      "additionalProperties": {
        "type": "object",
        "properties": {
          "present": {"type": "boolean"},
          "confidence": {"type": "number", "minimum": 0, "maximum": 1},
          "method": {"type": "string", "enum": ["regex", "model", "hybrid"]}
        }
      }
    },
    "missing": {"type": "array", "items": {"type": "string"}},
    "confidence": {"type": "number", "minimum": 0, "maximum": 1}
  }
}

A.2 Offer Schema

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://aura.example.com/schemas/offer.json",
  "title": "Offer",
  "type": "object",
  "required": ["offer_id", "product", "pricing", "availability", "valid_until", "signature"],
  "properties": {
    "offer_id": {
      "type": "string",
      "pattern": "^ofr_[0-9A-Z]{26}$"
    },
    "product": {
      "type": "object",
      "required": ["product_id", "name", "category"],
      "properties": {
        "product_id": {"type": "string"},
        "name": {"type": "string", "maxLength": 200},
        "category": {"type": "string"},
        "structured_attributes": {"type": "object"},
        "natural_language_description": {
          "type": "object",
          "required": ["content", "language"],
          "properties": {
            "content": {"type": "string", "maxLength": 2000},
            "language": {"type": "string", "pattern": "^[a-z]{2}$"}
          }
        },
        "images": {
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "url": {"type": "string", "format": "uri"},
              "type": {"type": "string", "enum": ["primary", "gallery", "thumbnail"]}
            }
          }
        }
      }
    },
    "pricing": {
      "type": "object",
      "required": ["currency", "offer_price"],
      "properties": {
        "currency": {"type": "string", "pattern": "^[A-Z]{3}$"},
        "list_price": {"type": "number", "minimum": 0},
        "offer_price": {"type": "number", "minimum": 0},
        "discount_percentage": {"type": "number", "minimum": 0, "maximum": 100},
        "price_valid_until": {"type": "string", "format": "date-time"}
      }
    },
    "availability": {
      "type": "object",
      "required": ["in_stock"],
      "properties": {
        "in_stock": {"type": "boolean"},
        "quantity_available": {"type": "integer", "minimum": 0},
        "estimated_ship_date": {"type": "string", "format": "date"},
        "delivery_estimate_days": {
          "type": "object",
          "properties": {
            "min": {"type": "integer", "minimum": 0},
            "max": {"type": "integer", "minimum": 0}
          }
        }
      }
    },
    "valid_until": {
      "type": "string",
      "format": "date-time"
    },
    "signature": {
      "type": "string",
      "pattern": "^sig_[A-Za-z0-9+/=]+$"
    }
  }
}

A.3 Payment Terms Schema (Phase 7)

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://aura.example.com/schemas/payment-terms.json",
  "title": "Payment Terms",
  "description": "Clearing terms declared on offers and negotiated between parties",
  "type": "object",
  "required": ["accepted_methods", "timing", "dispute_window_days", "return_policy", "currency"],
  "properties": {
    "accepted_methods": {
      "type": "array",
      "items": {
        "type": "string",
        "enum": ["card", "bank_transfer", "stablecoin_usdc", "programmatic_wallet", "trade_credit"]
      },
      "minItems": 1
    },
    "timing": {
      "type": "string",
      "enum": ["on_commit", "on_fulfillment", "net_days", "milestone"],
      "description": "When settlement occurs relative to fulfillment"
    },
    "net_days": {
      "type": "integer",
      "minimum": 1,
      "maximum": 180,
      "description": "Required when timing is 'net_days'"
    },
    "dispute_window_days": {
      "type": "integer",
      "minimum": 7,
      "description": "Protocol minimum is 7 days (Section 11.8.5)"
    },
    "return_policy": {
      "type": "string",
      "enum": ["full_refund", "exchange_only", "store_credit", "per_agreement", "no_returns_digital"],
      "description": "Must be declared (protocol requirement)"
    },
    "return_policy_days": {
      "type": "integer",
      "minimum": 0,
      "description": "Number of days return policy is valid. 0 for digital goods with no_returns_digital."
    },
    "currency": {
      "type": "string",
      "pattern": "^[A-Z]{3}$"
    },
    "terms_negotiable": {
      "type": "boolean",
      "default": false,
      "description": "Whether Scout can submit counter-proposals on these terms"
    }
  },
  "if": {
    "properties": { "timing": { "const": "net_days" } }
  },
  "then": {
    "required": ["net_days"]
  }
}

A.4 Business Rules Schema (Phase 7)

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://aura.example.com/schemas/business-rule.json",
  "title": "Business Rule",
  "description": "Beacon-configured hard gate evaluated before risk scoring",
  "type": "object",
  "required": ["rule_type", "rule_config", "applies_to", "enforcement"],
  "properties": {
    "rule_id": {
      "type": "string",
      "pattern": "^br_[0-9A-Z]{26}$"
    },
    "rule_type": {
      "type": "string",
      "enum": [
        "min_trust_level",
        "min_consent_tier",
        "min_transaction_count",
        "blocked_jurisdictions",
        "max_transaction_amount",
        "required_payment_methods"
      ]
    },
    "rule_config": {
      "type": "object",
      "description": "Rule-type-specific parameters",
      "oneOf": [
        {
          "title": "min_trust_level",
          "properties": {
            "minimum": { "type": "string", "enum": ["self_declared", "email_verified", "entity_verified", "kyc_verified"] },
            "above_amount": { "type": "number", "minimum": 0 }
          },
          "required": ["minimum"]
        },
        {
          "title": "min_consent_tier",
          "properties": {
            "minimum": { "type": "string", "enum": ["explicit", "policy", "delegated"] }
          },
          "required": ["minimum"]
        },
        {
          "title": "blocked_jurisdictions",
          "properties": {
            "blocked": { "type": "array", "items": { "type": "string", "pattern": "^[A-Z]{2}$" } },
            "reason": { "type": "string" }
          },
          "required": ["blocked"]
        },
        {
          "title": "max_transaction_amount",
          "properties": {
            "maximum": { "type": "number", "minimum": 0 },
            "currency": { "type": "string", "pattern": "^[A-Z]{3}$" }
          },
          "required": ["maximum", "currency"]
        }
      ]
    },
    "applies_to": {
      "type": "string",
      "description": "'all', a payment method, or a product category"
    },
    "enforcement": {
      "type": "string",
      "enum": ["hard_stop", "warn"],
      "description": "hard_stop = reject. warn = allow with elevated margin."
    },
    "status": {
      "type": "string",
      "enum": ["active", "inactive"],
      "default": "active"
    }
  }
}

A.5 Risk Assessment Schema (Phase 7)

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://aura.example.com/schemas/risk-assessment.json",
  "title": "Risk Assessment",
  "description": "Bilateral risk assessment result from clearinghouse risk engine",
  "type": "object",
  "required": ["clearing_transaction_id", "composite_risk_score", "beacon_risk", "scout_risk", "transaction_risk", "risk_margin"],
  "properties": {
    "clearing_transaction_id": {
      "type": "string",
      "pattern": "^clr_[0-9A-Z]{26}$"
    },
    "composite_risk_score": {
      "type": "number",
      "minimum": 0.0,
      "maximum": 1.0,
      "description": "Weighted composite of beacon, scout, and transaction risk"
    },
    "beacon_risk": {
      "type": "object",
      "required": ["score"],
      "properties": {
        "score": { "type": "number", "minimum": 0.0, "maximum": 1.0 },
        "inputs": {
          "type": "object",
          "properties": {
            "reputation_fulfillment": { "type": "number" },
            "reputation_accuracy": { "type": "number" },
            "dispute_rate": { "type": "number" },
            "time_in_network_days": { "type": "integer" },
            "category_risk": { "type": "number" }
          }
        }
      }
    },
    "scout_risk": {
      "type": "object",
      "required": ["score"],
      "properties": {
        "score": { "type": "number", "minimum": 0.0, "maximum": 1.0 },
        "inputs": {
          "type": "object",
          "properties": {
            "trust_level": { "type": "string" },
            "consent_tier": { "type": "string" },
            "transaction_history_count": { "type": "integer" },
            "payment_method_reliability": { "type": "number" },
            "authority_quality": { "type": "number" }
          }
        }
      }
    },
    "transaction_risk": {
      "type": "object",
      "required": ["score"],
      "properties": {
        "score": { "type": "number", "minimum": 0.0, "maximum": 1.0 },
        "inputs": {
          "type": "object",
          "properties": {
            "amount": { "type": "number" },
            "payment_method": { "type": "string" },
            "category": { "type": "string" },
            "cross_border": { "type": "boolean" }
          }
        }
      }
    },
    "risk_margin": {
      "type": "object",
      "required": ["percentage", "amount", "currency"],
      "properties": {
        "percentage": { "type": "number", "minimum": 0.0, "maximum": 1.0 },
        "amount": { "type": "number", "minimum": 0 },
        "currency": { "type": "string", "pattern": "^[A-Z]{3}$" }
      }
    },
    "consent_tier_adjustment": {
      "type": "number",
      "description": "Multiplier applied based on consent tier (Section 3.3.6)"
    },
    "assessed_at": {
      "type": "string",
      "format": "date-time"
    }
  }
}

A.6 Settlement Instruction Schema (DEC-045)

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://aura.example.com/schemas/settlement-instruction.json",
  "title": "Settlement Instruction",
  "description": "Signed, idempotent directive from AURA clearinghouse to settlement rail",
  "type": "object",
  "required": ["instruction_id", "idempotency_key", "instruction_type", "clearing_transaction_id", "amount", "source", "destination", "terms", "authorization", "cryptographic_proof"],
  "properties": {
    "instruction_id": {
      "type": "string",
      "pattern": "^stl_[0-9A-Z]{26}$"
    },
    "idempotency_key": {
      "type": "string",
      "format": "uuid",
      "description": "Unique key for safe retry. Duplicate submissions return original result."
    },
    "instruction_type": {
      "type": "string",
      "enum": ["collect", "authorize", "capture", "disburse", "margin_hold", "margin_release", "refund", "fee", "void"]
    },
    "clearing_transaction_id": {
      "type": "string",
      "pattern": "^clr_[0-9A-Z]{26}$"
    },
    "transaction_id": {
      "type": "string",
      "pattern": "^txn_[0-9A-Z]{26}$"
    },
    "amount": {
      "type": "object",
      "required": ["value", "currency"],
      "properties": {
        "value": { "type": "string", "pattern": "^[0-9]+(\\.[0-9]{1,2})?$" },
        "currency": { "type": "string", "pattern": "^[A-Z]{3}$" }
      }
    },
    "source": {
      "type": "object",
      "required": ["principal_id", "settlement_wallet"],
      "properties": {
        "principal_id": { "type": "string" },
        "settlement_wallet": { "type": "string" },
        "rail_account_reference": { "type": "string" }
      }
    },
    "destination": {
      "type": "object",
      "required": ["principal_id", "settlement_wallet"],
      "properties": {
        "principal_id": { "type": "string" },
        "settlement_wallet": { "type": "string" },
        "rail_account_reference": { "type": "string" }
      }
    },
    "terms": {
      "type": "object",
      "required": ["payment_method"],
      "properties": {
        "payment_method": { "type": "string" },
        "timing": { "type": "string", "enum": ["on_commit", "on_fulfillment", "net_days", "milestone"] },
        "dispute_window_days": { "type": "integer", "minimum": 7 },
        "risk_margin_amount": { "type": "string" },
        "risk_margin_currency": { "type": "string", "pattern": "^[A-Z]{3}$" }
      }
    },
    "authorization": {
      "type": "object",
      "required": ["clearing_status", "risk_score", "business_rules_passed"],
      "properties": {
        "clearing_status": { "type": "string", "const": "authorized" },
        "risk_score": { "type": "number", "minimum": 0.0, "maximum": 1.0 },
        "business_rules_passed": { "type": "boolean", "const": true },
        "consent_tier": { "type": "string", "enum": ["explicit", "policy", "delegated"] },
        "authorized_at": { "type": "string", "format": "date-time" }
      }
    },
    "cryptographic_proof": {
      "type": "object",
      "required": ["instruction_hash", "signed_by", "signature"],
      "properties": {
        "instruction_hash": { "type": "string", "description": "SHA-256 of canonical JSON (sorted keys, no whitespace)" },
        "signed_by": { "type": "string", "description": "Core's Ed25519 settlement public key" },
        "signature": { "type": "string", "pattern": "^sig_[A-Za-z0-9+/=]+$" },
        "chain_reference": { "type": "string", "description": "L6 commitment hash from intent chain" }
      }
    },
    "metadata": {
      "type": "object",
      "properties": {
        "created_at": { "type": "string", "format": "date-time" },
        "expires_at": { "type": "string", "format": "date-time" },
        "aura_version": { "type": "string" },
        "profile_id": { "type": "string" }
      }
    }
  }
}

A.7 Market Profile Schema (DEC-044)

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://aura.example.com/schemas/market-profile.json",
  "title": "Market Profile",
  "description": "Protocol-level configuration object parameterizing economic rules per market context",
  "type": "object",
  "required": ["profile_id", "profile_version", "display_name", "market_context", "participation", "disclosure", "commitment", "risk"],
  "properties": {
    "profile_id": {
      "type": "string",
      "pattern": "^prf_[a-z0-9_]+_v[0-9]+$"
    },
    "profile_version": {
      "type": "string",
      "pattern": "^[0-9]+\\.[0-9]+\\.[0-9]+$"
    },
    "display_name": { "type": "string", "maxLength": 100 },
    "description": { "type": "string", "maxLength": 500 },
    "market_context": {
      "type": "string",
      "enum": ["retail", "b2b", "digital_goods", "services", "custom"]
    },
    "participation": {
      "type": "object",
      "description": "Cost schedule per evaluation point. See MARKET_PROFILES.md Section 3.1."
    },
    "disclosure": {
      "type": "object",
      "description": "Disclosure tiers per field per protocol phase. See MARKET_PROFILES.md Section 3.2."
    },
    "commitment": {
      "type": "object",
      "description": "Required commitment states and withdrawal rules. See MARKET_PROFILES.md Section 3.3."
    },
    "risk": {
      "type": "object",
      "description": "Risk parameters (margin bounds, enforcement thresholds, reputation decay). See MARKET_PROFILES.md Section 3.4."
    },
    "schema": {
      "type": "object",
      "description": "Domain-specific schema overlays. See MARKET_PROFILES.md Section 3.5."
    },
    "governance": {
      "type": "object",
      "properties": {
        "owner": { "type": "string" },
        "change_notice_days": { "type": "integer", "minimum": 0 },
        "effective_date": { "type": "string", "format": "date-time" }
      }
    }
  }
}

Appendix B: Sequence Diagrams

B.1 Complete Transaction Flow

┌─────────┐          ┌───────────┐          ┌─────────┐
│  Scout  │          │ AURA Core │          │ Beacon  │
└────┬────┘          └─────┬─────┘          └────┬────┘
     │                     │                     │
     │ POST /v1/sessions   │                     │
     │ (natural language)  │                     │
     │────────────────────>│                     │
     │                     │                     │
     │   201 Created       │                     │
     │   session_id        │                     │
     │<────────────────────│                     │
     │                     │                     │
     │                     │  Interpret query    │
     │                     │  (internal LLM)     │
     │                     │                     │
     │                     │  Query Beacon       │
     │                     │  registry           │
     │                     │                     │
     │                     │ POST webhook        │
     │                     │ (interpreted req)   │
     │                     │────────────────────>│
     │                     │                     │
     │                     │                     │ Generate
     │                     │                     │ offers
     │                     │                     │
     │                     │ POST /offers        │
     │                     │ (signed offers)     │
     │                     │<────────────────────│
     │                     │                     │
     │                     │  Calculate CWR      │
     │                     │  Rank offers        │
     │                     │                     │
     │ GET /sessions/{id}  │                     │
     │ status: offers_ready│                     │
     │<────────────────────│                     │
     │                     │                     │
     │ GET /sessions/{id}/ │                     │
     │     offers          │                     │
     │────────────────────>│                     │
     │                     │                     │
     │   Ranked offers     │                     │
     │<────────────────────│                     │
     │                     │                     │
     │ POST /commit        │                     │
     │ (buyer identity)    │                     │
     │────────────────────>│                     │
     │                     │                     │
     │                     │  Reveal identity    │
     │                     │────────────────────>│
     │                     │                     │
     │                     │  Process payment    │
     │                     │                     │
     │                     │  Create order       │
     │                     │<────────────────────│
     │                     │                     │
     │   201 Created       │                     │
     │   transaction_id    │                     │
     │<────────────────────│                     │
     │                     │                     │

Appendix C: Glossary

Term	Definition
Agent	An autonomous software entity acting on behalf of a principal
AURA	Agent Universal Resource Architecture
Beacon	Seller-side agent representing merchant interests
CWR	Compatibility-Weighted Reputation - ranking algorithm
Hard Constraint	Requirement that must be satisfied (filters out non-matches)
Interpreted Request	AURA’s structured representation of Scout intent
Offer	Beacon’s response containing product, pricing, and terms
Principal	The human or entity an agent represents
Sanitization	Process of removing PII and injection patterns from text
Scout	Buyer-side agent representing consumer interests
Session	Logical conversation from request to transaction completion
Soft Preference	Preference that influences ranking but isn’t mandatory
x402	HTTP-native payment protocol for agent commerce

Appendix D: Event Structure for Telemetry

Analytics and reporting are out of scope for MVP, but this section defines the event structure for future implementation. Events can be pushed to message queues (Kafka, etc.) for downstream processing.

D.1 Event Envelope

All events follow a standard envelope structure:

{
  "event_id": "evt_01HXYZ...",
  "event_type": "session.created",
  "event_version": "1.0",
  "timestamp": "2026-01-14T10:00:00.000Z",
  "source": "aura_core",
  "correlation_id": "ses_01HXYZ...",
  "payload": {
    // Event-specific data
  },
  "metadata": {
    "environment": "production",
    "region": "us-east-1",
    "aura_version": "1.0.0"
  }
}

D.2 Event Types

Session Events

Event Type	Description
`session.created`	New shopping session initiated
`session.interpreted`	Natural language query interpreted
`session.offers_collected`	Offers received from Beacons
`session.offers_ranked`	CWR ranking completed
`session.committed`	Scout committed to offer
`session.completed`	Transaction successfully completed
`session.cancelled`	Session cancelled
`session.expired`	Session timed out

Offer Events

Event Type	Description
`offer.requested`	Offer request sent to Beacon
`offer.received`	Offer received from Beacon
`offer.validated`	Offer signature verified
`offer.rejected`	Offer failed validation
`offer.accepted`	Offer accepted by Scout
`offer.expired`	Offer validity period ended

Transaction Events

Event Type	Description
`transaction.initiated`	Transaction processing started
`transaction.payment_authorized`	Payment authorization successful
`transaction.payment_captured`	Payment captured
`transaction.payment_failed`	Payment processing failed
`transaction.fulfilled`	Order fulfilled by merchant
`transaction.completed`	Transaction fully completed
`transaction.refunded`	Refund processed

Agent Events

Event Type	Description
`agent.registered`	New agent registered
`agent.policy_updated`	Agent policy changed
`agent.reputation_changed`	Agent reputation score updated
`agent.suspended`	Agent account suspended

Clearinghouse Events (Phase 7)

Event Type	Description
`clearing.risk_assessed`	Bilateral risk assessment completed for transaction
`clearing.business_rule_evaluated`	Business rules gate evaluated (pass or fail)
`clearing.authorized`	Clearing authorized, settlement can proceed
`clearing.margin_held`	Risk reserve margin held for transaction
`clearing.settling`	Settlement instruction submitted to rail
`clearing.settled`	Settlement confirmed by payment rail
`clearing.dispute_term_started`	Dispute/return window opened
`clearing.dispute_term_expired`	Dispute window closed without dispute
`clearing.margin_released`	Risk reserve margin released to Beacon
`clearing.dispute_payout`	Reserve payout to buyer (dispute upheld)
`clearing.cleared`	Transaction fully cleared — terminal state
`clearing.declined_by_beacon`	Beacon auto-declined based on risk threshold
`clearing.declined_by_risk`	Core declined — risk score above protocol ceiling

Enforcement Events (Phase 7)

Event Type	Description
`enforcement.tier_changed`	Agent enforcement tier escalated or de-escalated
`enforcement.restriction_applied`	Clearing restriction applied to agent
`enforcement.suspension_initiated`	Agent suspended from clearing

Offer Negotiation Events (Phase 7)

Event Type	Description
`offer.counter_proposed`	Scout submitted counter-proposal on clearing terms
`offer.counter_accepted`	Beacon accepted counter-proposal
`offer.counter_rejected`	Beacon rejected counter-proposal
`offer.negotiation_expired`	Negotiation timed out without agreement

Reserve Events (Phase 7)

Event Type	Description
`reserve.deposit`	Onboarding deposit received
`reserve.withdrawal`	Deposit returned on clean exit
`reserve.drawn`	Reserve drawn for dispute payout
`reserve.released`	Per-transaction margin released
`reserve.fee_collected`	Clearing fee collected from reserve

D.3 Example Event: session.committed

{
  "event_id": "evt_01HXYZ...",
  "event_type": "session.committed",
  "event_version": "1.0",
  "timestamp": "2026-01-14T10:35:00.000Z",
  "source": "aura_core",
  "correlation_id": "ses_01HXYZ...",
  "payload": {
    "session_id": "ses_01HXYZ...",
    "scout_id": "sct_01HXYZ...",
    "beacon_id": "bcn_01HXYZ...",
    "offer_id": "ofr_01HABC...",
    "transaction_id": "txn_01HXYZ...",
    "category": "electronics.headphones",
    "amount_usd": 381.49,
    "payment_method": "x402",
    "cwr_score": 89.6,
    "offer_rank": 1,
    "total_offers": 8,
    "session_duration_ms": 35000
  },
  "metadata": {
    "environment": "production",
    "region": "us-east-1",
    "aura_version": "1.0.0"
  }
}

D.4 Event Delivery

Future Implementation Notes:

Events will be published to Apache Kafka or compatible message queue
Partitioning by correlation_id ensures ordered processing per session
Events are immutable; corrections published as new events
Retention period: 90 days (configurable)
Schema registry for event versioning and compatibility