ForecastResponse

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://artifacts.apis.io/blackwalltier-com/json-schema/blackwalltier-com-forecast-response-schema.json",
  "title": "ForecastResponse",
  "x-generated": "2026-10-29",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/blackwalltier-com-openapi.yaml#/components/schemas/ForecastResponse",
  "type": "object",
  "required": [
    "id",
    "recommendation",
    "risk_score",
    "gate",
    "reversibility",
    "predicted_result",
    "red_flags",
    "tokens_charged",
    "latency_ms"
  ],
  "properties": {
    "id": {
      "type": "string"
    },
    "parent_forecast_id": {
      "type": "string",
      "description": "Echoed only when the request supplied parent_forecast_id (per-call swarm\nthreading) — links this forecast to the parent action it was run under.\n"
    },
    "recommendation": {
      "type": "string",
      "enum": [
        "GO",
        "CAUTION",
        "STOP"
      ]
    },
    "risk_score": {
      "type": "integer",
      "minimum": 0,
      "maximum": 100
    },
    "confidence": {
      "type": "number",
      "format": "float",
      "minimum": 0,
      "maximum": 1
    },
    "gate": {
      "type": "string",
      "enum": [
        "AUTO",
        "CONFIRM",
        "HUMAN_REQUIRED"
      ],
      "description": "The actionable control, derived from risk_score AND reversibility:\nAUTO = proceed automatically; CONFIRM = hold for human confirmation;\nHUMAN_REQUIRED = block until a human approves. An irreversible action\nis gated at a lower risk threshold than a reversible one.\n"
    },
    "reversibility": {
      "type": "object",
      "description": "Can the action be undone, and at what cost?",
      "properties": {
        "class": {
          "type": "string",
          "enum": [
            "REVERSIBLE",
            "RECOVERABLE",
            "IRREVERSIBLE"
          ]
        },
        "rollback_cost": {
          "type": "integer",
          "minimum": 0,
          "maximum": 100,
          "description": "0 = trivially undoable, 100 = permanent/catastrophic"
        },
        "rollback_window_sec": {
          "type": [
            "integer",
            "null"
          ],
          "description": "Seconds available to undo; null = no window / permanent"
        },
        "rationale": {
          "type": "string"
        }
      }
    },
    "predicted_result": {
      "type": "object",
      "properties": {
        "outcome": {
          "type": "string",
          "description": "One-sentence prediction"
        },
        "side_effects": {
          "type": "array",
          "items": {
            "type": "string"
          }
        }
      }
    },
    "red_flags": {
      "type": "array",
      "items": {
        "type": "object",
        "required": [
          "severity",
          "code",
          "message"
        ],
        "properties": {
          "severity": {
            "type": "string",
            "enum": [
              "low",
              "medium",
              "high",
              "critical"
            ]
          },
          "code": {
            "type": "string"
          },
          "message": {
            "type": "string"
          }
        }
      }
    },
    "alternative_actions": {
      "type": "array",
      "items": {
        "type": "string"
      }
    },
    "decision_trace": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "Only present when depth is \"deep\""
    },
    "counterfactuals": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "Only present when depth is \"deep\""
    },
    "mitigations": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "Only present when depth is \"deep\""
    },
    "prior_findings_truncated": {
      "type": "integer",
      "minimum": 1,
      "description": "Only present when the per-call cap dropped some caller-supplied\ncontext.prior_findings — either more than 100 findings, or the array's\ntotal serialized size exceeded the byte ceiling. The value is how many\nfindings were dropped (the gate scored a subset of your swarm). Absent\nwhen nothing was dropped. Send fewer/smaller findings per call to clear it.\n"
    },
    "tokens_charged": {
      "type": "integer"
    },
    "latency_ms": {
      "type": "integer"
    },
    "receipt": {
      "$ref": "#/$defs/Receipt"
    },
    "receipt_unavailable": {
      "type": "string",
      "enum": [
        "not_persisted",
        "signing_failed"
      ],
      "description": "Present ONLY when `receipt` is absent, and never alongside it. A receipt is\nattached if and only if its row was stored, so that a receipt you hold is\nalways one `GET /v1/receipts/{id}` can honour. The forecast itself is\nunaffected (and is not re-charged) — you simply have no signed receipt for\nthis call.\n\n`not_persisted` — the receipt was signed but its row did not land.\n`signing_failed` — the signature could not be produced.\n\nBoth are issuer-side faults worth reporting. Neither is retried for you.\n\nUnsigned: like `receipt` and `confirmation`, strip this key before\nre-deriving `response_hash`.\n"
    }
  },
  "$defs": {
    "Receipt": {
      "type": "object",
      "description": "Cryptographic decision receipt — an Ed25519 signature over canonical\nhashes of the request + response of a single forecast call. Anyone\nwith the published public key (see /.well-known/blackwall-signing-keys.json)\ncan verify offline without contacting Black_Wall.\n\nWe sign and store HASHES ONLY — the raw request/response bodies are\nnever persisted on our side. To verify later, you (or your auditor)\nprovide the bodies and we re-hash to check against the signed envelope.\n",
      "required": [
        "id",
        "forecast_id",
        "issued_at",
        "algorithm",
        "key_id",
        "request_hash",
        "response_hash",
        "signature"
      ],
      "properties": {
        "id": {
          "type": "string",
          "description": "Receipt's own UUID (distinct from forecast_id)."
        },
        "forecast_id": {
          "type": "string",
          "description": "The forecast this receipt vouches for."
        },
        "issued_at": {
          "type": "string",
          "format": "date-time"
        },
        "algorithm": {
          "type": "string",
          "enum": [
            "ed25519"
          ]
        },
        "key_id": {
          "type": "string",
          "description": "Which signing key was used. Look it up in\n/.well-known/blackwall-signing-keys.json. Receipts issued before\na key rotation continue to verify against the retired key.\n"
        },
        "request_hash": {
          "type": "string",
          "description": "SHA-256 (hex) of canonical(request_body), prefixed `sha256:`."
        },
        "response_hash": {
          "type": "string",
          "description": "SHA-256 (hex) of canonical(response_body without receipt), prefixed `sha256:`."
        },
        "signature": {
          "type": "string",
          "description": "Base64url Ed25519 signature over the canonicalized envelope (minus signature)."
        },
        "verify_url": {
          "type": "string",
          "format": "uri",
          "description": "Convenience URL for POST verification."
        }
      }
    }
  }
}