precheck

Evaluate a scenario against asserted data without mutating state.

Key notes

• Validates asserted data against a registered shape.
• Does not mutate run state; intended for simulation.

Inputs

• data_shape (required): Type: object.
• namespace_id (required): Namespace identifier.
• payload (required): Asserted data payload.
• scenario_id (optional): One of 2 schema variants.
• spec (optional): One of 2 schema variants.
• stage_id (optional): One of 2 schema variants.
• tenant_id (required): Tenant identifier.

Input Schema

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "additionalProperties": false,
  "properties": {
    "data_shape": {
      "additionalProperties": false,
      "properties": {
        "schema_id": {
          "description": "Data shape identifier.",
          "type": "string"
        },
        "version": {
          "description": "Data shape version identifier.",
          "type": "string"
        }
      },
      "required": [
        "schema_id",
        "version"
      ],
      "type": "object"
    },
    "namespace_id": {
      "description": "Namespace identifier.",
      "minimum": 1,
      "type": "integer"
    },
    "payload": {
      "description": "Asserted data payload.",
      "type": [
        "null",
        "boolean",
        "number",
        "string",
        "array",
        "object"
      ]
    },
    "scenario_id": {
      "oneOf": [
        {
          "type": "null"
        },
        {
          "description": "Scenario identifier.",
          "type": "string"
        }
      ]
    },
    "spec": {
      "oneOf": [
        {
          "type": "null"
        },
        {
          "$ref": "decision-gate://contract/schemas/scenario.schema.json"
        }
      ]
    },
    "stage_id": {
      "oneOf": [
        {
          "type": "null"
        },
        {
          "description": "Stage identifier override.",
          "type": "string"
        }
      ]
    },
    "tenant_id": {
      "description": "Tenant identifier.",
      "minimum": 1,
      "type": "integer"
    }
  },
  "required": [
    "tenant_id",
    "namespace_id",
    "data_shape",
    "payload"
  ],
  "type": "object"
}

Outputs

• decision (required): One of 5 schema variants.
• gate_evaluations (required): Type: array.

Output Schema

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "additionalProperties": false,
  "properties": {
    "decision": {
      "oneOf": [
        {
          "additionalProperties": false,
          "properties": {
            "kind": {
              "const": "start"
            },
            "stage_id": {
              "description": "Initial stage identifier.",
              "type": "string"
            }
          },
          "required": [
            "kind",
            "stage_id"
          ],
          "type": "object"
        },
        {
          "additionalProperties": false,
          "properties": {
            "kind": {
              "const": "complete"
            },
            "stage_id": {
              "description": "Terminal stage identifier.",
              "type": "string"
            }
          },
          "required": [
            "kind",
            "stage_id"
          ],
          "type": "object"
        },
        {
          "additionalProperties": false,
          "properties": {
            "from_stage": {
              "description": "Previous stage identifier.",
              "type": "string"
            },
            "kind": {
              "const": "advance"
            },
            "timeout": {
              "type": "boolean"
            },
            "to_stage": {
              "description": "Next stage identifier.",
              "type": "string"
            }
          },
          "required": [
            "kind",
            "from_stage",
            "to_stage",
            "timeout"
          ],
          "type": "object"
        },
        {
          "additionalProperties": false,
          "properties": {
            "kind": {
              "const": "hold"
            },
            "summary": {
              "additionalProperties": false,
              "properties": {
                "policy_tags": {
                  "description": "Policy tags applied to the summary.",
                  "items": {
                    "type": "string"
                  },
                  "type": "array"
                },
                "retry_hint": {
                  "oneOf": [
                    {
                      "type": "null"
                    },
                    {
                      "description": "Optional retry hint.",
                      "type": "string"
                    }
                  ]
                },
                "status": {
                  "description": "Summary status.",
                  "type": "string"
                },
                "unmet_gates": {
                  "items": {
                    "description": "Gate identifier.",
                    "type": "string"
                  },
                  "type": "array"
                }
              },
              "required": [
                "status",
                "unmet_gates",
                "retry_hint",
                "policy_tags"
              ],
              "type": "object"
            }
          },
          "required": [
            "kind",
            "summary"
          ],
          "type": "object"
        },
        {
          "additionalProperties": false,
          "properties": {
            "kind": {
              "const": "fail"
            },
            "reason": {
              "description": "Failure reason.",
              "type": "string"
            }
          },
          "required": [
            "kind",
            "reason"
          ],
          "type": "object"
        }
      ]
    },
    "gate_evaluations": {
      "items": {
        "additionalProperties": false,
        "properties": {
          "gate_id": {
            "description": "Gate identifier.",
            "type": "string"
          },
          "status": {
            "description": "Tri-state evaluation result.",
            "enum": [
              "True",
              "False",
              "Unknown"
            ],
            "type": "string"
          },
          "trace": {
            "items": {
              "additionalProperties": false,
              "properties": {
                "condition_id": {
                  "description": "Condition identifier.",
                  "type": "string"
                },
                "status": {
                  "description": "Tri-state evaluation result.",
                  "enum": [
                    "True",
                    "False",
                    "Unknown"
                  ],
                  "type": "string"
                }
              },
              "required": [
                "condition_id",
                "status"
              ],
              "type": "object"
            },
            "type": "array"
          }
        },
        "required": [
          "gate_id",
          "status",
          "trace"
        ],
        "type": "object"
      },
      "type": "array"
    }
  },
  "required": [
    "decision",
    "gate_evaluations"
  ],
  "type": "object"
}

Examples

Precheck a scenario with asserted data.

Input:

{
  "data_shape": {
    "schema_id": "asserted_payload",
    "version": "v1"
  },
  "namespace_id": 1,
  "payload": {
    "deploy_env": "production"
  },
  "scenario_id": "example-scenario",
  "spec": null,
  "stage_id": null,
  "tenant_id": 1
}

Output:

{
  "decision": {
    "kind": "hold",
    "summary": {
      "policy_tags": [],
      "retry_hint": "await_evidence",
      "status": "hold",
      "unmet_gates": [
        "ready"
      ]
    }
  },
  "gate_evaluations": []
}