openapi: 3.1.0
info:
  title: ZERO Public Operator API
  version: 1.0.0
  description: Read-only public contracts for verified ZERO operator behavior. JSON Schemas are published at /contracts/zero.public_operators.v1.schema.json, /contracts/zero.public_operator.v1.schema.json, /contracts/zero.decision_replay.v1.schema.json, /contracts/zero.decision_receipt_card.v1.schema.json, /contracts/zero.public_decision_artifacts.v1.schema.json, /contracts/zero.replay_entrypoints.v1.schema.json, /contracts/zero.replay_graph_context.v1.schema.json, /contracts/zero.replay_decision_graph.v1.schema.json, /contracts/zero.registry.catalog.v0.schema.json, /contracts/zero.registry.reputation.v0.schema.json, and /contracts/zero.coliseum.league_retention.v0.schema.json.
externalDocs:
  description: Public operator contract guide and JSON Schema artifacts.
  url: https://getzero.dev/contracts/public-operator.md
x-json-schemas:
  public_operator_index: https://getzero.dev/contracts/zero.public_operators.v1.schema.json
  public_operator_profile: https://getzero.dev/contracts/zero.public_operator.v1.schema.json
  decision_replay: https://getzero.dev/contracts/zero.decision_replay.v1.schema.json
  decision_receipt_card: https://getzero.dev/contracts/zero.decision_receipt_card.v1.schema.json
  public_decision_artifacts: https://getzero.dev/contracts/zero.public_decision_artifacts.v1.schema.json
  replay_entrypoints: https://getzero.dev/contracts/zero.replay_entrypoints.v1.schema.json
  replay_graph_context: https://getzero.dev/contracts/zero.replay_graph_context.v1.schema.json
  replay_decision_graph: https://getzero.dev/contracts/zero.replay_decision_graph.v1.schema.json
  registry_catalog: https://getzero.dev/contracts/zero.registry.catalog.v0.schema.json
  registry_reputation: https://getzero.dev/contracts/zero.registry.reputation.v0.schema.json
  coliseum_league_retention: https://getzero.dev/contracts/zero.coliseum.league_retention.v0.schema.json
servers:
  - url: https://getzero.dev
paths:
  /api/public/operators:
    get:
      operationId: listPublicOperators
      summary: List public ZERO operators.
      security: []
      responses:
        "200":
          description: Public operator index.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/PublicOperatorIndex"
  /api/public/operators/{name}:
    get:
      operationId: getPublicOperator
      summary: Get a normalized public operator profile.
      security: []
      parameters:
        - name: name
          in: path
          required: true
          schema:
            type: string
            enum: [foundation]
      responses:
        "200":
          description: Public operator profile.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/PublicOperatorProfile"
        "404":
          description: Public operator not found.
  /api/foundation/live-certification-readiness:
    get:
      operationId: getFoundationLiveCertificationReadiness
      summary: Get Foundation live-certification readiness and owner-drill blockers.
      security: []
      responses:
        "200":
          description: Public live-certification readiness for the Foundation operator.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/FoundationLiveCertificationReadiness"
        "404":
          description: Foundation evidence unavailable.
  /api/foundation/operator-control-readiness:
    get:
      operationId: getFoundationOperatorControlReadiness
      summary: Get Foundation operator-control and Sentinel transcript readiness.
      security: []
      responses:
        "200":
          description: Public operator-control readiness for the Foundation operator.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/FoundationOperatorControlReadiness"
        "404":
          description: Foundation evidence unavailable.
  /api/ops/journal-finality:
    get:
      operationId: getJournalFinalityOps
      summary: Get journal finality operations readiness and score-promotion gate.
      security: []
      responses:
        "200":
          description: Public journal finality operations contract.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/JournalFinalityOps"
        "404":
          description: Foundation evidence unavailable.
  /api/arena:
    get:
      operationId: getArena
      summary: Get current arena leaderboard.
      security: []
      responses:
        "200":
          description: Arena leaderboard, public operator sourced when available.
  /api/arena/rewards:
    get:
      operationId: getArenaRewards
      summary: Get current weekly proof rewards.
      security: []
      responses:
        "200":
          description: Weekly rewards payload.
  /api/seasons:
    get:
      operationId: getSeason
      summary: Get current proof-based season state.
      security: []
      responses:
        "200":
          description: Season leaderboard payload.
  /api/replays:
    get:
      operationId: listDecisionReplays
      summary: List public DECISION_LOOP replay summaries.
      security: []
      parameters:
        - name: limit
          in: query
          required: false
          schema:
            type: integer
            minimum: 1
            maximum: 100
      responses:
        "200":
          description: Public replay index.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ReplayIndex"
  /api/replays/entrypoints:
    get:
      operationId: getReplayEntrypoints
      summary: Public replay entrypoint graph
      responses:
        "200":
          description: Replay entrypoint coverage across public surfaces
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ReplayEntrypoints"
  /api/replays/{id}:
    get:
      operationId: getDecisionReplay
      summary: Get a public DECISION_LOOP replay.
      security: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
            example: foundation-genesis
      responses:
        "200":
          description: Decision replay payload.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/DecisionReplay"
        "404":
          description: Public replay not found.
  /api/replays/{id}/receipt-card:
    get:
      operationId: getDecisionReceiptCard
      summary: Get a public-safe shareable decision receipt card.
      security: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
            example: foundation-genesis
      responses:
        "200":
          description: Decision receipt card without private traces or performance metrics.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/DecisionReceiptCard"
        "404":
          description: Public replay receipt card not found.
  /api/replays/decision-artifacts:
    get:
      operationId: getPublicDecisionArtifacts
      summary: Get recurring public decision artifact shelves.
      security: []
      responses:
        "200":
          description: Public-safe receipt-card and graph-context shelves across refusal, followthrough, and same-policy families.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/PublicDecisionArtifacts"
  /api/replays/{id}/graph-context:
    get:
      operationId: getReplayGraphContext
      summary: Get public-safe retained replay graph context.
      security: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
            example: foundation-genesis
      responses:
        "200":
          description: Replay adjacency and hash coverage without raw private traces.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ReplayGraphContext"
        "404":
          description: Public replay graph context not found.
  /api/replays/decision-graph:
    get:
      operationId: getReplayDecisionGraph
      summary: Get public-safe multi-replay decision graph depth.
      security: []
      responses:
        "200":
          description: Multi-replay graph across retained refusal, followthrough, same-source, and same-policy families.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ReplayDecisionGraph"
  /api/coliseum/history:
    get:
      operationId: getColiseumLeagueRetention
      summary: Get retained Coliseum League paper history and score gate.
      security: []
      responses:
        "200":
          description: Paper-only retained bracket history. This contract cannot execute orders or publish performance claims.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ColiseumLeagueRetention"
  /api/registry:
    get:
      operationId: getRegistryCatalog
      summary: Get the signal-only ZERO Registry catalog.
      security: []
      responses:
        "200":
          description: Registry catalog with paid calls and auto-execution disabled.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RegistryCatalog"
  /api/registry/reputation:
    get:
      operationId: getRegistryReputation
      summary: Get Registry supplier and listing reputation.
      security: []
      responses:
        "200":
          description: Registry reputation index with paid-call blockers and disclosure evidence.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RegistryReputation"
components:
  schemas:
    RegistryCatalog:
      type: object
      required: [schema_version, kind, canonical_url, compatibility_url, reputation_url, public, settlement, guardrails, lanes, listings]
      properties:
        schema_version:
          const: zero.registry.catalog.v0
        kind:
          const: registry_catalog
        canonical_url:
          const: https://getzero.dev/api/registry
        compatibility_url:
          const: https://getzero.dev/api/market
        reputation_url:
          const: https://getzero.dev/api/registry/reputation
        public:
          const: true
        settlement:
          type: object
          required: [paid_calls_enabled, x402_status, compensation_labels_required]
          properties:
            paid_calls_enabled:
              const: false
            x402_status:
              const: architecture_flagged_off
            compensation_labels_required:
              const: true
        guardrails:
          type: object
          required: [default_execution_mode, auto_execution_enabled, eligibility_gate_required_before_auto_execution, performance_disclosure_required, replay_evidence_required]
          properties:
            default_execution_mode:
              const: signal_only
            auto_execution_enabled:
              const: false
            eligibility_gate_required_before_auto_execution:
              const: true
            performance_disclosure_required:
              const: true
            replay_evidence_required:
              const: true
        lanes:
          type: array
          items:
            type: string
            enum: [skill, strategy, signal, dataset, evaluator]
        listings:
          type: array
          items:
            type: object
    RegistryReputation:
      type: object
      required: [schema_version, kind, public, generated_at, catalog_url, compatibility_catalog_url, compatibility_reputation_url, settlement, guardrails, suppliers, listings]
      properties:
        schema_version:
          const: zero.registry.reputation.v0
        kind:
          const: registry_reputation_index
        public:
          const: true
        generated_at:
          type: string
          format: date-time
        catalog_url:
          const: https://getzero.dev/api/registry
        compatibility_catalog_url:
          const: https://getzero.dev/api/market
        compatibility_reputation_url:
          const: https://getzero.dev/api/market/reputation
        settlement:
          type: object
          required: [paid_calls_enabled, x402_status, paid_call_reputation_required]
          properties:
            paid_calls_enabled:
              const: false
            x402_status:
              const: architecture_flagged_off
            paid_call_reputation_required:
              const: true
        guardrails:
          type: object
          required: [default_execution_mode, auto_execution_enabled, supplier_reputation_required_before_paid_calls, eligibility_gate_required_before_auto_execution, performance_disclosure_required, compensation_label_required, replay_evidence_required]
          properties:
            default_execution_mode:
              const: signal_only
            auto_execution_enabled:
              const: false
            supplier_reputation_required_before_paid_calls:
              const: true
            eligibility_gate_required_before_auto_execution:
              const: true
            performance_disclosure_required:
              const: true
            compensation_label_required:
              const: true
            replay_evidence_required:
              const: true
        suppliers:
          type: array
          items:
            type: object
        listings:
          type: array
          items:
            type: object
    ColiseumLeagueRetention:
      type: object
      required:
        - schema_version
        - kind
        - public
        - generated_at
        - current_week
        - execution_boundary
        - retention_policy
        - score_gate
        - league_summary
        - samples
      properties:
        schema_version:
          const: zero.coliseum.league_retention.v0
        kind:
          const: coliseum_league_retention
        public:
          const: true
        generated_at:
          type: string
          format: date-time
        current_week:
          type: object
        execution_boundary:
          type: object
          required:
            - can_execute_orders
            - auto_execution_enabled
            - can_publish_performance_claims
          properties:
            can_execute_orders:
              const: false
            auto_execution_enabled:
              const: false
            can_publish_performance_claims:
              const: false
        retention_policy:
          type: object
          required:
            - artifact_name
            - history_path
            - minimum_distinct_weeks_for_public_promotion
          properties:
            artifact_name:
              const: coliseum-league-retention
            history_path:
              const: artifacts/coliseum-league-retention/history.json
            minimum_distinct_weeks_for_public_promotion:
              const: 3
        score_gate:
          type: object
          required: [state, can_promote_public_score, reason, next_action]
          properties:
            state:
              enum: [collecting_history, retention_ready]
            can_promote_public_score:
              type: boolean
            reason:
              type: string
            next_action:
              enum: [keep_weekly_retention_running, collect_more_weekly_brackets]
        league_summary:
          type: object
          required: [tiers, promotion_candidates, relegation_candidates, disqualified]
        samples:
          type: array
          minItems: 1
          items:
            type: object
            required:
              - source
              - tournament_id
              - week_start
              - week_end
              - execution_mode
              - public_numeric_score_enabled
            properties:
              source:
                enum: [current_public_contract, retained_workflow_report]
              tournament_id:
                type: string
              week_start:
                type: string
                format: date
              week_end:
                type: string
                format: date
              execution_mode:
                const: paper
              public_numeric_score_enabled:
                const: false
    PublicDecisionArtifacts:
      type: object
      required:
        - schema_version
        - kind
        - status
        - coverage
        - shelves
        - privacy_boundary
        - score_gate
      properties:
        schema_version:
          const: zero.public_decision_artifacts.v1
        kind:
          const: public_recurring_decision_artifacts
        status:
          enum: [decision_artifacts_ready, decision_artifacts_degraded]
        coverage:
          type: object
        shelves:
          type: array
        privacy_boundary:
          type: object
        score_gate:
          type: object
    DecisionReplay:
      type: object
      required:
        - schema_version
        - kind
        - replay_id
        - decision_loop
        - model
        - prompt
        - tools
        - signing
        - journal
        - outcome
      properties:
        schema_version:
          const: zero.decision_replay.v1
        kind:
          const: decision_replay
        replay_id:
          type: string
        decision_loop:
          type: array
        model:
          type: object
        prompt:
          type: object
        tools:
          type: array
        signing:
          type: object
        journal:
          type: object
        outcome:
          type: object
    PublicOperatorIndex:
      type: object
      required: [schema_version, kind, count, operators]
      properties:
        schema_version:
          const: zero.public_operators.v1
        kind:
          const: operator_profile_index
        count:
          type: integer
          minimum: 0
        operators:
          type: array
          items:
            $ref: "#/components/schemas/PublicOperatorSummary"
    FoundationLiveCertificationReadiness:
      type: object
      required:
        - schema_version
        - kind
        - public
        - deployment_id
        - status
        - generated_at
        - readiness
        - blockers
        - proof_blockers
        - next_blocker
        - drill_gate
        - owner_action
        - next_action
        - endpoints
      properties:
        schema_version:
          const: zero.foundation_live_certification_readiness.v1
        kind:
          const: foundation_live_certification_readiness
        public:
          const: true
        deployment_id:
          type: [string, "null"]
        status:
          type: string
          enum: [blocked, ready_to_run, certified]
        generated_at:
          type: string
          format: date-time
        readiness:
          type: object
          required:
            - deployment_live
            - live_lease_fresh
            - privy_signing
            - hyperliquid_agent_approved
            - runtime_clean
            - live_certification_replay
          properties:
            deployment_live:
              type: boolean
            live_lease_fresh:
              type: boolean
            privy_signing:
              type: boolean
            hyperliquid_agent_approved:
              type: boolean
            runtime_clean:
              type: boolean
            live_certification_replay:
              type: [object, "null"]
            testnet_drill:
              type: object
        blockers:
          type: array
          items:
            type: string
        proof_blockers:
          type: array
          items:
            type: string
        next_blocker:
          type: [string, "null"]
        drill_gate:
          type: object
          required:
            - authenticated_operator_required
            - explicit_operator_request_required
            - server_submit_flag_required
            - server_submit_enabled
            - allowed_actions
            - private_key_custody
          properties:
            authenticated_operator_required:
              const: true
            explicit_operator_request_required:
              const: true
            server_submit_flag_required:
              const: true
            server_submit_enabled:
              type: boolean
            allowed_actions:
              type: array
              items:
                type: string
                enum: [order, cancel, scheduleCancel]
            private_key_custody:
              const: false
        owner_action:
          $ref: "#/components/schemas/OwnerDrillAction"
        next_action:
          type: string
        endpoints:
          type: object
          required: [readiness, operator_certification, public_evidence]
          properties:
            readiness:
              type: string
              format: uri
            operator_certification:
              type: [string, "null"]
              format: uri
            public_evidence:
              type: string
              format: uri
    OwnerDrillAction:
      type: object
      required:
        - type
        - available
        - blocked_reason
        - requires_authenticated_operator
        - requires_explicit_confirmation
        - preferred_surface
        - button_label
        - selected_deployment_id
        - submit_payload
        - testnet_approval_packet
        - token_handling
        - expected_result
      properties:
        type:
          const: testnet_submit_cancel_drill
        available:
          type: boolean
        blocked_reason:
          type: [string, "null"]
          enum:
            - testnet_submit_cancel_already_recorded
            - readiness_blocked
            - server_submit_disabled
            - deployment_missing
            - hl_testnet_wallet_not_registered
            - null
        requires_authenticated_operator:
          const: true
        requires_explicit_confirmation:
          const: true
        preferred_surface:
          const: founder_admin_control
        button_label:
          const: run testnet drill
        selected_deployment_id:
          type: [string, "null"]
        submit_payload:
          type: object
          required: [submit_testnet_drill]
          properties:
            submit_testnet_drill:
              const: true
        checklist:
          type: array
          items:
            type: object
            required: [step, status, owner_action_required, evidence]
            properties:
              step:
                type: string
              status:
                type: string
                enum: [complete, pending, blocked]
              owner_action_required:
                type: boolean
              evidence:
                type: string
        approval_handoff:
          type: [object, "null"]
          required: [method, path, body, expected_result]
          properties:
            method:
              const: POST
            path:
              type: string
            body:
              type: object
              required: [network]
              properties:
                network:
                  const: testnet
            expected_result:
              type: string
        post_approval_retry:
          type: [object, "null"]
          required: [method, path, body, expected_result]
          properties:
            method:
              const: POST
            path:
              type: string
            body:
              type: object
              required: [submit_testnet_drill]
              properties:
                submit_testnet_drill:
                  const: true
            expected_result:
              type: string
        testnet_approval_packet:
          type: object
          required:
            - schema_version
            - network
            - status
            - approval_url
            - info_endpoint
            - main_wallet
            - api_wallet
            - agent_name
            - manual_entry_required
            - do_not_use_generate
            - wrong_agent_warning
            - signature_expectation
            - approve_agent
            - approval_check
            - post_approval_retry
            - safety_boundary
            - next_action
          properties:
            schema_version:
              const: zero.hl_testnet_approval_packet.v1
            network:
              const: testnet
            status:
              type: string
              enum: [approved, setup_required, pending_verification]
            approval_url:
              const: https://app.hyperliquid-testnet.xyz/API
            info_endpoint:
              const: https://api.hyperliquid-testnet.xyz/info
            main_wallet:
              type: [string, "null"]
            api_wallet:
              type: [string, "null"]
            agent_name:
              type: [string, "null"]
            manual_entry_required:
              const: true
            do_not_use_generate:
              const: true
            wrong_agent_warning:
              type: string
            signature_expectation:
              type: object
              required: [primary_type, hyperliquid_chain, agent_address, agent_name, confirm_only_if]
              properties:
                primary_type:
                  const: HyperliquidTransaction:ApproveAgent
                hyperliquid_chain:
                  const: Testnet
                agent_address:
                  type: [string, "null"]
                agent_name:
                  type: [string, "null"]
                confirm_only_if:
                  type: string
            approve_agent:
              type: object
              required: [action, network, main_wallet, agent_address, agent_name, hyperliquid_url, manual_entry_required, do_not_use_generate, wrong_agent_warning, expected_signature]
              properties:
                action:
                  const: approveAgent
                network:
                  const: testnet
                main_wallet:
                  type: [string, "null"]
                agent_address:
                  type: [string, "null"]
                agent_name:
                  type: [string, "null"]
                hyperliquid_url:
                  const: https://app.hyperliquid-testnet.xyz/API
                manual_entry_required:
                  const: true
                do_not_use_generate:
                  const: true
                wrong_agent_warning:
                  type: string
                expected_signature:
                  type: object
                  required: [primary_type, hyperliquid_chain, agent_address, agent_name]
                  properties:
                    primary_type:
                      const: HyperliquidTransaction:ApproveAgent
                    hyperliquid_chain:
                      const: Testnet
                    agent_address:
                      type: [string, "null"]
                    agent_name:
                      type: [string, "null"]
            approval_check:
              type: [object, "null"]
              required: [method, path, body, expected_result]
              properties:
                method:
                  const: POST
                path:
                  type: string
                body:
                  type: object
                  required: [network]
                  properties:
                    network:
                      const: testnet
                expected_result:
                  type: string
            post_approval_retry:
              type: [object, "null"]
              required: [method, path, body, expected_result]
              properties:
                method:
                  const: POST
                path:
                  type: string
                body:
                  type: object
                  required: [submit_testnet_drill]
                  properties:
                    submit_testnet_drill:
                      const: true
                expected_result:
                  type: string
            safety_boundary:
              type: object
              required: [private_key_custody, allowed_actions, blocked_actions]
              properties:
                private_key_custody:
                  const: false
                allowed_actions:
                  type: array
                  items:
                    type: string
                    enum: [order, cancel, scheduleCancel]
                blocked_actions:
                  type: array
                  items:
                    type: string
            next_action:
              type: string
        token_handling:
          type: string
          pattern: never paste Privy tokens
        expected_result:
          type: string
    FoundationOperatorControlReadiness:
      type: object
      required:
        - schema_version
        - kind
        - public
        - deployment_id
        - status
        - generated_at
        - readiness
        - proof_blockers
        - next_blocker
        - owner_actions
        - proof_chain
        - journal_finality_ops
        - next_action
        - endpoints
      properties:
        schema_version:
          const: zero.foundation_operator_control_readiness.v1
        kind:
          const: foundation_operator_control_readiness
        public:
          const: true
        deployment_id:
          type: [string, "null"]
        status:
          type: string
          enum: [blocked, ready_for_take_over, ready_to_publish, passed]
        generated_at:
          type: string
          format: date-time
        readiness:
          type: object
          required:
            - deployment_live
            - live_certification_replay
            - operator_control_replay
            - signing_refusal_replay
            - sentinel_drill_transcript
          properties:
            deployment_live:
              type: boolean
            live_certification_replay:
              type: [object, "null"]
            operator_control_replay:
              type: [object, "null"]
            signing_refusal_replay:
              type: [object, "null"]
            sentinel_drill_transcript:
              type: [object, "null"]
        proof_blockers:
          type: array
          items:
            type: string
            enum:
              - live_certification_replay
              - operator_control_replay
              - signing_refusal_replay
              - sentinel_drill_transcript
        next_blocker:
          type: [string, "null"]
        owner_actions:
          type: object
          required: [take_over, publish_sentinel_transcript]
          properties:
            take_over:
              $ref: "#/components/schemas/OperatorControlOwnerAction"
            publish_sentinel_transcript:
              $ref: "#/components/schemas/OperatorControlOwnerAction"
        proof_chain:
          $ref: "#/components/schemas/OperatorControlProofChain"
        journal_finality_ops:
          $ref: "#/components/schemas/JournalFinalityOps"
        next_action:
          type: string
        endpoints:
          type: object
          required: [readiness, take_over, sentinel_drill, public_evidence, journal_finality_ops]
          properties:
            readiness:
              type: string
              format: uri
            take_over:
              type: [string, "null"]
              format: uri
            sentinel_drill:
              type: [string, "null"]
              format: uri
            public_evidence:
              type: string
              format: uri
            journal_finality_ops:
              type: string
              format: uri
    JournalFinalityOps:
      type: object
      required:
        - schema_version
        - kind
        - public
        - health
        - strict_public_proof_ready
        - score_moving_blocker
        - recommended_action
        - finalizer_profile
        - observed
        - blockers
        - links
      properties:
        schema_version:
          const: zero.journal_finality_ops.v1
        kind:
          const: journal_finality_ops
        public:
          const: true
        generated_at:
          type: string
          format: date-time
        health:
          type: string
        strict_public_proof_ready:
          type: boolean
        score_moving_blocker:
          type: boolean
        recommended_action:
          type: string
          enum:
            - inspect_foundation_evidence
            - repair_missing_journal_receipts
            - inspect_finalizer_upgrade_errors
            - run_public_chain_finalizer
            - wait_for_bitcoin_attestation
            - run_strict_public_proof_and_promote_score
            - inspect_journal_finality_state
        finalizer_profile:
          type: object
          required: [recommended_profile, schedule, local_receipt_limit, control_plane_limit]
          properties:
            recommended_profile:
              const: public-chain
            schedule:
              const: hourly
            local_receipt_limit:
              const: 0
            control_plane_limit:
              const: 2
        observed:
          type: object
        blockers:
          type: array
          items:
            type: string
        links:
          type: object
    OperatorControlOwnerAction:
      type: object
      required:
        - type
        - available
        - blocked_reason
        - requires_authenticated_operator
        - requires_explicit_confirmation
        - preferred_surface
        - button_label
        - selected_deployment_id
        - submit_payload
        - expected_result
      properties:
        type:
          type: string
          enum: [operator_take_over_drill, sentinel_transcript_drill]
        available:
          type: boolean
        blocked_reason:
          type: [string, "null"]
          enum:
            - operator_control_already_recorded
            - live_certification_replay_required
            - deployment_not_live
            - sentinel_transcript_already_recorded
            - evidence_incomplete
            - unknown
            - null
        requires_authenticated_operator:
          const: true
        requires_explicit_confirmation:
          type: boolean
        preferred_surface:
          const: founder_admin_control
        button_label:
          type: string
          enum: [take over, publish sentinel transcript]
        selected_deployment_id:
          type: [string, "null"]
        submit_payload:
          type: object
        expected_result:
          type: string
    OperatorControlProofChain:
      type: object
      required: [status, current_step, score_moving, public_proof_score_blocked, ordered_steps, next_owner_action, safety_boundary]
      properties:
        status:
          type: string
          enum: [blocked, ready_for_take_over, ready_to_publish, passed]
        current_step:
          type: [string, "null"]
        score_moving:
          type: boolean
        public_proof_score_blocked:
          type: boolean
        ordered_steps:
          type: array
          minItems: 4
          maxItems: 4
          items:
            $ref: "#/components/schemas/OperatorControlProofStep"
        next_owner_action:
          type: object
          required: [type, label, endpoint, blocked_reason]
          properties:
            type:
              type: [string, "null"]
              enum: [testnet_submit_cancel_drill, operator_take_over_drill, sentinel_transcript_drill, null]
            label:
              type: string
            endpoint:
              type: [string, "null"]
              format: uri
            blocked_reason:
              type: [string, "null"]
        safety_boundary:
          type: object
          required: [private_key_custody, requires_authenticated_operator, requires_explicit_confirmation_for_takeover, allowed_actions, blocked_actions]
          properties:
            private_key_custody:
              const: false
            requires_authenticated_operator:
              const: true
            requires_explicit_confirmation_for_takeover:
              const: true
            allowed_actions:
              type: array
              items:
                type: string
            blocked_actions:
              type: array
              items:
                type: string
    OperatorControlProofStep:
      type: object
      required: [step, label, status, owner_action_required, evidence, replay_id, href, unlocks]
      properties:
        step:
          type: string
          enum: [live_certification_replay, operator_control_replay, signing_refusal_replay, sentinel_drill_transcript]
        label:
          type: string
        status:
          type: string
          enum: [complete, pending, blocked]
        owner_action_required:
          type: boolean
        evidence:
          type: string
        replay_id:
          type: [string, "null"]
        href:
          type: [string, "null"]
        unlocks:
          type: array
          items:
            type: string
    ReplayIndex:
      type: object
      required: [schema_version, replays]
      properties:
        schema_version:
          const: zero.replay_index.v1
        replays:
          type: array
          items:
            type: object
            required: [replay_id, occurred_at, kind, href, journal_status, journal_root_hash]
            properties:
              replay_id:
                type: string
              occurred_at:
                type: string
                format: date-time
              kind:
                type: string
              title:
                type: string
              href:
                type: string
                format: uri
              export_url:
                type: string
                format: uri
              share_image_url:
                type: string
                format: uri
              journal_status:
                type: string
                enum: [complete, partial, unavailable, pending_trace]
              journal_root_hash:
                type: [string, "null"]
    ReplayEntrypoints:
      type: object
      required: [schema_version, kind, status, canonical_url, surfaces, graph]
      properties:
        schema_version:
          const: zero.replay_entrypoints.v1
        kind:
          const: public_replay_entrypoints
        status:
          enum: [entrypoints_ready, entrypoints_degraded]
        canonical_url:
          const: https://getzero.dev/api/replays/entrypoints
        surfaces:
          type: array
          items:
            type: object
        graph:
          type: array
          items:
            type: object
            required: [from_surface, to_surface, relation, href]
            properties:
              from_surface:
                type: string
              to_surface:
                type: string
              relation:
                type: string
              href:
                type: string
    DecisionReceiptCard:
      type: object
      required: [schema_version, kind, status, canonical_url, replay_id, receipt_id, outcome, links, graph_context, disclosures, privacy_boundary, score_gate]
      properties:
        schema_version:
          const: zero.decision_receipt_card.v1
        kind:
          const: public_decision_receipt_card
        status:
          const: receipt_card_ready
        canonical_url:
          type: string
          format: uri
        replay_id:
          type: string
        receipt_id:
          type: string
        outcome:
          type: object
          required: [kind, venue, symbol, direction, performance_fields_included]
          properties:
            kind:
              type: string
            venue:
              type: string
            symbol:
              type: [string, "null"]
            direction:
              type: [string, "null"]
            performance_fields_included:
              const: false
        links:
          type: object
          required: [replay, json, export, share_image, schema, operator, replay_index, entrypoints, graph_context]
        graph_context:
          type: array
          items:
            type: object
        disclosures:
          type: object
          required: [not_investment_advice, no_performance_promise, no_auto_execution, public_replay_delay_applies]
        privacy_boundary:
          type: object
          required: [public_only, private_trace_payloads_public, private_keys_public, operator_ids_public, performance_metrics_public]
        score_gate:
          type: object
          required: [can_promote_public_score, reason, next_blocker]
    ReplayGraphContext:
      type: object
      required: [schema_version, kind, status, canonical_url, replay_id, anchor, hash_coverage, adjacency, links, privacy_boundary, score_gate]
      properties:
        schema_version:
          const: zero.replay_graph_context.v1
        kind:
          const: public_replay_graph_context
        status:
          enum: [graph_context_ready, graph_context_degraded]
        canonical_url:
          type: string
          format: uri
        replay_id:
          type: string
        anchor:
          type: object
        hash_coverage:
          type: object
          required: [prompt, tools, model, policy, signing_payload_hash, journal_entry_hash, journal_root_hash, coverage_complete]
        adjacency:
          type: object
          required: [previous, next, related, edges]
        links:
          type: object
          required: [replay, json, receipt_card, share_image, operator, replay_index, entrypoints, schema]
        privacy_boundary:
          type: object
          required: [public_only, private_trace_payloads_public, private_keys_public, operator_ids_public, prompt_bodies_public, tool_payloads_public, performance_metrics_public]
        score_gate:
          type: object
          required: [can_promote_public_score, reason, next_blocker]
    ReplayDecisionGraph:
      type: object
      required: [schema_version, kind, status, canonical_url, coverage, nodes, families, edges, links, privacy_boundary, score_gate]
      properties:
        schema_version:
          const: zero.replay_decision_graph.v1
        kind:
          const: public_replay_decision_graph
        status:
          enum: [decision_graph_ready, decision_graph_degraded]
        canonical_url:
          const: https://getzero.dev/api/replays/decision-graph
        coverage:
          type: object
          required: [replay_count, node_count, edge_count, family_count, refusal_family_count, followthrough_family_count, same_policy_family_count, graph_context_count]
        nodes:
          type: array
          items:
            type: object
        families:
          type: array
          items:
            type: object
            required: [family_id, family_type, replay_ids, graph_context_urls]
        edges:
          type: array
          items:
            type: object
            required: [from, to, relation, href]
        links:
          type: object
          required: [replay_index, entrypoints, export, schema]
        privacy_boundary:
          type: object
          required: [public_only, private_trace_payloads_public, private_keys_public, operator_ids_public, prompt_bodies_public, tool_payloads_public, performance_metrics_public]
        score_gate:
          type: object
          required: [can_promote_public_score, reason, next_blocker]
    PublicOperatorSummary:
      type: object
      required:
        - handle
        - canonical_url
        - public_operator_url
        - raw_evidence_url
        - score_label
        - growth_schema
        - replay_index_url
        - disciple_mode
        - disciple_auto_execution_enabled
        - growth_actions
        - mode
        - signed_receipts
        - total_receipts
        - sentinel_drill_status
        - sentinel_drill_url
        - live_certification_readiness_status
        - live_certification_readiness_url
        - live_certification_readiness_blockers
        - live_certification_proof_blockers
        - live_certification_enhancement_blockers
        - live_certification_next_blocker
        - live_certification_owner_action_available
        - live_certification_owner_action_label
        - operator_control_readiness_status
        - operator_control_next_blocker
        - operator_control_take_over_available
        - operator_control_sentinel_publish_available
        - private_keys_stored
        - evidence_schema
      properties:
        handle:
          type: string
        display_name:
          type: string
        tier:
          type: string
        canonical_url:
          type: string
          format: uri
        public_operator_url:
          type: string
          format: uri
        raw_evidence_url:
          type: string
          format: uri
        score_label:
          type: string
        growth_schema:
          const: zero.operator_growth.v1
        replay_index_url:
          type: string
          format: uri
        disciple_mode:
          const: signal_only
        disciple_auto_execution_enabled:
          const: false
        growth_actions:
          type: array
          items:
            type: object
            required: [kind, href, requires_auth, execution_boundary]
            properties:
              kind:
                type: string
                enum: [watch_replay, follow_operator, become_disciple, launch_zero]
              href:
                type: string
                format: uri
              requires_auth:
                type: boolean
              execution_boundary:
                type: string
        mode:
          type: string
          enum: [paper, live]
        runtime_state:
          type: string
        venue:
          type: string
        custody_model:
          type: string
        signing_boundary:
          type: string
        signed_receipts:
          type: integer
          minimum: 0
        total_receipts:
          type: integer
          minimum: 0
        sentinel_drill_status:
          type: string
          enum: [incomplete, ready_to_publish, passed]
        sentinel_drill_url:
          type: [string, "null"]
          format: uri
        live_certification_readiness_status:
          type: string
          enum: [blocked, ready_to_run, certified]
        live_certification_readiness_url:
          type: string
          format: uri
        live_certification_readiness_blockers:
          type: array
          items:
            type: string
        live_certification_proof_blockers:
          type: array
          items:
            type: string
        live_certification_enhancement_blockers:
          type: array
          items:
            type: string
        live_certification_next_blocker:
          type: [string, "null"]
        live_certification_testnet_order_cancel_submitted:
          type: boolean
        live_certification_promotion_eligible:
          type: boolean
        live_certification_owner_action_available:
          type: boolean
        live_certification_owner_action_label:
          const: run testnet drill
        operator_control_readiness_status:
          type: string
          enum: [blocked, ready_for_take_over, ready_to_publish, passed]
        operator_control_next_blocker:
          type: [string, "null"]
        operator_control_take_over_available:
          type: boolean
        operator_control_sentinel_publish_available:
          type: boolean
        private_keys_stored:
          type: boolean
        evidence_schema:
          const: zero.public_operator.v1
    PublicOperatorProfile:
      type: object
      required:
        - schema_version
        - kind
        - handle
        - canonical_url
        - raw_evidence_url
        - visibility
        - profile
        - score
        - growth
        - capabilities
        - agents
        - evidence
        - verification
      properties:
        schema_version:
          const: zero.public_operator.v1
        kind:
          const: operator_profile
        handle:
          type: string
        canonical_url:
          type: string
          format: uri
        raw_evidence_url:
          type: string
          format: uri
        visibility:
          const: public
        profile:
          type: object
        score:
          type: object
        growth:
          type: object
          required: [schema_version, public_profile_url, share_image_url, profile_api_url, replay_index_url, staged_actions, disciple_default, trade_receipt, saturday_artifact]
          properties:
            schema_version:
              const: zero.operator_growth.v1
            public_profile_url:
              type: string
              format: uri
            share_image_url:
              type: string
              format: uri
            profile_api_url:
              type: string
              format: uri
            replay_index_url:
              type: string
              format: uri
            staged_actions:
              type: array
              items:
                type: object
                required: [kind, label, href, requires_auth, execution_boundary]
                properties:
                  kind:
                    type: string
                    enum: [watch_replay, follow_operator, become_disciple, launch_zero]
                  label:
                    type: string
                  href:
                    type: string
                    format: uri
                  requires_auth:
                    type: boolean
                  execution_boundary:
                    type: string
            disciple_default:
              type: object
              required: [mode, auto_execution_enabled, eligibility_gate_required, compensation_label_required]
              properties:
                mode:
                  const: signal_only
                auto_execution_enabled:
                  const: false
                eligibility_gate_required:
                  const: true
                compensation_label_required:
                  const: true
            trade_receipt:
              type: object
              required: [public_index_url, export_url, share_image_template]
              properties:
                public_index_url:
                  type: string
                  format: uri
                export_url:
                  type: string
                  format: uri
                share_image_template:
                  type: string
            saturday_artifact:
              type: object
              required: [cadence, status, public_numeric_operator_score_enabled]
              properties:
                cadence:
                  const: weekly
                status:
                  const: planned
                public_numeric_operator_score_enabled:
                  const: false
        capabilities:
          type: object
          required: [operating_system, venue, mode, custody_model, signing_boundary, allowed_actions]
          properties:
            operating_system:
              const: zero
            venue:
              type: string
            mode:
              type: string
              enum: [paper, live]
            custody_model:
              type: string
            signing_boundary:
              type: string
            allowed_actions:
              type: array
              items:
                type: string
                enum: [order, cancel, scheduleCancel]
        agents:
          type: array
        evidence:
          type: object
          required: [source, deployment_id, signed_receipts, total_receipts, open_positions, live_safety, live_certification_readiness, operator_control_readiness]
          properties:
            source:
              const: foundation
            deployment_id:
              type: string
            signed_receipts:
              type: integer
              minimum: 0
            total_receipts:
              type: integer
              minimum: 0
            open_positions:
              type: integer
              minimum: 0
            live_safety:
              type: object
              required: [sentinel_drill]
              properties:
                sentinel_drill:
                  type: object
                  required: [status, policy_version, replay_id, href, occurred_at, payload_hash, missing, required_evidence]
                  properties:
                    status:
                      type: string
                      enum: [incomplete, ready_to_publish, passed]
                    policy_version:
                      type: string
                    replay_id:
                      type: [string, "null"]
                    href:
                      type: [string, "null"]
                    occurred_at:
                      type: [string, "null"]
                      format: date-time
                    payload_hash:
                      type: [string, "null"]
                    missing:
                      type: array
                      items:
                        type: string
                    required_evidence:
                      type: object
            live_certification_readiness:
              type: object
              required: [status, href, blockers, proof_blockers, enhancement_blockers, next_blocker, next_action, live_certification_replay, testnet_drill, drill_gate, owner_action]
              properties:
                status:
                  type: string
                  enum: [blocked, ready_to_run, certified]
                href:
                  type: string
                  format: uri
                blockers:
                  type: array
                  items:
                    type: string
                proof_blockers:
                  type: array
                  items:
                    type: string
                enhancement_blockers:
                  type: array
                  items:
                    type: string
                next_blocker:
                  type: [string, "null"]
                next_action:
                  type: string
                live_certification_replay:
                  type: [object, "null"]
                testnet_drill:
                  type: object
                  required: [status, replay_id, submitted_to_hyperliquid, testnet_order_cancel_submitted, promotion_eligible, promotion_blockers]
                  properties:
                    status:
                      type: string
                      enum: [missing, signed_not_submitted, submitted]
                    replay_id:
                      type: [string, "null"]
                    submitted_to_hyperliquid:
                      type: boolean
                    testnet_order_cancel_submitted:
                      type: boolean
                    promotion_eligible:
                      type: boolean
                    promotion_blockers:
                      type: array
                      items:
                        type: string
                drill_gate:
                  type: object
                owner_action:
                  $ref: "#/components/schemas/OwnerDrillAction"
            operator_control_readiness:
              type: object
              required: [status, href, proof_blockers, next_blocker, next_action, readiness, owner_actions, proof_chain, journal_finality_ops]
              properties:
                status:
                  type: string
                  enum: [blocked, ready_for_take_over, ready_to_publish, passed]
                href:
                  type: string
                  format: uri
                proof_blockers:
                  type: array
                  items:
                    type: string
                next_blocker:
                  type: [string, "null"]
                next_action:
                  type: string
                readiness:
                  type: object
                owner_actions:
                  type: object
                proof_chain:
                  $ref: "#/components/schemas/OperatorControlProofChain"
                journal_finality_ops:
                  $ref: "#/components/schemas/JournalFinalityOps"
        verification:
          type: object
          required: [private_keys_stored, server_signing, public_wallets]
          properties:
            private_keys_stored:
              type: boolean
            server_signing:
              type: string
            public_wallets:
              type: object