decide-fyi Counterfactuals API

openapi: 3.2.0
info:
  title: Decide Decision Counterfactuals API
  summary: Decision protocol for state-changing software actions.
  description: Call Decide before products, agents, queues, billing systems, CRMs, or internal tools change state. The API returns a signed Decision Record v1 object with policy bundle attestation, evidence, action binding, replay, verification handles, portable Decision Packet v1 exports, simulation-only counterfactual analysis, cryptographic audit chains, Action Execution Receipts, Outcome Records, CRM Sync Records, predictive confidence, first-party policy pattern templates, policy effectiveness metrics, opt-in anonymized benchmarks, and explainable anomaly reports derived from reported outcomes.
  version: 1.13.0
  x-decision-protocol-version: decision_protocol_v1
  x-decision-record-version: decision_record_v1
  x-decision-packet-version: decision_packet_v1
servers:
- url: https://www.decide.fyi
  description: Production
security:
- ApiKeyAuth: []
tags:
- name: Counterfactuals
  description: Simulation-only what-if analysis for stored Decision Records.
paths:
  /api/decision/{decision_id}/counterfactuals:
    post:
      tags:
      - Counterfactuals
      operationId: createDecisionCounterfactuals
      summary: Evaluate what-if scenarios for a stored decision
      description: Runs labeled simulation-only scenarios against the current Decision API runtime. Counterfactuals do not authorize downstream mutation; use the returned diffs for planning, rollout review, and policy tuning.
      parameters:
      - $ref: '#/components/parameters/DecisionId'
      - $ref: '#/components/parameters/DecisionResponseView'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CounterfactualRequest'
            examples:
              pricingDiscountScenarios:
                summary: Compare discount levels
                value:
                  response_view: standard
                  scenarios:
                  - scenario_id: discount_10_percent
                    label: 10% discount
                    context_patch:
                      discount_percent: 10
                  - scenario_id: discount_25_percent
                    label: 25% discount
                    context_patch:
                      discount_percent: 25
                      margin_floor: review_required
      responses:
        '200':
          description: Counterfactual report
          headers:
            x-decision-counterfactuals-version:
              schema:
                type: string
                const: decision_counterfactuals_v1
            x-decision-counterfactual-hash:
              schema:
                type: string
            x-decision-counterfactual-scenarios:
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DecisionCounterfactualsResult'
        '400':
          description: Missing or invalid scenarios
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          description: Decision not found in the authenticated caller scope
        '422':
          description: Base input unavailable
components:
  schemas:
    RuntimeBinding:
      type: object
      required:
      - production_core
      - binding_mode
      - verdict_authority
      - customer_supplied_code
      properties:
        production_core:
          type: string
          const: hybrid_declarative_rulebook_with_trusted_adapters
        binding_mode:
          type: string
          enum:
          - direct_declarative_rulebook
          - trusted_adapter_facts_then_declarative_rulebook
        verdict_authority:
          type: string
          const: declarative_rulebook
        adapter_authority:
          type: string
          const: facts_only
        customer_supplied_code:
          type: string
          const: rejected
      additionalProperties: false
    TrustedAdapterAttestation:
      type: object
      required:
      - manifest_version
      - adapter_id
      - version
      - implementation_revision
      - implementation_hash
      - manifest_hash
      - input_hash
      - output_hash
      - execution_isolation
      - capability_enforcement
      - execution_timeout_ms
      properties:
        manifest_version:
          type: string
          const: trusted_adapter_manifest_v1
        adapter_id:
          type: string
        version:
          type: string
        implementation_revision:
          type: string
        implementation_hash:
          type: string
          pattern: ^[a-f0-9]{64}$
        manifest_hash:
          type: string
          pattern: ^[a-f0-9]{64}$
        input_hash:
          type: string
          pattern: ^[a-f0-9]{64}$
        output_hash:
          type: string
          pattern: ^[a-f0-9]{64}$
        execution_isolation:
          type: string
          const: worker_thread_one_shot_v1
        capability_enforcement:
          type: string
          const: ambient_capability_deny_v2
        execution_timeout_ms:
          type: integer
          minimum: 1
      additionalProperties: false
    DecisionCounterfactualsResult:
      type: object
      required:
      - ok
      - decision_counterfactuals_version
      - source_decision_id
      - simulation_only
      - baseline
      - scenarios
      - counterfactual_hash
      properties:
        ok:
          type: boolean
        decision_counterfactuals_version:
          type: string
          const: decision_counterfactuals_v1
        generated_at:
          type: string
        source_decision_id:
          type: string
        simulation_only:
          type: boolean
          const: true
        baseline:
          type: object
          additionalProperties: true
        scenario_count:
          type: integer
        evaluated_count:
          type: integer
        changed_count:
          type: integer
        scenarios:
          type: array
          items:
            type: object
            properties:
              scenario_id:
                type: string
              label:
                type: string
              status:
                type: string
                enum:
                - evaluated
                - failed
              simulation_only:
                type: boolean
              changed:
                type: boolean
              verdict:
                type: string
              action:
                type: string
              input_hash:
                type: string
              output_hash:
                type: string
              record_hash:
                type: string
              receipt_hash:
                type: string
              diff:
                type: object
                additionalProperties: true
              decision:
                $ref: '#/components/schemas/DecisionRecord'
              scenario_hash:
                type: string
            additionalProperties: true
        data_quality:
          type: object
          additionalProperties: true
        counterfactual_hash:
          type: string
      additionalProperties: true
    RulebookRegistryMetadata:
      type: object
      required:
      - rulebook_registry_version
      - schema_version
      - rulebook_id
      - version
      - hash
      - evaluator_version
      - hash_algorithm
      - canonicalization
      - scope_hash
      - registry_attestation
      - registered_at
      properties:
        rulebook_registry_version:
          type: string
          const: decision_rulebook_registry_v1
        schema_version:
          type: string
          const: rulebook_v1
        rulebook_id:
          type: string
        version:
          type: string
        hash:
          type: string
          minLength: 64
          maxLength: 64
        evaluator_version:
          type: string
        trusted_adapter:
          $ref: '#/components/schemas/TrustedAdapterDependency'
        hash_algorithm:
          type: string
          const: sha256
        canonicalization:
          type: string
          const: json.sort_deep.v1
        scope_hash:
          type: string
          pattern: ^[a-f0-9]{64}$
        registry_attestation:
          $ref: '#/components/schemas/RegistryAttestation'
        registered_at:
          type: string
          format: date-time
      additionalProperties: false
    RulebookOutcome:
      type: object
      required:
      - decision
      - verdict
      - action
      - reason_code
      properties:
        decision:
          type: string
          enum:
          - 'yes'
          - 'no'
          - review
        verdict:
          type: string
          pattern: ^[A-Z][A-Z0-9_]{1,79}$
        action:
          type: string
          minLength: 1
          maxLength: 160
        reason_code:
          type: string
          pattern: ^[A-Z][A-Z0-9_]{1,79}$
      additionalProperties: false
    CounterfactualRequest:
      type: object
      required:
      - scenarios
      properties:
        base_input:
          $ref: '#/components/schemas/DecisionRequest'
        input:
          $ref: '#/components/schemas/DecisionRequest'
        response_view:
          type: string
          enum:
          - minimal
          - standard
          - full
        scenarios:
          type: array
          minItems: 1
          maxItems: 8
          items:
            $ref: '#/components/schemas/CounterfactualScenario'
      additionalProperties: true
    PolicyBundle:
      type: object
      properties:
        id:
          type: string
        version:
          type: string
        hash:
          type: string
        hash_algorithm:
          type: string
          default: sha256
        canonicalization:
          type: string
          default: json.sort_deep.v1
        source:
          type: string
        status:
          type: string
        effective_at:
          type: string
        deprecated_at:
          type: string
        changelog:
          type: string
        content_hash:
          type: string
      additionalProperties: true
    DecisionRecord:
      type: object
      required:
      - decision_protocol_version
      - decision_record_version
      - decision_id
      - request_id
      - verdict
      - record_hash
      - receipt_hash
      - verify_url
      - replay_url
      properties:
        decision_protocol_version:
          type: string
          const: decision_protocol_v1
        decision_record_version:
          type: string
          const: decision_record_v1
        response_view:
          type: string
          enum:
          - minimal
          - standard
          - full
        decision_id:
          type: string
          maxLength: 600
        request_id:
          type: string
        idempotency_key:
          type: string
        c:
          type: string
        v:
          type: string
        verdict:
          type: string
        application_verdict:
          type: string
          description: Purpose-specific bounded verdict produced by Rulebook v1, such as APPROVE, BLOCK, REVIEW, or NEEDS_INPUT.
        evaluator_version:
          type: string
          description: Versioned evaluator that produced the binding rulebook result.
        rulebook_contract:
          $ref: '#/components/schemas/RulebookContract'
        action:
          type: string
        reason_code:
          type: string
        matched_rule_id:
          type:
          - string
          - 'null'
        rulebook:
          type: object
          properties:
            schema_version:
              type: string
              const: rulebook_v1
            id:
              type: string
            version:
              type: string
            hash:
              type: string
          additionalProperties: true
        rulebook_registry:
          $ref: '#/components/schemas/RulebookRegistryMetadata'
        runtime_binding:
          $ref: '#/components/schemas/RuntimeBinding'
        trusted_adapter:
          $ref: '#/components/schemas/TrustedAdapterAttestation'
        adapter_facts:
          type: object
          description: Schema-validated facts emitted by the pinned trusted adapter before Rulebook v1 evaluation.
          additionalProperties: true
        action_binding:
          $ref: '#/components/schemas/ActionBinding'
        evidence:
          type: array
          items:
            type: string
        evidence_manifest:
          $ref: '#/components/schemas/EvidenceManifest'
        policy_id:
          type: string
        policy_version:
          type: string
        policy_hash:
          type: string
        source_hash:
          type: string
          description: Backend lineage hash returned in the full Decision Record response when the upstream decision engine supplies it.
        policy_bundle:
          $ref: '#/components/schemas/PolicyBundle'
        policy_bundle_hash:
          type: string
        confidence:
          $ref: '#/components/schemas/DecisionConfidence'
        decision_confidence:
          $ref: '#/components/schemas/DecisionConfidence'
        confidence_hash:
          type: string
        input_hash:
          type: string
        output_hash:
          type: string
        record_hash:
          type: string
          description: Tamper-evident hash of the normalized Decision Record v1 envelope, including binding application verdict, reason, matched rule, rulebook lineage, registry attestation, trusted adapter attestation, and adapter facts when present.
        receipt_hash:
          type: string
          description: Portable receipt hash over record_hash plus input/output, policy, action-binding, and evidence-manifest proof hashes.
        receipt_key_id:
          type: string
        receipt_signature:
          type: string
        receipt_signature_algorithm:
          type: string
          enum:
          - hmac-sha256
          - ed25519
        receipt_public_key:
          type: string
        receipt_public_key_fingerprint:
          type: string
        integrity:
          $ref: '#/components/schemas/Integrity'
        verify_url:
          type: string
        replay_url:
          type: string
        created_at:
          type: string
        audit_chain:
          $ref: '#/components/schemas/AuditChain'
        chain_url:
          type: string
      additionalProperties: true
    DecisionConfidence:
      type: object
      required:
      - ok
      - decision_confidence_version
      - score
      - level
      - recommendation
      - confidence_hash
      properties:
        ok:
          type: boolean
        decision_confidence_version:
          type: string
          const: decision_confidence_v1
        generated_at:
          type: string
        source:
          type: string
          const: decision_outcomes
        scope:
          type: string
          const: caller_api_key
        decision_id:
          type:
          - string
          - 'null'
        policy_id:
          type:
          - string
          - 'null'
        policy_version:
          type:
          - string
          - 'null'
        verdict:
          type: string
        action:
          type:
          - string
          - 'null'
        score:
          type: number
          minimum: 0
          maximum: 1
        level:
          type: string
          enum:
          - high
          - medium
          - low
          - weak
          - insufficient_data
        based_on:
          type: integer
        similar_decisions:
          type: integer
        policy_stability:
          type: string
          enum:
          - high
          - medium
          - low
          - insufficient_data
        recommendation:
          type: string
          enum:
          - collect_more_outcomes
          - high_confidence_proceed
          - high_confidence_block
          - high_confidence_review
          - proceed_with_monitoring
          - route_for_review
          - monitor
        metrics:
          type: object
          additionalProperties: true
        baseline:
          type: object
          additionalProperties: true
        data_quality:
          type: object
          additionalProperties: true
        reasons:
          type: array
          items:
            type: object
            additionalProperties: true
        confidence_hash:
          type: string
      additionalProperties: true
    AuditChain:
      type: object
      required:
      - decision_chain_version
      - chain_id
      - chain_position
      - leaf_hash
      - merkle_root
      - link_hash
      properties:
        decision_chain_version:
          type: string
          const: decision_chain_v1
        chain_id:
          type: string
        chain_position:
          type: integer
        previous_link_hash:
          type:
          - string
          - 'null'
        leaf_hash:
          type: string
        merkle_root:
          type: string
        merkle_strategy:
          type: string
          const: rolling_sha256_pair_v1
        link_hash:
          type: string
        chain_url:
          type: string
        created_at:
          type: string
        entry_type:
          type: string
      additionalProperties: true
    RulebookRule:
      type: object
      required:
      - rule_id
      - condition
      - outcome
      properties:
        rule_id:
          type: string
          pattern: ^[a-z][a-z0-9_.:-]{1,119}$
        priority:
          type: integer
          minimum: -1000
          maximum: 1000
          default: 0
        condition:
          $ref: '#/components/schemas/RulebookCondition'
        outcome:
          $ref: '#/components/schemas/RulebookOutcome'
      additionalProperties: false
    RulebookCondition:
      oneOf:
      - type: object
        required:
        - all
        properties:
          all:
            type: array
            minItems: 1
            maxItems: 32
            items:
              $ref: '#/components/schemas/RulebookCondition'
        additionalProperties: false
      - type: object
        required:
        - any
        properties:
          any:
            type: array
            minItems: 1
            maxItems: 32
            items:
              $ref: '#/components/schemas/RulebookCondition'
        additionalProperties: false
      - type: object
        required:
        - not
        properties:
          not:
            $ref: '#/components/schemas/RulebookCondition'
        additionalProperties: false
      - type: object
        required:
        - field
        - operator
        properties:
          field:
            type: string
            pattern: ^[A-Za-z_][A-Za-z0-9_.-]{0,159}$
          operator:
            type: string
            enum:
            - exists
            - not_exists
            - eq
            - neq
            - gt
            - gte
            - lt
            - lte
            - in
            - not_in
            - contains
            - not_contains
          value: {}
        additionalProperties: false
    RegistryAttestation:
      type: object
      required:
      - registry_attestation_version
      - status
      - attestation_hash
      properties:
        registry_attestation_version:
          type: string
          const: decision_registry_attestation_v1
        status:
          type: string
          enum:
          - signed
          - unsigned
        attestation_hash:
          type: string
          pattern: ^[a-f0-9]{64}$
        key_id:
          type: string
        signature_algorithm:
          type: string
          const: ed25519
        signature:
          type: string
          pattern: '^ed25519:'
        public_key:
          type: string
        public_key_fingerprint:
          type: string
          pattern: ^[a-f0-9]{64}$
      additionalProperties: false
    CounterfactualScenario:
      type: object
      required:
      - scenario_id
      properties:
        scenario_id:
          type: string
        label:
          type: string
        description:
          type: string
        input:
          $ref: '#/components/schemas/DecisionRequest'
        request:
          $ref: '#/components/schemas/DecisionRequest'
        patch:
          type: object
          additionalProperties: true
        context_patch:
          type: object
          additionalProperties: true
        question:
          type: string
        mode:
          type: string
      additionalProperties: true
    TrustedAdapterDependency:
      type: object
      required:
      - manifest_version
      - adapter_id
      - version
      - implementation_revision
      - implementation_hash
      - manifest_hash
      properties:
        manifest_version:
          type: string
          const: trusted_adapter_manifest_v1
        adapter_id:
          type: string
        version:
          type: string
        implementation_revision:
          type: string
        implementation_hash:
          type: string
          pattern: ^[a-f0-9]{64}$
        manifest_hash:
          type: string
          pattern: ^[a-f0-9]{64}$
      additionalProperties: false
    RulebookContract:
      type: object
      required:
      - schema_version
      - schema_url
      - schema_hash
      - evaluator_version
      properties:
        schema_version:
          type: string
          const: rulebook_v1
        schema_url:
          type: string
          const: https://api.decide.fyi/schemas/rulebook-v1.schema.json
        schema_hash:
          type: string
          pattern: ^[a-f0-9]{64}$
          description: SHA-256 hash of the published Rulebook v1 JSON Schema enforced by the runtime.
        evaluator_version:
          type: string
          const: decide_rulebook_v1
      additionalProperties: false
    Integrity:
      type: object
      properties:
        canonicalization:
          type: string
        decision_protocol_version:
          type: string
        hash_algorithm:
          type: string
        input_hash:
          type: string
        output_hash:
          type: string
        policy_hash:
          type: string
        policy_bundle_hash:
          type: string
        record_hash:
          type: string
        receipt_hash:
          type: string
        replay_url:
          type: string
        verify_url:
          type: string
        signature:
          type: object
          additionalProperties: true
      additionalProperties: true
    DecisionRequest:
      type: object
      anyOf:
      - required:
        - question
      - required:
        - prompt
        - context
      - required:
        - mode
        - rulebook
        - context
        properties:
          mode:
            const: rulebook
      properties:
        question:
          type: string
        mode:
          type: string
          enum:
          - single
          - multi
          - runtime
          - rulebook
        prompt:
          type: string
        stem:
          type: string
        options:
          type: array
          minItems: 2
          maxItems: 8
          items:
            type: string
        context:
          type:
          - object
          - string
          additionalProperties: true
        response_view:
          type: string
          enum:
          - minimal
          - standard
          - full
        rulebook:
          $ref: '#/components/schemas/RulebookV1'
        adapter:
          $ref: '#/components/schemas/TrustedAdapterInvocation'
      additionalProperties: false
    TrustedAdapterInvocation:
      type: object
      required:
      - adapter_id
      - version
      - manifest_hash
      - input
      properties:
        adapter_id:
          type: string
          pattern: ^[a-z][a-z0-9_.:-]{1,119}$
        version:
          type: string
          pattern: ^[0-9]+\.[0-9]+\.[0-9]+$
        manifest_hash:
          type: string
          pattern: ^[a-f0-9]{64}$
        input:
          type: object
          additionalProperties: true
      additionalProperties: false
    ActionBinding:
      type: object
      properties:
        actor:
          type: string
        system:
          type: string
        resource:
          type: string
        proposed_action:
          type: string
        subject:
          type: string
        amount:
          type: string
        currency:
          type: string
        target_system:
          type: string
        target_object_id:
          type: string
        mutation:
          type: string
        expires_at:
          type: string
        execution_state:
          type: string
        execution_id:
          type: string
      additionalProperties: true
    EvidenceSource:
      type: object
      properties:
        id:
          type: string
        type:
          type: string
        vendor:
          type: string
        title:
          type: string
        url:
          type: string
        policy_ref:
          type: string
        observed_at:
          type: string
        retrieval_id:
          type: string
        hash:
          type: string
        snapshot_hash:
          type: string
        content_hash:
          type: string
        version:
          type: string
      additionalProperties: true
    RulebookInputSchema:
      type: object
      properties:
        required:
          type: array
          items:
            type: string
            pattern: ^[A-Za-z_][A-Za-z0-9_.-]{0,159}$
        properties:
          type: object
          additionalProperties:
            type: object
            required:
            - type
            properties:
              type:
                type: string
                enum:
                - string
                - number
                - integer
                - boolean
                - array
                - object
                - 'null'
            additionalProperties: false
      additionalProperties: false
    ErrorResponse:
      type: object
      properties:
        c:
          type: string
        v:
          type: string
        request_id:
          type: string
        error:
          type: string
        message:
          type: string
      additionalProperties: true
    RulebookV1:
      type: object
      required:
      - schema_version
      - rulebook_id
      - version
      - rules
      - default_outcome
      properties:
        schema_version:
          type: string
          const: rulebook_v1
        rulebook_id:
          type: string
          pattern: ^[a-z][a-z0-9_.:-]{1,119}$
        version:
          type: string
          minLength: 1
          maxLength: 80
        input_schema:
          $ref: '#/components/schemas/RulebookInputSchema'
        rules:
          type: array
          minItems: 1
          maxItems: 100
          items:
            $ref: '#/components/schemas/RulebookRule'
        default_outcome:
          $ref: '#/components/schemas/RulebookOutcome'
      additionalProperties: false
    EvidenceManifest:
      type: object
      properties:
        codes:
          type: array
          items:
            type: string
        sources:
          type: array
          items:
            $ref: '#/components/schemas/EvidenceSource'
      additionalProperties: false
  responses:
    Unauthorized:
      description: API key missing, invalid, inactive, or unauthorized
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
  parameters:
    DecisionId:
      name: decision_id
      in: path
      required: true
      schema:
        type: string
        maxLength: 600
    DecisionResponseView:
      name: x-decision-response-view
      in: header
      required: false
      schema:
        type: string
        enum:
        - minimal
        - standard
        - full
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: x-api-key