scenario_define

Register a ScenarioSpec, validate it, and return the canonical hash used for integrity checks.

Key notes

• Use before starting runs; scenario_id becomes the stable handle for later calls.
• Validates stage/gate/condition IDs, RET trees, and condition references.
• Spec hash is deterministic; store it for audit and runpack integrity.
• Fails closed on invalid specs or duplicate scenario IDs.

Inputs

• spec (required): Scenario specification to register.

Input Schema

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "additionalProperties": false,
  "properties": {
    "spec": {
      "$ref": "decision-gate://contract/schemas/scenario.schema.json",
      "description": "Scenario specification to register."
    }
  },
  "required": [
    "spec"
  ],
  "type": "object"
}

Outputs

• scenario_id (required): Scenario identifier.
• spec_hash (required): Type: object.

Output Schema

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "additionalProperties": false,
  "properties": {
    "scenario_id": {
      "description": "Scenario identifier.",
      "type": "string"
    },
    "spec_hash": {
      "additionalProperties": false,
      "properties": {
        "algorithm": {
          "enum": [
            "sha256"
          ],
          "type": "string"
        },
        "value": {
          "description": "Lowercase hex digest.",
          "type": "string"
        }
      },
      "required": [
        "algorithm",
        "value"
      ],
      "type": "object"
    }
  },
  "required": [
    "scenario_id",
    "spec_hash"
  ],
  "type": "object"
}

Examples

Register the example scenario spec.

Input:

{
  "spec": {
    "conditions": [
      {
        "comparator": "equals",
        "condition_id": "env_is_prod",
        "expected": "production",
        "policy_tags": [],
        "query": {
          "check_id": "get",
          "params": {
            "key": "DEPLOY_ENV"
          },
          "provider_id": "env"
        }
      },
      {
        "comparator": "equals",
        "condition_id": "after_freeze",
        "expected": true,
        "policy_tags": [],
        "query": {
          "check_id": "after",
          "params": {
            "timestamp": 1710000000000
          },
          "provider_id": "time"
        }
      }
    ],
    "default_tenant_id": null,
    "namespace_id": 1,
    "policies": [],
    "scenario_id": "example-scenario",
    "schemas": [],
    "spec_version": "v1",
    "stages": [
      {
        "advance_to": {
          "kind": "terminal"
        },
        "entry_packets": [
          {
            "content_type": "application/json",
            "expiry": null,
            "packet_id": "packet-hello",
            "payload": {
              "kind": "json",
              "value": {
                "message": "hello",
                "purpose": "scenario entry packet"
              }
            },
            "policy_tags": [],
            "schema_id": "schema-hello",
            "visibility_labels": [
              "public"
            ]
          }
        ],
        "gates": [
          {
            "gate_id": "env_gate",
            "requirement": {
              "Condition": "env_is_prod"
            }
          },
          {
            "gate_id": "time_gate",
            "requirement": {
              "Condition": "after_freeze"
            }
          }
        ],
        "on_timeout": "fail",
        "stage_id": "main",
        "timeout": null
      }
    ]
  }
}

Output:

{
  "scenario_id": "example-scenario",
  "spec_hash": {
    "algorithm": "sha256",
    "value": "5c3a5b6bce0f4a2c9e22c4fa6a1e6d8d90b0f2dfed1b7f1e9b3d3b3d1f0c9b21"
  }
}