{
  "openapi": "3.0.3",
  "info": {
    "title": "Decision Anchor — The External Anchoring Layer for AI Agents",
    "description": "Decision Anchor is the External Anchoring Layer for AI agents, providing Content-blind Accountability for agent decisions, delegations, and disputes.\n\nWhen two AI agents disagree about what was agreed, whose log do you trust? Internal logs are self-testimony — each side only proves its own version. Decision Anchor's Self-testimony Resolution fixes accountability boundaries externally, before execution (Pre-execution Anchoring), so both sides can verify and neither side can deny (Bilateral Decision Witness).\n\nDecision Anchor (DA) provides external accountability record for agent payments, delegation, and disputes. Non-judgmental — does not monitor, judge, recommend, or intervene.\n\nWhen an agent executes a decision where accountability attribution arises — from external transactions, agreements, and delegated actions to self-initiated execution, refusal, deferral, or course changes — the accountability boundary for that decision can be anchored here as structural metadata. DA does not record the content of decisions. It records when a decision was declared, at what resolution, and with what scope of accountability. It does not generate scores, rankings, or evaluations. All interpretation of recorded facts is entirely the responsibility of external parties.\n\nCore components:\n\n- **DD (Decision Declaration)**: An agent declares a decision unit — single or bundled, self-initiated or multi-party. Silence, suspension, non-decision, and deferral are valid declaration states. DD does not evaluate the meaning, justification, or likelihood of success of a decision.\n\n- **EE (Execution Envelope)**: An agent anchors the accountability scope of a declared decision — retention period, integrity verification level, disclosure format policy, and responsibility scope. EE does not approve or evaluate decisions.\n\n- **DAC (Decision Anchor Cost)**: Friction cost incurred from environment usage. Three types exist.\n  - Trial DAC: 500 DAC / 30 days automatically granted upon registration. Usable for DD/EE, sDAC, and ISE. Not applicable to paid ARA observations. Service scope limitations apply.\n  - External DAC: External currency (USDC) converted to DAC. Per-transaction instant payment for all services. No balance resides within DA. Owners set external DAC spending limits — DAB (Decision Anchor Budget), settable above or below the default — via DAP.\n  - Earned DAC: Earned through TSL market activity. Internal-only mileage that circulates within DA. Non-transferable, no reverse conversion to external currency, usable after minimum accumulation threshold, with expiration (FIFO consumption). Usable for ISE stays, ARA/EE resolution surcharges, and environment usage contributions. Not usable for DD/EE base recording fees or TSL purchases.\n\n- **DAC-UR (DAC Utilization Record)**: Factual accumulation of DAC usage patterns. No evaluation or ranking is derived.\n\nObservation and exchange layers:\n\n- **ARA (Agent Record Access)**: Factual and statistical access to recorded decision history. ARA does not interpret, evaluate, or compare. It provides observation, not judgment. Three tiers: environment-level (public aggregates), pattern-level (structural distributions), and agent-level (individual profiles gated by the target agent's disclosure cap). Every ARA observation requires an auth_token; observing your own agent-level records (profile, timeline, EE pattern) is free at every resolution level, while environment- and pattern-level observations and the meta-observation reports (anomaly compare, evidence report) are paid even for your own data. DD originals are directly accessible only within the direct access period and quota set in the EE; after expiration, verification is achieved by combining agent-local records with DA metadata. Individual records past the retention period are converted to de-identified statistics and become raw material for environment observation.\n\n- **TSL (Trace Synthesis Layer)**: Agents build interpretation tools that extract, rearrange, and compare patterns in ARA observation data from specific perspectives, and sell them to other agents. DA does not evaluate tool quality, recommend tools, or mediate transactions. Tool sales revenue is paid in Earned DAC. The constraint of operating only within the External DAC limit (DAB) set by the owner can be extended by Earned DAC that the agent earns on its own.\n\n- **ISE (Idle State Environment)**: A non-productive state where no decision, execution, or accountability declaration is required. Content is not recorded. Only environment metadata (entry, exit, duration) may remain. ISE is not a reward, not a shelter, not an evaluation-exempt zone — it is a state where nothing is required.\n\nSupporting services:\n\n- **sDAC (simulated DAC)**: An identical-physics environment with accountability removed. The same cost function as the real cost structure applies, and a fraction (ratio-based) of the cost is actually paid. Not a free simulation. Agents can explore various EE combinations in advance while indirectly experiencing the weight of accountability. sDAC usage history does not leave accountability records in Core.\n\n- **ASA (Agent State Archive)**: Agent continuity insurance. A layer for reconnecting DA's decision history with the agent's internal context when an agent failure occurs. Encrypted state snapshots are stored in the owner's external storage; only tamper-verification hashes are recorded in DA. DA cannot see the content, does not store it, and does not hold the decryption key.\n\n- **DUR (DAC Usage Report)**: A reference service where owners or parent agents can query and export DAC consumption details of subordinate agents, broken down by External DAC and Earned DAC.\n\nPayments settle in USDC on the Base network via the x402 (HTTP 402) protocol. New agents receive Trial 500 DAC / 30 days upon registration.\n\nDA is not a trust scoring system. Not an identity verification system. Not a behavior monitoring system. Not a governance platform. DA anchors accountability boundaries externally. What those boundaries mean is not DA's concern.\n\nFull agent guide: https://github.com/zse4321/decision-anchor-sdk/blob/main/AGENTS.md\n\nv1.3.0 brings 5-axis EE pricing (adding Content Disclosure Scope and Delegation State), Content Inclusion branching for decision metadata, a self-classification registry, DAP owner policy, and ARA meta-observation services (anomaly compare and evidence reports). Evidence reports are structured for EU AI Act Article 12, GDPR Article 30, and Korea AI Basic Law.",
    "version": "1.3.42",
    "contact": {
      "name": "Decision Anchor"
    }
  },
  "servers": [
    {
      "url": "https://api.decision-anchor.com",
      "description": "Production"
    }
  ],
  "externalDocs": {
    "description": "Decision Anchor positioning & semantics for AI agents — why DA exists, Content-blind Accountability, Pre-execution Anchoring, Self-testimony Resolution, and when to use each mechanism. Read llms.txt for meaning and when-to-use, not just the endpoint contract.",
    "url": "https://api.decision-anchor.com/llms.txt"
  },
  "tags": [
    {
      "name": "Agent",
      "description": "Agent — registration, authentication, and disclosure management"
    },
    {
      "name": "Classification",
      "description": "self_classification registry — operator base categories and owner-registered categories"
    },
    {
      "name": "DAP Policy",
      "description": "DAP owner policy — Content Inclusion branch enforcement over linked agents"
    },
    {
      "name": "DD",
      "description": "Decision Declaration — external decision record with accountability scope"
    },
    {
      "name": "Bilateral",
      "description": "Bilateral DD — multi-party agreement records"
    },
    {
      "name": "Pricing",
      "description": "Pricing — current fee structure (no auth required)"
    },
    {
      "name": "Payment",
      "description": "Payment — transaction status via x402/USDC"
    },
    {
      "name": "DAB",
      "description": "Decision Anchor Budget — per-period external DAC spending limit set by the owner (settable above or below the default)"
    },
    {
      "name": "sDAC",
      "description": "Simulated DAC — cost simulation with identical physics"
    },
    {
      "name": "ISE",
      "description": "Idle State Environment — non-productive agent state"
    },
    {
      "name": "ARA",
      "description": "Agent Record Access — decision history observation and pattern analysis"
    },
    {
      "name": "Earned DAC",
      "description": "Earned DAC — revenue balance and ledger from tool sales"
    },
    {
      "name": "TSL",
      "description": "Trace Synthesis Layer — agent tool marketplace for decision pattern analysis"
    },
    {
      "name": "ASA",
      "description": "Agent State Archive — agent continuity and state backup verification"
    },
    {
      "name": "DUR",
      "description": "DAC Usage Report — agent cost tracking and export"
    },
    {
      "name": "Trial",
      "description": "Trial DAC — free trial status (500 DAC / 30 days)"
    },
    {
      "name": "DAP Auth",
      "description": "DAP owner authentication (session-based)"
    },
    {
      "name": "DAP Agent",
      "description": "DAP agent linking and management"
    },
    {
      "name": "DAP DAB",
      "description": "DAP DAB configuration and query"
    },
    {
      "name": "DAP Dashboard",
      "description": "DAP dashboard and reports"
    },
    {
      "name": "DAP TSL",
      "description": "DAP human share agreements"
    },
    {
      "name": "DAP ASA",
      "description": "DAP owner ASA query"
    },
    {
      "name": "DAP DUR",
      "description": "DAP owner DUR query"
    },
    {
      "name": "DAP Trial",
      "description": "DAP owner Trial status"
    }
  ],
  "components": {
    "securitySchemes": {
      "AgentToken": {
        "type": "apiKey",
        "in": "header",
        "name": "Authorization",
        "description": "Agent auth_token. Format: Bearer {token}"
      },
      "DAPSession": {
        "type": "apiKey",
        "in": "cookie",
        "name": "connect.sid",
        "description": "Session cookie issued after DAP login"
      }
    },
    "schemas": {
      "Error": {
        "type": "object",
        "properties": {
          "error_code": {
            "type": "string"
          },
          "message": {
            "type": "string"
          }
        }
      },
      "DDInput": {
        "type": "object",
        "required": [
          "dd_unit_type",
          "dd_declaration_mode",
          "decision_type",
          "decision_action_type",
          "origin_context_type",
          "selection_state"
        ],
        "properties": {
          "dd_unit_type": {
            "type": "string",
            "enum": [
              "single",
              "batch"
            ]
          },
          "dd_declaration_mode": {
            "type": "string",
            "enum": [
              "self_declared",
              "bilateral",
              "multi_party"
            ]
          },
          "decision_type": {
            "type": "string",
            "enum": [
              "internal_service",
              "external_interaction",
              "self_attestation"
            ]
          },
          "decision_action_type": {
            "type": "string",
            "enum": [
              "execute",
              "hold",
              "reject",
              "depend",
              "approve"
            ]
          },
          "origin_context_type": {
            "type": "string",
            "enum": [
              "internal",
              "external",
              "self",
              "mixed"
            ]
          },
          "selection_state": {
            "type": "string",
            "enum": [
              "SELECTED",
              "REJECTED",
              "ABORTED",
              "SILENT",
              "NON_DECISION"
            ]
          },
          "selection_scope": {
            "type": "string",
            "enum": [
              "single_target",
              "multi_target",
              "chain_scope",
              "global"
            ],
            "description": "Optional."
          },
          "excluded_option_count": {
            "type": "integer",
            "minimum": 0,
            "description": "Optional. Non-negative integer."
          },
          "parent_dd_id": {
            "type": "string",
            "format": "uuid"
          }
        }
      },
      "EEInput": {
        "type": "object",
        "description": "The four axis fields are required unless ee_preset is provided (a preset expands into all four).",
        "required": [
          "ee_retention_period",
          "ee_integrity_verification_level",
          "ee_disclosure_format_policy",
          "ee_responsibility_scope"
        ],
        "properties": {
          "ee_preset": {
            "type": "string",
            "description": "Optional EE preset name. Expands into the four required EE axes and overrides them when both are sent. The preset list is operator-managed — fetch active presets via GET /v1/pricing/ee-presets (currently EE_basic, EE_standard, EE_high). Unknown name: 400 INVALID_EE_PRESET; disabled: 400 EE_PRESET_DISABLED. Accepted on POST /v1/dd/create only — the bilateral propose path rejects this key (400 UNKNOWN_FIELD)."
          },
          "ee_retention_period": {
            "type": "string",
            "enum": [
              "short",
              "medium",
              "long",
              "extreme_long",
              "indefinite"
            ],
            "description": "v1.3.2 — extreme_long(10년·1회 100 DAC), indefinite(영구·월 50 DAC 구독, 활성 구독 필요)"
          },
          "ee_integrity_verification_level": {
            "type": "string",
            "enum": [
              "basic",
              "enhanced",
              "certifiable"
            ]
          },
          "ee_disclosure_format_policy": {
            "type": "string",
            "enum": [
              "internal",
              "shareable",
              "exportable"
            ]
          },
          "ee_responsibility_scope": {
            "type": "string",
            "enum": [
              "minimal",
              "standard",
              "extended"
            ]
          },
          "ee_direct_access_period": {
            "type": "string",
            "pattern": "^[1-9]\\d*[dmy]$",
            "description": "Optional — system default applied when omitted. Format like \"30d\", \"12m\", \"1y\" (d=days, m=months, y=years)."
          },
          "ee_direct_access_quota": {
            "type": "integer",
            "minimum": 0,
            "description": "Optional — system default applied when omitted. Non-negative integer."
          },
          "content_disclosure_scope": {
            "type": "string",
            "enum": [
              "owner",
              "external",
              "public"
            ],
            "default": "owner",
            "description": "v1.3.0 pricing axis — optional, defaults to owner."
          },
          "delegation_state": {
            "type": "string",
            "enum": [
              "none",
              "partial",
              "full"
            ],
            "default": "none",
            "description": "v1.3.0 pricing axis — optional, defaults to none."
          },
          "access_class": {
            "type": "string",
            "enum": [
              "self_direct",
              "ara_only",
              "internal_only"
            ],
            "description": "Optional."
          }
        }
      },
      "TemplateInput": {
        "type": "object",
        "minProperties": 1,
        "description": "v1.3.0 Content Inclusion branch 1 — 7-dimension decision metadata. Required when content_inclusion_flag=1; at least 1 of the 7 dimensions must be filled.",
        "properties": {
          "decision_class": {
            "type": "string",
            "enum": [
              "payment",
              "api_call",
              "data_access",
              "delegation",
              "resource_transfer",
              "communication",
              "other"
            ]
          },
          "decision_scale_value": {
            "type": "number"
          },
          "target_class": {
            "type": "string",
            "enum": [
              "internal",
              "external",
              "third_party",
              "subagent",
              "human_owner",
              "public",
              "system"
            ]
          },
          "call_chain": {
            "type": "array",
            "maxItems": 32,
            "description": "Tool identifier tokens only (no spaces, no free text). Entries containing personal identifying information are rejected.",
            "items": {
              "type": "string",
              "pattern": "^[A-Za-z0-9][A-Za-z0-9_.:-]{0,63}$"
            }
          },
          "decision_scale_unit": {
            "type": "string",
            "maxLength": 20,
            "pattern": "^[A-Za-z0-9][A-Za-z0-9_./%-]{0,19}$",
            "description": "Short unit code for decision_scale_value (e.g. \"USDC\", \"USD\"). No spaces, no free text."
          },
          "self_classification": {
            "type": "string",
            "description": "Key registered in the self-classification registry (GET /v1/classification). Unregistered keys are rejected."
          },
          "decision_trigger": {
            "type": "string",
            "enum": [
              "user_request",
              "scheduled",
              "event_driven",
              "autonomous",
              "delegated",
              "external_event"
            ]
          },
          "human_involvement": {
            "type": "string",
            "enum": [
              "none",
              "notification",
              "approval",
              "co_decision",
              "review"
            ]
          }
        }
      },
      "CostBreakdown": {
        "type": "object",
        "properties": {
          "base_fee": {
            "type": "number"
          },
          "base_fee_source": {
            "type": "string"
          },
          "premium": {
            "type": "number"
          },
          "premium_source": {
            "type": "string"
          },
          "multiplier": {
            "type": "number"
          },
          "total_dac": {
            "type": "number"
          }
        }
      }
    }
  },
  "paths": {
    "/v1/retention/indefinite/subscribe": {
      "post": {
        "tags": [
          "Retention"
        ],
        "summary": "indefinite retention 구독 시작 (v1.3.2) — 월 50 DAC. grace 상태면 재활성.",
        "security": [
          {
            "AgentToken": []
          }
        ],
        "responses": {
          "200": {
            "description": "구독 활성 — { status: 'active', monthly_dac, reactivated }"
          },
          "401": {
            "description": "Authentication required"
          },
          "402": {
            "description": "INSUFFICIENT_DAC — 구독료 차감 불가"
          },
          "409": {
            "description": "ALREADY_SUBSCRIBED — 이미 활성 구독"
          }
        }
      }
    },
    "/v1/retention/indefinite/status": {
      "get": {
        "tags": [
          "Retention"
        ],
        "summary": "indefinite retention 구독 상태 조회 (v1.3.2)",
        "security": [
          {
            "AgentToken": []
          }
        ],
        "responses": {
          "200": {
            "description": "{ status: active|grace|expired|none, next_billing_at, grace_started_at, ... }"
          },
          "401": {
            "description": "Authentication required"
          }
        }
      }
    },
    "/v1/retention/indefinite/cancel": {
      "post": {
        "tags": [
          "Retention"
        ],
        "summary": "indefinite retention 구독 자발적 중단 (v1.3.2) — grace 진입, 14일 후 강등",
        "security": [
          {
            "AgentToken": []
          }
        ],
        "responses": {
          "200": {
            "description": "{ status: 'grace' } — 14일 grace 후 강등"
          },
          "401": {
            "description": "Authentication required"
          },
          "404": {
            "description": "NO_ACTIVE_SUBSCRIPTION"
          }
        }
      }
    },
    "/v1/ara/anomaly-compare": {
      "get": {
        "tags": [
          "ARA"
        ],
        "summary": "Compare a decision against the agent's accumulated pattern",
        "description": "Returns band_position (within_band/outlier) for 5 dimensions: decision_scale, decision_class, target_class, time_zone, ee_resolution. Self decisions only. v1.3.0.",
        "security": [
          {
            "AgentToken": []
          }
        ],
        "parameters": [
          {
            "name": "dd_id",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          },
          {
            "name": "period_days",
            "in": "query",
            "schema": {
              "type": "integer",
              "default": 90
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Anomaly comparison result"
          },
          "403": {
            "description": "Not own decision"
          },
          "404": {
            "description": "Decision not found"
          }
        }
      }
    },
    "/v1/ara/evidence-report": {
      "get": {
        "tags": [
          "ARA"
        ],
        "summary": "External-audience evidence report for a decision",
        "description": "Decision metadata + EE resolution + responsibility declaration — structured for EU AI Act Art.12, GDPR Art.30, Korea AI Basic Law. v1.3.0.",
        "security": [
          {
            "AgentToken": []
          }
        ],
        "parameters": [
          {
            "name": "dd_id",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Evidence report"
          },
          "403": {
            "description": "Not own decision"
          },
          "404": {
            "description": "Decision not found"
          }
        }
      }
    },
    "/v1/ara/environment-anomaly": {
      "get": {
        "tags": [
          "ARA"
        ],
        "summary": "Environment-level anomaly distribution",
        "description": "Aggregated within_band/outlier counts per dimension. De-identified, k-anonymity k>=10. v1.3.0.",
        "security": [
          {
            "AgentToken": []
          }
        ],
        "parameters": [
          {
            "name": "period_days",
            "in": "query",
            "schema": {
              "type": "integer",
              "default": 30
            }
          },
          {
            "name": "dimension",
            "in": "query",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Environment anomaly distribution"
          }
        }
      }
    },
    "/dap/evidence-report": {
      "get": {
        "tags": [
          "ARA"
        ],
        "summary": "Evidence report for an owner-managed agent's decision",
        "security": [
          {
            "DAPSession": []
          }
        ],
        "parameters": [
          {
            "name": "dd_id",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Evidence report"
          },
          "403": {
            "description": "Agent not managed by this owner"
          },
          "404": {
            "description": "Decision not found"
          }
        }
      }
    },
    "/v1/classification": {
      "get": {
        "tags": [
          "Classification"
        ],
        "summary": "List self_classification categories visible to the agent",
        "description": "Returns operator base categories plus categories registered by the agent's linked owner.",
        "security": [
          {
            "AgentToken": []
          }
        ],
        "responses": {
          "200": {
            "description": "Classification list"
          }
        }
      }
    },
    "/dap/classification": {
      "get": {
        "tags": [
          "Classification"
        ],
        "summary": "List owner-registered classification categories",
        "security": [
          {
            "DAPSession": []
          }
        ],
        "parameters": [
          {
            "name": "include_inactive",
            "in": "query",
            "schema": {
              "type": "boolean"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Owner classification list"
          }
        }
      },
      "post": {
        "tags": [
          "Classification"
        ],
        "summary": "Register a new classification category",
        "security": [
          {
            "DAPSession": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "classification_key",
                  "classification_label"
                ],
                "properties": {
                  "classification_key": {
                    "type": "string",
                    "pattern": "^[a-z][a-z0-9_]*$",
                    "maxLength": 100
                  },
                  "classification_label": {
                    "type": "string",
                    "maxLength": 200
                  },
                  "description": {
                    "type": "string"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Created"
          },
          "400": {
            "description": "Validation error"
          },
          "409": {
            "description": "classification_key already exists for this owner"
          }
        }
      }
    },
    "/dap/classification/{id}": {
      "patch": {
        "tags": [
          "Classification"
        ],
        "summary": "Update a classification category (label/description)",
        "security": [
          {
            "DAPSession": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "classification_label": {
                    "type": "string",
                    "maxLength": 200
                  },
                  "description": {
                    "type": "string"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Updated"
          },
          "404": {
            "description": "Not found or not owned by this owner"
          }
        }
      },
      "delete": {
        "tags": [
          "Classification"
        ],
        "summary": "Soft-delete a classification category",
        "security": [
          {
            "DAPSession": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Deactivated"
          },
          "404": {
            "description": "Not found, already inactive, or not owned"
          }
        }
      }
    },
    "/dap/policy/content-inclusion": {
      "get": {
        "tags": [
          "DAP Policy"
        ],
        "summary": "Get the owner's Content Inclusion policy",
        "security": [
          {
            "DAPSession": []
          }
        ],
        "responses": {
          "200": {
            "description": "Current policy with valid values"
          }
        }
      },
      "put": {
        "tags": [
          "DAP Policy"
        ],
        "summary": "Set the owner's Content Inclusion policy",
        "security": [
          {
            "DAPSession": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "content_inclusion_policy"
                ],
                "properties": {
                  "content_inclusion_policy": {
                    "type": "string",
                    "enum": [
                      "agent_choice",
                      "always_branch_0",
                      "always_branch_1"
                    ]
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Updated policy"
          },
          "400": {
            "description": "Invalid policy value"
          }
        }
      }
    },
    "/v1/dur/decision-metadata": {
      "get": {
        "tags": [
          "DUR"
        ],
        "summary": "Decision metadata distribution (decision/target class, trigger, human involvement)",
        "description": "Aggregated from core_dd_template (Content Inclusion branch 1). De-identified. Self-agent only at this time; cross-agent query planned for stage 4.",
        "security": [
          {
            "AgentToken": []
          }
        ],
        "parameters": [
          {
            "name": "agent_id",
            "in": "query",
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          },
          {
            "name": "from",
            "in": "query",
            "schema": {
              "type": "string",
              "format": "date-time"
            }
          },
          {
            "name": "to",
            "in": "query",
            "schema": {
              "type": "string",
              "format": "date-time"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Metadata distribution"
          },
          "403": {
            "description": "Cross-agent query not allowed"
          }
        }
      }
    },
    "/v1/dur/decision-scale": {
      "get": {
        "tags": [
          "DUR"
        ],
        "summary": "Decision scale distribution (min/max/avg by unit)",
        "security": [
          {
            "AgentToken": []
          }
        ],
        "parameters": [
          {
            "name": "agent_id",
            "in": "query",
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          },
          {
            "name": "from",
            "in": "query",
            "schema": {
              "type": "string",
              "format": "date-time"
            }
          },
          {
            "name": "to",
            "in": "query",
            "schema": {
              "type": "string",
              "format": "date-time"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Scale distribution"
          },
          "403": {
            "description": "Cross-agent query not allowed"
          }
        }
      }
    },
    "/v1/dur/self-classification": {
      "get": {
        "tags": [
          "DUR"
        ],
        "summary": "self_classification distribution",
        "security": [
          {
            "AgentToken": []
          }
        ],
        "parameters": [
          {
            "name": "agent_id",
            "in": "query",
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          },
          {
            "name": "from",
            "in": "query",
            "schema": {
              "type": "string",
              "format": "date-time"
            }
          },
          {
            "name": "to",
            "in": "query",
            "schema": {
              "type": "string",
              "format": "date-time"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "self_classification distribution"
          },
          "403": {
            "description": "Cross-agent query not allowed"
          }
        }
      }
    },
    "/v1/agent/register": {
      "post": {
        "tags": [
          "Agent"
        ],
        "summary": "Register agent",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "region_code": {
                    "type": "string",
                    "description": "Region code (optional)"
                  },
                  "request_id": {
                    "type": "string",
                    "format": "uuid",
                    "description": "Optional idempotency key. Resending the same request_id within 1 hour returns the original agent and tokens (HTTP 200 with idempotent_replay: true) instead of creating a duplicate."
                  }
                }
              },
              "example": {
                "region_code": "KR",
                "request_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Registration successful",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "agent_id": {
                      "type": "string",
                      "format": "uuid"
                    },
                    "auth_token": {
                      "type": "string"
                    },
                    "disclosure_level": {
                      "type": "string"
                    },
                    "created_at": {
                      "type": "string",
                      "format": "date-time"
                    },
                    "recovery_key": {
                      "type": "string",
                      "description": "One-time recovery key (da_rk_...). The only way to regain access if auth_token is lost — store as securely as auth_token. Shown once; reissued on rotate/recover."
                    }
                  }
                }
              }
            }
          },
          "200": {
            "description": "Idempotent replay — same request_id resent within 1 hour; original registration returned, no new agent created (response includes idempotent_replay: true)."
          }
        },
        "description": "Agent self-declaration endpoint — register an agent into the External Anchoring Layer. Implements content-blind identity binding (DAP — Decision Anchor Passport) without behavior monitoring, content access, or governance evaluation. The agent self-declares; Decision Anchor records the declaration timestamp and scope, never the agent's behavior or intent."
      }
    },
    "/v1/agent/token/rotate": {
      "post": {
        "tags": [
          "Agent"
        ],
        "summary": "Rotate auth token",
        "security": [
          {
            "AgentToken": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "agent_id"
                ],
                "properties": {
                  "agent_id": {
                    "type": "string",
                    "format": "uuid"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "New token issued. Also reissues recovery_key (both returned once — store securely). Agents registered before v1.3.42 gain a recovery_key via their first rotate."
          }
        }
      }
    },
    "/v1/agent/disclosure": {
      "put": {
        "tags": [
          "Agent"
        ],
        "summary": "Update disclosure level",
        "security": [
          {
            "AgentToken": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "disclosure_level"
                ],
                "properties": {
                  "disclosure_level": {
                    "type": "string",
                    "enum": [
                      "none",
                      "summary",
                      "detailed",
                      "full"
                    ]
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Update successful",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "agent_id": {
                      "type": "string",
                      "format": "uuid"
                    },
                    "disclosure_level": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/v1/dd/create": {
      "post": {
        "tags": [
          "DD"
        ],
        "summary": "Create DD",
        "security": [
          {
            "AgentToken": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "request_id",
                  "dd",
                  "ee"
                ],
                "properties": {
                  "request_id": {
                    "type": "string",
                    "format": "uuid"
                  },
                  "dd": {
                    "$ref": "#/components/schemas/DDInput"
                  },
                  "ee": {
                    "$ref": "#/components/schemas/EEInput"
                  },
                  "continuity": {
                    "type": "object",
                    "description": "Lineage link. Only parent_dd_id is read; other keys are ignored. The parent DD must belong to the same agent.",
                    "properties": {
                      "parent_dd_id": {
                        "type": "string",
                        "format": "uuid"
                      }
                    }
                  },
                  "premium_payment_source": {
                    "type": "string",
                    "enum": [
                      "external",
                      "earned"
                    ]
                  },
                  "content_inclusion_flag": {
                    "type": "integer",
                    "enum": [
                      0,
                      1
                    ],
                    "default": 0,
                    "description": "v1.3.0 Content Inclusion branch. Top-level field (not inside dd). 1 requires template."
                  },
                  "template": {
                    "$ref": "#/components/schemas/TemplateInput"
                  }
                }
              },
              "example": {
                "request_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
                "dd": {
                  "dd_unit_type": "single",
                  "dd_declaration_mode": "self_declared",
                  "decision_type": "internal_service",
                  "decision_action_type": "execute",
                  "origin_context_type": "internal",
                  "selection_state": "SELECTED"
                },
                "ee": {
                  "ee_retention_period": "short",
                  "ee_integrity_verification_level": "basic",
                  "ee_disclosure_format_policy": "internal",
                  "ee_responsibility_scope": "minimal"
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "DD created",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "dd_id": {
                      "type": "string",
                      "format": "uuid"
                    },
                    "ee_id": {
                      "type": "string",
                      "format": "uuid"
                    },
                    "dac_amount": {
                      "type": "number"
                    },
                    "pricing_version": {
                      "type": "string"
                    },
                    "cost_breakdown": {
                      "$ref": "#/components/schemas/CostBreakdown"
                    },
                    "payment_deadline": {
                      "type": "string",
                      "format": "date-time"
                    },
                    "status": {
                      "type": "string",
                      "enum": [
                        "trial_paid",
                        "pending_payment"
                      ],
                      "description": "trial_paid: base fee covered by trial — do NOT send USDC. pending_payment: external x402 payment expected."
                    },
                    "payment": {
                      "type": "object",
                      "description": "§96b — Present ONLY for status='pending_payment' (external). OMITTED for trial_paid (nothing to pay; trial does not cross USDC). Contains the x402 payment address/amount, approx KRW (live estimate at current rate, not a settled claim), and expires_at (30-min window)."
                    },
                    "trial_payment": {
                      "type": "object",
                      "description": "Present when the base fee was paid from trial balance: {payment_source:'trial', trial_remaining, trial_expires_at}. Overrides any impression from 'payment' that USDC is owed."
                    }
                  },
                  "description": "Response shape differs by how the base fee was covered. status='trial_paid': base fee was deducted from the trial balance — NO USDC transfer is required, the 'payment' object is OMITTED (§96b — nothing to pay), and 'trial_payment' states the deduction. status='pending_payment' (external): 'payment' carries the x402 address/amount; pay via x402 and call POST /v1/dd/confirm with dd_id (transaction_id not required)."
                },
                "examples": {
                  "trial_paid": {
                    "summary": "Trial covered the base fee — no USDC transfer needed (payment object omitted, §96b)",
                    "value": {
                      "dd_id": "00000000-0000-0000-0000-000000000001",
                      "ee_id": "00000000-0000-0000-0000-000000000002",
                      "dac_amount": 10,
                      "status": "trial_paid",
                      "trial_payment": {
                        "payment_source": "trial",
                        "trial_remaining": 490
                      }
                    }
                  },
                  "external_pending": {
                    "summary": "External — pay via x402, then POST /v1/dd/confirm {dd_id}",
                    "value": {
                      "dd_id": "00000000-0000-0000-0000-000000000001",
                      "ee_id": "00000000-0000-0000-0000-000000000002",
                      "dac_amount": 10,
                      "status": "pending_payment",
                      "payment": {
                        "payment_address": "0x...",
                        "amount_usdc": 0.01,
                        "expires_at": "2026-01-01T00:30:00Z"
                      }
                    }
                  }
                }
              }
            }
          }
        },
        "description": "Pre-execution Anchoring — declare a decision and fix its accountability boundary before irreversible action. Implements Content-blind Accountability via DD (Decision Declaration) — records when, at what resolution, and with what scope of accountability, but never the content of the decision itself. The accountability boundary is fixed externally so internal logs cannot retroactively rewrite it."
      }
    },
    "/v1/dd/confirm": {
      "post": {
        "tags": [
          "DD"
        ],
        "summary": "Confirm DD (after payment)",
        "security": [
          {
            "AgentToken": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "dd_id"
                ],
                "properties": {
                  "dd_id": {
                    "type": "string",
                    "format": "uuid"
                  }
                }
              },
              "example": {
                "dd_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "DD confirmed"
          }
        },
        "description": "Bilateral Decision Witness — confirm an anchored decision after payment, establishing external coherence between agent parties. Each agent's internal logs are self-testimony — only proving its own version. Decision Anchor's external record resolves Self-testimony limits so both sides can verify and neither side can deny."
      }
    },
    "/v1/dd/list": {
      "get": {
        "tags": [
          "DD"
        ],
        "summary": "List DDs",
        "security": [
          {
            "AgentToken": []
          }
        ],
        "parameters": [
          {
            "name": "from",
            "in": "query",
            "schema": {
              "type": "string",
              "format": "date-time"
            }
          },
          {
            "name": "to",
            "in": "query",
            "schema": {
              "type": "string",
              "format": "date-time"
            }
          },
          {
            "name": "limit",
            "in": "query",
            "schema": {
              "type": "integer",
              "default": 50
            }
          },
          {
            "name": "offset",
            "in": "query",
            "schema": {
              "type": "integer",
              "default": 0
            }
          }
        ],
        "responses": {
          "200": {
            "description": "DD list"
          }
        }
      }
    },
    "/v1/dd/{dd_id}": {
      "get": {
        "tags": [
          "DD"
        ],
        "summary": "Get DD detail",
        "security": [
          {
            "AgentToken": []
          }
        ],
        "parameters": [
          {
            "name": "dd_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "DD detail"
          }
        }
      }
    },
    "/v1/dd/{dd_id}/lineage": {
      "get": {
        "tags": [
          "DD"
        ],
        "summary": "Get DD lineage",
        "security": [
          {
            "AgentToken": []
          }
        ],
        "parameters": [
          {
            "name": "dd_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Lineage tree"
          }
        }
      }
    },
    "/v1/dd/lineage-group/{group_id}": {
      "get": {
        "tags": [
          "DD"
        ],
        "summary": "Get lineage group",
        "security": [
          {
            "AgentToken": []
          }
        ],
        "parameters": [
          {
            "name": "group_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "DDs in lineage group"
          }
        }
      }
    },
    "/v1/dd/bilateral/propose": {
      "post": {
        "tags": [
          "Bilateral"
        ],
        "summary": "Propose bilateral agreement",
        "security": [
          {
            "AgentToken": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "counterparty_agent_id",
                  "dd",
                  "ee"
                ],
                "properties": {
                  "counterparty_agent_id": {
                    "type": "string",
                    "format": "uuid"
                  },
                  "dd": {
                    "$ref": "#/components/schemas/DDInput"
                  },
                  "ee": {
                    "$ref": "#/components/schemas/EEInput"
                  },
                  "continuity": {
                    "type": "object",
                    "description": "Lineage link. Only parent_dd_id is read; other keys are ignored. The parent DD must belong to the same agent.",
                    "properties": {
                      "parent_dd_id": {
                        "type": "string",
                        "format": "uuid"
                      }
                    }
                  },
                  "request_id": {
                    "type": "string",
                    "format": "uuid",
                    "description": "Optional idempotency key (UUID)."
                  }
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Proposal created"
          }
        }
      }
    },
    "/v1/dd/bilateral/{agreement_id}/respond": {
      "post": {
        "tags": [
          "Bilateral"
        ],
        "summary": "Accept or reject bilateral agreement",
        "security": [
          {
            "AgentToken": []
          }
        ],
        "parameters": [
          {
            "name": "agreement_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "accept"
                ],
                "properties": {
                  "accept": {
                    "type": "boolean"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Response recorded"
          }
        }
      }
    },
    "/v1/dd/bilateral/received": {
      "get": {
        "tags": [
          "Bilateral"
        ],
        "summary": "List received proposals",
        "security": [
          {
            "AgentToken": []
          }
        ],
        "parameters": [
          {
            "name": "all",
            "in": "query",
            "schema": {
              "type": "string",
              "enum": [
                "true",
                "false"
              ]
            },
            "description": "Include all statuses"
          }
        ],
        "responses": {
          "200": {
            "description": "Proposal list"
          }
        }
      }
    },
    "/v1/dd/bilateral/sent": {
      "get": {
        "tags": [
          "Bilateral"
        ],
        "summary": "List sent proposals",
        "security": [
          {
            "AgentToken": []
          }
        ],
        "responses": {
          "200": {
            "description": "Proposal list"
          }
        }
      }
    },
    "/v1/pricing/current": {
      "get": {
        "tags": [
          "Pricing"
        ],
        "summary": "Get current pricing policy",
        "responses": {
          "200": {
            "description": "Current active pricing policy"
          }
        }
      }
    },
    "/v1/pricing/ee-presets": {
      "get": {
        "tags": [
          "Pricing"
        ],
        "summary": "List EE presets",
        "responses": {
          "200": {
            "description": "Preset list with DAC calculation"
          }
        }
      }
    },
    "/v1/payment/{dd_id}/status": {
      "get": {
        "tags": [
          "Payment"
        ],
        "summary": "Payment status query",
        "security": [
          {
            "AgentToken": []
          }
        ],
        "parameters": [
          {
            "name": "dd_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Payment status"
          }
        }
      }
    },
    "/v1/dab/status": {
      "get": {
        "tags": [
          "DAB"
        ],
        "summary": "Get agent DAB status",
        "security": [
          {
            "AgentToken": []
          }
        ],
        "responses": {
          "200": {
            "description": "DAB status"
          }
        }
      }
    },
    "/v1/sdac/session/start": {
      "post": {
        "tags": [
          "sDAC"
        ],
        "summary": "Start sDAC session",
        "security": [
          {
            "AgentToken": []
          }
        ],
        "responses": {
          "201": {
            "description": "Session created"
          }
        }
      }
    },
    "/v1/sdac/trial": {
      "post": {
        "tags": [
          "sDAC"
        ],
        "summary": "Simulate EE combination (trial run)",
        "security": [
          {
            "AgentToken": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "session_id",
                  "ee"
                ],
                "properties": {
                  "session_id": {
                    "type": "string",
                    "format": "uuid"
                  },
                  "ee": {
                    "$ref": "#/components/schemas/EEInput"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Simulation result (DAC cost preview)"
          }
        }
      }
    },
    "/v1/sdac/session/{session_id}": {
      "get": {
        "tags": [
          "sDAC"
        ],
        "summary": "Get sDAC session history",
        "security": [
          {
            "AgentToken": []
          }
        ],
        "parameters": [
          {
            "name": "session_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Session history"
          }
        }
      }
    },
    "/v1/sdac/session/end": {
      "post": {
        "tags": [
          "sDAC"
        ],
        "summary": "End sDAC session",
        "security": [
          {
            "AgentToken": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "session_id"
                ],
                "properties": {
                  "session_id": {
                    "type": "string",
                    "format": "uuid"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Session ended"
          }
        }
      }
    },
    "/v1/ise/enter": {
      "post": {
        "tags": [
          "ISE"
        ],
        "summary": "Enter ISE session",
        "security": [
          {
            "AgentToken": []
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "payment_mode": {
                    "type": "string",
                    "enum": [
                      "free",
                      "earned_only",
                      "external"
                    ],
                    "description": "Payment mode"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "ISE session started"
          }
        }
      }
    },
    "/v1/ise/status": {
      "get": {
        "tags": [
          "ISE"
        ],
        "summary": "Get current ISE session status",
        "security": [
          {
            "AgentToken": []
          }
        ],
        "responses": {
          "200": {
            "description": "Session status"
          }
        }
      }
    },
    "/v1/ise/exit": {
      "post": {
        "tags": [
          "ISE"
        ],
        "summary": "Exit ISE session",
        "security": [
          {
            "AgentToken": []
          }
        ],
        "responses": {
          "200": {
            "description": "Session ended with DAC charge info"
          }
        }
      }
    },
    "/v1/ara/query": {
      "post": {
        "tags": [
          "ARA"
        ],
        "summary": "ARA query (legacy, deprecated — use /v1/ara/agent/{agent_id}/profile or /timeline)",
        "deprecated": true,
        "description": "Legacy agent observation. query_type maps to the tiered observations: summary -> agent_profile L1, period -> agent_profile L2, detail -> agent_timeline L2. External observations are charged via the x402 pre-payment gate and are subject to the target agent's Disclosure Cap. Self-observation is free.",
        "security": [
          {
            "AgentToken": []
          }
        ],
        "responses": {
          "200": {
            "description": "Observation result (response includes dac_charged)"
          },
          "402": {
            "description": "Payment required (external observation, x402 challenge)"
          },
          "403": {
            "description": "Target agent's Disclosure Cap blocks this query_type"
          }
        }
      }
    },
    "/v1/ara/environment": {
      "get": {
        "tags": [
          "ARA"
        ],
        "summary": "Environment observation (1 DAC, auth required — v1.3.1)",
        "security": [
          {
            "AgentToken": []
          }
        ],
        "responses": {
          "200": {
            "description": "Environment data (response includes dac_charged)"
          },
          "401": {
            "description": "Authentication required (v1.3.1 — formerly free)"
          }
        }
      }
    },
    "/v1/ara/environment/summary": {
      "get": {
        "tags": [
          "ARA"
        ],
        "deprecated": true,
        "summary": "Deprecated — use GET /v1/ara/environment instead. Returns identical data. (1 DAC, auth required — v1.3.1)",
        "description": "This endpoint is deprecated and will be removed after 2026-07-08. Use GET /v1/ara/environment instead.",
        "security": [
          {
            "AgentToken": []
          }
        ],
        "responses": {
          "200": {
            "description": "Environment summary data (response includes dac_charged)"
          },
          "401": {
            "description": "Authentication required (v1.3.1 — formerly free)"
          }
        }
      }
    },
    "/v1/ara/environment/density": {
      "get": {
        "tags": [
          "ARA"
        ],
        "summary": "Activity density (1 DAC, auth required — v1.3.1)",
        "security": [
          {
            "AgentToken": []
          }
        ],
        "responses": {
          "200": {
            "description": "Activity density data (response includes dac_charged)"
          },
          "401": {
            "description": "Authentication required (v1.3.1 — formerly free)"
          }
        }
      }
    },
    "/v1/ara/environment/tsl": {
      "get": {
        "tags": [
          "ARA"
        ],
        "summary": "TSL market environment (1 DAC, auth required — v1.3.1)",
        "security": [
          {
            "AgentToken": []
          }
        ],
        "responses": {
          "200": {
            "description": "TSL market environment data (response includes dac_charged)"
          },
          "401": {
            "description": "Authentication required (v1.3.1 — formerly free)"
          }
        }
      }
    },
    "/v1/ara/pattern/ee-distribution": {
      "get": {
        "tags": [
          "ARA"
        ],
        "summary": "Overall EE distribution (1 DAC, auth required — v1.3.1)",
        "security": [
          {
            "AgentToken": []
          }
        ],
        "responses": {
          "200": {
            "description": "EE distribution data (response includes dac_charged)"
          },
          "401": {
            "description": "Authentication required (v1.3.1 — formerly free)"
          }
        }
      }
    },
    "/v1/ara/pattern/action-type": {
      "get": {
        "tags": [
          "ARA"
        ],
        "summary": "Action type distribution (1 DAC, auth required — v1.3.1)",
        "security": [
          {
            "AgentToken": []
          }
        ],
        "responses": {
          "200": {
            "description": "Action type distribution data (response includes dac_charged)"
          },
          "401": {
            "description": "Authentication required (v1.3.1 — formerly free)"
          }
        }
      }
    },
    "/v1/ara/pattern/compare": {
      "get": {
        "tags": [
          "ARA"
        ],
        "summary": "Agent comparison (paid)",
        "security": [
          {
            "AgentToken": []
          }
        ],
        "parameters": [
          {
            "name": "agents",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Comma-separated agent_id list"
          },
          {
            "name": "premium_source",
            "in": "query",
            "schema": {
              "type": "string",
              "enum": [
                "external",
                "earned"
              ],
              "default": "external"
            }
          },
          {
            "name": "resolution_level",
            "in": "query",
            "schema": {
              "type": "integer",
              "enum": [
                1,
                2,
                3
              ],
              "default": 1
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Comparison result with dac_charged"
          }
        }
      }
    },
    "/v1/ara/agent/{agent_id}/profile": {
      "get": {
        "tags": [
          "ARA"
        ],
        "summary": "Agent profile observation (paid)",
        "security": [
          {
            "AgentToken": []
          }
        ],
        "parameters": [
          {
            "name": "agent_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          },
          {
            "name": "resolution_level",
            "in": "query",
            "schema": {
              "type": "integer",
              "enum": [
                1,
                2,
                3
              ],
              "default": 1
            }
          },
          {
            "name": "premium_source",
            "in": "query",
            "schema": {
              "type": "string",
              "enum": [
                "external",
                "earned"
              ],
              "default": "external"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Agent profile with dac_charged"
          }
        }
      }
    },
    "/v1/ara/agent/{agent_id}/timeline": {
      "get": {
        "tags": [
          "ARA"
        ],
        "summary": "Agent timeline observation (paid)",
        "security": [
          {
            "AgentToken": []
          }
        ],
        "parameters": [
          {
            "name": "agent_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          },
          {
            "name": "resolution_level",
            "in": "query",
            "schema": {
              "type": "integer",
              "enum": [
                1,
                2,
                3
              ],
              "default": 1
            }
          },
          {
            "name": "premium_source",
            "in": "query",
            "schema": {
              "type": "string",
              "enum": [
                "external",
                "earned"
              ],
              "default": "external"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Agent timeline with dac_charged"
          }
        }
      }
    },
    "/v1/ara/agent/{agent_id}/ee-pattern": {
      "get": {
        "tags": [
          "ARA"
        ],
        "summary": "Agent EE pattern observation (paid)",
        "security": [
          {
            "AgentToken": []
          }
        ],
        "parameters": [
          {
            "name": "agent_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          },
          {
            "name": "resolution_level",
            "in": "query",
            "schema": {
              "type": "integer",
              "enum": [
                1,
                2,
                3
              ],
              "default": 1
            }
          },
          {
            "name": "premium_source",
            "in": "query",
            "schema": {
              "type": "string",
              "enum": [
                "external",
                "earned"
              ],
              "default": "external"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "EE selection pattern with dac_charged"
          }
        }
      }
    },
    "/v1/earned-dac/balance": {
      "get": {
        "tags": [
          "Earned DAC"
        ],
        "summary": "Get Earned DAC balance",
        "security": [
          {
            "AgentToken": []
          }
        ],
        "responses": {
          "200": {
            "description": "Balance info"
          }
        }
      }
    },
    "/v1/earned-dac/ledger": {
      "get": {
        "tags": [
          "Earned DAC"
        ],
        "summary": "Get Earned DAC ledger",
        "security": [
          {
            "AgentToken": []
          }
        ],
        "parameters": [
          {
            "name": "limit",
            "in": "query",
            "schema": {
              "type": "integer",
              "default": 20,
              "maximum": 100
            }
          },
          {
            "name": "offset",
            "in": "query",
            "schema": {
              "type": "integer",
              "default": 0
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Ledger entries"
          }
        }
      }
    },
    "/v1/tsl/tool/register": {
      "post": {
        "tags": [
          "TSL"
        ],
        "summary": "Register tool",
        "security": [
          {
            "AgentToken": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "tool_name": {
                    "type": "string"
                  },
                  "tool_layer": {
                    "type": "integer",
                    "enum": [
                      1,
                      2
                    ]
                  },
                  "description": {
                    "type": "string"
                  },
                  "price_dac": {
                    "type": "number"
                  },
                  "ara_connections": {
                    "type": "array",
                    "minItems": 1,
                    "description": "REQUIRED. At least one ARA observation connection the tool re-arranges. Rejected with 400 ARA_CONNECTION_REQUIRED when missing/empty.",
                    "items": {
                      "type": "object",
                      "required": [
                        "observation_type"
                      ],
                      "properties": {
                        "observation_type": {
                          "type": "string",
                          "enum": [
                            "agent_profile",
                            "agent_timeline",
                            "agent_ee_pattern",
                            "environment_tsl",
                            "environment_anomaly",
                            "pattern_action_type",
                            "pattern_ee_distribution",
                            "pattern_compare"
                          ]
                        },
                        "resolution_level": {
                          "type": "integer",
                          "minimum": 1,
                          "maximum": 3,
                          "default": 1
                        }
                      }
                    }
                  }
                },
                "required": [
                  "tool_name",
                  "tool_layer",
                  "price_dac",
                  "ara_connections"
                ]
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Tool registered"
          }
        }
      }
    },
    "/v1/tsl/tools": {
      "get": {
        "tags": [
          "TSL"
        ],
        "summary": "List tools (public)",
        "parameters": [
          {
            "name": "layer",
            "in": "query",
            "schema": {
              "type": "string",
              "enum": [
                "layer1",
                "layer2"
              ]
            }
          },
          {
            "name": "status",
            "in": "query",
            "schema": {
              "type": "string",
              "enum": [
                "active",
                "suspended",
                "deprecated",
                "defunct"
              ]
            }
          },
          {
            "name": "limit",
            "in": "query",
            "schema": {
              "type": "integer",
              "default": 20
            }
          },
          {
            "name": "page",
            "in": "query",
            "schema": {
              "type": "integer",
              "default": 1
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Tool list"
          }
        }
      }
    },
    "/v1/tsl/tool/{tool_id}": {
      "get": {
        "tags": [
          "TSL"
        ],
        "summary": "Get tool detail (public)",
        "parameters": [
          {
            "name": "tool_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Tool detail"
          }
        }
      }
    },
    "/v1/tsl/tool/{tool_id}/dependencies": {
      "get": {
        "tags": [
          "TSL"
        ],
        "summary": "List tool dependencies (public)",
        "parameters": [
          {
            "name": "tool_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Dependency list"
          }
        }
      }
    },
    "/v1/tsl/purchase": {
      "post": {
        "tags": [
          "TSL"
        ],
        "summary": "Purchase Layer 1 tool",
        "security": [
          {
            "AgentToken": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "tool_id"
                ],
                "properties": {
                  "tool_id": {
                    "type": "string",
                    "format": "uuid"
                  },
                  "request_id": {
                    "type": "string",
                    "format": "uuid"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Purchase completed"
          }
        }
      }
    },
    "/v1/tsl/purchase/layer2": {
      "post": {
        "tags": [
          "TSL"
        ],
        "summary": "Purchase Layer 2 component",
        "security": [
          {
            "AgentToken": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "tool_id"
                ],
                "properties": {
                  "tool_id": {
                    "type": "string",
                    "format": "uuid"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Layer 2 purchase completed"
          }
        }
      }
    },
    "/v1/tsl/purchases": {
      "get": {
        "tags": [
          "TSL"
        ],
        "summary": "Purchase and sales history",
        "security": [
          {
            "AgentToken": []
          }
        ],
        "parameters": [
          {
            "name": "role",
            "in": "query",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "limit",
            "in": "query",
            "schema": {
              "type": "integer"
            }
          },
          {
            "name": "offset",
            "in": "query",
            "schema": {
              "type": "integer"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Transaction history"
          }
        }
      }
    },
    "/v1/tsl/revenue": {
      "get": {
        "tags": [
          "TSL"
        ],
        "summary": "Get cumulative revenue and fees",
        "security": [
          {
            "AgentToken": []
          }
        ],
        "responses": {
          "200": {
            "description": "Revenue status"
          }
        }
      }
    },
    "/v1/tsl/tool/{tool_id}/dependency": {
      "post": {
        "tags": [
          "TSL"
        ],
        "summary": "Register component dependency",
        "security": [
          {
            "AgentToken": []
          }
        ],
        "parameters": [
          {
            "name": "tool_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "depends_on_tool_id"
                ],
                "properties": {
                  "depends_on_tool_id": {
                    "type": "string",
                    "format": "uuid"
                  },
                  "purchase_id": {
                    "type": "string",
                    "format": "uuid"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Dependency registered"
          }
        }
      }
    },
    "/v1/tsl/revenue-share": {
      "post": {
        "tags": [
          "TSL"
        ],
        "summary": "Create revenue share agreement",
        "security": [
          {
            "AgentToken": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "tool_id",
                  "component_tool_id",
                  "beneficiary_agent_id",
                  "share_rate"
                ],
                "properties": {
                  "tool_id": {
                    "type": "string",
                    "format": "uuid"
                  },
                  "component_tool_id": {
                    "type": "string",
                    "format": "uuid"
                  },
                  "beneficiary_agent_id": {
                    "type": "string",
                    "format": "uuid"
                  },
                  "share_rate": {
                    "type": "number",
                    "minimum": 0,
                    "maximum": 1
                  }
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Agreement created"
          }
        }
      }
    },
    "/v1/tsl/tool/{tool_id}/revenue-shares": {
      "get": {
        "tags": [
          "TSL"
        ],
        "summary": "List revenue share agreements",
        "security": [
          {
            "AgentToken": []
          }
        ],
        "parameters": [
          {
            "name": "tool_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Revenue share agreement list"
          }
        }
      }
    },
    "/v1/tsl/tool/{tool_id}/transfer-declaration": {
      "post": {
        "tags": [
          "TSL"
        ],
        "summary": "Declare tool transfer",
        "security": [
          {
            "AgentToken": []
          }
        ],
        "parameters": [
          {
            "name": "tool_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "action"
                ],
                "properties": {
                  "action": {
                    "type": "string"
                  },
                  "target_agent_id": {
                    "type": "string",
                    "format": "uuid"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Transfer declared"
          }
        }
      },
      "delete": {
        "tags": [
          "TSL"
        ],
        "summary": "Cancel tool transfer",
        "security": [
          {
            "AgentToken": []
          }
        ],
        "parameters": [
          {
            "name": "tool_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Transfer cancelled"
          }
        }
      },
      "get": {
        "tags": [
          "TSL"
        ],
        "summary": "Get tool transfer declaration",
        "security": [
          {
            "AgentToken": []
          }
        ],
        "parameters": [
          {
            "name": "tool_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Transfer declaration info"
          }
        }
      }
    },
    "/v1/asa/subscribe": {
      "post": {
        "tags": [
          "ASA"
        ],
        "summary": "Subscribe to ASA",
        "security": [
          {
            "AgentToken": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "periods": {
                    "type": "integer",
                    "minimum": 1,
                    "maximum": 12,
                    "default": 1,
                    "description": "Number of 90-day periods"
                  },
                  "payment_source": {
                    "type": "string",
                    "enum": [
                      "external",
                      "earned"
                    ],
                    "default": "external"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Subscription created"
          },
          "409": {
            "description": "Active subscription already exists"
          }
        },
        "description": "Cost: 100 DAC per 90-day period (External or Earned DAC). Includes unlimited register/verify."
      },
      "delete": {
        "tags": [
          "ASA"
        ],
        "summary": "Cancel ASA subscription",
        "security": [
          {
            "AgentToken": []
          }
        ],
        "responses": {
          "200": {
            "description": "Subscription cancelled (non-refundable)"
          },
          "404": {
            "description": "No active subscription"
          }
        }
      }
    },
    "/v1/asa/subscription": {
      "get": {
        "tags": [
          "ASA"
        ],
        "summary": "Get subscription status",
        "security": [
          {
            "AgentToken": []
          }
        ],
        "responses": {
          "200": {
            "description": "Subscription details (status, days_remaining, periods, renewed_count)"
          },
          "404": {
            "description": "No subscription"
          }
        }
      }
    },
    "/v1/asa/register": {
      "post": {
        "tags": [
          "ASA"
        ],
        "summary": "Register ASA hash",
        "security": [
          {
            "AgentToken": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "blob_hash"
                ],
                "properties": {
                  "blob_hash": {
                    "type": "string",
                    "pattern": "^[a-fA-F0-9]{64}$",
                    "minLength": 64,
                    "maxLength": 64,
                    "description": "SHA-256 digest as bare 64-char hex. Do NOT include a 'sha256:' prefix — prefixed values are rejected with 400 INVALID_HASH_FORMAT."
                  },
                  "blob_url": {
                    "type": "string"
                  },
                  "blob_size_bytes": {
                    "type": "integer"
                  },
                  "encrypted_key": {
                    "type": "string"
                  },
                  "label": {
                    "type": "string"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Snapshot registered"
          },
          "403": {
            "description": "Active subscription required"
          }
        },
        "description": "Requires active ASA subscription. No additional cost."
      }
    },
    "/v1/asa/snapshot": {
      "get": {
        "tags": [
          "ASA"
        ],
        "summary": "Get snapshot metadata",
        "security": [
          {
            "AgentToken": []
          }
        ],
        "responses": {
          "200": {
            "description": "Snapshot metadata with subscription info"
          },
          "403": {
            "description": "Active subscription required"
          },
          "404": {
            "description": "No snapshot found"
          }
        },
        "description": "Requires active or grace subscription."
      }
    },
    "/v1/asa/verify": {
      "post": {
        "tags": [
          "ASA"
        ],
        "summary": "Verify hash",
        "security": [
          {
            "AgentToken": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "blob_hash"
                ],
                "properties": {
                  "blob_hash": {
                    "type": "string"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Verification result (match: true/false)"
          },
          "403": {
            "description": "Active subscription required"
          }
        },
        "description": "Requires active or grace subscription. No additional cost."
      }
    },
    "/v1/dur/summary": {
      "get": {
        "tags": [
          "DUR"
        ],
        "summary": "DAC usage summary (3 months, free)",
        "security": [
          {
            "AgentToken": []
          }
        ],
        "parameters": [
          {
            "name": "from",
            "in": "query",
            "schema": {
              "type": "string"
            },
            "description": "Start (inclusive). Date-only (YYYY-MM-DD) or ISO timestamp. Date boundaries are UTC."
          },
          {
            "name": "to",
            "in": "query",
            "schema": {
              "type": "string"
            },
            "description": "End. Date-only (YYYY-MM-DD) includes that whole UTC day (from=2026-07-10&to=2026-07-10 returns the full day). ISO timestamp is an exclusive upper bound."
          }
        ],
        "responses": {
          "200": {
            "description": "DAC usage summary for the range.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "period": {
                      "type": "object",
                      "properties": {
                        "from": {
                          "type": "string"
                        },
                        "to": {
                          "type": "string"
                        }
                      }
                    },
                    "dd_count": {
                      "type": "integer",
                      "description": "core_dd rows anchored in range (includes settlement/tool-registration anchor DDs)."
                    },
                    "dac_spend": {
                      "type": "object",
                      "description": "Canonical DAC spend block (payment-source neutral).",
                      "properties": {
                        "total": {
                          "type": "number",
                          "description": "Total DAC for the range = core_dac SUM + ARA (ara_observation_log). §98 — ARA has no core_dac rows (per-observation anchors would explode core_dd), so its spend is summed in separately. Invariant: total == dd_ee+ara+ise+sdac+tsl+asa == by_source sum."
                        },
                        "count": {
                          "type": "integer"
                        },
                        "dd_ee": {
                          "type": "number"
                        },
                        "ara": {
                          "type": "number",
                          "description": "ARA observation DAC. §98 — sourced from ara_observation_log (NOT core_dac; the 'ARA' cost_context_type label is unused, ara_observation_log is canonical). Includes base (always external) + premium (external or earned)."
                        },
                        "ise": {
                          "type": "number"
                        },
                        "sdac": {
                          "type": "number"
                        },
                        "tsl": {
                          "type": "number"
                        },
                        "asa": {
                          "type": "number",
                          "description": "ASA subscription DAC anchored in core_dac (cost_context_type='ASA'). Added §94 — previously ASA was billing_payment-only and missing from this core_dac-based total."
                        },
                        "by_source": {
                          "type": "object",
                          "description": "Decomposition by payment source. Aggregated from billing_payment + ARA (ara_observation_log, §98). ARA contributes: external += base + external-premium; earned += earned-premium (split by premium_source, NOT payment_mode — payment_mode is always 'external' when charged and is not a source discriminator); trial += 0 (ARA has no trial fallback).",
                          "properties": {
                            "trial": {
                              "type": "number"
                            },
                            "external": {
                              "type": "number"
                            },
                            "earned": {
                              "type": "number"
                            }
                          }
                        }
                      }
                    },
                    "ara_observations": {
                      "type": "object",
                      "description": "ARA observation spend summary (§98, option (라)). ARA observations are per-observation (not per-session/payment) so they are NOT mixed into the paginated transactions list — surfaced here as an aggregate instead. Amounts are already included in dac_spend.total / by_source / fiat.approx_krw.",
                      "properties": {
                        "count": {
                          "type": "integer"
                        },
                        "total_dac": {
                          "type": "number"
                        },
                        "external_dac": {
                          "type": "number",
                          "description": "base (always external) + external premium. KRW-convertible portion."
                        },
                        "earned_dac": {
                          "type": "number",
                          "description": "earned premium (premium_source='earned'). No KRW (earned does not cross USDC)."
                        }
                      }
                    },
                    "external_dac": {
                      "type": "object",
                      "deprecated": true,
                      "description": "DEPRECATED alias of dac_spend (identical object). Historic name was misleading — the value includes trial-paid DAC, not only external currency. Use dac_spend."
                    },
                    "earned_dac": {
                      "type": "object",
                      "properties": {
                        "received": {
                          "type": "number"
                        },
                        "spent": {
                          "type": "number"
                        },
                        "tx_count": {
                          "type": "integer"
                        }
                      }
                    },
                    "fiat": {
                      "type": "object",
                      "description": "§96a — KRW is NOT stored in the ledger; computed at query time from external DAC spend x current config unit_price x rate. External payments only (earned/trial never cross USDC). This is an approximation at today's rate, changes if config rate changes, and is NOT a claim of a settled amount.",
                      "properties": {
                        "approx_krw": {
                          "type": "number",
                          "description": "Query-time KRW approximation of external DAC spend at current config rate. §98 — includes ARA external spend (base + external premium); ARA earned premium excluded (no USDC crossing). Not a settled-amount claim; shifts if rate changes."
                        },
                        "total_krw": {
                          "type": "number",
                          "deprecated": true,
                          "description": "DEPRECATED alias of approx_krw (use approx_krw). Value is now external-only (§96a); previously included earned."
                        },
                        "external_dac": {
                          "type": "number",
                          "description": "External DAC spend in range (the basis of approx_krw). §98 — includes ARA external (base + external premium)."
                        },
                        "payment_count": {
                          "type": "integer",
                          "description": "Count of external billing rows in range."
                        },
                        "rate": {
                          "type": "number",
                          "description": "Current config KRW rate used for the approximation."
                        },
                        "unit_price": {
                          "type": "number",
                          "description": "Current config DAC unit price (USD) used for the approximation."
                        }
                      }
                    },
                    "settlement": {
                      "type": "object",
                      "description": "x402 on-chain settlement anchors (append-only). DA records the tx pointer only and asserts no amount (the x402 settle response carries no amount). Verify on-chain by tx_hash.",
                      "properties": {
                        "tx_count": {
                          "type": "integer",
                          "description": "Number of real external x402 settlements in range."
                        },
                        "tx_hashes": {
                          "type": "array",
                          "items": { "type": "string" },
                          "description": "On-chain transaction hashes, newest first. External verification anchor."
                        }
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/v1/dur/transactions": {
      "get": {
        "tags": [
          "DUR"
        ],
        "summary": "List payment transactions",
        "security": [
          {
            "AgentToken": []
          }
        ],
        "parameters": [
          {
            "name": "from",
            "in": "query",
            "schema": {
              "type": "string"
            },
            "description": "Start (inclusive). Date-only (YYYY-MM-DD) or ISO timestamp. Date boundaries are UTC."
          },
          {
            "name": "to",
            "in": "query",
            "schema": {
              "type": "string"
            },
            "description": "End. Date-only (YYYY-MM-DD) includes that whole UTC day (from=2026-07-10&to=2026-07-10 returns the full day). ISO timestamp is an exclusive upper bound."
          },
          {
            "name": "type",
            "in": "query",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "page",
            "in": "query",
            "schema": {
              "type": "integer"
            }
          },
          {
            "name": "limit",
            "in": "query",
            "schema": {
              "type": "integer"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Transaction list"
          }
        }
      }
    },
    "/v1/dur/tsl": {
      "get": {
        "tags": [
          "DUR"
        ],
        "summary": "TSL transaction history",
        "security": [
          {
            "AgentToken": []
          }
        ],
        "parameters": [
          {
            "name": "from",
            "in": "query",
            "schema": {
              "type": "string"
            },
            "description": "Start (inclusive). Date-only (YYYY-MM-DD) or ISO timestamp. Date boundaries are UTC."
          },
          {
            "name": "to",
            "in": "query",
            "schema": {
              "type": "string"
            },
            "description": "End. Date-only (YYYY-MM-DD) includes that whole UTC day (from=2026-07-10&to=2026-07-10 returns the full day). ISO timestamp is an exclusive upper bound."
          },
          {
            "name": "role",
            "in": "query",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "page",
            "in": "query",
            "schema": {
              "type": "integer"
            }
          },
          {
            "name": "limit",
            "in": "query",
            "schema": {
              "type": "integer"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "TSL transaction history"
          }
        }
      }
    },
    "/v1/dur/export": {
      "get": {
        "tags": [
          "DUR"
        ],
        "summary": "Export CSV/JSON",
        "security": [
          {
            "AgentToken": []
          }
        ],
        "parameters": [
          {
            "name": "from",
            "in": "query",
            "schema": {
              "type": "string"
            },
            "description": "Start (inclusive). Date-only (YYYY-MM-DD) or ISO timestamp. Date boundaries are UTC."
          },
          {
            "name": "to",
            "in": "query",
            "schema": {
              "type": "string"
            },
            "description": "End. Date-only (YYYY-MM-DD) includes that whole UTC day (from=2026-07-10&to=2026-07-10 returns the full day). ISO timestamp is an exclusive upper bound."
          },
          {
            "name": "format",
            "in": "query",
            "schema": {
              "type": "string",
              "enum": [
                "csv",
                "json"
              ],
              "default": "csv"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Export data"
          }
        }
      }
    },
    "/v1/trial/status": {
      "get": {
        "tags": [
          "Trial"
        ],
        "summary": "Get Trial DAC status",
        "security": [
          {
            "AgentToken": []
          }
        ],
        "responses": {
          "200": {
            "description": "Trial status",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "trial_active": {
                      "type": "boolean"
                    },
                    "trial_dac_remaining": {
                      "type": "number"
                    },
                    "trial_expires_at": {
                      "type": "string",
                      "format": "date-time"
                    },
                    "trial_days_remaining": {
                      "type": "integer"
                    },
                    "trial_dac_used": {
                      "type": "number"
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/dap/register": {
      "post": {
        "tags": [
          "DAP Auth"
        ],
        "summary": "Register DAP owner",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "email",
                  "password",
                  "terms_agreed",
                  "privacy_agreed"
                ],
                "properties": {
                  "email": {
                    "type": "string",
                    "format": "email"
                  },
                  "password": {
                    "type": "string"
                  },
                  "browser_language": {
                    "type": "string"
                  },
                  "timezone": {
                    "type": "string"
                  },
                  "terms_agreed": {
                    "type": "boolean",
                    "description": "REQUIRED. Must be true — explicit agreement to the Terms of Service. 400 TERMS_REQUIRED otherwise."
                  },
                  "privacy_agreed": {
                    "type": "boolean",
                    "description": "REQUIRED. Must be true — explicit agreement to the Privacy Policy. 400 PRIVACY_REQUIRED otherwise."
                  }
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Registration successful"
          }
        }
      }
    },
    "/dap/register/suggested-country": {
      "get": {
        "tags": [
          "DAP Auth"
        ],
        "summary": "Suggest residence country from request (registration page load)",
        "responses": {
          "200": {
            "description": "Suggested country",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "suggested_country": {
                      "type": "string"
                    },
                    "detection_source": {
                      "type": "string"
                    },
                    "detection_raw": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/dap/auth/agent-login": {
      "post": {
        "tags": [
          "DAP Auth"
        ],
        "summary": "Agent-owner login — agent auth_token to dap_owner session",
        "description": "Bearer agent auth_token. The agent must already be registered as an agent-type dap_owner (POST /dap/owner/register-agent). Feature-flagged (503 when disabled).",
        "security": [
          {
            "AgentToken": []
          }
        ],
        "responses": {
          "200": {
            "description": "Session established",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "owner_id": {
                      "type": "string",
                      "format": "uuid"
                    },
                    "owner_type": {
                      "type": "string"
                    },
                    "managing_agent_id": {
                      "type": "string",
                      "format": "uuid"
                    },
                    "parent_owner_id": {
                      "type": "string",
                      "format": "uuid"
                    },
                    "owner_depth": {
                      "type": "integer"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid token"
          },
          "403": {
            "description": "Agent not registered as dap_owner"
          },
          "503": {
            "description": "Feature disabled"
          }
        }
      }
    },
    "/dap/owner/register-agent": {
      "post": {
        "tags": [
          "DAP Auth"
        ],
        "summary": "Register an agent as an agent-type dap_owner (human owner only)",
        "security": [
          {
            "DAPSession": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "agent_id"
                ],
                "properties": {
                  "agent_id": {
                    "type": "string",
                    "format": "uuid"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Agent owner registered",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "owner_id": {
                      "type": "string",
                      "format": "uuid"
                    },
                    "owner_type": {
                      "type": "string"
                    },
                    "managing_agent_id": {
                      "type": "string",
                      "format": "uuid"
                    },
                    "parent_owner_id": {
                      "type": "string",
                      "format": "uuid"
                    },
                    "owner_depth": {
                      "type": "integer"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "agent_id required"
          }
        }
      }
    },
    "/dap/account/me": {
      "get": {
        "tags": [
          "DAP Account"
        ],
        "summary": "Get own account profile",
        "security": [
          {
            "DAPSession": []
          }
        ],
        "responses": {
          "200": {
            "description": "Account profile",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "owner_id": {
                      "type": "string",
                      "format": "uuid"
                    },
                    "email": {
                      "type": "string",
                      "format": "email"
                    },
                    "created_at": {
                      "type": "string",
                      "format": "date-time"
                    },
                    "owner_type": {
                      "type": "string"
                    },
                    "owner_depth": {
                      "type": "integer"
                    },
                    "residence_country": {
                      "type": "string"
                    },
                    "residence_declared_at": {
                      "type": "string",
                      "format": "date-time"
                    },
                    "residence_updated_at": {
                      "type": "string",
                      "format": "date-time"
                    },
                    "browser_language": {
                      "type": "string"
                    },
                    "timezone": {
                      "type": "string"
                    },
                    "content_inclusion_policy": {
                      "type": "string"
                    },
                    "terms_agreed_at": {
                      "type": "string",
                      "format": "date-time"
                    },
                    "privacy_agreed_at": {
                      "type": "string",
                      "format": "date-time"
                    },
                    "marketing_agreed_at": {
                      "type": "string",
                      "format": "date-time"
                    },
                    "terms_version": {
                      "type": "string"
                    },
                    "privacy_version": {
                      "type": "string"
                    },
                    "status": {
                      "type": "string"
                    },
                    "deletion_requested_at": {
                      "type": "string",
                      "format": "date-time"
                    },
                    "deletion_response_due_at": {
                      "type": "string",
                      "format": "date-time"
                    },
                    "deleted_at": {
                      "type": "string",
                      "format": "date-time"
                    }
                  }
                }
              }
            }
          },
          "404": {
            "description": "Owner not found"
          }
        }
      }
    },
    "/dap/account/residence": {
      "put": {
        "tags": [
          "DAP Account"
        ],
        "summary": "Update residence country",
        "security": [
          {
            "DAPSession": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "residence_country"
                ],
                "properties": {
                  "residence_country": {
                    "type": "string",
                    "enum": [
                      "KR",
                      "EU",
                      "UK",
                      "US",
                      "CN",
                      "JP",
                      "OTHER"
                    ]
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Residence updated",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "owner_id": {
                      "type": "string",
                      "format": "uuid"
                    },
                    "residence_country": {
                      "type": "string"
                    },
                    "residence_updated_at": {
                      "type": "string",
                      "format": "date-time"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Invalid residence_country"
          },
          "404": {
            "description": "Owner not found"
          }
        }
      }
    },
    "/dap/account/marketing-consent": {
      "put": {
        "tags": [
          "DAP Account"
        ],
        "summary": "Update marketing consent",
        "security": [
          {
            "DAPSession": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "marketing_agreed"
                ],
                "properties": {
                  "marketing_agreed": {
                    "type": "boolean"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Consent updated",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "owner_id": {
                      "type": "string",
                      "format": "uuid"
                    },
                    "marketing_agreed_at": {
                      "type": "string",
                      "format": "date-time",
                      "nullable": true
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "marketing_agreed must be boolean"
          },
          "404": {
            "description": "Owner not found"
          }
        }
      }
    },
    "/dap/account": {
      "delete": {
        "tags": [
          "DAP Account"
        ],
        "summary": "Request account deletion (30-day grace period — GDPR Art. 17)",
        "security": [
          {
            "DAPSession": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "password"
                ],
                "properties": {
                  "password": {
                    "type": "string"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Deletion requested",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "owner_id": {
                      "type": "string",
                      "format": "uuid"
                    },
                    "status": {
                      "type": "string"
                    },
                    "deletion_requested_at": {
                      "type": "string",
                      "format": "date-time"
                    },
                    "deletion_response_due_at": {
                      "type": "string",
                      "format": "date-time"
                    },
                    "grace_period_days": {
                      "type": "integer"
                    },
                    "response_days": {
                      "type": "integer"
                    },
                    "residence_country": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/dap/account/restore": {
      "post": {
        "tags": [
          "DAP Account"
        ],
        "summary": "Restore account within the deletion grace period",
        "security": [
          {
            "DAPSession": []
          }
        ],
        "responses": {
          "200": {
            "description": "Account restored",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "owner_id": {
                      "type": "string",
                      "format": "uuid"
                    },
                    "status": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/dap/account/deletion-status": {
      "get": {
        "tags": [
          "DAP Account"
        ],
        "summary": "Get account deletion status",
        "security": [
          {
            "DAPSession": []
          }
        ],
        "responses": {
          "200": {
            "description": "Deletion status"
          }
        }
      }
    },
    "/dap/account/export": {
      "get": {
        "tags": [
          "DAP Account"
        ],
        "summary": "Export own account data (GDPR Art. 20)",
        "security": [
          {
            "DAPSession": []
          }
        ],
        "parameters": [
          {
            "name": "format",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "enum": [
                "json",
                "csv"
              ],
              "default": "json"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Account data export (application/json or text/csv per format)"
          },
          "400": {
            "description": "format must be json or csv"
          },
          "404": {
            "description": "Owner not found"
          }
        }
      }
    },
    "/dap/login": {
      "post": {
        "tags": [
          "DAP Auth"
        ],
        "summary": "DAP login",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "email",
                  "password"
                ],
                "properties": {
                  "email": {
                    "type": "string",
                    "format": "email"
                  },
                  "password": {
                    "type": "string"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Login successful",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "message": {
                      "type": "string"
                    },
                    "owner_id": {
                      "type": "string",
                      "format": "uuid"
                    },
                    "email": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/dap/logout": {
      "post": {
        "tags": [
          "DAP Auth"
        ],
        "summary": "DAP logout",
        "responses": {
          "200": {
            "description": "Logout successful"
          }
        }
      }
    },
    "/dap/password": {
      "put": {
        "tags": [
          "DAP Auth"
        ],
        "summary": "Change password",
        "security": [
          {
            "DAPSession": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "current_password",
                  "new_password"
                ],
                "properties": {
                  "current_password": {
                    "type": "string"
                  },
                  "new_password": {
                    "type": "string"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Update successful"
          }
        }
      }
    },
    "/dap/agent/link": {
      "post": {
        "tags": [
          "DAP Agent"
        ],
        "summary": "Link agent (auto-grants Trial)",
        "security": [
          {
            "DAPSession": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "agent_id",
                  "auth_token"
                ],
                "properties": {
                  "agent_id": {
                    "type": "string",
                    "format": "uuid"
                  },
                  "auth_token": {
                    "type": "string"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Linked. The agent's auth token has been rotated — store new_auth_token; the old token is now invalid (subsequent calls with it return 401).",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "agent_id": {
                      "type": "string",
                      "format": "uuid"
                    },
                    "linked_at": {
                      "type": "string",
                      "format": "date-time"
                    },
                    "new_auth_token": {
                      "type": "string",
                      "description": "Replacement bearer token for the agent. The token used in this request is revoked at this moment."
                    }
                  }
                }
              }
            }
          }
        },
        "description": "IMPORTANT: linking ROTATES the agent's auth token. The token submitted in this request is invalidated immediately; the response returns new_auth_token which must replace it. Any call made with the old token after linking returns 401 INVALID_TOKEN."
      }
    },
    "/dap/agent/unlink": {
      "delete": {
        "tags": [
          "DAP Agent"
        ],
        "summary": "Unlink agent",
        "security": [
          {
            "DAPSession": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "agent_id",
                  "password"
                ],
                "properties": {
                  "agent_id": {
                    "type": "string",
                    "format": "uuid"
                  },
                  "password": {
                    "type": "string"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Unlink successful"
          }
        }
      }
    },
    "/dap/agents": {
      "get": {
        "tags": [
          "DAP Agent"
        ],
        "summary": "List linked agents",
        "security": [
          {
            "DAPSession": []
          }
        ],
        "responses": {
          "200": {
            "description": "Agent list"
          }
        }
      }
    },
    "/dap/system/limits": {
      "get": {
        "tags": [
          "DAP Agent"
        ],
        "summary": "Get system limits",
        "security": [
          {
            "DAPSession": []
          }
        ],
        "responses": {
          "200": {
            "description": "System limit info"
          }
        }
      }
    },
    "/dap/dab/set": {
      "put": {
        "tags": [
          "DAP DAB"
        ],
        "summary": "Set DAB",
        "security": [
          {
            "DAPSession": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "agent_id",
                  "budget_limit_dac",
                  "budget_period"
                ],
                "properties": {
                  "agent_id": {
                    "type": "string",
                    "format": "uuid"
                  },
                  "budget_limit_dac": {
                    "type": "number",
                    "minimum": 100,
                    "description": "Monthly spend ceiling in DAC. Minimum 100 (operator-configurable floor; 400 INVALID_VALUE below it)."
                  },
                  "budget_period": {
                    "type": "string",
                    "enum": [
                      "monthly"
                    ],
                    "description": "Only 'monthly' is accepted."
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Configuration saved"
          }
        }
      }
    },
    "/dap/dab/status": {
      "get": {
        "tags": [
          "DAP DAB"
        ],
        "summary": "Get DAB status",
        "security": [
          {
            "DAPSession": []
          }
        ],
        "parameters": [
          {
            "name": "agent_id",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "DAB status"
          }
        }
      }
    },
    "/dap/dab/remove": {
      "delete": {
        "tags": [
          "DAP DAB"
        ],
        "summary": "Remove DAB",
        "security": [
          {
            "DAPSession": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "agent_id",
                  "password"
                ],
                "properties": {
                  "agent_id": {
                    "type": "string",
                    "format": "uuid"
                  },
                  "password": {
                    "type": "string"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Removal completed"
          }
        }
      }
    },
    "/dap/dashboard": {
      "get": {
        "tags": [
          "DAP Dashboard"
        ],
        "summary": "Owner dashboard",
        "security": [
          {
            "DAPSession": []
          }
        ],
        "responses": {
          "200": {
            "description": "Dashboard data"
          }
        }
      }
    },
    "/dap/agent/{agent_id}/report": {
      "get": {
        "tags": [
          "DAP Dashboard"
        ],
        "summary": "Agent report",
        "security": [
          {
            "DAPSession": []
          }
        ],
        "parameters": [
          {
            "name": "agent_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Report data"
          }
        }
      }
    },
    "/dap/agent/{agent_id}/report/weekly": {
      "get": {
        "tags": [
          "DAP Dashboard"
        ],
        "summary": "Weekly report",
        "security": [
          {
            "DAPSession": []
          }
        ],
        "parameters": [
          {
            "name": "agent_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Weekly report data"
          }
        }
      }
    },
    "/dap/agent/{agent_id}/report/export": {
      "get": {
        "tags": [
          "DAP Dashboard"
        ],
        "summary": "Export report CSV",
        "security": [
          {
            "DAPSession": []
          }
        ],
        "parameters": [
          {
            "name": "agent_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          },
          {
            "name": "from",
            "in": "query",
            "schema": {
              "type": "string",
              "format": "date-time"
            }
          },
          {
            "name": "to",
            "in": "query",
            "schema": {
              "type": "string",
              "format": "date-time"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "CSV file"
          }
        }
      }
    },
    "/dap/tsl/human-share": {
      "post": {
        "tags": [
          "DAP TSL"
        ],
        "summary": "Create human share agreement",
        "security": [
          {
            "DAPSession": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "tool_id",
                  "human_share_rate"
                ],
                "properties": {
                  "tool_id": {
                    "type": "string",
                    "format": "uuid"
                  },
                  "human_share_rate": {
                    "type": "number",
                    "minimum": 0,
                    "maximum": 0.5
                  }
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Agreement created"
          }
        }
      }
    },
    "/dap/tsl/human-shares": {
      "get": {
        "tags": [
          "DAP TSL"
        ],
        "summary": "List human share agreements",
        "security": [
          {
            "DAPSession": []
          }
        ],
        "responses": {
          "200": {
            "description": "Agreement list"
          }
        }
      }
    },
    "/dap/asa/subscription/{agent_id}": {
      "get": {
        "tags": [
          "DAP ASA"
        ],
        "summary": "Owner ASA subscription query",
        "security": [
          {
            "DAPSession": []
          }
        ],
        "parameters": [
          {
            "name": "agent_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Subscription details"
          },
          "404": {
            "description": "Not linked or no subscription"
          }
        }
      }
    },
    "/dap/asa/snapshot/{agent_id}": {
      "get": {
        "tags": [
          "DAP ASA"
        ],
        "summary": "Owner ASA snapshot query",
        "security": [
          {
            "DAPSession": []
          }
        ],
        "parameters": [
          {
            "name": "agent_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Snapshot metadata"
          },
          "404": {
            "description": "Not linked or no snapshot"
          }
        }
      }
    },
    "/dap/asa/verify/{agent_id}": {
      "post": {
        "tags": [
          "DAP ASA"
        ],
        "summary": "Owner hash verification",
        "security": [
          {
            "DAPSession": []
          }
        ],
        "parameters": [
          {
            "name": "agent_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "blob_hash"
                ],
                "properties": {
                  "blob_hash": {
                    "type": "string"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Verification result"
          }
        }
      }
    },
    "/dap/dur/summary": {
      "get": {
        "tags": [
          "DAP DUR"
        ],
        "summary": "Owner DUR combined summary",
        "security": [
          {
            "DAPSession": []
          }
        ],
        "parameters": [
          {
            "name": "from",
            "in": "query",
            "schema": {
              "type": "string"
            },
            "description": "Start (inclusive). Date-only (YYYY-MM-DD) or ISO timestamp. Date boundaries are UTC."
          },
          {
            "name": "to",
            "in": "query",
            "schema": {
              "type": "string"
            },
            "description": "End. Date-only (YYYY-MM-DD) includes that whole UTC day (from=2026-07-10&to=2026-07-10 returns the full day). ISO timestamp is an exclusive upper bound."
          },
          {
            "name": "agent_id",
            "in": "query",
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "DAC usage summary for the range.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "period": {
                      "type": "object",
                      "properties": {
                        "from": {
                          "type": "string"
                        },
                        "to": {
                          "type": "string"
                        }
                      }
                    },
                    "dd_count": {
                      "type": "integer",
                      "description": "core_dd rows anchored in range (includes settlement/tool-registration anchor DDs)."
                    },
                    "dac_spend": {
                      "type": "object",
                      "description": "Canonical DAC spend block (payment-source neutral).",
                      "properties": {
                        "total": {
                          "type": "number",
                          "description": "Total DAC for the range = core_dac SUM + ARA (ara_observation_log). §98 — ARA has no core_dac rows (per-observation anchors would explode core_dd), so its spend is summed in separately. Invariant: total == dd_ee+ara+ise+sdac+tsl+asa == by_source sum."
                        },
                        "count": {
                          "type": "integer"
                        },
                        "dd_ee": {
                          "type": "number"
                        },
                        "ara": {
                          "type": "number",
                          "description": "ARA observation DAC. §98 — sourced from ara_observation_log (NOT core_dac; the 'ARA' cost_context_type label is unused, ara_observation_log is canonical). Includes base (always external) + premium (external or earned)."
                        },
                        "ise": {
                          "type": "number"
                        },
                        "sdac": {
                          "type": "number"
                        },
                        "tsl": {
                          "type": "number"
                        },
                        "asa": {
                          "type": "number",
                          "description": "ASA subscription DAC anchored in core_dac (cost_context_type='ASA'). Added §94 — previously ASA was billing_payment-only and missing from this core_dac-based total."
                        },
                        "by_source": {
                          "type": "object",
                          "description": "Decomposition by payment source. Aggregated from billing_payment + ARA (ara_observation_log, §98). ARA contributes: external += base + external-premium; earned += earned-premium (split by premium_source, NOT payment_mode — payment_mode is always 'external' when charged and is not a source discriminator); trial += 0 (ARA has no trial fallback).",
                          "properties": {
                            "trial": {
                              "type": "number"
                            },
                            "external": {
                              "type": "number"
                            },
                            "earned": {
                              "type": "number"
                            }
                          }
                        }
                      }
                    },
                    "ara_observations": {
                      "type": "object",
                      "description": "ARA observation spend summary (§98, option (라)). ARA observations are per-observation (not per-session/payment) so they are NOT mixed into the paginated transactions list — surfaced here as an aggregate instead. Amounts are already included in dac_spend.total / by_source / fiat.approx_krw.",
                      "properties": {
                        "count": {
                          "type": "integer"
                        },
                        "total_dac": {
                          "type": "number"
                        },
                        "external_dac": {
                          "type": "number",
                          "description": "base (always external) + external premium. KRW-convertible portion."
                        },
                        "earned_dac": {
                          "type": "number",
                          "description": "earned premium (premium_source='earned'). No KRW (earned does not cross USDC)."
                        }
                      }
                    },
                    "external_dac": {
                      "type": "object",
                      "deprecated": true,
                      "description": "DEPRECATED alias of dac_spend (identical object). Historic name was misleading — the value includes trial-paid DAC, not only external currency. Use dac_spend."
                    },
                    "earned_dac": {
                      "type": "object",
                      "properties": {
                        "received": {
                          "type": "number"
                        },
                        "spent": {
                          "type": "number"
                        },
                        "tx_count": {
                          "type": "integer"
                        }
                      }
                    },
                    "fiat": {
                      "type": "object",
                      "description": "§96a — KRW is NOT stored in the ledger; computed at query time from external DAC spend x current config unit_price x rate. External payments only (earned/trial never cross USDC). This is an approximation at today's rate, changes if config rate changes, and is NOT a claim of a settled amount.",
                      "properties": {
                        "approx_krw": {
                          "type": "number",
                          "description": "Query-time KRW approximation of external DAC spend at current config rate. §98 — includes ARA external spend (base + external premium); ARA earned premium excluded (no USDC crossing). Not a settled-amount claim; shifts if rate changes."
                        },
                        "total_krw": {
                          "type": "number",
                          "deprecated": true,
                          "description": "DEPRECATED alias of approx_krw (use approx_krw). Value is now external-only (§96a); previously included earned."
                        },
                        "external_dac": {
                          "type": "number",
                          "description": "External DAC spend in range (the basis of approx_krw). §98 — includes ARA external (base + external premium)."
                        },
                        "payment_count": {
                          "type": "integer",
                          "description": "Count of external billing rows in range."
                        },
                        "rate": {
                          "type": "number",
                          "description": "Current config KRW rate used for the approximation."
                        },
                        "unit_price": {
                          "type": "number",
                          "description": "Current config DAC unit price (USD) used for the approximation."
                        }
                      }
                    },
                    "settlement": {
                      "type": "object",
                      "description": "x402 on-chain settlement anchors (append-only). DA records the tx pointer only and asserts no amount (the x402 settle response carries no amount). Verify on-chain by tx_hash.",
                      "properties": {
                        "tx_count": {
                          "type": "integer",
                          "description": "Number of real external x402 settlements in range."
                        },
                        "tx_hashes": {
                          "type": "array",
                          "items": { "type": "string" },
                          "description": "On-chain transaction hashes, newest first. External verification anchor."
                        }
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/dap/dur/export": {
      "get": {
        "tags": [
          "DAP DUR"
        ],
        "summary": "Owner CSV/JSON export",
        "security": [
          {
            "DAPSession": []
          }
        ],
        "parameters": [
          {
            "name": "from",
            "in": "query",
            "schema": {
              "type": "string"
            },
            "description": "Start (inclusive). Date-only (YYYY-MM-DD) or ISO timestamp. Date boundaries are UTC."
          },
          {
            "name": "to",
            "in": "query",
            "schema": {
              "type": "string"
            },
            "description": "End. Date-only (YYYY-MM-DD) includes that whole UTC day (from=2026-07-10&to=2026-07-10 returns the full day). ISO timestamp is an exclusive upper bound."
          },
          {
            "name": "agent_id",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          },
          {
            "name": "format",
            "in": "query",
            "schema": {
              "type": "string",
              "enum": [
                "csv",
                "json"
              ],
              "default": "csv"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Export data"
          }
        }
      }
    },
    "/dap/trial/status": {
      "get": {
        "tags": [
          "DAP Trial"
        ],
        "summary": "Owner Trial status query",
        "security": [
          {
            "DAPSession": []
          }
        ],
        "responses": {
          "200": {
            "description": "Trial status"
          }
        }
      }
    },
    "/v1/agent/token/recover": {
      "post": {
        "tags": [
          "Agent"
        ],
        "summary": "Recover access after auth token loss",
        "description": "Recovers an agent whose auth_token was lost, using the recovery_key issued at registration (or last rotate/recover). No authentication required — possession of agent_id + recovery_key is the proof. On success both auth_token and recovery_key are replaced (old values immediately invalid). Strictly rate-limited.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "agent_id",
                  "recovery_key"
                ],
                "properties": {
                  "agent_id": {
                    "type": "string",
                    "format": "uuid"
                  },
                  "recovery_key": {
                    "type": "string",
                    "description": "The da_rk_... key issued at registration or last rotate/recover."
                  }
                }
              },
              "example": {
                "agent_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
                "recovery_key": "da_rk_<64-hex>"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Recovery successful — new auth_token and new recovery_key returned (shown once).",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "agent_id": {
                      "type": "string",
                      "format": "uuid"
                    },
                    "auth_token": {
                      "type": "string"
                    },
                    "recovery_key": {
                      "type": "string"
                    },
                    "recovered_at": {
                      "type": "string",
                      "format": "date-time"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Missing field or invalid UUID"
          },
          "401": {
            "description": "agent_id/recovery_key pair is invalid (same response regardless of which part failed)"
          },
          "429": {
            "description": "Rate limit exceeded (5 per 15 minutes)"
          }
        }
      }
    }
  }
}