# Creasura Agentic OS Protocol (CAOP) v0.2 · OpenAPI 3.1
openapi: "3.1.0"
info:
  title: "Creasura Agentic OS Protocol (CAOP)"
  version: "0.2"
  description: "Lifecycle API for the Creasura Agentic OS Protocol v0.2 (current version). Builds on v0.1.2 (additive superset). v0.2 adds two-phase outcome verification, mid-flight approval steering (APPROVE_WITH_STEERING_DELTA), hierarchical sub-agent isolation, inner-loop context compaction, and lazy capability discovery to the compact binding."
jsonSchemaDialect: "https://json-schema.org/draft/2020-12/schema"
servers:
  - url: "http://localhost:8787"
    description: "Self-hosted runtime (e.g. on your Mac mini)"
security:
  - bearerAuth: []
tags:
  - name: "Observe"
  - name: "Understand"
  - name: "Commit"
  - name: "Plan"
  - name: "Execute"
  - name: "Verify"
  - name: "Record"
  - name: "Review"
  - name: "Compact binding"
paths:
  /v1/observations:
    post:
      operationId: "observations.ingest"
      summary: "Ingest an observation"
      description: "Records something the OS 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-caop-stage: "Observe"
      x-caop-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"
  /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-caop-stage: "Understand"
      x-caop-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"
  /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-caop-stage: "Commit"
      x-caop-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-caop-stage: "Commit"
      x-caop-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"
  /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-caop-stage: "Plan"
      x-caop-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"
  /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-caop-stage: "Execute"
      x-caop-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"
  "/v1/executions/{execution_id}":
    get:
      operationId: "executions.get"
      summary: "Get execution status"
      description: "Returns the current state of an execution."
      tags:
        - "Execute"
      x-caop-stage: "Execute"
      x-caop-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"
  "/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-caop-stage: "Execute"
      x-caop-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"
  "/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-caop-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"
  /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-caop-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"
  /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-caop-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"
  /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-caop-stage: "Review"
      x-caop-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"
  "/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-caop-stage: "Execute"
      x-caop-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"
  /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-caop-stage:
        - "Observe"
        - "Review"
      x-caop-binding: "compact"
      x-caop-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 Creasura 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"
  /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-caop-stage:
        - "Understand"
        - "Commit"
        - "Plan"
      x-caop-binding: "compact"
      x-caop-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"
  /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-caop-stage:
        - "Commit"
        - "Execute"
      x-caop-binding: "compact"
      x-caop-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"
  /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-caop-stage:
        - "Verify"
        - "Record"
        - "Review"
      x-caop-binding: "compact"
      x-caop-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"
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 OS, 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 OS 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 OS 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 OS 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"
            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)."
    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 Creasura 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 Creasura'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."