# MAOP: Multi-Agent Orchestration Protocol v1.0.0-draft.1 · OpenAPI 3.1 (DRAFT)
openapi: 3.1.0
info:
  title: 'MAOP: Multi-Agent Orchestration Protocol'
  version: 1.0.0-draft.1
  description: 'Lifecycle API for MAOP v1.0.0-draft.1 (DRAFT). Keeps all 17 CAOP v0.2 operations with the same operationIds, shapes and errors under /maop/v1, and adds 6 operations for multi-agent supervision: agent registration, delegation, fenced lease renewal, receipts and event-driven guard evaluation.'
jsonSchemaDialect: https://json-schema.org/draft/2020-12/schema
servers:
- url: https://maop.example.com
  description: Placeholder server
security:
- bearerAuth: []
tags:
- name: Observe
- name: Understand
- name: Commit
- name: Plan
- name: Execute
- name: Verify
- name: Record
- name: Review
- name: Compact binding
- name: Coordinate
- name: Supervise
paths:
  /maop/v1/observations:
    post:
      operationId: observations.ingest
      summary: Ingest an observation
      description: 'Records something the runtime learned from an external source. Replaying the same source event with the same idempotency_key returns the existing observation with duplicate: true.'
      tags:
      - Observe
      x-maop-stage: Observe
      x-maop-mcp-tool: observe
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ObservationCreate'
            example:
              source:
                provider: gmail
                resource_id: message_123
              type: message.received
              occurred_at: '2026-11-01T14:00:00Z'
              payload_ref: artifact_456
              idempotency_key: gmail-message-123
      responses:
        '202':
          description: Accepted
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ObservationAccepted'
              example:
                observation_id: obs_123
                status: accepted
                duplicate: false
        '400':
          description: Invalid request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Unauthenticated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: Forbidden or approval required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /maop/v1/context/resolve:
    post:
      operationId: context.resolve
      summary: Resolve context
      description: Resolves observations against known state. Retrieved facts and inferred interpretations are returned separately.
      tags:
      - Understand
      x-maop-stage: Understand
      x-maop-mcp-tool: get_context
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ContextResolveRequest'
            example:
              observation_ids:
              - obs_123
              scope:
                workspace_id: personal
                project_ids:
                - mortgage-refinance
              include:
              - related_goals
              - open_commitments
              - relevant_policies
              - prior_decisions
      responses:
        '200':
          description: Context bundle
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ContextBundle'
              example:
                context_id: ctx_123
                state_version: 42
                related_goals:
                - goal_refinance
                open_commitments:
                - commitment_12
                applicable_policies:
                - policy_financial_approval
                unresolved_questions: []
        '400':
          description: Invalid request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Unauthenticated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: Forbidden or approval required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /maop/v1/commitments:
    post:
      operationId: commitments.create
      summary: Create a commitment
      description: Creates a durable obligation or objective. A commitment cannot be completed solely because an agent claims it is complete.
      tags:
      - Commit
      x-maop-stage: Commit
      x-maop-mcp-tool: create_commitment
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CommitmentCreate'
            example:
              goal_id: goal_refinance
              objective: Evaluate updated refinancing offer
              success_criteria:
              - type: artifact_exists
                artifact_type: refinancing_comparison
              deadline: '2026-11-05T23:59:00Z'
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Commitment'
              example:
                commitment_id: com_123
                status: open
                version: 1
        '400':
          description: Invalid request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Unauthenticated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: Forbidden or approval required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
    get:
      operationId: commitments.list
      summary: List commitments
      description: Returns outstanding and recent commitments for the caller’s workspace.
      tags:
      - Commit
      x-maop-stage: Commit
      x-maop-mcp-tool: list_commitments
      parameters:
      - name: status
        in: query
        schema:
          type: string
          enum:
          - open
          - completed
          - failed
          - cancelled
          - expired
      - name: goal_id
        in: query
        schema:
          type: string
      - name: cursor
        in: query
        schema:
          type: string
      responses:
        '200':
          description: Commitments
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CommitmentList'
        '401':
          description: Unauthenticated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /maop/v1/plans:
    post:
      operationId: plans.create
      summary: Create a plan
      description: Produces an execution plan. The planner may use an LLM; the runtime validates the plan against schemas, dependencies, and policy.
      tags:
      - Plan
      x-maop-stage: Plan
      x-maop-mcp-tool: propose_plan
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PlanCreate'
            example:
              commitment_id: com_123
              constraints:
                require_approval_for_external_actions: true
              preferred_capabilities:
              - document_analysis
              - calculator
              - research
      responses:
        '201':
          description: Plan created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Plan'
              example:
                plan_id: plan_123
                steps:
                - id: step_1
                  capability: document_analysis
                  depends_on: []
                - id: step_2
                  capability: calculator
                  depends_on:
                  - step_1
                - id: step_3
                  capability: report_generation
                  depends_on:
                  - step_2
        '400':
          description: Invalid request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Unauthenticated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: Forbidden or approval required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /maop/v1/executions:
    post:
      operationId: executions.start
      summary: Start an execution
      description: Starts an authorized execution of a plan. Execution is asynchronous; acceptance does not mean completion.
      tags:
      - Execute
      x-maop-stage: Execute
      x-maop-mcp-tool: start_work
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ExecutionCreate'
            example:
              plan_id: plan_123
              idempotency_key: execute-plan-123-v1
              authorization_context:
                principal_id: user_123
      responses:
        '202':
          description: Queued
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ExecutionAccepted'
              example:
                execution_id: exec_123
                status: queued
                next_action: await_execution
        '400':
          description: Invalid request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Unauthenticated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: Forbidden or approval required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /maop/v1/executions/{execution_id}:
    get:
      operationId: executions.get
      summary: Get execution status
      description: Returns the current state of an execution.
      tags:
      - Execute
      x-maop-stage: Execute
      x-maop-mcp-tool: get_work_status
      parameters:
      - name: execution_id
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Execution
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Execution'
              example:
                execution_id: exec_123
                plan_id: plan_123
                state: RUNNING
                state_version: 3
                correlation_id: goal_refinance
                updated_at: '2026-11-01T14:05:00Z'
        '401':
          description: Unauthenticated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /maop/v1/executions/{execution_id}/results:
    post:
      operationId: executions.submit_result
      summary: Submit a result
      description: Submits output and evidence for verification. Moves a RUNNING execution to VERIFYING.
      tags:
      - Execute
      x-maop-stage: Execute
      x-maop-mcp-tool: submit_result
      parameters:
      - name: execution_id
        in: path
        required: true
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ResultSubmission'
            example:
              output:
                report: artifact_789
              evidence_refs:
              - artifact_789
              idempotency_key: submit-exec-123-v1
      responses:
        '202':
          description: Accepted for verification
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Execution'
              example:
                execution_id: exec_123
                plan_id: plan_123
                state: RUNNING
                state_version: 3
                correlation_id: goal_refinance
                updated_at: '2026-11-01T14:05:00Z'
        '400':
          description: Invalid request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Unauthenticated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '409':
          description: Invalid transition or state version conflict
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /maop/v1/executions/{execution_id}/transitions:
    post:
      operationId: executions.transition
      summary: Transition an execution
      description: Moves an execution between states. Invalid transitions are rejected with INVALID_TRANSITION; a stale expected_state yields STATE_VERSION_CONFLICT.
      tags:
      - Execute
      x-maop-stage: Execute
      parameters:
      - name: execution_id
        in: path
        required: true
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TransitionRequest'
            example:
              expected_state: VERIFYING
              target_state: COMPLETED
              verification_id: verify_123
      responses:
        '200':
          description: Transition accepted
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Transition'
              example:
                transition_id: tr_9
                execution_id: exec_123
                from_state: VERIFYING
                to_state: COMPLETED
                state_version: 5
                actor:
                  type: service
                  id: caop-runtime
                reason: verification passed
                correlation_id: goal_refinance
                occurred_at: '2026-11-01T15:00:00Z'
        '400':
          description: Invalid request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Unauthenticated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: Forbidden or approval required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '409':
          description: Invalid transition or state version conflict
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /maop/v1/verifications:
    post:
      operationId: verifications.evaluate
      summary: Evaluate verification
      description: Evaluates an execution result against criteria. The verdict lists every check performed and its kind.
      tags:
      - Verify
      x-maop-stage: Verify
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/VerificationRequest'
            example:
              execution_id: exec_123
              criteria:
              - all_required_steps_completed
              - result_has_supporting_evidence
              - no_policy_violations
      responses:
        '200':
          description: Verdict
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Verification'
              example:
                verification_id: verify_123
                verdict: passed
                evidence_refs:
                - artifact_789
                checks:
                - name: all_required_steps_completed
                  kind: deterministic
                  result: pass
                - name: result_has_supporting_evidence
                  kind: model_rubric
                  result: pass
                - name: no_policy_violations
                  kind: deterministic
                  result: pass
        '400':
          description: Invalid request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Unauthenticated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '422':
          description: Verification failed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /maop/v1/records/commit:
    post:
      operationId: records.commit
      summary: Commit a record
      description: Persists facts, evidence, and outcomes with optimistic concurrency on expected_state_version.
      tags:
      - Record
      x-maop-stage: Record
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RecordCommit'
            example:
              execution_id: exec_123
              verification_id: verify_123
              expected_state_version: 42
              changes:
              - entity_id: com_123
                operation: set_status
                value: completed
      responses:
        '200':
          description: Committed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RecordCommitted'
              example:
                transaction_id: txn_123
                state_version: 43
                status: committed
        '400':
          description: Invalid request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Unauthenticated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: Forbidden or approval required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '409':
          description: Invalid transition or state version conflict
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /maop/v1/reviews:
    post:
      operationId: reviews.evaluate
      summary: Evaluate a review
      description: Evaluates progress toward a goal. Recommended actions are proposals, not authorized actions.
      tags:
      - Review
      x-maop-stage: Review
      x-maop-mcp-tool: review_goals
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ReviewRequest'
            example:
              goal_id: goal_refinance
              review_type: progress
              include:
              - outcomes
              - unresolved_commitments
              - failures
              - next_actions
      responses:
        '200':
          description: Review
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Review'
              example:
                review_id: review_123
                goal_status: active
                recommended_actions:
                - action: request_final_offer
                  requires_approval: true
        '400':
          description: Invalid request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Unauthenticated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /maop/v1/approvals/{approval_request_id}/decision:
    post:
      operationId: approvals.decide
      summary: Decide an approval request
      description: Grants or denies a scoped, expiring authorization for a consequential action.
      tags:
      - Execute
      x-maop-stage: Execute
      x-maop-mcp-tool: approve_action
      parameters:
      - name: approval_request_id
        in: path
        required: true
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ApprovalDecision'
            example:
              decision: approve
              scope:
                document: offer-v2
                max_price: 632000
              expires_at: '2026-11-02T22:00:00Z'
      responses:
        '200':
          description: Decision recorded
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Approval'
              example:
                approval_id: appr_301
                approval_request_id: approval_123
                decision: approve
                scope:
                  document: offer-v2
                approved_by:
                  type: user
                  id: user_123
                expires_at: '2026-11-02T22:00:00Z'
        '400':
          description: Invalid request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Unauthenticated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: Forbidden or approval required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /maop/v1/compact/pulse:
    post:
      operationId: compact.pulse
      summary: Pulse
      description: 'OBSERVE + REVIEW. Ingests unobserved events (which may supersede facts and trigger causal invalidation) and returns the zero-upload resume_brief: unsettled leases, stale commitments, unassigned blockers, ranked next actions, and system advisories (e.g. STAGE_UPGRADE_RECOMMENDED). Resets the dead-man heartbeat. v0.2: compaction_mode selects how session state is compacted (FACT_POINTERS_ONLY, SUMMARY_WITH_LINEAGE, FULL_RAW_ARTIFACTS); the response lists capability_stubs and hydrates full input schemas only for hydrate_capability_ids (returned as data; the host’s tool list does not change). In CAOP-STAGE-1 the pulse also runs deferred Phase-2 outcome checks that are due (outcome_verifications).'
      tags:
      - Compact binding
      x-maop-stage:
      - Observe
      - Review
      x-maop-binding: compact
      x-maop-mcp-tool: caop_pulse
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PulseInput'
            example:
              scope_goal_ids:
              - goal_payment_ledger_v2
              unobserved_events:
              - source: benchmark_ci
                summary: 'November p99 benchmark: 48ms at 15k TPS'
                external_ref: ci_run_5521
                supersedes_fact_id: fct_bench_2026_10_p99
              compaction_mode: FACT_POINTERS_ONLY
              hydrate_capability_ids:
              - github.pulls.create
      responses:
        '200':
          description: Resume brief
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PulseResponse'
              example:
                pulse_timestamp: '2026-11-05T13:00:00Z'
                workspace_stage_profile: CAOP-STAGE-1
                resume_brief:
                  unsettled_leases: []
                  stale_commitments:
                  - work_id: wrk_rfc_sharding_09
                    fact_id: fct_rfc_sharding_decision
                    title: Single-Region Hash Partitioning for Payment Ledger
                    epistemic_status: RATIFIED_COMMITMENT
                    freshness: STALE_UPSTREAM_PREMISE
                    invalidated_by_fact_id: fct_bench_2026_11_p99
                    summary: p99 latency spiked from 12ms to 48ms in November benchmark run, invalidating the 15k TPS single-region assumption.
                  unassigned_blockers:
                  - work_id: wrk_load_test_replay
                    title: Run shadow-traffic replay on Iceberg partition
                    missing_hook: REQUIRE_EXPLICIT_OWNER
                  ranked_next_actions:
                  - rank: 1
                    work_id: wrk_rfc_sharding_09
                    action_type: REPLAN_STALE_COMMITMENT
                    blocking_dependents_count: 3
                    recommended_prompt: Re-evaluate partition strategy given fct_bench_2026_11_p99 (48ms p99) and stage an updated commitment.
                  - rank: 2
                    work_id: wrk_load_test_replay
                    action_type: ASSIGN_PRINCIPAL_OWNER
                    blocking_dependents_count: 1
                    recommended_prompt: Assign an owner_principal_id to unblock shadow-traffic replay.
                  system_advisories:
                  - code: STAGE_UPGRADE_RECOMMENDED
                    capability_id: gmail.users.messages.send
                    message: 2 host leases expired in the past 7 days. Connect Gmail OAuth to the runtime vault to upgrade to CAOP-STAGE-2 (KERNEL_PROXIED).
                capability_stubs:
                - capability_id: github.pulls.create
                  summary: Open a pull request in a connected repository.
                - capability_id: metrics.query
                  summary: Query a production metric over a time window.
                hydrated_capabilities:
                - capability_id: github.pulls.create
                  input_schema:
                    type: object
                    required:
                    - repo
                    - title
                    - head
                    - base
                    properties:
                      repo:
                        type: string
                      title:
                        type: string
                      head:
                        type: string
                      base:
                        type: string
                      draft:
                        type: boolean
                outcome_verifications:
                - work_id: wrk_rfc_sharding_10
                  invocation_id: inv_99512C
                  sub_state: VERIFY_PHASE_2_DEFERRED
                  verification_capability_id: metrics.query
                  success_predicate: ledger.p99_latency_ms < 20 AND ledger.tps >= 15000
                  check_due_at: '2026-11-06T13:40:00Z'
                  status: PENDING
        '400':
          description: Invalid request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Unauthenticated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '413':
          description: Invalidation subgraph too large (CAOP_413_INVALIDATION_SUBGRAPH_TOO_LARGE); nothing was applied
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                error:
                  code: CAOP_413_INVALIDATION_SUBGRAPH_TOO_LARGE
                  message: Superseding fct_bench_2026_10_p99 would invalidate 1,284 dependents; the limit is 500. Nothing was applied.
                  retryable: false
                  details:
                    superseded_fact_id: fct_bench_2026_10_p99
                    affected_subgraph_size: 1284
                    max_invalidation_subgraph: 500
                trace_id: trace_7c41e4
  /maop/v1/compact/stage-work:
    post:
      operationId: compact.stage_work
      summary: Stage work
      description: 'UNDERSTAND → COMMIT → PLAN. Evaluates Policy pre-commit hooks and minimum_attestation, then halts at approval (COMMIT_AWAITING_APPROVAL) or at EXECUTE_PENDING. A failed hook keeps the work item in CANDIDATE_PROPOSAL and returns CAOP_422_PRECOMMIT_HOOK_FAILED with details.failed_hooks; unknown or cross-workspace fact IDs return CAOP_422_PRECOMMIT_UNKNOWN_FACT_ID. Rejected with CAOP_409_UNSETTLED_EXECUTION_LEASE while a lease is open. v0.2: parent_work_id and isolation_policy stage a child work scope; it inherits the parent’s authority and can only narrow it.'
      tags:
      - Compact binding
      x-maop-stage:
      - Understand
      - Commit
      - Plan
      x-maop-binding: compact
      x-maop-mcp-tool: caop_stage_work
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/StageWorkInput'
            example:
              goal_id: goal_q4_strategy
              parent_work_id: wrk_q4_strategy_master
              isolation_policy:
                execution_scope: ISOLATED_SUBAGENT_CONTEXT
                return_contract: DISTILLED_FACTS_AND_ARTIFACT_REF_ONLY
                max_token_budget: 16000
                prune_raw_traces_on_record: true
                retention_policy: retain_30_days
              understanding:
                intent_summary: Benchmark vendor latency and pricing for the Q4 strategy RFC.
                derived_facts: []
              commitment:
                title: Market benchmark matrix
                rationale: The parent RFC needs verified latency and pricing comparisons.
                owner_principal_id: user_123
                reversible: true
              plan_steps:
              - step_index: 1
                capability_id: research.web
                arguments:
                  query: vendor p99 latency published benchmarks
      responses:
        '200':
          description: Staged
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StageWorkResult'
              example:
                work_id: wrk_rfc_sharding_10
                lifecycle_stage: COMMIT
                sub_state: COMMIT_AWAITING_APPROVAL
                epistemic_status: CANDIDATE_PROPOSAL
        '400':
          description: Invalid request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Unauthenticated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: Forbidden or approval required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '409':
          description: Unsettled execution lease (CAOP_409_UNSETTLED_EXECUTION_LEASE), invalid transition, or state version conflict
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                error:
                  code: CAOP_409_UNSETTLED_EXECUTION_LEASE
                  message: Settle the open execution lease (inv_99481A) via caop_settle_receipt before staging or dispatching new work.
                  retryable: false
                  details:
                    blocking_work_id: wrk_01J9Z8K4M2
                    blocking_invocation_id: inv_99481A
                    required_nonce: nnc_884920_x9
                trace_id: trace_7c41e3
        '422':
          description: Pre-commit hook failed (CAOP_422_PRECOMMIT_*) or receipt nonce / artifact mismatch (CAOP_422_VERIFY_ARTIFACT_MISMATCH)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                error:
                  code: CAOP_422_PRECOMMIT_HOOK_FAILED
                  message: One or more Policy pre-commit hooks failed. The work item remains in CANDIDATE_PROPOSAL.
                  retryable: false
                  details:
                    failed_hooks:
                    - hook_id: REQUIRE_EXPLICIT_OWNER
                      error_code: CAOP_422_PRECOMMIT_MISSING_OWNER
                      remediation: Specify commitment.owner_principal_id (or ask the user to assign an owner) before committing this work plan.
                trace_id: trace_7c41e2
  /maop/v1/compact/dispatch-work:
    post:
      operationId: compact.dispatch_work
      summary: Dispatch work
      description: 'COMMIT resolution → EXECUTE. HOST_DELEGATED: enters EXECUTE_DISPATCHED and returns the anti-termination DispatchDirective with a single-use nonce. KERNEL_PROXIED: runs the OAuth proxy call and auto-folds VERIFY + RECORD, returning a SettlementResult. Rejected with CAOP_409_UNSETTLED_EXECUTION_LEASE while a lease is open. v0.2: APPROVE_WITH_STEERING_DELTA binds the approval to the patched plan: the kernel applies steering_delta, re-runs every Policy pre-commit hook and minimum_attestation check on it, and dispatches only if all pass; otherwise the work item returns to CANDIDATE_PROPOSAL with CAOP_422_PRECOMMIT_HOOK_FAILED. two_phase_verification configures the deferred Phase-2 outcome check.'
      tags:
      - Compact binding
      x-maop-stage:
      - Commit
      - Execute
      x-maop-binding: compact
      x-maop-mcp-tool: caop_dispatch_work
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DispatchWorkInput'
            example:
              work_id: wrk_rfc_sharding_10
              decision: APPROVE_WITH_STEERING_DELTA
              steering_delta:
                patched_step_arguments:
                - step_index: 1
                  argument_overrides:
                    reviewers:
                    - principal_eng
                    draft: true
                added_policy_constraints:
                - NO_PRODUCTION_DEPLOY_BEFORE_SHADOW_REPLAY
                rationale: Open the RFC as a draft and add the principal engineer as reviewer; no deploy until the shadow replay passes.
              two_phase_verification:
                phase_1_immediate: REQUIRE_NONCE_AND_ARTIFACT
                phase_2_deferred:
                  check_after_seconds: 86400
                  verification_capability_id: metrics.query
                  success_predicate: ledger.p99_latency_ms < 20 AND ledger.tps >= 15000
      responses:
        '200':
          description: Dispatched
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DispatchWorkResult'
              example:
                work_id: wrk_01J9Z8K4M2
                lifecycle_stage: EXECUTE
                sub_state: EXECUTE_DISPATCHED
                turn_directive: INCOMPLETE_TURN_CONTINUATION_REQUIRED
                DO_NOT_RESPOND_TO_USER_YET: true
                directive:
                  invocation_id: inv_99481A
                  execution_locus: HOST_DELEGATED
                  idempotency_key: idem_wrk_01J9Z8K4M2_step_1
                  lease_expires_at: '2026-11-05T06:50:00Z'
                  mandatory_next_steps:
                  - step: 1
                    action: INVOKE_HOST_NATIVE_TOOL
                    target_capability: google_calendar.events.insert
                    arguments:
                      summary: Q4 Architecture Review
                      start_time: '2026-11-06T15:00:00Z'
                      end_time: '2026-11-06T15:30:00Z'
                  - step: 2
                    action: CALL_CAOP_TOOL
                    tool_name: caop_settle_receipt
                    required_nonce: nnc_884920_x9
                    required_receipt_fields:
                    - external_ref
                    - htmlLink
                    - iCalUID
        '400':
          description: Invalid request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Unauthenticated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: Forbidden or approval required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '409':
          description: Unsettled execution lease (CAOP_409_UNSETTLED_EXECUTION_LEASE), invalid transition, or state version conflict
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                error:
                  code: CAOP_409_UNSETTLED_EXECUTION_LEASE
                  message: Settle the open execution lease (inv_99481A) via caop_settle_receipt before staging or dispatching new work.
                  retryable: false
                  details:
                    blocking_work_id: wrk_01J9Z8K4M2
                    blocking_invocation_id: inv_99481A
                    required_nonce: nnc_884920_x9
                trace_id: trace_7c41e3
        '413':
          description: Invalidation subgraph too large (CAOP_413_INVALIDATION_SUBGRAPH_TOO_LARGE); nothing was applied
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '422':
          description: Pre-commit hook failed (CAOP_422_PRECOMMIT_*) or receipt nonce / artifact mismatch (CAOP_422_VERIFY_ARTIFACT_MISMATCH)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                error:
                  code: CAOP_422_PRECOMMIT_HOOK_FAILED
                  message: The patched plan failed a Policy pre-commit hook. The work item returns to CANDIDATE_PROPOSAL.
                  retryable: false
                  details:
                    failed_hooks:
                    - hook_id: REQUIRE_EXPLICIT_OWNER
                      error_code: CAOP_422_PRECOMMIT_MISSING_OWNER
                      remediation: The steering delta cleared commitment.owner_principal_id. Keep an explicit owner and dispatch again.
                trace_id: trace_7c41e7
  /maop/v1/compact/settle-receipt:
    post:
      operationId: compact.settle_receipt
      summary: Settle a receipt
      description: 'VERIFY → RECORD → REVIEW. Verifies the nonce and required_receipt_fields, writes a HOST_ASSERTED fact, and unlocks the thread. For KERNEL_PROXIED work it is used only for manual USER_CONFIRMED overrides. v0.2: with a phase_2_deferred check, Phase 1 records the receipt as facts with their attestation tier and returns RECORDED_AWAITING_OUTCOME_VERIFY; the commitment stays open until the deferred check passes. A child work scope returns distilled_return_payload; its raw traces are pruned from the active context, not from provenance.'
      tags:
      - Compact binding
      x-maop-stage:
      - Verify
      - Record
      - Review
      x-maop-binding: compact
      x-maop-mcp-tool: caop_settle_receipt
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SettleReceiptInput'
            example:
              work_id: wrk_sub_market_scan
              invocation_id: inv_99481A
              idempotency_key: idem_wrk_01J9Z8K4M2_step_1
              nonce: nnc_884920_x9
              status: SUCCEEDED
              external_ref: gcal_evt_8839201
              raw_output:
                external_ref: gcal_evt_8839201
                htmlLink: https://www.google.com/calendar/event?eid=ODgzOTIwMQ
                iCalUID: 8839201@google.com
              review_outcome: GOAL_SATISFIED
              distilled_return_payload:
                artifact_ref: art_market_benchmark_matrix_v1
                promoted_fact_ids:
                - fct_competitor_latency_p99
                - fct_pricing_tier_delta
                compacted_summary: Audited 18 vendor specs; isolated 2 verified latency bottlenecks linked to parent RFC.
                trace_hash: sha256:9f2c4e7a1b03d58e6c2f9a4b7d1e0c35a8b6f2d4e9c17a0b3d5f8e2c6a4b19d7
      responses:
        '200':
          description: Settled
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SettlementResult'
              example:
                work_id: wrk_rfc_sharding_10
                invocation_id: inv_99512C
                lifecycle_stage: RECORD
                sub_state: RECORDED_AWAITING_OUTCOME_VERIFY
                attestation: HOST_ASSERTED
                fact_ids:
                - fct_77311D
                thread_unlocked: true
                outcome_verification:
                  work_id: wrk_rfc_sharding_10
                  invocation_id: inv_99512C
                  sub_state: VERIFY_PHASE_2_DEFERRED
                  verification_capability_id: metrics.query
                  success_predicate: ledger.p99_latency_ms < 20 AND ledger.tps >= 15000
                  check_due_at: '2026-11-06T13:40:00Z'
                  status: PENDING
        '400':
          description: Invalid request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Unauthenticated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '413':
          description: Invalidation subgraph too large (CAOP_413_INVALIDATION_SUBGRAPH_TOO_LARGE); nothing was applied
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '422':
          description: Pre-commit hook failed (CAOP_422_PRECOMMIT_*) or receipt nonce / artifact mismatch (CAOP_422_VERIFY_ARTIFACT_MISMATCH)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                error:
                  code: CAOP_422_VERIFY_ARTIFACT_MISMATCH
                  message: 'Receipt raw_output is missing required_receipt_fields: iCalUID.'
                  retryable: false
                  details:
                    work_id: wrk_01J9Z8K4M2
                    invocation_id: inv_99481A
                    missing_fields:
                    - iCalUID
                trace_id: trace_7c41e5
  /maop/v1/agents:
    post:
      operationId: agents.register
      summary: Register an agent
      description: Registers an agent identity with the roles it may take and its lazily advertised capability stubs. Registration grants no authority. Replaying the same idempotency_key returns the existing registration.
      tags:
      - Coordinate
      x-maop-stage: Coordinate
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AgentRegistration'
            example:
              identity: &id001
                agent_id: agt_impl_7
                display_name: Implementer 7
                principal:
                  type: service
                  id: svc_build_fleet
                provider: example-provider
                model: example-model-large
                public_key: ed25519:MCowBQYDK2VwAyEAG2q0rI3kq6QvVq9a7S4Zr0b5mJqgYb6dKkX8P1lC0aM=
                attestation: HOST_ASSERTED
              roles: &id002
              - implementer
              - verifier
              capability_stubs: &id003
              - capability_id: github.pulls.create
                summary: Open a pull request in a connected repository.
              max_concurrent_leases: 2
              idempotency_key: reg-agt_impl_7
      responses:
        '201':
          description: Agent registered
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AgentRegistration'
              example:
                registration_id: reg_0192
                identity: *id001
                roles: *id002
                capability_stubs: *id003
                max_concurrent_leases: 2
                status: active
                registered_at: '2026-11-22T09:00:00Z'
        '400': &id009
          description: Invalid request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401': &id010
          description: Unauthenticated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '409':
          description: agent_id already registered to a different principal
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /maop/v1/delegations:
    post:
      operationId: delegations.create
      summary: Delegate child work
      description: A supervisor delegates a child work item to another agent with an isolation policy, a budget and an authority subset. The delegated authority MUST be a subset of the supervisor's own (403 FORBIDDEN otherwise). Replaying the same idempotency_key returns the existing delegation.
      tags:
      - Coordinate
      x-maop-stage: Coordinate
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DelegationCreate'
            example:
              parent_work_id: wrk_payment_ledger_v2
              supervisor_agent_id: agt_supervisor_1
              child_agent_id: agt_impl_7
              role: implementer
              objective: Implement range partitioning for the ledger table and open a pull request.
              acceptance_criteria: &id004
              - type: metric_threshold
                metric: ledger.p99_latency_ms
                lt: 20
              isolation_policy: &id005
                execution_scope: ISOLATED_SUBAGENT_CONTEXT
                return_contract: DISTILLED_FACTS_AND_ARTIFACT_REF_ONLY
                max_token_budget: 16000
                prune_raw_traces_on_record: true
              budget: &id006
                max_token_budget: 16000
                max_wall_clock_seconds: 3600
              authority: &id007
                grant_id: grt_impl_7_ledger
                grantor:
                  type: agent
                  id: agt_supervisor_1
                grantee_agent_id: agt_impl_7
                parent_grant_id: grt_supervisor_1_ledger
                trust_level: T1_attested
                scope:
                - github.pulls.create
                - metrics.query
                expires_at: '2026-11-22T17:00:00Z'
              guards: &id008
              - guard_id: grd_sod_reviewer
                kind: separation_of_duties
                expression: review.actor.id != execution.actor.id
                durable: true
                applies_to:
                - review
                on_failure: coordinate
                description: The reviewer must be a different agent than the implementer.
              lease_seconds: 900
              idempotency_key: dlg-wrk_payment_ledger_v2-impl-1
      responses:
        '201':
          description: Delegation created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Delegation'
              example: &id011
                delegation_id: dlg_7f3c
                child_work_id: wrk_ledger_partitioning
                parent_work_id: wrk_payment_ledger_v2
                supervisor_agent_id: agt_supervisor_1
                child_agent_id: agt_impl_7
                role: implementer
                objective: Implement range partitioning for the ledger table and open a pull request.
                acceptance_criteria: *id004
                isolation_policy: *id005
                budget: *id006
                authority: *id007
                guards: *id008
                lease_seconds: 900
                state: leased
                lease:
                  lease_id: lse_51a2
                  holder: agt_impl_7
                  work_id: wrk_ledger_partitioning
                  delegation_id: dlg_7f3c
                  fencing_token: 42
                  state: active
                  issued_at: '2026-11-22T09:05:00Z'
                  expires_at: '2026-11-22T09:20:00Z'
                receipt_ids: []
                state_version: 2
                created_at: '2026-11-22T09:04:00Z'
                updated_at: '2026-11-22T09:05:00Z'
        '400': *id009
        '401': *id010
        '403':
          description: Authority is not a subset of the supervisor's, or separation of duties is violated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Parent work item or agent not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '409':
          description: Idempotency key reused with a different request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /maop/v1/delegations/{delegation_id}:
    get:
      operationId: delegations.get
      summary: Get a delegation
      description: Returns a delegated child work item with its lifecycle state, lease and receipts.
      tags:
      - Coordinate
      x-maop-stage: Coordinate
      parameters:
      - name: delegation_id
        in: path
        required: true
        schema:
          type: string
        example: dlg_7f3c
      responses:
        '200':
          description: Delegation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Delegation'
              example: *id011
        '401': *id010
        '404': &id012
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /maop/v1/leases/{lease_id}/renew:
    post:
      operationId: leases.renew
      summary: Renew an execution lease
      description: Extends a fenced execution lease held by the caller. The fencing token is kept; a stale fencing token or an expired lease is rejected with 409 and the holder must stop writing.
      tags:
      - Execute
      x-maop-stage: Execute
      parameters:
      - name: lease_id
        in: path
        required: true
        schema:
          type: string
        example: lse_51a2
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/LeaseRenewal'
            example:
              holder: agt_impl_7
              fencing_token: 42
              extend_seconds: 900
              idempotency_key: renew-lse_51a2-1
      responses:
        '200':
          description: Lease renewed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Lease'
              example:
                lease_id: lse_51a2
                holder: agt_impl_7
                work_id: wrk_ledger_partitioning
                delegation_id: dlg_7f3c
                fencing_token: 42
                state: active
                issued_at: '2026-11-22T09:05:00Z'
                expires_at: '2026-11-22T09:35:00Z'
        '400': *id009
        '401': *id010
        '403':
          description: Caller is not the lease holder
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404': *id012
        '409':
          description: Stale fencing token or expired lease
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                error:
                  code: STATE_VERSION_CONFLICT
                  message: fencing_token 41 is stale; current is 42.
                  retryable: false
                  details:
                    lease_id: lse_51a2
                    current_fencing_token: 42
                trace_id: trace_5d20aa
  /maop/v1/receipts/{receipt_id}:
    get:
      operationId: receipts.get
      summary: Get a receipt
      description: Returns a durable receipt for one side-effecting action, including its outcome and causal parents.
      tags:
      - Record
      x-maop-stage: Record
      parameters:
      - name: receipt_id
        in: path
        required: true
        schema:
          type: string
        example: rct_88d1
      responses:
        '200':
          description: Receipt
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Receipt'
              example:
                receipt_id: rct_88d1
                action: github.pulls.create
                actor:
                  type: agent
                  id: agt_impl_7
                idempotency_key: pr-wrk_ledger_partitioning-1
                outcome: succeeded
                evidence_refs:
                - art_pr_1284
                causal_parents:
                - evd_plan_v3
                work_id: wrk_ledger_partitioning
                delegation_id: dlg_7f3c
                lease_id: lse_51a2
                fencing_token: 42
                trust_level: T1_attested
                attestation: KERNEL_ATTESTED
                digest: sha256:9f2c4e7a1b03d58e6c2f9a4b7d1e0c35a8b6f2d4e9c17a0b3d5f8e2c6a4b19d7
                recorded_at: '2026-11-22T09:40:00Z'
        '401': *id010
        '404': *id012
  /maop/v1/supervision/{work_id}/evaluate:
    post:
      operationId: supervision.evaluate
      summary: Evaluate supervision guards
      description: Event-driven re-evaluation of a work item's durable guards against new evidence, receipts or child states. Returns the next supervision transition, including back-edges (act→decide, act→coordinate, verify→act, any→recover, recover→decide).
      tags:
      - Supervise
      x-maop-stage:
      - Decide
      - Coordinate
      - Recover
      parameters:
      - name: work_id
        in: path
        required: true
        schema:
          type: string
        example: wrk_payment_ledger_v2
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SupervisionEvaluation'
            example:
              current_stage: act
              trigger: evidence.received
              evidence:
              - evidence_id: evd_bench_2026_11
                kind: metric
                digest: sha256:3b7e1d9c0a4f62b85e1c7d3a9f0b2e64c8d1a5f7b3e9c2d0a6f4b8e1c3d5a7f9
                derived_from:
                - evd_ci_run_5521
                observed_at: '2026-11-22T10:00:00Z'
                valid_time:
                  start: '2026-11-22T09:55:00Z'
                  end: null
                source: benchmark_ci
                ref: ci_run_5521
              guard_ids:
              - grd_freshness_premise
              - grd_lease_valid
              child_states:
              - delegation_id: dlg_7f3c
                state: executing
              expected_state_version: 7
              idempotency_key: eval-wrk_payment_ledger_v2-7
      responses:
        '200':
          description: Transition decision
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TransitionDecision'
              example:
                work_id: wrk_payment_ledger_v2
                from_stage: act
                to_stage: decide
                trigger: evidence.received
                guards_passed:
                - grd_lease_valid
                guards_failed:
                - grd_freshness_premise
                back_edge: true
                next_action:
                  action: replan
                  summary: New benchmark evidence invalidates the plan premise; re-decide before further action.
                  delegation_id: dlg_7f3c
                state_version: 8
                decided_at: '2026-11-22T10:00:05Z'
        '400': *id009
        '401': *id010
        '404': *id012
        '409':
          description: expected_state_version does not match
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '422':
          description: A guard expression could not be evaluated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
  schemas:
    PrincipalRef:
      type: object
      properties:
        type:
          type: string
          enum:
          - user
          - role
          - agent
          - service
        id:
          type: string
      additionalProperties: false
      required:
      - type
      - id
      description: 'An authenticated principal: a person, a role, an agent, or a service account.'
    EntityRef:
      type: string
      description: Identifier of any entity known to the runtime, e.g. "property/14-oak-lane".
    EvidenceRef:
      type: string
      description: Identifier of a piece of evidence (an artifact, observation, or record) that supports a fact or outcome.
    ArtifactRef:
      type: string
      description: Identifier of a stored artifact such as a document or report.
    Expression:
      type: string
      description: A condition evaluated by the policy engine, e.g. "recipient.type == 'client'".
    Criterion:
      type: object
      properties:
        type:
          type: string
      additionalProperties: true
      required:
      - type
      description: A success criterion. "type" selects the evaluator; other members are evaluator-specific.
    Constraint:
      type: object
      properties:
        type:
          type: string
      additionalProperties: true
      required:
      - type
      description: A constraint on how a goal may be pursued.
    AuthorizationPolicy:
      type: object
      properties:
        requiredScopes:
          type: array
          items:
            type: string
        policyIds:
          type: array
          items:
            type: string
      additionalProperties: false
      description: What a caller must hold to invoke a capability.
    Goal:
      type: object
      properties:
        id:
          type: string
        objective:
          type: string
        owner:
          $ref: '#/components/schemas/PrincipalRef'
        successCriteria:
          type: array
          items:
            $ref: '#/components/schemas/Criterion'
        constraints:
          type: array
          items:
            $ref: '#/components/schemas/Constraint'
        status:
          type: string
          enum:
          - active
          - paused
          - achieved
          - abandoned
        createdAt:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time
      additionalProperties: false
      required:
      - id
      - objective
      - owner
      - successCriteria
      - constraints
      - status
      - createdAt
      - updatedAt
      description: A desired outcome that persists beyond a single conversation.
    WorkItem:
      type: object
      properties:
        id:
          type: string
        goalId:
          type: string
        description:
          type: string
        dependencies:
          type: array
          items:
            type: string
        status:
          type: string
          enum:
          - pending
          - ready
          - running
          - blocked
          - completed
          - failed
          - cancelled
        assignedCapability:
          type: string
        result:
          $ref: '#/components/schemas/ArtifactRef'
        deadline:
          type: string
          format: date-time
      additionalProperties: false
      required:
      - id
      - goalId
      - description
      - dependencies
      - status
      description: A bounded unit of execution that advances a goal.
    Fact:
      type: object
      properties:
        id:
          type: string
        subject:
          $ref: '#/components/schemas/EntityRef'
        predicate:
          type: string
        object: {}
        source:
          $ref: '#/components/schemas/EvidenceRef'
        observedAt:
          type: string
          format: date-time
        validFrom:
          type: string
          format: date-time
        validTo:
          type: string
          format: date-time
        confidence:
          type: number
          minimum: 0
          maximum: 1
      additionalProperties: false
      required:
      - id
      - subject
      - predicate
      - object
      - source
      - observedAt
      description: A durable, provenance-bearing statement in the runtime state. Every material fact has a traceable source.
    Capability:
      type: object
      properties:
        id:
          type: string
        operations:
          type: array
          items:
            type: string
        inputSchema:
          type: object
        outputSchema:
          type: object
        authorization:
          $ref: '#/components/schemas/AuthorizationPolicy'
        executionMode:
          type: string
          enum:
          - interactive
          - background
          - scheduled
        provider:
          type: string
      additionalProperties: false
      required:
      - id
      - operations
      - inputSchema
      - outputSchema
      - authorization
      - executionMode
      - provider
      description: Something the runtime can invoke to perform work.
    Policy:
      type: object
      properties:
        id:
          type: string
        scope:
          type: string
        condition:
          $ref: '#/components/schemas/Expression'
        effect:
          type: string
          enum:
          - allow
          - deny
          - require_approval
        version:
          type: string
        enforcement:
          type: string
          enum:
          - advisory
          - enforced
          description: Advisory policies are instructions to a model. Enforced policies are checked by the runtime before an action executes.
        minimum_attestation:
          $ref: '#/components/schemas/AttestationTier'
        pre_commit_hooks:
          type: array
          items:
            $ref: '#/components/schemas/PreCommitHook'
      additionalProperties: false
      required:
      - id
      - scope
      - condition
      - effect
      - version
      - enforcement
      description: A constraint governing execution. v0.1.2 adds minimum_attestation and pre_commit_hooks.
    CapabilityDescriptor:
      type: object
      properties:
        id:
          type: string
        provider:
          type: string
        operations:
          type: array
          items:
            type: string
        inputSchema:
          type: object
        outputSchema:
          type: object
        supportsAsync:
          type: boolean
        supportsResume:
          type: boolean
        supportsCancellation:
          type: boolean
        authorizationRequired:
          type: boolean
        sideEffectLevel:
          type: string
          enum:
          - none
          - reversible
          - irreversible
        execution_locus:
          $ref: '#/components/schemas/ExecutionLocus'
        auth_custodian:
          $ref: '#/components/schemas/AuthCustodian'
        receipt_lease_seconds:
          type: integer
          minimum: 1
          description: Maximum duration a HOST_DELEGATED invocation may remain uncommitted in EXECUTE_DISPATCHED before transitioning to EXECUTE_EXPIRED.
        required_receipt_fields:
          type: array
          items:
            type: string
          description: Provider-specific receipt verification keys that MUST be present in raw_output during VERIFY.
        promotion_policy:
          $ref: '#/components/schemas/PromotionPolicy'
      additionalProperties: false
      required:
      - id
      - provider
      - operations
      - inputSchema
      - outputSchema
      - supportsAsync
      - supportsResume
      - supportsCancellation
      - authorizationRequired
      - sideEffectLevel
      description: What an execution provider can do, independent of any one AI vendor. v0.1.2 adds execution_locus, auth_custodian, receipt_lease_seconds, required_receipt_fields and promotion_policy.
    CapabilityInvocation:
      type: object
      properties:
        invocationId:
          type: string
        capabilityId:
          type: string
        input: {}
        contextRefs:
          type: array
          items:
            type: string
        authorizationRef:
          type: string
        idempotencyKey:
          type: string
      additionalProperties: false
      required:
      - invocationId
      - capabilityId
      - input
      - contextRefs
      - idempotencyKey
      description: A request to a capability.
    CapabilityResult:
      type: object
      properties:
        invocationId:
          type: string
        status:
          type: string
          enum:
          - completed
          - failed
          - pending
          - requires_approval
        output: {}
        evidenceRefs:
          type: array
          items:
            type: string
        error:
          type: object
          properties:
            code:
              type: string
            message:
              type: string
            retryable:
              type: boolean
          additionalProperties: false
          required:
          - code
          - message
          - retryable
      additionalProperties: false
      required:
      - invocationId
      - status
      - evidenceRefs
      description: The outcome of a capability invocation.
    ExecutionState:
      type: string
      enum:
      - CREATED
      - READY
      - RUNNING
      - WAITING_APPROVAL
      - BLOCKED
      - VERIFYING
      - FAILED
      - COMPLETED
      - CANCELLED
      - EXPIRED
      description: Execution states. COMPLETED, CANCELLED, and EXPIRED are terminal. Invalid transitions are rejected.
    ObservationCreate:
      type: object
      properties:
        source:
          type: object
          properties:
            provider:
              type: string
            resource_id:
              type: string
          additionalProperties: false
          required:
          - provider
          - resource_id
        type:
          type: string
        occurred_at:
          type: string
          format: date-time
        payload_ref:
          $ref: '#/components/schemas/ArtifactRef'
        idempotency_key:
          type: string
      additionalProperties: false
      required:
      - source
      - type
      - occurred_at
      - idempotency_key
      description: Something the runtime learned from an external source. Replaying the same source event must not create a duplicate.
    ObservationAccepted:
      type: object
      properties:
        observation_id:
          type: string
        status:
          type: string
          enum:
          - accepted
        duplicate:
          type: boolean
      additionalProperties: false
      required:
      - observation_id
      - status
      - duplicate
    ContextResolveRequest:
      type: object
      properties:
        observation_ids:
          type: array
          items:
            type: string
        goal_id:
          type: string
        scope:
          type: object
          properties:
            workspace_id:
              type: string
            project_ids:
              type: array
              items:
                type: string
          additionalProperties: false
          required:
          - workspace_id
        include:
          type: array
          items:
            type: string
            enum:
            - related_goals
            - open_commitments
            - relevant_policies
            - prior_decisions
      additionalProperties: false
      required:
      - scope
      - include
    ContextBundle:
      type: object
      properties:
        context_id:
          type: string
        state_version:
          type: integer
          minimum: 0
        related_goals:
          type: array
          items:
            type: string
        open_commitments:
          type: array
          items:
            type: string
        applicable_policies:
          type: array
          items:
            type: string
        unresolved_questions:
          type: array
          items:
            type: string
        retrieved_facts:
          type: array
          items:
            $ref: '#/components/schemas/Fact'
        inferences:
          type: array
          items:
            type: object
            properties:
              statement:
                type: string
              based_on:
                type: array
                items:
                  type: string
            additionalProperties: false
            required:
            - statement
            - based_on
      additionalProperties: false
      required:
      - context_id
      - state_version
      - related_goals
      - open_commitments
      - applicable_policies
      - unresolved_questions
      description: Resolved context. Retrieved facts and inferred interpretations are kept separate.
    CommitmentCreate:
      type: object
      properties:
        goal_id:
          type: string
        objective:
          type: string
        success_criteria:
          type: array
          items:
            $ref: '#/components/schemas/Criterion'
        deadline:
          type: string
          format: date-time
      additionalProperties: false
      required:
      - goal_id
      - objective
      - success_criteria
    Commitment:
      type: object
      properties:
        commitment_id:
          type: string
        goal_id:
          type: string
        objective:
          type: string
        success_criteria:
          type: array
          items:
            $ref: '#/components/schemas/Criterion'
        deadline:
          type: string
          format: date-time
        status:
          type: string
          enum:
          - open
          - completed
          - failed
          - cancelled
          - expired
        version:
          type: integer
          minimum: 0
      additionalProperties: false
      required:
      - commitment_id
      - status
      - version
      description: A durable obligation. It cannot be marked completed solely because an agent claims it is complete.
    CommitmentList:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/Commitment'
        next_cursor:
          type:
          - string
          - 'null'
      additionalProperties: false
      required:
      - data
    PlanCreate:
      type: object
      properties:
        commitment_id:
          type: string
        constraints:
          type: object
          properties:
            require_approval_for_external_actions:
              type: boolean
          additionalProperties: true
        preferred_capabilities:
          type: array
          items:
            type: string
      additionalProperties: false
      required:
      - commitment_id
    Plan:
      type: object
      properties:
        plan_id:
          type: string
        commitment_id:
          type: string
        steps:
          type: array
          items:
            type: object
            properties:
              id:
                type: string
              capability:
                type: string
              depends_on:
                type: array
                items:
                  type: string
            additionalProperties: false
            required:
            - id
            - capability
            - depends_on
      additionalProperties: false
      required:
      - plan_id
      - steps
      description: A validated proposal. The runtime checks it against schemas, dependencies, and policy before execution.
    ExecutionCreate:
      type: object
      properties:
        plan_id:
          type: string
        idempotency_key:
          type: string
        authorization_context:
          type: object
          properties:
            principal_id:
              type: string
          additionalProperties: false
          required:
          - principal_id
      additionalProperties: false
      required:
      - plan_id
      - idempotency_key
      - authorization_context
    ExecutionAccepted:
      type: object
      properties:
        execution_id:
          type: string
        status:
          type: string
          enum:
          - queued
        next_action:
          type: string
      additionalProperties: false
      required:
      - execution_id
      - status
      description: Execution is asynchronous. Acceptance does not mean the work is complete.
    Execution:
      type: object
      properties:
        execution_id:
          type: string
        plan_id:
          type: string
        state:
          $ref: '#/components/schemas/ExecutionState'
        state_version:
          type: integer
          minimum: 0
        correlation_id:
          type: string
        updated_at:
          type: string
          format: date-time
      additionalProperties: false
      required:
      - execution_id
      - state
      - state_version
    TransitionRequest:
      type: object
      properties:
        expected_state:
          $ref: '#/components/schemas/ExecutionState'
        target_state:
          $ref: '#/components/schemas/ExecutionState'
        verification_id:
          type: string
        reason:
          type: string
      additionalProperties: false
      required:
      - expected_state
      - target_state
    Transition:
      type: object
      properties:
        transition_id:
          type: string
        execution_id:
          type: string
        from_state:
          $ref: '#/components/schemas/ExecutionState'
        to_state:
          $ref: '#/components/schemas/ExecutionState'
        state_version:
          type: integer
          minimum: 0
        actor:
          $ref: '#/components/schemas/PrincipalRef'
        reason:
          type: string
        correlation_id:
          type: string
        occurred_at:
          type: string
          format: date-time
      additionalProperties: false
      required:
      - transition_id
      - execution_id
      - from_state
      - to_state
      - state_version
      - actor
      - correlation_id
      - occurred_at
      description: Every accepted transition is persisted with an actor, timestamp, reason, and correlation ID.
    ResultSubmission:
      type: object
      properties:
        output: {}
        evidence_refs:
          type: array
          items:
            type: string
        idempotency_key:
          type: string
      additionalProperties: false
      required:
      - evidence_refs
      - idempotency_key
    VerificationRequest:
      type: object
      properties:
        execution_id:
          type: string
        criteria:
          type: array
          items:
            type: string
      additionalProperties: false
      required:
      - execution_id
      - criteria
    Verification:
      type: object
      properties:
        verification_id:
          type: string
        verdict:
          type: string
          enum:
          - passed
          - failed
        evidence_refs:
          type: array
          items:
            type: string
        checks:
          type: array
          items:
            type: object
            properties:
              name:
                type: string
              kind:
                type: string
                enum:
                - deterministic
                - model_rubric
                - human
              result:
                type: string
                enum:
                - pass
                - fail
            additionalProperties: false
            required:
            - name
            - kind
            - result
      additionalProperties: false
      required:
      - verification_id
      - verdict
      - evidence_refs
      - checks
      description: A verdict must identify which checks were performed.
    RecordCommit:
      type: object
      properties:
        execution_id:
          type: string
        verification_id:
          type: string
        expected_state_version:
          type: integer
          minimum: 0
        changes:
          type: array
          items:
            type: object
            properties:
              entity_id:
                type: string
              operation:
                type: string
              value: {}
            additionalProperties: false
            required:
            - entity_id
            - operation
      additionalProperties: false
      required:
      - expected_state_version
      - changes
      description: A state mutation. A conflicting state version rejects the transaction or invokes a declared conflict policy.
    RecordCommitted:
      type: object
      properties:
        transaction_id:
          type: string
        state_version:
          type: integer
          minimum: 0
        status:
          type: string
          enum:
          - committed
      additionalProperties: false
      required:
      - transaction_id
      - state_version
      - status
    ReviewRequest:
      type: object
      properties:
        goal_id:
          type: string
        review_type:
          type: string
          enum:
          - progress
          - outcome
          - risk
        include:
          type: array
          items:
            type: string
            enum:
            - outcomes
            - unresolved_commitments
            - failures
            - next_actions
      additionalProperties: false
      required:
      - goal_id
      - review_type
    Review:
      type: object
      properties:
        review_id:
          type: string
        goal_status:
          type: string
          enum:
          - active
          - paused
          - achieved
          - abandoned
        recommended_actions:
          type: array
          items:
            type: object
            properties:
              action:
                type: string
              requires_approval:
                type: boolean
            additionalProperties: false
            required:
            - action
            - requires_approval
      additionalProperties: false
      required:
      - review_id
      - goal_status
      - recommended_actions
      description: Recommendations are proposals, not authorized actions.
    ApprovalDecision:
      type: object
      properties:
        decision:
          type: string
          enum:
          - approve
          - deny
        scope:
          type: object
          description: What exactly is authorized, e.g. a document, amount, or recipient.
        expires_at:
          type: string
          format: date-time
      additionalProperties: false
      required:
      - decision
      - expires_at
    Approval:
      type: object
      properties:
        approval_id:
          type: string
        approval_request_id:
          type: string
        decision:
          type: string
          enum:
          - approve
          - deny
        scope:
          type: object
        approved_by:
          $ref: '#/components/schemas/PrincipalRef'
        expires_at:
          type: string
          format: date-time
      additionalProperties: false
      required:
      - approval_id
      - approval_request_id
      - decision
      - approved_by
      - expires_at
      description: A scoped, expiring authorization for a consequential action.
    EventEnvelope:
      type: object
      properties:
        event_id:
          type: string
        event_type:
          type: string
          description: e.g. observation.received, commitment.created, plan.approved, execution.started, execution.blocked, approval.requested, approval.granted, execution.completed, verification.failed, record.committed, goal.achieved
        schema_version:
          type: string
        occurred_at:
          type: string
          format: date-time
        workspace_id:
          type: string
        subject_id:
          type: string
        correlation_id:
          type: string
        causation_id:
          type: string
        payload:
          type: object
      additionalProperties: false
      required:
      - event_id
      - event_type
      - schema_version
      - occurred_at
      - workspace_id
      - subject_id
      - correlation_id
      - payload
    Error:
      type: object
      properties:
        error:
          type: object
          properties:
            code:
              type: string
              enum:
              - INVALID_REQUEST
              - UNAUTHENTICATED
              - FORBIDDEN
              - NOT_FOUND
              - POLICY_APPROVAL_REQUIRED
              - POLICY_DENIED
              - INVALID_TRANSITION
              - STATE_VERSION_CONFLICT
              - VERIFICATION_FAILED
              - RATE_LIMITED
              - INTERNAL
              - CAOP_409_UNSETTLED_EXECUTION_LEASE
              - CAOP_413_INVALIDATION_SUBGRAPH_TOO_LARGE
              - CAOP_422_VERIFY_ARTIFACT_MISMATCH
              - CAOP_422_PRECOMMIT_HOOK_FAILED
              - CAOP_422_PRECOMMIT_MISSING_OWNER
              - CAOP_422_PRECOMMIT_MISSING_LINEAGE
              - CAOP_422_PRECOMMIT_STALE_DEPENDENCY
              - CAOP_422_PRECOMMIT_UNKNOWN_FACT_ID
              - STAGE_UPGRADE_RECOMMENDED
              - MAOP_403_AUTHORITY_INVALID
              - MAOP_403_AUTHORITY_WIDENING
              - MAOP_403_TRUST_FLOOR
              - MAOP_403_SEPARATION_OF_DUTIES
              - MAOP_409_LEASE_CONFLICT
              - MAOP_409_LEASE_FENCED
              - MAOP_410_LEASE_EXPIRED
              - MAOP_409_IDEMPOTENCY_KEY_REUSED
              - MAOP_409_OUTCOME_UNRECONCILED
              - MAOP_422_GUARD_FAILED
              - MAOP_422_EVIDENCE_MISMATCH
              - MAOP_422_BUDGET_EXCEEDED
            message:
              type: string
            retryable:
              type: boolean
            details:
              type: object
          additionalProperties: false
          required:
          - code
          - message
          - retryable
        trace_id:
          type: string
      additionalProperties: false
      required:
      - error
      - trace_id
      description: Standard error envelope (§7.1). v0.1.2 adds CAOP_409_UNSETTLED_EXECUTION_LEASE (HTTP 409), CAOP_413_INVALIDATION_SUBGRAPH_TOO_LARGE (HTTP 413), CAOP_422_VERIFY_ARTIFACT_MISMATCH and the CAOP_422_PRECOMMIT_* codes (HTTP 422; CAOP_422_PRECOMMIT_HOOK_FAILED carries details.failed_hooks), and STAGE_UPGRADE_RECOMMENDED (advisory code, used in resume_brief.system_advisories). MAOP v1 adds the MAOP_* codes of MAOP section 23.2 (HTTP 403, 409, 410 and 422 as the code's number states); MAOP_422_GUARD_FAILED carries details.guards_failed.
    MetricNode:
      type: object
      properties:
        id:
          type: string
        name:
          type: string
        formula:
          type: string
        parentMetricId:
          type: string
        childMetricIds:
          type: array
          items:
            type: string
        owner:
          $ref: '#/components/schemas/PrincipalRef'
        baselineCadence:
          type: string
          enum:
          - hourly
          - daily
          - weekly
          - monthly
        varianceThresholds:
          type: object
          properties:
            warningDeltaPct:
              type: number
            criticalDeltaPct:
              type: number
          additionalProperties: false
          required:
          - warningDeltaPct
          - criticalDeltaPct
      additionalProperties: false
      required:
      - id
      - name
      - childMetricIds
      - owner
      - baselineCadence
      - varianceThresholds
      description: A node in a hierarchical KPI tree. Variance beyond thresholds triggers Understand or a Commitment.
    ApprovalRoutingRule:
      type: object
      properties:
        policyId:
          type: string
        requiredRoles:
          type: array
          items:
            type: string
        minQuorum:
          type: integer
          minimum: 1
        expirationSeconds:
          type: integer
          minimum: 1
        escalateToRoleOnTimeout:
          type: string
      additionalProperties: false
      required:
      - policyId
      - requiredRoles
      - minQuorum
      - expirationSeconds
      description: Delegation of Authority routing for a policy.
    LoopDriver:
      type: string
      enum:
      - CLIENT_POLLED
      - KERNEL_MANAGED
      description: 'Who drives the trigger loop: the conversational host (CLIENT_POLLED) or the runtime kernel (KERNEL_MANAGED).'
    ExecutionLocus:
      type: string
      enum:
      - HOST_DELEGATED
      - KERNEL_PROXIED
      description: Whether EXECUTE returns a delegation directive to the calling host or executes server-side.
    AuthCustodian:
      type: string
      enum:
      - CLIENT_SESSION
      - CREASURA_VAULT
      description: Whether downstream OAuth tokens are held by the host client or stored in the runtime's vault.
    AttestationTier:
      type: string
      enum:
      - HOST_ASSERTED
      - KERNEL_ATTESTED
      - USER_CONFIRMED
      description: 'provenance.attestation: how the execution evidence behind a fact was obtained. Field presence is evidence, not proof; hence HOST_ASSERTED.'
    ConformanceProfileId:
      type: string
      enum:
      - CAOP-STAGE-1
      - CAOP-STAGE-2
      - CAOP-STAGE-3
    ConformanceProfile:
      type: object
      properties:
        id:
          $ref: '#/components/schemas/ConformanceProfileId'
        loop_driver:
          $ref: '#/components/schemas/LoopDriver'
        auth_custodian:
          $ref: '#/components/schemas/AuthCustodian'
        execution_locus:
          $ref: '#/components/schemas/ExecutionLocus'
        max_attestation:
          $ref: '#/components/schemas/AttestationTier'
        v0_1_conformance_level:
          type: string
          enum:
          - L2
          - L3
          description: CAOP-STAGE-1 and CAOP-STAGE-2 are variants of L2 (Stateful); CAOP-STAGE-3 corresponds to L3 (Autonomous).
      additionalProperties: false
      required:
      - id
      - loop_driver
      - auth_custodian
      - execution_locus
      - max_attestation
      - v0_1_conformance_level
      description: A runtime conformance profile. Advancing from Stage 1 to Stage 3 requires no breaking change to Goals, the eight-stage lifecycle, or bitemporal State queries.
    PromotionPolicy:
      type: object
      properties:
        max_expired_leases_before_stage2_prompt:
          type: integer
          minimum: 1
        rolling_window_days:
          type: integer
          minimum: 1
      additionalProperties: false
      required:
      - max_expired_leases_before_stage2_prompt
      - rolling_window_days
      description: Threshold at which repeated EXECUTE_EXPIRED leases trigger a recommendation to promote a capability from HOST_DELEGATED (Stage 1) to KERNEL_PROXIED (Stage 2).
    CapabilityRegistration:
      type: object
      properties:
        capability_id:
          type: string
        version:
          type: string
        execution_locus:
          $ref: '#/components/schemas/ExecutionLocus'
        auth_custodian:
          $ref: '#/components/schemas/AuthCustodian'
        receipt_lease_seconds:
          type: integer
          minimum: 1
          description: Maximum duration a HOST_DELEGATED invocation may remain uncommitted in EXECUTE_DISPATCHED before transitioning to EXECUTE_EXPIRED.
        required_receipt_fields:
          type: array
          items:
            type: string
          description: Provider-specific receipt verification keys that MUST be present in raw_output during VERIFY.
        promotion_policy:
          $ref: '#/components/schemas/PromotionPolicy'
        input_schema:
          type: object
        output_schema:
          type: object
      additionalProperties: false
      required:
      - capability_id
      - version
      - execution_locus
      - auth_custodian
      - receipt_lease_seconds
      - required_receipt_fields
      - promotion_policy
      description: A capability as registered in the v0.1.2 Capability API. It MUST declare its execution locus, credential custodian, lease timeout, provider-specific receipt verification keys, and Stage-2 promotion thresholds.
    EpistemicStatus:
      type: string
      enum:
      - CANDIDATE_PROPOSAL
      - RATIFIED_COMMITMENT
      - VERIFIED_FACT
      description: 'Adoption: CANDIDATE_PROPOSAL (UNDERSTAND or PLAN; excluded from default truth queries until ratified) → RATIFIED_COMMITMENT (passed pre-commit hooks and approval at COMMIT) → VERIFIED_FACT (promoted at RECORD once evidence passes VERIFY). Freshness is tracked separately.'
    Freshness:
      type: string
      enum:
      - CURRENT
      - STALE_UPSTREAM_PREMISE
      description: Freshness, separate from adoption. STALE_UPSTREAM_PREMISE is assigned by the kernel when a required premise has no remaining CURRENT support. A stale VERIFIED_FACT keeps epistemic_status VERIFIED_FACT. Default truth queries flag, but do not hide, stale entries.
    DependsOnAlternatives:
      type: array
      items:
        type: array
        items:
          type: string
      description: Groups of interchangeable supporting Fact IDs. Each inner array is one required premise; it stays supported while ANY member is CURRENT.
    InvalidationContext:
      type: object
      properties:
        invalidated_by_fact_id:
          type: string
        invalidated_at:
          type: string
          format: date-time
        reason:
          type: string
      additionalProperties: false
      required:
      - invalidated_by_fact_id
      - invalidated_at
      description: Why a dependent lost CURRENT support. Only freshness and invalidation_context change on dependents.
    FactProvenance:
      type: object
      properties:
        work_id:
          type: string
        invocation_id:
          type: string
        execution_locus:
          $ref: '#/components/schemas/ExecutionLocus'
        attestation:
          $ref: '#/components/schemas/AttestationTier'
        verified_fields:
          type: array
          items:
            type: string
      additionalProperties: false
      required:
      - work_id
      - execution_locus
      - attestation
      description: Execution provenance of a fact. The attestation tier is immutable.
    BitemporalFact:
      type: object
      properties:
        fact_id:
          type: string
        subject:
          $ref: '#/components/schemas/EntityRef'
        predicate:
          type: string
        object: {}
        epistemic_status:
          $ref: '#/components/schemas/EpistemicStatus'
        freshness:
          $ref: '#/components/schemas/Freshness'
        depends_on_fact_ids:
          type: array
          items:
            type: string
          description: Upstream Fact IDs; each entry is a required premise on its own.
        depends_on_alternatives:
          $ref: '#/components/schemas/DependsOnAlternatives'
        invalidation_context:
          oneOf:
          - $ref: '#/components/schemas/InvalidationContext'
          - type: 'null'
        valid_time:
          type: object
          properties:
            start:
              type: string
              format: date-time
            end:
              type:
              - string
              - 'null'
              format: date-time
          additionalProperties: false
          required:
          - start
        transaction_time:
          type: object
          properties:
            recorded_at:
              type: string
              format: date-time
            superseded_at:
              type:
              - string
              - 'null'
              format: date-time
          additionalProperties: false
          required:
          - recorded_at
        provenance:
          $ref: '#/components/schemas/FactProvenance'
      additionalProperties: false
      required:
      - fact_id
      - subject
      - predicate
      - object
      - epistemic_status
      - freshness
      - depends_on_fact_ids
      - valid_time
      - transaction_time
      description: A bitemporal fact (valid_time and transaction_time) with explicit upstream lineage and execution provenance. Superseded facts and their history are never rewritten.
    StateConfig:
      type: object
      properties:
        workspace_id:
          type: string
        max_invalidation_subgraph:
          type: integer
          minimum: 1
          description: Largest affected subgraph one update may invalidate. Larger updates are rejected before commit with CAOP_413_INVALIDATION_SUBGRAPH_TOO_LARGE; nothing is partially applied.
      additionalProperties: false
      required:
      - workspace_id
      - max_invalidation_subgraph
      description: Workspace State API limits for synchronous causal invalidation.
    PreCommitHook:
      type: object
      properties:
        hook_id:
          type: string
          description: e.g. REQUIRE_EXPLICIT_OWNER, REQUIRE_EVIDENCE_LINEAGE, BLOCK_STALE_PREMISES
        target_path:
          type: string
          description: Path into the staged work, e.g. commitment.owner_principal_id
        condition:
          type: string
          description: e.g. NON_EMPTY_PRINCIPAL_REF, NON_EMPTY_ARRAY, ALL_UPSTREAM_FACTS_VERIFIED_ACTIVE (every upstream fact is VERIFIED_FACT with freshness CURRENT)
        error_code:
          type: string
          description: A CAOP_422_PRECOMMIT_* code reported in failed_hooks
      additionalProperties: false
      required:
      - hook_id
      - target_path
      - condition
      - error_code
      description: A deterministic check evaluated at COMMIT before a plan may reach EXECUTE_PENDING or request approval.
    PolicyRegistration:
      type: object
      properties:
        policy_id:
          type: string
        scope_goal_types:
          type: array
          items:
            type: string
        minimum_attestation:
          $ref: '#/components/schemas/AttestationTier'
        require_human_approval:
          type: boolean
        pre_commit_hooks:
          type: array
          items:
            $ref: '#/components/schemas/PreCommitHook'
      additionalProperties: false
      required:
      - policy_id
      - pre_commit_hooks
      description: A Policy as registered in the v0.1.2 Policy API.
    FailedHook:
      type: object
      properties:
        hook_id:
          type: string
        error_code:
          type: string
        remediation:
          type: string
      additionalProperties: false
      required:
      - hook_id
      - error_code
      - remediation
    ExecuteSubState:
      type: string
      enum:
      - EXECUTE_PENDING
      - EXECUTE_DISPATCHED
      - EXECUTE_COMPLETED
      - EXECUTE_EXPIRED
      - EXECUTE_FAILED
      description: 'Sub-states of the EXECUTE lifecycle stage. They refine, not replace, the v0.1 execution states: EXECUTE_PENDING ↔ READY; EXECUTE_DISPATCHED ↔ RUNNING (host-delegated); EXECUTE_COMPLETED → VERIFYING; EXECUTE_EXPIRED ↔ EXPIRED; EXECUTE_FAILED ↔ FAILED.'
    CommitSubState:
      type: string
      enum:
      - COMMIT_AWAITING_APPROVAL
      description: 'Sub-state of the COMMIT lifecycle stage: pre-commit hooks passed, human approval required before dispatch. Maps to WAITING_APPROVAL / POLICY_APPROVAL_REQUIRED.'
    DispatchStep:
      type: object
      properties:
        step:
          type: integer
          minimum: 1
        action:
          type: string
          enum:
          - INVOKE_HOST_NATIVE_TOOL
          - CALL_CAOP_TOOL
        target_capability:
          type: string
        arguments:
          type: object
        tool_name:
          type: string
        required_nonce:
          type: string
        required_receipt_fields:
          type: array
          items:
            type: string
      additionalProperties: false
      required:
      - step
      - action
      description: One mandatory step the host must perform in the same turn.
    DispatchDirective:
      type: object
      properties:
        work_id:
          type: string
        lifecycle_stage:
          type: string
          enum:
          - EXECUTE
        sub_state:
          $ref: '#/components/schemas/ExecuteSubState'
        turn_directive:
          type: string
          enum:
          - INCOMPLETE_TURN_CONTINUATION_REQUIRED
        DO_NOT_RESPOND_TO_USER_YET:
          type: boolean
        directive:
          type: object
          properties:
            invocation_id:
              type: string
            execution_locus:
              $ref: '#/components/schemas/ExecutionLocus'
            idempotency_key:
              type: string
            lease_expires_at:
              type: string
              format: date-time
            mandatory_next_steps:
              type: array
              items:
                $ref: '#/components/schemas/DispatchStep'
          additionalProperties: false
          required:
          - invocation_id
          - execution_locus
          - idempotency_key
          - lease_expires_at
          - mandatory_next_steps
      additionalProperties: false
      required:
      - work_id
      - lifecycle_stage
      - sub_state
      - turn_directive
      - DO_NOT_RESPOND_TO_USER_YET
      - directive
      description: Normative Stage-1 dispatch response (anti-termination envelope). turn_directive and DO_NOT_RESPOND_TO_USER_YET are instructions to the host model; the enforceable guarantee is the lease lock (CAOP_409_UNSETTLED_EXECUTION_LEASE).
    GoalPulseSLA:
      type: object
      properties:
        goal_id:
          type: string
        loop_driver:
          $ref: '#/components/schemas/LoopDriver'
        expected_pulse_interval_seconds:
          type: integer
          minimum: 1
        grace_period_seconds:
          type: integer
          minimum: 0
        last_pulse_at:
          type: string
          format: date-time
      additionalProperties: false
      required:
      - goal_id
      - loop_driver
      - expected_pulse_interval_seconds
      - grace_period_seconds
      description: Heartbeat SLA for a CLIENT_POLLED Goal (the dead-man’s switch). Requires a kernel-side timer and an out-of-band notification channel.
    PulseInput:
      type: object
      properties:
        scope_goal_ids:
          type: array
          items:
            type: string
        unobserved_events:
          type: array
          items:
            type: object
            required:
            - source
            - summary
            properties:
              source:
                type: string
              summary:
                type: string
              external_ref:
                type: string
              supersedes_fact_id:
                type: string
        compaction_mode:
          $ref: '#/components/schemas/CompactionMode'
        hydrate_capability_ids:
          type: array
          items:
            type: string
          description: 'Lazy Capability Discovery: Pass specific capability IDs from the stub directory to load their full JSON input schemas.'
      description: 'v0.2 adds compaction_mode and hydrate_capability_ids (published inputSchema: PulseInputV02).'
    StageWorkInput:
      type: object
      required:
      - goal_id
      - understanding
      - commitment
      - plan_steps
      properties:
        goal_id:
          type: string
        supersedes_work_id:
          type: string
          description: Optional ID of a STALE_UPSTREAM_PREMISE work item being replaced.
        understanding:
          type: object
          required:
          - intent_summary
          - derived_facts
          properties:
            intent_summary:
              type: string
            derived_facts:
              type: array
              items:
                type: object
                required:
                - subject
                - predicate
                - object
                properties:
                  subject:
                    type: string
                  predicate:
                    type: string
                  object:
                    type: object
                  depends_on_fact_ids:
                    type: array
                    items:
                      type: string
                    description: Upstream Fact IDs that this derived fact or decision relies upon. Omit if unknown; the REQUIRE_EVIDENCE_LINEAGE hook will reject commit and the host must ask the user.
                  depends_on_alternatives:
                    type: array
                    items:
                      type: array
                      items:
                        type: string
                    description: Optional groups of interchangeable supporting Fact IDs. The premise stays supported while any member is CURRENT.
                  valid_from:
                    type: string
                    format: date-time
        commitment:
          type: object
          required:
          - title
          - rationale
          - reversible
          properties:
            title:
              type: string
            rationale:
              type: string
            owner_principal_id:
              type: string
              description: Explicit human or agent principal responsible for this commitment. Omit if unknown; the REQUIRE_EXPLICIT_OWNER hook will reject commit and the host must ask the user.
            due_at:
              type: string
              format: date-time
            reversible:
              type: boolean
        plan_steps:
          type: array
          items:
            type: object
            required:
            - step_index
            - capability_id
            - arguments
            properties:
              step_index:
                type: integer
              capability_id:
                type: string
              arguments:
                type: object
        parent_work_id:
          type: string
          description: Stages this work as a child work scope of the given parent (hierarchical sub-agent isolation).
        isolation_policy:
          $ref: '#/components/schemas/IsolationPolicy'
      description: v0.2 adds parent_work_id and isolation_policy for child work scopes.
    DispatchWorkInput:
      type: object
      required:
      - work_id
      - decision
      properties:
        work_id:
          type: string
        decision:
          type: string
          enum:
          - APPROVE_AND_DISPATCH
          - APPROVE_WITH_STEERING_DELTA
          - REJECT_WORK
        approval_note:
          type: string
        steering_delta:
          $ref: '#/components/schemas/SteeringDelta'
        two_phase_verification:
          $ref: '#/components/schemas/TwoPhaseVerification'
      description: 'v0.2 adds APPROVE_WITH_STEERING_DELTA, steering_delta and two_phase_verification (published inputSchema: DispatchWorkInputV02).'
    SettleReceiptInput:
      type: object
      required:
      - work_id
      - invocation_id
      - idempotency_key
      - nonce
      - status
      properties:
        work_id:
          type: string
        invocation_id:
          type: string
        idempotency_key:
          type: string
        nonce:
          type: string
          description: Exact required_nonce returned by caop_dispatch_work.
        status:
          type: string
          enum:
          - SUCCEEDED
          - FAILED
          - USER_CONFIRMED_OVERRIDE
        external_ref:
          type: string
        raw_output:
          type: object
          description: Raw JSON output from the host native tool containing all required_receipt_fields.
        error_detail:
          type: string
        review_outcome:
          type: string
          enum:
          - GOAL_SATISFIED
          - PARTIAL_PROGRESS
          - REPLAN_REQUIRED
        distilled_return_payload:
          $ref: '#/components/schemas/DistilledReturnPayload'
      description: v0.2 adds distilled_return_payload, returned by a child work scope when it completes RECORD.
    OpenLease:
      type: object
      properties:
        work_id:
          type: string
        invocation_id:
          type: string
        sub_state:
          $ref: '#/components/schemas/ExecuteSubState'
        required_nonce:
          type: string
        lease_expires_at:
          type: string
          format: date-time
      additionalProperties: false
      required:
      - work_id
      - invocation_id
      - sub_state
      - required_nonce
      description: An unsettled EXECUTE_DISPATCHED or EXECUTE_EXPIRED invocation.
    StaleCommitment:
      type: object
      properties:
        work_id:
          type: string
        fact_id:
          type: string
        title:
          type: string
        epistemic_status:
          $ref: '#/components/schemas/EpistemicStatus'
        freshness:
          $ref: '#/components/schemas/Freshness'
        invalidated_by_fact_id:
          type: string
        summary:
          type: string
      additionalProperties: false
      required:
      - work_id
      - fact_id
      - title
      - epistemic_status
      - freshness
      description: A commitment whose freshness is STALE_UPSTREAM_PREMISE; it keeps its adoption status.
    UnassignedBlocker:
      type: object
      properties:
        work_id:
          type: string
        title:
          type: string
        missing_hook:
          type: string
      additionalProperties: false
      required:
      - work_id
      - title
      - missing_hook
    RankedNextAction:
      type: object
      properties:
        rank:
          type: integer
          minimum: 1
        work_id:
          type: string
        action_type:
          type: string
        blocking_dependents_count:
          type: integer
          minimum: 0
        recommended_prompt:
          type: string
      additionalProperties: false
      required:
      - rank
      - work_id
      - action_type
    SystemAdvisory:
      type: object
      properties:
        code:
          type: string
          enum:
          - STAGE_UPGRADE_RECOMMENDED
        capability_id:
          type: string
        message:
          type: string
      additionalProperties: false
      required:
      - code
      - message
    ResumeBrief:
      type: object
      properties:
        unsettled_leases:
          type: array
          items:
            $ref: '#/components/schemas/OpenLease'
        stale_commitments:
          type: array
          items:
            $ref: '#/components/schemas/StaleCommitment'
        unassigned_blockers:
          type: array
          items:
            $ref: '#/components/schemas/UnassignedBlocker'
        ranked_next_actions:
          type: array
          items:
            $ref: '#/components/schemas/RankedNextAction'
        system_advisories:
          type: array
          items:
            $ref: '#/components/schemas/SystemAdvisory'
      additionalProperties: false
      required:
      - unsettled_leases
      - stale_commitments
      - unassigned_blockers
      - ranked_next_actions
      - system_advisories
      description: Deterministic, ranked delta brief returned at the start of a session, without file uploads or chat history reconstruction.
    PulseResponse:
      type: object
      properties:
        pulse_timestamp:
          type: string
          format: date-time
        workspace_stage_profile:
          $ref: '#/components/schemas/ConformanceProfileId'
        resume_brief:
          $ref: '#/components/schemas/ResumeBrief'
        capability_stubs:
          type: array
          items:
            $ref: '#/components/schemas/CapabilityStub'
        hydrated_capabilities:
          type: array
          items:
            $ref: '#/components/schemas/HydratedCapability'
        outcome_verifications:
          type: array
          items:
            $ref: '#/components/schemas/OutcomeVerification'
      additionalProperties: false
      required:
      - pulse_timestamp
      - workspace_stage_profile
      - resume_brief
      description: Normative caop_pulse response payload. v0.2 adds capability_stubs, hydrated_capabilities and outcome_verifications.
    StageWorkResult:
      type: object
      properties:
        work_id:
          type: string
        lifecycle_stage:
          type: string
          enum:
          - COMMIT
          - EXECUTE
        sub_state:
          type: string
          enum:
          - COMMIT_AWAITING_APPROVAL
          - EXECUTE_PENDING
        epistemic_status:
          $ref: '#/components/schemas/EpistemicStatus'
      additionalProperties: false
      required:
      - work_id
      - lifecycle_stage
      - sub_state
      description: 'UNDERSTAND → COMMIT → PLAN: pre-commit hooks passed; halted at approval (COMMIT_AWAITING_APPROVAL) or at EXECUTE_PENDING.'
    SettlementResult:
      type: object
      properties:
        work_id:
          type: string
        invocation_id:
          type: string
        lifecycle_stage:
          type: string
          enum:
          - RECORD
          - REVIEW
        attestation:
          $ref: '#/components/schemas/AttestationTier'
        fact_ids:
          type: array
          items:
            type: string
        thread_unlocked:
          type: boolean
        review_outcome:
          type: string
          enum:
          - GOAL_SATISFIED
          - PARTIAL_PROGRESS
          - REPLAN_REQUIRED
        sub_state:
          $ref: '#/components/schemas/RecordSubState'
        outcome_verification:
          $ref: '#/components/schemas/OutcomeVerification'
      additionalProperties: false
      required:
      - work_id
      - invocation_id
      - lifecycle_stage
      - attestation
      - thread_unlocked
      description: 'Result of VERIFY → RECORD (→ REVIEW): receipt verified, facts recorded with their attestation tier, thread lease released. v0.2: with a phase_2_deferred check, settlement records the receipt and returns sub_state RECORDED_AWAITING_OUTCOME_VERIFY.'
    DispatchWorkResult:
      oneOf:
      - $ref: '#/components/schemas/DispatchDirective'
      - $ref: '#/components/schemas/SettlementResult'
      description: 'HOST_DELEGATED: the anti-termination DispatchDirective. KERNEL_PROXIED: executed via the vault with VERIFY + RECORD auto-folded, returning a SettlementResult.'
    SteeringDelta:
      type: object
      description: Non-destructive mid-flight overrides applied before EXECUTE without aborting the work lifecycle.
      properties:
        patched_step_arguments:
          type: array
          items:
            type: object
            required:
            - step_index
            - argument_overrides
            properties:
              step_index:
                type: integer
              argument_overrides:
                type: object
        added_policy_constraints:
          type: array
          items:
            type: string
        rationale:
          type: string
    Phase2DeferredCheck:
      type: object
      required:
      - check_after_seconds
      - verification_capability_id
      - success_predicate
      properties:
        check_after_seconds:
          type: integer
        verification_capability_id:
          type: string
        success_predicate:
          type: string
    TwoPhaseVerification:
      type: object
      properties:
        phase_1_immediate:
          type: string
          enum:
          - REQUIRE_NONCE_AND_ARTIFACT
        phase_2_deferred:
          $ref: '#/components/schemas/Phase2DeferredCheck'
    VerifySubState:
      type: string
      enum:
      - VERIFY_PHASE_1_IMMEDIATE
      - VERIFY_PHASE_2_DEFERRED
      description: Sub-states of the VERIFY lifecycle stage. VERIFY_PHASE_1_IMMEDIATE validates the execution receipt (nonce and artifact); VERIFY_PHASE_2_DEFERRED evaluates success_predicate with verification_capability_id once check_after_seconds has elapsed. Both map to the v0.1 VERIFYING state.
    RecordSubState:
      type: string
      enum:
      - RECORDED_AWAITING_OUTCOME_VERIFY
      description: 'Receipts recorded in Phase 1 are written as facts with their attestation tier, and the commitment stays open until the deferred Phase-2 check passes. Maps to the v0.1 VERIFYING state: the execution reaches COMPLETED only after that check passes. In CAOP-STAGE-1 the check runs on the next caop_pulse after check_after_seconds, so it depends on the host pulsing.'
    OutcomeVerification:
      type: object
      properties:
        work_id:
          type: string
        invocation_id:
          type: string
        sub_state:
          $ref: '#/components/schemas/VerifySubState'
        verification_capability_id:
          type: string
        success_predicate:
          type: string
        check_due_at:
          type: string
          format: date-time
        status:
          type: string
          enum:
          - PENDING
          - PASSED
          - FAILED
        fact_ids:
          type: array
          items:
            type: string
      additionalProperties: false
      required:
      - work_id
      - sub_state
      - verification_capability_id
      - success_predicate
      - check_due_at
      - status
      description: A deferred Phase-2 outcome check as reported by caop_pulse.
    IsolationPolicy:
      type: object
      properties:
        execution_scope:
          type: string
          enum:
          - ISOLATED_SUBAGENT_CONTEXT
        return_contract:
          type: string
          enum:
          - DISTILLED_FACTS_AND_ARTIFACT_REF_ONLY
        max_token_budget:
          type: integer
          minimum: 1
          description: Enforced by the kernel only when it drives the model (CAOP-STAGE-3); advisory in CAOP-STAGE-1.
        prune_raw_traces_on_record:
          type: boolean
        trace_hash:
          type: string
          description: Content hash of the pruned raw trace, e.g. "sha256:<hex>". Promoted facts keep it as part of their provenance pointer.
        retention_policy:
          type: string
          description: Declared retention policy under which raw traces MAY be deleted, e.g. "retain_30_days". Without one, pruned traces leave the active context but are not deleted.
      additionalProperties: false
      required:
      - execution_scope
      - return_contract
      description: How a child work scope is isolated from its parent. A child inherits the parent’s authority and can only narrow it.
    DistilledReturnPayload:
      type: object
      properties:
        artifact_ref:
          $ref: '#/components/schemas/ArtifactRef'
        promoted_fact_ids:
          type: array
          items:
            type: string
        compacted_summary:
          type: string
        trace_hash:
          type: string
          description: Content hash of the pruned raw trace, e.g. "sha256:<hex>". Promoted facts keep it as part of their provenance pointer.
        retention_policy:
          type: string
          description: Declared retention policy under which raw traces MAY be deleted, e.g. "retain_30_days". Without one, pruned traces leave the active context but are not deleted.
      additionalProperties: false
      required:
      - promoted_fact_ids
      - compacted_summary
      description: 'What a child work scope returns to its parent at RECORD: the ratified commitment and distilled facts only. Pruning removes raw traces from the active context, not from provenance: every promoted fact keeps a provenance pointer (child work_id, invocation IDs and trace_hash).'
    ChildWork:
      type: object
      properties:
        work_id:
          type: string
        parent_work_id:
          type: string
        isolation_policy:
          $ref: '#/components/schemas/IsolationPolicy'
        distilled_return_payload:
          $ref: '#/components/schemas/DistilledReturnPayload'
      additionalProperties: false
      required:
      - work_id
      - parent_work_id
      - isolation_policy
      description: A child work scope (hierarchical sub-agent isolation), as staged through caop_stage_work.
    CompactionMode:
      type: string
      enum:
      - FACT_POINTERS_ONLY
      - SUMMARY_WITH_LINEAGE
      - FULL_RAW_ARTIFACTS
      default: SUMMARY_WITH_LINEAGE
    CapabilityStub:
      type: object
      properties:
        capability_id:
          type: string
        summary:
          type: string
      additionalProperties: false
      required:
      - capability_id
      - summary
      description: 'Compact directory entry returned by caop_pulse. Capabilities are not MCP tools: they are invoked through caop_stage_work plan_steps by capability_id.'
    HydratedCapability:
      type: object
      properties:
        capability_id:
          type: string
        input_schema:
          type: object
      additionalProperties: false
      required:
      - capability_id
      - input_schema
      description: A capability schema hydrated on request (hydrate_capability_ids). It is returned as data; it does not change the host’s tool list.
    DispatchWorkInputV02:
      type: object
      required:
      - work_id
      - decision
      properties:
        work_id:
          type: string
        decision:
          type: string
          enum:
          - APPROVE_AND_DISPATCH
          - APPROVE_WITH_STEERING_DELTA
          - REJECT_WORK
        steering_delta:
          type: object
          description: Non-destructive mid-flight overrides applied before EXECUTE without aborting the work lifecycle.
          properties:
            patched_step_arguments:
              type: array
              items:
                type: object
                required:
                - step_index
                - argument_overrides
                properties:
                  step_index:
                    type: integer
                  argument_overrides:
                    type: object
            added_policy_constraints:
              type: array
              items:
                type: string
            rationale:
              type: string
        two_phase_verification:
          type: object
          properties:
            phase_1_immediate:
              type: string
              enum:
              - REQUIRE_NONCE_AND_ARTIFACT
            phase_2_deferred:
              type: object
              required:
              - check_after_seconds
              - verification_capability_id
              - success_predicate
              properties:
                check_after_seconds:
                  type: integer
                verification_capability_id:
                  type: string
                success_predicate:
                  type: string
    PulseInputV02:
      type: object
      properties:
        scope_goal_ids:
          type: array
          items:
            type: string
        compaction_mode:
          type: string
          enum:
          - FACT_POINTERS_ONLY
          - SUMMARY_WITH_LINEAGE
          - FULL_RAW_ARTIFACTS
          default: SUMMARY_WITH_LINEAGE
        hydrate_capability_ids:
          type: array
          items:
            type: string
          description: 'Lazy Capability Discovery: Pass specific capability IDs from the stub directory to load their full JSON input schemas.'
    AgentIdentity:
      type: object
      properties:
        agent_id:
          type: string
          pattern: ^agt_[A-Za-z0-9_.-]+$
          description: Stable agent identifier, e.g. "agt_impl_7".
        display_name:
          type: string
        principal:
          $ref: '#/components/schemas/PrincipalRef'
          description: The accountable principal (user, role or service) the agent acts for.
        provider:
          type: string
          description: Free-form model or runtime provider label. Informational only; never used for authorization.
        model:
          type: string
          description: Free-form model label. Informational only.
        public_key:
          type: string
          description: Optional public key (e.g. "ed25519:<base64>") used to attest receipts (trust_level T1_attested).
        attestation:
          $ref: '#/components/schemas/AttestationTier'
      additionalProperties: false
      required:
      - agent_id
      - principal
      description: Vendor-neutral identity of one agent. Identity is separate from roles and from authority.
    AgentRole:
      type: string
      enum:
      - supervisor
      - planner
      - implementer
      - reviewer
      - verifier
      - approver
      - observer
      description: 'Role an agent may hold in a supervision tree. Separation of duties is checked per work item: the implementer of a child work item MUST NOT also be its reviewer or approver.'
    AgentRegistration:
      type: object
      properties:
        registration_id:
          type: string
          description: Assigned by the runtime; omitted in the request.
        identity:
          $ref: '#/components/schemas/AgentIdentity'
        roles:
          type: array
          items:
            $ref: '#/components/schemas/AgentRole'
          minItems: 1
          uniqueItems: true
        capability_stubs:
          type: array
          items:
            $ref: '#/components/schemas/CapabilityStub'
          description: Capabilities advertised lazily as compact stubs; full input schemas are hydrated on demand (see HydratedCapability).
        max_concurrent_leases:
          type: integer
          minimum: 1
        idempotency_key:
          type: string
          minLength: 1
        status:
          type: string
          enum:
          - active
          - suspended
          - retired
        registered_at:
          type: string
          format: date-time
      additionalProperties: false
      required:
      - identity
      - roles
      description: 'Request and result of agents.register: an agent identity, the roles it may take, and its lazily advertised capabilities. Registering grants no authority; authority is granted per delegation (AuthorityGrant).'
    Delegation:
      type: object
      properties:
        delegation_id:
          type: string
          minLength: 1
        child_work_id:
          type: string
          minLength: 1
        parent_work_id:
          type: string
          minLength: 1
        supervisor_agent_id:
          type: string
          pattern: ^agt_[A-Za-z0-9_.-]+$
          description: Stable agent identifier, e.g. "agt_impl_7".
        child_agent_id:
          type: string
          pattern: ^agt_[A-Za-z0-9_.-]+$
          description: Stable agent identifier, e.g. "agt_impl_7".
        role:
          $ref: '#/components/schemas/AgentRole'
        objective:
          type: string
          minLength: 1
        acceptance_criteria:
          type: array
          items:
            $ref: '#/components/schemas/Criterion'
        isolation_policy:
          $ref: '#/components/schemas/IsolationPolicy'
        budget:
          type: object
          properties:
            max_token_budget:
              type: integer
              minimum: 1
            max_wall_clock_seconds:
              type: integer
              minimum: 1
            max_cost_units:
              type: number
              minimum: 0
            max_attempts:
              type: integer
              minimum: 1
          additionalProperties: false
          minProperties: 1
          description: Resource budget for the child work item. A child budget MUST NOT exceed the parent's remaining budget.
        authority:
          $ref: '#/components/schemas/AuthorityGrant'
          description: The authority subset delegated to the child.
        guards:
          type: array
          items:
            $ref: '#/components/schemas/Guard'
        lease_seconds:
          type: integer
          minimum: 1
          description: Requested execution lease duration.
        state:
          $ref: '#/components/schemas/ChildLifecycleState'
        lease:
          $ref: '#/components/schemas/Lease'
        receipt_ids:
          type: array
          items:
            type: string
        distilled_return_payload:
          $ref: '#/components/schemas/DistilledReturnPayload'
        state_version:
          type: integer
          minimum: 0
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
      additionalProperties: false
      required:
      - delegation_id
      - parent_work_id
      - child_work_id
      - supervisor_agent_id
      - child_agent_id
      - role
      - objective
      - isolation_policy
      - authority
      - state
      - created_at
      description: A delegated child work item and its current lifecycle state. Result of delegations.create and delegations.get.
    DelegationCreate:
      type: object
      properties:
        parent_work_id:
          type: string
          minLength: 1
        supervisor_agent_id:
          type: string
          pattern: ^agt_[A-Za-z0-9_.-]+$
          description: Stable agent identifier, e.g. "agt_impl_7".
        child_agent_id:
          type: string
          pattern: ^agt_[A-Za-z0-9_.-]+$
          description: Stable agent identifier, e.g. "agt_impl_7".
        role:
          $ref: '#/components/schemas/AgentRole'
        objective:
          type: string
          minLength: 1
        acceptance_criteria:
          type: array
          items:
            $ref: '#/components/schemas/Criterion'
        isolation_policy:
          $ref: '#/components/schemas/IsolationPolicy'
        budget:
          type: object
          properties:
            max_token_budget:
              type: integer
              minimum: 1
            max_wall_clock_seconds:
              type: integer
              minimum: 1
            max_cost_units:
              type: number
              minimum: 0
            max_attempts:
              type: integer
              minimum: 1
          additionalProperties: false
          minProperties: 1
          description: Resource budget for the child work item. A child budget MUST NOT exceed the parent's remaining budget.
        authority:
          $ref: '#/components/schemas/AuthorityGrant'
          description: The authority subset delegated to the child.
        guards:
          type: array
          items:
            $ref: '#/components/schemas/Guard'
        lease_seconds:
          type: integer
          minimum: 1
          description: Requested execution lease duration.
        idempotency_key:
          type: string
          minLength: 1
      additionalProperties: false
      required:
      - parent_work_id
      - supervisor_agent_id
      - child_agent_id
      - role
      - objective
      - isolation_policy
      - authority
      - idempotency_key
      description: 'Request of delegations.create: a supervisor delegates a child work item to another agent with an isolation policy, a budget and an authority subset.'
    AuthorityGrant:
      type: object
      properties:
        grant_id:
          type: string
          minLength: 1
          description: Grant identifier.
        grantor:
          $ref: '#/components/schemas/PrincipalRef'
          description: Who grants the authority (the supervisor agent or a human principal).
        grantee_agent_id:
          type: string
          pattern: ^agt_[A-Za-z0-9_.-]+$
          description: Stable agent identifier, e.g. "agt_impl_7".
        parent_grant_id:
          type: string
          description: The grant this one is derived from. A derived grant's scope MUST be a subset of its parent's, and its expires_at MUST NOT be later.
        trust_level:
          type: string
          enum:
          - T0_relayed
          - T1_attested
          description: 'T0_relayed: the grantee''s claims are relayed by the host and treated as assertions. T1_attested: the grantee''s receipts are attested (signed or runtime-observed).'
        scope:
          type: array
          items:
            type: string
            minLength: 1
          minItems: 1
          uniqueItems: true
          description: Capability ids or action scopes the grantee may use, e.g. "github.pulls.create".
        constraints:
          type: array
          items:
            $ref: '#/components/schemas/Constraint'
        expires_at:
          type: string
          format: date-time
        principal_statement:
          type: string
          minLength: 1
          description: The principal's words as relayed, recorded verbatim. MUST be present when trust_level is T0_relayed (MAOP section 5.1).
        digest:
          type: string
          pattern: ^(sha256|sha384|sha512|blake3):[0-9a-f]{32,128}$
          description: Digest of the canonical grant "<algorithm>:<lowercase hex>", so approvals and receipts can bind to it.
        revoked_at:
          type:
          - string
          - 'null'
          format: date-time
          description: When the grant was withdrawn; null or absent while it is not revoked. A revoked grant authorizes nothing, nor does any grant derived from it.
      additionalProperties: false
      required:
      - grant_id
      - grantee_agent_id
      - trust_level
      - scope
      - expires_at
      allOf:
      - if:
          properties:
            trust_level:
              const: T0_relayed
          required:
          - trust_level
        then:
          required:
          - principal_statement
      description: A time-bounded, scoped grant of authority to one agent. Authority only narrows down the delegation tree.
    Lease:
      type: object
      properties:
        lease_id:
          type: string
          minLength: 1
        holder:
          type: string
          pattern: ^agt_[A-Za-z0-9_.-]+$
          description: Stable agent identifier, e.g. "agt_impl_7".
        work_id:
          type: string
        delegation_id:
          type: string
        fencing_token:
          type: integer
          minimum: 0
          description: 'Monotonic per work item: it increases on every new acquisition and never decreases. Writes carrying a fencing_token lower than the current one MUST be rejected.'
        state:
          type: string
          enum:
          - active
          - expired
          - released
          - revoked
        issued_at:
          type: string
          format: date-time
        expires_at:
          type: string
          format: date-time
      additionalProperties: false
      required:
      - lease_id
      - holder
      - fencing_token
      - expires_at
      description: A fenced, time-bounded execution lease held by one agent.
    LeaseRenewal:
      type: object
      properties:
        holder:
          type: string
          pattern: ^agt_[A-Za-z0-9_.-]+$
          description: Stable agent identifier, e.g. "agt_impl_7".
        fencing_token:
          type: integer
          minimum: 0
          description: The holder's current fencing token. A stale token is rejected with 409.
        extend_seconds:
          type: integer
          minimum: 1
        idempotency_key:
          type: string
          minLength: 1
      additionalProperties: false
      required:
      - holder
      - fencing_token
      - extend_seconds
      description: Request of leases.renew. Renewal keeps the fencing token; an expired lease cannot be renewed and must be re-acquired (with a higher token).
    Receipt:
      type: object
      properties:
        receipt_id:
          type: string
          minLength: 1
        action:
          type: string
          minLength: 1
          description: The action or capability performed, e.g. "github.pulls.create".
        actor:
          $ref: '#/components/schemas/PrincipalRef'
          description: Who performed the action.
        idempotency_key:
          type: string
          minLength: 1
        outcome:
          type: string
          enum:
          - succeeded
          - failed
          - outcome_unknown
          description: outcome_unknown (e.g. a timeout after dispatch) MUST route the work item to the recover stage; it is never treated as success.
        evidence_refs:
          type: array
          items:
            $ref: '#/components/schemas/EvidenceRef'
        causal_parents:
          type: array
          items:
            type: string
          description: Receipt or evidence ids this receipt causally depends on.
        work_id:
          type: string
        delegation_id:
          type: string
        lease_id:
          type: string
        fencing_token:
          type: integer
          minimum: 0
        trust_level:
          type: string
          enum:
          - T0_relayed
          - T1_attested
        attestation:
          $ref: '#/components/schemas/AttestationTier'
        digest:
          type: string
          pattern: ^(sha256|sha384|sha512|blake3):[0-9a-f]{32,128}$
          description: Content digest "<algorithm>:<lowercase hex>", e.g. "sha256:<64 hex>".
        recorded_at:
          type: string
          format: date-time
      additionalProperties: false
      required:
      - receipt_id
      - action
      - actor
      - idempotency_key
      - outcome
      - evidence_refs
      - causal_parents
      - recorded_at
      description: Durable, idempotent record of one side-effecting action and its outcome.
    SupervisionStage:
      type: string
      enum:
      - observe
      - decide
      - plan
      - coordinate
      - act
      - verify
      - review
      - approve
      - record
      - recover
      - closed
      description: 'Stage of the outer supervision lifecycle. Back-edges: act→decide, act→coordinate, verify→act, any→recover, recover→decide.'
    ChildLifecycleState:
      type: string
      enum:
      - proposed
      - delegated
      - leased
      - executing
      - submitted
      - verifying
      - accepted
      - rejected
      - cancelled
      - expired
      description: Lifecycle state of a delegated child work item.
    Guard:
      type: object
      properties:
        guard_id:
          type: string
          minLength: 1
        kind:
          type: string
          enum:
          - authority
          - policy
          - evidence
          - freshness
          - lease
          - separation_of_duties
          - budget
        expression:
          $ref: '#/components/schemas/Expression'
        durable:
          const: true
          description: Guards are persisted with the work item and re-evaluated on every relevant event, never held only in a prompt.
        applies_to:
          type: array
          items:
            $ref: '#/components/schemas/SupervisionStage'
          description: Stages whose exit this guard gates.
        on_failure:
          $ref: '#/components/schemas/SupervisionStage'
          description: Stage to transition to when the guard fails.
        enforcement:
          type: string
          enum:
          - ENFORCED
          - ADVISORY
          default: ENFORCED
          description: 'ENFORCED: a failed guard blocks the transition. ADVISORY: a failed guard is reported in guards_failed and does not block it. Absent means ENFORCED.'
        description:
          type: string
      additionalProperties: false
      required:
      - guard_id
      - kind
      - expression
      - durable
      description: A durable, machine-evaluable condition that gates a supervision transition.
    SupervisionEvaluation:
      type: object
      properties:
        current_stage:
          $ref: '#/components/schemas/SupervisionStage'
        trigger:
          type: string
          minLength: 1
          description: The event that caused re-evaluation, e.g. "receipt.recorded", "evidence.superseded", "lease.expired".
        trigger_event:
          $ref: '#/components/schemas/EventEnvelope'
        evidence:
          type: array
          items:
            $ref: '#/components/schemas/CausalEvidence'
        guard_ids:
          type: array
          items:
            type: string
          description: 'Guards to evaluate; default: all durable guards of the work item.'
        child_states:
          type: array
          items:
            type: object
            properties:
              delegation_id:
                type: string
              state:
                $ref: '#/components/schemas/ChildLifecycleState'
            additionalProperties: false
            required:
            - delegation_id
            - state
        expected_state_version:
          type: integer
          minimum: 0
        idempotency_key:
          type: string
          minLength: 1
      additionalProperties: false
      required:
      - current_stage
      - trigger
      description: 'Request of supervision.evaluate: event-driven re-evaluation of a work item''s durable guards.'
    TransitionDecision:
      type: object
      properties:
        work_id:
          type: string
        from_stage:
          $ref: '#/components/schemas/SupervisionStage'
        to_stage:
          $ref: '#/components/schemas/SupervisionStage'
        trigger:
          type: string
          minLength: 1
        guards_passed:
          type: array
          items:
            type: string
        guards_failed:
          type: array
          items:
            type: string
        back_edge:
          type: boolean
          description: True when the transition moves backwards (e.g. act→decide, verify→act).
        next_action:
          type: object
          properties:
            action:
              type: string
              enum:
              - wait
              - plan
              - delegate
              - re_delegate
              - execute
              - verify
              - review
              - request_approval
              - record
              - recover
              - replan
              - close
            summary:
              type: string
            delegation_id:
              type: string
            target_agent_id:
              type: string
              pattern: ^agt_[A-Za-z0-9_.-]+$
              description: Stable agent identifier, e.g. "agt_impl_7".
          additionalProperties: false
          required:
          - action
        state_version:
          type: integer
          minimum: 0
        decided_at:
          type: string
          format: date-time
      additionalProperties: false
      required:
      - from_stage
      - to_stage
      - trigger
      - guards_passed
      - guards_failed
      - next_action
      description: 'Result of supervision.evaluate: the next supervision transition and why.'
    CausalEvidence:
      type: object
      properties:
        evidence_id:
          type: string
          minLength: 1
        kind:
          type: string
          enum:
          - observation
          - fact
          - receipt
          - artifact
          - verification
          - review
          - approval
          - metric
        digest:
          type: string
          pattern: ^(sha256|sha384|sha512|blake3):[0-9a-f]{32,128}$
          description: Content digest "<algorithm>:<lowercase hex>", e.g. "sha256:<64 hex>".
        derived_from:
          type: array
          items:
            type: string
          description: Ids of the evidence this item was derived from (empty for primary evidence).
        observed_at:
          type: string
          format: date-time
        valid_time:
          type: object
          properties:
            start:
              type: string
              format: date-time
            end:
              type:
              - string
              - 'null'
              format: date-time
          additionalProperties: false
          required:
          - start
        source:
          type: string
        ref:
          $ref: '#/components/schemas/EvidenceRef'
      additionalProperties: false
      required:
      - evidence_id
      - kind
      - digest
      - derived_from
      - observed_at
      - valid_time
      description: Content-addressed evidence with causal lineage and bitemporal validity.
