flowspec2 1.0.0__py3-none-any.whl

flowspec2/flowspec-2.schema.json

@@ -0,0 +1,635 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://wllsena.github.io/flowspec2/schemas/flowspec-2.json",
+  "title": "flowspec/2 — declarative conversational flow definition compiled to LangGraph",
+  "description": "A single self-contained JSON document describing one citizen-facing service flow. The running ReAct agent loads it and compiles a StateGraph[ServiceState] inside the multi_step_service MCP tool. RAIL fields (the deterministic structure) pin states, slot value-domains, transitions, guards, tool bindings, interrupts, idempotency/reset and guardrails. LLM-FREEDOM fields (non-deterministic execution within the rails) are ONLY: route.description, route.trigger_phrases, every prompt.text (unless verbatim:true), domains.*.normalize hints, and the capabilities the LLM MAY invoke. The boundary is positional: by FIELD (only prompt.text/extract_hint/route.* are LLM-editable), by LOCATION (path/overrides/uses are rails; capabilities is the fenced LLM zone), and by CONSTRUCT (the closed domain IS the boundary — the LLM extracts a candidate, the generated validator rejects out-of-domain).",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["schema", "flow", "version", "route", "domains", "path"],
+  "properties": {
+    "schema": { "description": "RAIL. Format identifier + major version of THIS spec language (not the flow).", "const": "flowspec/2" },
+    "flow": { "description": "RAIL. Stable flow id == service_name; StateManager + checkpointer + config.yaml flow.registry key. Immutable across versions.", "type": "string", "pattern": "^[a-z][a-z0-9_]*$" },
+    "version": { "description": "RAIL. Semver of this flow document. Bump per change; diff-friendly.", "type": "string", "pattern": "^[0-9]+\\.[0-9]+\\.[0-9]+$" },
+    "service": {
+      "description": "RAIL. First-class service-identity metadata, decoupled from executable nodes. Carries service catalog codes, slugs, and knowledge identifiers; authors declare these values here instead of synthesizing an initialization node.",
+      "type": "object", "additionalProperties": false,
+      "properties": {
+        "id": { "type": "string", "description": "ticketing system/1746 service id, e.g. '18131'." },
+        "service_code": { "type": "string" },
+        "knowledge_service_id": { "type": "string", "description": "Knowledge-hub id for best-effort context load." },
+        "identification_required": { "type": "boolean", "default": false },
+        "slugs": { "type": "array", "items": { "type": "string" }, "description": "RAIL. Catalog/service-detail slug(s) this flow serves. A host app auto-exposes the guided flow for any service whose slug is listed here, so adding a guided flow is just dropping a JSON with its slug(s) — no host code change. Several slugs may point at one flow." }
+      }
+    },
+    "route": {
+      "description": "LLM-FREEDOM surface. The ONLY hook the top-level ReAct LLM uses to enter this flow. description = the routing hook (non-deterministic route-in). trigger_phrases = a versionable seed, NOT the sole signal. entry_args_schema = the closed set of initial slots the LLM may pass on entry (routing metadata only, never app state).",
+      "type": "object", "additionalProperties": false, "required": ["description"],
+      "properties": {
+        "description": { "type": "string", "minLength": 1 },
+        "trigger_phrases": { "type": "array", "items": { "type": "string" } },
+        "entry_args_schema": { "description": "JSON-Schema object of slots permitted on flow entry. Keys must be declared slots.", "type": "object" }
+      }
+    },
+    "config": {
+      "description": "RAIL. Guardrail booleans consumed by subflows and the engine. Deterministically force skip/default/end. No LLM hook.",
+      "type": "object", "additionalProperties": false,
+      "properties": {
+        "address_required": { "type": "boolean", "default": false },
+        "identification_required": { "type": "boolean", "default": false },
+        "max_attempts": { "type": "integer", "minimum": 1, "default": 3 }
+      }
+    },
+    "entry": {
+      "description": "RAIL. Generic best-effort, non-terminal entry side effect. Runs once before the path; never asks, blocks, or resets. Service identity remains in the service contract instead of this executable hook.",
+      "type": "object", "additionalProperties": false, "required": ["tool"],
+      "properties": {
+        "tool": { "$ref": "#/$defs/identifier", "description": "Registered tool name to call on entry." },
+        "blocking": { "type": "boolean", "default": false, "description": "false = failure is swallowed and the flow proceeds." },
+        "writes": { "$ref": "#/$defs/identifier", "description": "Data-partition key under which the result is stored." }
+      }
+    },
+    "domains": {
+      "description": "RAIL + the SPINE. The closed value-domain registry materializes the Pydantic before-validator, AgentResponse.payload_schema, interactive button titles, and interactive list rows. Categorical options come from values/rows; bool options expose true/false with Yes/No titles. Declaring a domain once is the entire structure/execution boundary: values are the rail and free-text-to-token extraction is LLM work. The validator prevents widening the domain. normalize is the only LLM-facing hint and is still deterministically enforced.",
+      "type": "object", "minProperties": 1,
+      "propertyNames": { "$ref": "#/$defs/domainIdentifier" },
+      "additionalProperties": {
+        "description": "Closed union by domain kind. A kind accepts only fields consumed by its validator.",
+        "oneOf": [
+          {
+            "title": "Categorical domain",
+            "type": "object", "additionalProperties": false, "required": ["values"],
+            "properties": {
+              "type": { "const": "categorical", "default": "categorical" },
+              "values": { "description": "Ordered closed token set. null is an explicit member.", "type": "array", "minItems": 1, "uniqueItems": true, "items": { "oneOf": [{ "type": "string", "minLength": 1 }, { "type": "null" }] } },
+              "rows": {
+                "description": "Optional per-token presentation subtitles. Semantic linking requires each row value to belong to values and to appear once.",
+                "type": "array",
+                "items": { "type": "object", "additionalProperties": false, "required": ["value"], "properties": { "value": { "type": "string", "minLength": 1 }, "description": { "type": "string" } } }
+              },
+              "normalize": {
+                "description": "Deterministic free-speech to closed-token coercion.",
+                "type": "object", "additionalProperties": false,
+                "properties": {
+                  "accent_fold": { "type": "boolean", "default": false },
+                  "number_words": { "type": "boolean", "default": false, "description": "Map supported number words to the positional token." },
+                  "synonyms": { "description": "Free-text alias to a canonical categorical token.", "type": "object", "propertyNames": { "minLength": 1 }, "additionalProperties": { "type": ["string", "null"] } }
+                }
+              }
+            }
+          },
+          {
+            "title": "Boolean domain",
+            "type": "object", "additionalProperties": false, "required": ["type"],
+            "properties": {
+              "type": { "const": "bool" },
+              "normalize": {
+                "description": "Deterministic boolean coercion and aliases.",
+                "type": "object", "additionalProperties": false,
+                "properties": {
+                  "accent_fold": { "type": "boolean", "default": false },
+                  "affirmation": { "type": "boolean", "default": false },
+                  "emoji_veto": { "type": "boolean", "default": false },
+                  "synonyms": { "description": "Free-text alias to a canonical boolean.", "type": "object", "propertyNames": { "minLength": 1 }, "additionalProperties": { "type": "boolean" } }
+                },
+                "allOf": [
+                  {
+                    "if": { "properties": { "emoji_veto": { "const": true } }, "required": ["emoji_veto"] },
+                    "then": { "properties": { "affirmation": { "const": true } }, "required": ["affirmation"] }
+                  }
+                ]
+              }
+            }
+          },
+          {
+            "title": "Free-text domain",
+            "type": "object", "additionalProperties": false, "required": ["type"],
+            "properties": {
+              "type": { "const": "free_text" },
+              "optional": { "description": "Accept an empty answer as an explicit empty string.", "type": "boolean", "default": false }
+            }
+          },
+          {
+            "title": "Brazilian tax ID domain",
+            "type": "object", "additionalProperties": false, "required": ["type"],
+            "properties": { "type": { "const": "brazilian_tax_id" } }
+          },
+          {
+            "title": "Email domain",
+            "type": "object", "additionalProperties": false, "required": ["type"],
+            "properties": { "type": { "const": "email" } }
+          },
+          {
+            "title": "Name domain",
+            "type": "object", "additionalProperties": false, "required": ["type"],
+            "properties": { "type": { "const": "name" } }
+          },
+          {
+            "title": "Integer domain",
+            "type": "object", "additionalProperties": false, "required": ["type"],
+            "properties": {
+              "type": { "const": "integer" },
+              "minimum": { "type": "number", "description": "Inclusive lower bound." },
+              "maximum": { "type": "number", "description": "Inclusive upper bound." }
+            }
+          },
+          {
+            "title": "Number domain",
+            "type": "object", "additionalProperties": false, "required": ["type"],
+            "properties": {
+              "type": { "const": "number" },
+              "minimum": { "type": "number", "description": "Inclusive lower bound." },
+              "maximum": { "type": "number", "description": "Inclusive upper bound." }
+            }
+          }
+        ]
+      }
+    },
+    "slots": {
+      "description": "RAIL. Per-slot declarations referenced by path steps, interactive options, and corrections. Binds a stable state key to a domain + persistence partition + collection guardrails. Position is rediscovered from filled slots; NO step pointer is persisted.",
+      "type": "object",
+      "propertyNames": { "$ref": "#/$defs/identifier" },
+      "additionalProperties": {
+        "type": "object", "additionalProperties": false, "required": ["domain"],
+        "properties": {
+          "domain": { "$ref": "#/$defs/domainIdentifier", "description": "References a key in domains{}." },
+          "persist": { "description": "Which persistent ServiceState partition owns the validated slot. 'data' is agent-visible; 'internal' is hidden.", "enum": ["data", "internal"], "default": "data" },
+          "required": { "type": "boolean", "default": false, "description": "When true, a gate-open collector requires a domain-valid value; explicit null is accepted only when nullable is true. When false, explicit null deterministically skips collection without storing a slot value." },
+          "nullable": { "type": "boolean", "default": false, "description": "Explicit null is a domain-valid stored value. This is distinct from the no-value skip performed by required:false." },
+          "requires": { "description": "RAIL. Hard precedence + dependency edges: these slots must be filled before this one is asked, AND this slot's value is invalidated (cleared) when any is corrected. The clear-cascade is DERIVED from this — author declares NOTHING extra (footgun killer).", "type": "array", "uniqueItems": true, "items": { "$ref": "#/$defs/identifier" } },
+          "prefill_sources": { "description": "Channels allowed to pre-fill this slot without its own prompt when fill_only_when_asked is true. e.g. whatsapp_flow, govbr_token.", "type": "array", "minItems": 1, "uniqueItems": true, "items": { "$ref": "#/$defs/identifier" } },
+          "max_attempts": { "type": "integer", "minimum": 1, "description": "Re-ask budget; engine owns the counter. Defaults to config.max_attempts." },
+          "on_exhaust": { "description": "After max_attempts: reask, skip without storing a value, store default, handoff, or END.", "enum": ["reask", "skip", "default", "handoff", "END"], "default": "reask" },
+          "default": { "description": "Fallback value stored only by on_exhaust:default. The compiler validates and normalizes it against the slot domain; null therefore requires a nullable domain." },
+          "fill_only_when_asked": { "description": "RAIL (single declarative flag, fixes A9). When true, the engine accepts this slot only after its own prompt or from a channel listed in prefill_sources. NOT a rule engine.", "type": "boolean", "default": false }
+        },
+        "allOf": [
+          {
+            "if": {
+              "properties": { "on_exhaust": { "const": "default" } },
+              "required": ["on_exhaust"]
+            },
+            "then": { "required": ["default"] },
+            "else": { "not": { "required": ["default"] } }
+          },
+          {
+            "if": {
+              "properties": { "nullable": { "const": true } },
+              "required": ["nullable"]
+            },
+            "then": {
+              "properties": { "required": { "const": true } },
+              "required": ["required"]
+            }
+          },
+          {
+            "if": { "required": ["prefill_sources"] },
+            "then": {
+              "properties": { "fill_only_when_asked": { "const": true } },
+              "required": ["fill_only_when_asked"]
+            }
+          }
+        ]
+      }
+    },
+    "path": {
+      "description": "RAIL. The flat ordered happy path. Implicit fall-through: each step is one StateGraph node; linear order is the default edge; the PAUSE->END and back-to-agent edges are synthesized. The step pointer is never serialized; position is rediscovered from state. A step is exactly one of slot | confirm | derive | terminal | use | await_external.",
+      "type": "array", "minItems": 1, "items": { "$ref": "#/$defs/step" }
+    },
+    "uses": {
+      "description": "RAIL + the MINIMALITY lever. Versioned reusable subflows (mixins) composed by id@major + config flags. Splices the subflow's slots+nodes+routers at its anchor in path; inherits invisible idempotency/reset/max-attempt defaults so a new author cannot forget them. The compiler discovers each subflow's exposed slots and validates corrections, requirements, derives, and terminal mappings after expansion.",
+      "type": "array", "items": { "$ref": "#/$defs/subflowRef" }
+    },
+    "derive": {
+      "description": "RAIL. Computed values, never asked (escape hatch #1). Lookup-table-ONLY with a single $from[i] fallback — deliberately too weak to be an expression language. Inserted as a no-prompt node that always advances. Prevents value-domain leak: the LLM never computes a classification.",
+      "type": "array", "items": { "$ref": "#/$defs/deriveDef" }
+    },
+    "confirm": {
+      "description": "RAIL. The data-confirmation state + non-linear correction routing (escape hatch #2). On confirmation -> terminal. The constrained decoder emits the exact canonical identifier of one correctable slot; the compiler routes to that slot's node and clears it + its transitive requires[]-dependents + derives that read them. Author lists only the directly-correctable slots; the cascade is derived.",
+      "$ref": "#/$defs/confirmDef"
+    },
+    "terminal": {
+      "description": "RAIL. The single fulfillment action + lifecycle (idempotency/reset/empty-payload). Reachable only when every required gate-open slot is filled. idempotent:true is one flag; the sha256 key recipe + retryable-exception taxonomy stay in the library. Outcome TRICHOTOMY: success (reset_next), retryable (preserve_state, re-enter), fatal (reset_next).",
+      "$ref": "#/$defs/terminalDef"
+    },
+    "overrides": {
+      "description": "RAIL. The hard-case tier (escape hatches), kept OUT of the linear path so the happy-path read stays clean. Only flows that need them pay. A simple linear service omits this entirely.",
+      "type": "object", "additionalProperties": false,
+      "properties": {
+        "gates": { "description": "Multi-slot gate predicates keyed by step id. gate==false => the step's slot is satisfied-by-vacuity (skipped uniformly, no special skip-node). Uses the frozen object grammar.", "type": "object", "propertyNames": { "$ref": "#/$defs/identifier" }, "additionalProperties": { "$ref": "#/$defs/predicate" } }
+      }
+    },
+    "auto_flow": {
+      "description": "RAIL. Pre-graph WhatsApp Flow gate (NOT a state — it suspends on nfm_reply, not the next text turn). If send_when holds and the entry slot is empty, the compiler sends the Meta Flow envelope and returns status:flow_sent WITHOUT entering the graph. On submission the nfm_reply is re-injected as payload._source=whatsapp_flow and resumed at resume_at. alias_map handles one-Flow-field -> multiple-slots fan-out (fixes A4) bound HARD to a flat value-keyed map (no nested logic).",
+      "$ref": "#/$defs/autoFlowDef"
+    },
+    "capabilities": {
+      "description": "FENCED LLM-FREEDOM zone (boundary by LOCATION). Agent-scope non-deterministic side-actions the LLM MAY invoke at its discretion, bounded by the Mule outbound whitelist (cross-checked by the COMPILER against config.yaml, never encoded here). await_external is the one reusable out-of-band primitive: it is bound either to an explicit path marker or to a subflow-provided step.",
+      "type": "object", "additionalProperties": false,
+      "properties": {
+        "media_in": { "type": "object", "additionalProperties": false, "properties": { "analyze": { "type": "array", "minItems": 1, "uniqueItems": true, "items": { "enum": ["image", "audio", "video"] } }, "route_by": { "$ref": "#/$defs/identifier" } } },
+        "media_out": {
+          "description": "Outbound media types the LLM may send. A template entry carries a Meta 24h-window template name + variable bindings (fixes A7). Plain types are bare strings.",
+          "type": "array", "minItems": 1, "uniqueItems": true,
+          "items": {
+            "oneOf": [
+              { "enum": ["image", "video", "audio", "document", "location", "contacts"] },
+              { "type": "object", "additionalProperties": false, "required": ["template"], "properties": { "template": { "type": "object", "additionalProperties": false, "required": ["name"], "properties": { "name": { "type": "string" }, "vars": { "type": "array", "items": { "type": "string" } } } } } }
+            ]
+          }
+        },
+        "tts": { "type": "boolean", "default": false },
+        "location_in": { "type": "boolean", "default": false },
+        "handoff": { "type": "object", "additionalProperties": false, "properties": { "target": { "type": "string", "description": "e.g. '1746' or a human queue." }, "when": { "enum": ["llm_decides"], "default": "llm_decides" } } },
+        "session_reset": { "type": "boolean", "default": false },
+        "await_external": {
+          "description": "First-class out-of-band suspend/resume primitive (gov.br OAuth, payment redirect, alternate IdP). Emits an out-of-band host marker with an absolute deadline when timeout is configured, suspends on an EXTERNAL signal (not the next text turn), and resumes with atomic bounded mappings. Timeout is delivered by the host as _external_event=timeout; the runtime owns no scheduler.",
+          "type": "object", "additionalProperties": false, "required": ["kind", "resume_on"],
+          "dependentRequired": { "timeout_seconds": ["timeout"] },
+          "properties": {
+            "kind": { "enum": ["cta_url"] },
+            "step": { "$ref": "#/$defs/identifier", "description": "Stable id of a subflow-provided await node. An explicit path await_external step may supply the same id instead." },
+            "resume_on": { "$ref": "#/$defs/identifier", "description": "External signal payload key, e.g. govbr_token." },
+            "resume": { "$ref": "#/$defs/resumeContractDef", "description": "Versioned token, correlation, replay, and late-delivery contract. Required by strict runtime profiles; omission identifies a legacy capability." },
+            "prompt": { "$ref": "#/$defs/promptDef" },
+            "interactive": {
+              "allOf": [
+                { "$ref": "#/$defs/interactiveDef" },
+                { "properties": { "kind": { "const": "cta_url" }, "out_of_band": { "const": true } } }
+              ]
+            },
+            "on_resume": {
+              "type": "object", "additionalProperties": false,
+              "properties": {
+                "set": { "$ref": "#/$defs/stateBindingMap", "description": "State key -> literal or $token.path binding. Resolved writes are committed atomically." },
+                "enrich": {
+                  "description": "Explicit enrichment call. A bare tool name remains accepted for legacy subflow documents; new documents declare the object contract.",
+                  "oneOf": [
+                    { "type": "string", "minLength": 1 },
+                    { "$ref": "#/$defs/enrichmentDef" }
+                  ]
+                }
+              }
+            },
+            "timeout": { "$ref": "#/$defs/transition" },
+            "timeout_seconds": { "type": "integer", "exclusiveMinimum": 0, "description": "Relative duration used to materialize the absolute host deadline." },
+            "max_resends": { "type": "integer", "minimum": 0, "description": "Optional runtime-enforced budget for accepted resend recovery events. Omission leaves resend limiting to the host." },
+            "recovery": { "type": "object", "additionalProperties": false, "properties": { "abort": { "$ref": "#/$defs/transition" }, "resend": { "$ref": "#/$defs/transition" }, "switch": { "$ref": "#/$defs/transition" } } }
+          },
+          "allOf": [
+            {
+              "if": { "required": ["timeout"] },
+              "then": { "properties": { "timeout_seconds": { "default": 900 } } }
+            },
+            {
+              "if": { "required": ["max_resends"] },
+              "then": {
+                "required": ["recovery"],
+                "properties": { "recovery": { "required": ["resend"] } }
+              }
+            }
+          ]
+        }
+      }
+    }
+  },
+  "$defs": {
+    "identifier": {
+      "type": "string",
+      "pattern": "^[a-z][a-z0-9_]*$"
+    },
+    "domainIdentifier": {
+      "type": "string",
+      "pattern": "^[A-Za-z][A-Za-z0-9_]*$"
+    },
+    "fieldIdentifier": {
+      "type": "string",
+      "pattern": "^[A-Za-z][A-Za-z0-9_]*$"
+    },
+    "promptDef": {
+      "description": "Citizen-facing fallback text. text is LLM-editable (the LLM may rephrase) UNLESS verbatim:true, which pins legally/contractually fixed wording (gov.br CTA, 1746 disclaimer). extract_hint is LLM guidance for free-text->token extraction (LLM-freedom).",
+      "type": "object", "additionalProperties": false, "required": ["text"],
+      "properties": { "text": { "type": "string" }, "verbatim": { "type": "boolean", "default": false }, "extract_hint": { "type": "string" } }
+    },
+    "predicate": {
+      "description": "Closed object-form predicate grammar. Read-only namespaces: slots.<name>, internal.<name>, payload.<key>, config.<flag>, address.<field>. Operators: in, eq, ne, is_present, and, or, not. Canonical flows do not accept string-expression shorthand. null is a valid literal.",
+      "type": "object", "minProperties": 1, "maxProperties": 1, "additionalProperties": false,
+      "properties": {
+        "in": { "type": "array", "minItems": 2, "maxItems": 2, "prefixItems": [ { "$ref": "#/$defs/stateReference" }, { "type": "array", "items": { "type": ["string", "number", "boolean", "null"] } } ], "items": false },
+        "eq": { "type": "array", "minItems": 2, "maxItems": 2, "items": { "$ref": "#/$defs/predicateOperand" } },
+        "ne": { "type": "array", "minItems": 2, "maxItems": 2, "items": { "$ref": "#/$defs/predicateOperand" } },
+        "is_present": { "$ref": "#/$defs/stateReference" },
+        "and": { "type": "array", "minItems": 1, "items": { "$ref": "#/$defs/predicate" } },
+        "or": { "type": "array", "minItems": 1, "items": { "$ref": "#/$defs/predicate" } },
+        "not": { "$ref": "#/$defs/predicate" }
+      }
+    },
+    "predicateOperand": {
+      "description": "A scalar operand. A bare namespaced string is always a state reference; wrap it as {literal: ...} when that exact string is the intended literal.",
+      "oneOf": [
+        { "type": ["string", "number", "boolean", "null"] },
+        {
+          "type": "object", "additionalProperties": false, "required": ["literal"],
+          "properties": { "literal": { "type": ["string", "number", "boolean", "null"] } }
+        }
+      ]
+    },
+    "stateReference": {
+      "description": "Namespaced state reference; true iff its resolved value is filled and non-null.",
+      "type": "string",
+      "oneOf": [
+        { "pattern": "^slots\\.[a-z][a-z0-9_]*$" },
+        { "pattern": "^(internal|payload|config)\\.[A-Za-z_][A-Za-z0-9_]*$" },
+        { "pattern": "^address\\.[A-Za-z_][A-Za-z0-9_]*(?:\\.[A-Za-z_][A-Za-z0-9_]*)*$" }
+      ]
+    },
+    "interactiveDef": {
+      "description": "RAIL. Closed UI union. Choice variants materialize options from the target domain. The CTA variant is reserved for external waits.",
+      "oneOf": [
+        {
+          "title": "Buttons",
+          "type": "object", "additionalProperties": false, "required": ["kind", "field", "from_domain"],
+          "properties": {
+            "kind": { "const": "buttons" },
+            "field": { "$ref": "#/$defs/fieldIdentifier" },
+            "from_domain": { "$ref": "#/$defs/domainIdentifier" },
+            "options_when": { "$ref": "#/$defs/conditionalOptions" }
+          }
+        },
+        {
+          "title": "List",
+          "type": "object", "additionalProperties": false, "required": ["kind", "field", "from_domain"],
+          "properties": {
+            "kind": { "const": "list" },
+            "field": { "$ref": "#/$defs/fieldIdentifier" },
+            "from_domain": { "$ref": "#/$defs/domainIdentifier" },
+            "options_when": { "$ref": "#/$defs/conditionalOptions" }
+          }
+        },
+        {
+          "title": "Out-of-band CTA",
+          "type": "object", "additionalProperties": false, "required": ["kind", "field", "out_of_band"],
+          "properties": {
+            "kind": { "const": "cta_url" },
+            "field": { "$ref": "#/$defs/fieldIdentifier" },
+            "out_of_band": { "const": true },
+            "next_step": { "$ref": "#/$defs/identifier" }
+          }
+        }
+      ]
+    },
+    "conditionalOptions": {
+      "description": "Conditional visibility for canonical rendered options.",
+      "type": "array", "uniqueItems": true,
+      "items": {
+        "type": "object", "additionalProperties": false, "required": ["value", "gate"],
+        "properties": {
+          "value": { "type": ["string", "boolean"] },
+          "gate": { "$ref": "#/$defs/predicate" }
+        }
+      }
+    },
+    "choiceInteractiveDef": {
+      "allOf": [
+        { "$ref": "#/$defs/interactiveDef" },
+        { "properties": { "kind": { "enum": ["buttons", "list"] } } }
+      ]
+    },
+    "step": {
+      "description": "RAIL. A closed union of path-step contracts. Each kind exposes only fields the compiler consumes.",
+      "oneOf": [
+        {
+          "title": "Collect step",
+          "type": "object", "additionalProperties": false, "required": ["slot"],
+          "properties": {
+            "step": { "$ref": "#/$defs/identifier", "description": "Stable node id. Defaults to the slot name." },
+            "slot": { "$ref": "#/$defs/identifier", "description": "References a declared slot and pauses while it is unfilled." },
+            "prompt": { "$ref": "#/$defs/promptDef" },
+            "interactive": { "$ref": "#/$defs/choiceInteractiveDef" },
+            "ask_when": { "$ref": "#/$defs/predicate", "description": "Ask only when this predicate is true." },
+            "skip_when": { "$ref": "#/$defs/predicate", "description": "Skip this collection when this predicate is true." }
+          }
+        },
+        {
+          "title": "Confirmation step",
+          "type": "object", "additionalProperties": false, "required": ["confirm"],
+          "properties": {
+            "step": { "$ref": "#/$defs/identifier", "description": "Stable node id. Defaults to the confirmation slot name." },
+            "confirm": { "$ref": "#/$defs/identifier", "description": "References a declared boolean confirmation slot." },
+            "prompt": { "$ref": "#/$defs/promptDef" },
+            "interactive": { "$ref": "#/$defs/choiceInteractiveDef" },
+            "ask_when": { "$ref": "#/$defs/predicate", "description": "Ask only when this predicate is true." },
+            "skip_when": { "$ref": "#/$defs/predicate", "description": "Skip this confirmation when this predicate is true." },
+            "on_reject": { "description": "Ends the flow with a message when the citizen declines.", "type": "object", "additionalProperties": false, "required": ["end"], "properties": { "end": { "type": "string", "minLength": 1 } } },
+            "correctable": { "const": true, "description": "Marks this confirmation as the correction hub." }
+          },
+          "allOf": [
+            { "not": { "required": ["on_reject", "correctable"] } },
+            {
+              "if": { "required": ["correctable"] },
+              "then": {
+                "not": {
+                  "anyOf": [
+                    { "required": ["ask_when"] },
+                    { "required": ["skip_when"] }
+                  ]
+                }
+              }
+            },
+            {
+              "if": { "required": ["on_reject"] },
+              "then": { "not": { "required": ["ask_when"] } }
+            },
+            {
+              "if": {
+                "not": {
+                  "anyOf": [
+                    { "required": ["on_reject"] },
+                    { "required": ["correctable"] }
+                  ]
+                }
+              },
+              "then": { "not": { "required": ["skip_when"] } }
+            }
+          ]
+        },
+        {
+          "title": "Derivation step",
+          "type": "object", "additionalProperties": false, "required": ["derive"],
+          "properties": {
+            "step": { "$ref": "#/$defs/identifier", "description": "Stable node id. Defaults to derive_<target>." },
+            "derive": { "$ref": "#/$defs/identifier", "description": "References a derive definition by its writes target." }
+          }
+        },
+        {
+          "title": "Terminal step",
+          "type": "object", "additionalProperties": false, "required": ["terminal"],
+          "properties": {
+            "terminal": { "const": true, "description": "Binds the top-level terminal action at this position." }
+          }
+        },
+        {
+          "title": "Subflow step",
+          "type": "object", "additionalProperties": false, "required": ["use"],
+          "properties": {
+            "use": { "type": "string", "minLength": 1, "description": "References a declared versioned subflow use." }
+          }
+        },
+        {
+          "title": "External-wait step",
+          "type": "object", "additionalProperties": false, "required": ["await_external"],
+          "properties": {
+            "step": { "$ref": "#/$defs/identifier", "description": "Stable node id shared with the external-wait capability." },
+            "await_external": { "const": true, "description": "Binds the singular external-wait capability at this position." },
+            "prompt": { "$ref": "#/$defs/promptDef" },
+            "interactive": {
+              "allOf": [
+                { "$ref": "#/$defs/interactiveDef" },
+                { "properties": { "kind": { "const": "cta_url" }, "out_of_band": { "const": true } } }
+              ]
+            }
+          }
+        }
+      ]
+    },
+    "subflowRef": {
+      "description": "RAIL. A versioned mixin reference. ref = name@major (visible, diffable version event). with{} flips the subflow's common_config rails. The subflow brings its own slots/nodes/await_external and inherits idempotency/reset defaults.",
+      "type": "object", "additionalProperties": false, "required": ["ref"],
+      "properties": {
+        "ref": { "type": "string", "pattern": "^[a-z][a-z0-9_]*@[0-9]+$" },
+        "with": {
+          "description": "Configuration is structurally an object; the resolved subflow manifest is the single source of truth for its closed keys and values.",
+          "type": "object"
+        }
+      }
+    },
+    "deriveDef": {
+      "description": "RAIL. A computed value. Lookup table keyed by '|'.join(from-values) (null member => empty segment, e.g. 'Hanging||'). default is a literal or the single sigil $from[i] (the i-th source value). after = the step id this derive runs immediately after.",
+      "type": "object", "additionalProperties": false, "required": ["writes", "from", "lookup"],
+      "properties": {
+        "writes": { "$ref": "#/$defs/identifier", "description": "data key the result is written to (a derived slot, never asked)." },
+        "from": { "type": "array", "minItems": 1, "uniqueItems": true, "items": { "$ref": "#/$defs/identifier" }, "description": "ordered source slot names." },
+        "after": { "$ref": "#/$defs/identifier", "description": "step id after which this derive node runs." },
+        "lookup": { "description": "key ('|'-joined from-values) -> value.", "type": "object", "additionalProperties": { "type": "string" } },
+        "default": { "type": "string", "description": "literal, or $from[i] (the ONLY deref sigil). Used on lookup miss." }
+      }
+    },
+    "confirmDef": {
+      "type": "object", "additionalProperties": false, "required": ["step", "slot", "correctable"],
+      "properties": {
+        "step": { "$ref": "#/$defs/identifier", "description": "node id of the confirm state." },
+        "slot": { "$ref": "#/$defs/identifier", "description": "bool slot that records confirmation." },
+        "prompt": { "$ref": "#/$defs/promptDef", "description": "Compatibility copy of the matching correctable path prompt; when both are present they must be identical." },
+        "interactive": { "$ref": "#/$defs/choiceInteractiveDef", "description": "Compatibility copy of the matching correctable path interactive definition; when both are present they must be identical." },
+        "on_confirm": { "$ref": "#/$defs/identifier", "description": "step/anchor to go to on Yes (usually the terminal/requests anchor)." },
+        "correctable": { "description": "RAIL. The set of directly-correctable slots. The constrained decoder must return one exact identifier from this closed set; the compiler routes to its node and clears it + its transitive requires[]-dependents + reading derives. No clears[] list is hand-declared.", "type": "array", "items": { "$ref": "#/$defs/identifier" }, "minItems": 1, "uniqueItems": true }
+      }
+    },
+    "terminalDef": {
+      "type": "object", "additionalProperties": false, "required": ["step", "tool", "idempotent", "outcomes"],
+      "properties": {
+        "step": { "$ref": "#/$defs/identifier", "description": "node id (e.g. open_ticket)." },
+        "tool": { "$ref": "#/$defs/identifier", "description": "registered fulfillment tool (e.g. open_service_request)." },
+        "idempotent": { "type": "boolean", "description": "true => compiler computes sha256 key over inputs + replay-caches. Recipe stays in library." },
+        "input": { "description": "RAIL. param -> slot binding for the tool call.", "type": "array", "items": { "type": "object", "additionalProperties": false, "required": ["param", "slot"], "properties": { "param": { "$ref": "#/$defs/fieldIdentifier" }, "slot": { "$ref": "#/$defs/identifier" } } } },
+        "outputs": { "description": "RAIL. Mapping from destination state key to a canonical result.* tool-result path (e.g. protocol_id: result.protocol_id).", "type": "object", "propertyNames": { "$ref": "#/$defs/identifier" }, "additionalProperties": { "type": "string", "pattern": "^result\\.[A-Za-z][A-Za-z0-9_]*(?:\\.[A-Za-z][A-Za-z0-9_]*)*$" } },
+        "outcomes": {
+          "description": "RAIL. The outcome trichotomy. success: set+reset_next. retryable: preserve_state, re-enter. fatal: reset_next, END.",
+          "type": "object", "additionalProperties": false, "required": ["success", "retryable", "fatal"],
+          "properties": {
+            "success": { "type": "object", "additionalProperties": false, "properties": { "set": { "$ref": "#/$defs/stateLiteralMap" }, "reset_next": { "type": "boolean", "default": true } } },
+            "retryable": { "type": "object", "additionalProperties": false, "properties": { "preserve_state": { "type": "boolean", "default": true } } },
+            "fatal": { "type": "object", "additionalProperties": false, "properties": { "reset_next": { "type": "boolean", "default": true } } }
+          }
+        },
+        "empty_payload": { "description": "RAIL. Empty-payload reset semantics. never_saved: reset (treat as fresh). in_progress: ignore (don't wipe mid-flow).", "type": "object", "additionalProperties": false, "properties": { "never_saved": { "enum": ["reset", "ignore"], "default": "reset" }, "in_progress": { "enum": ["reset", "ignore"], "default": "ignore" } } }
+      }
+    },
+    "autoFlowDef": {
+      "type": "object", "additionalProperties": false, "required": ["meta_flow_ref", "send_when", "recovery"],
+      "properties": {
+        "meta_flow_ref": { "$ref": "#/$defs/fieldIdentifier", "description": "registered Meta Flow id (config.yaml whatsapp.flow.registry)." },
+        "send_when": { "$ref": "#/$defs/predicate", "description": "send the Flow envelope (pre-graph) iff true, e.g. not is_present(slots.streetlight_issue)." },
+        "prefill_from": { "type": "array", "uniqueItems": true, "items": { "$ref": "#/$defs/identifier" }, "description": "slots carried into flow_token (${data.X} prefill)." },
+        "resume_at": { "$ref": "#/$defs/identifier", "description": "path step id to resume at after nfm_reply submission." },
+        "on_submit_source": { "type": "string", "const": "whatsapp_flow" },
+        "alias_map": { "description": "RAIL but BOUNDED (W5). Flat fan-out for Meta-Flow field-shape mismatch ONLY. Outer key = Flow field name. Inner: either a direct slot mapping {slot:value}, OR value-keyed { <flow_value>: {slot:value,...} } for one-field->many-slots. No nested predicates, no transform DSL.", "type": "object", "propertyNames": { "$ref": "#/$defs/fieldIdentifier" }, "additionalProperties": { "$ref": "#/$defs/aliasMapping" } },
+        "recovery": { "$ref": "#/$defs/autoFlowRecoveryDef" }
+      }
+    },
+    "autoFlowRecoveryDef": {
+      "description": "Closed pending-state policy. The runtime accepts exact cancel, resend, fallback, and timeout events; the host schedules timeout from the emitted absolute deadline.",
+      "type": "object", "additionalProperties": false,
+      "required": ["fallback_at", "cancel", "timeout", "max_resends", "timeout_seconds"],
+      "properties": {
+        "fallback_at": { "$ref": "#/$defs/identifier", "description": "Native path step used by the fallback event and fallback policy actions." },
+        "cancel": { "enum": ["END", "fallback"], "description": "Deterministic action for a cancel event." },
+        "timeout": { "enum": ["END", "fallback"], "description": "Deterministic action when the deadline expires or a timeout event arrives." },
+        "max_resends": { "type": "integer", "minimum": 0 },
+        "timeout_seconds": { "type": "integer", "exclusiveMinimum": 0 }
+      }
+    },
+    "aliasLiteral": {
+      "description": "A JSON scalar or $value, copied without evaluation beyond the exact $value placeholder.",
+      "type": ["string", "number", "boolean", "null"]
+    },
+    "directAliasMapping": {
+      "type": "object", "minProperties": 1,
+      "propertyNames": { "$ref": "#/$defs/identifier" },
+      "additionalProperties": { "$ref": "#/$defs/aliasLiteral" }
+    },
+    "aliasMapping": {
+      "oneOf": [
+        { "$ref": "#/$defs/directAliasMapping" },
+        {
+          "type": "object", "minProperties": 1,
+          "additionalProperties": { "$ref": "#/$defs/directAliasMapping" }
+        }
+      ]
+    },
+    "transition": {
+      "description": "A routing target with optional set. Used by await_external timeout/recovery branches.",
+      "type": "object", "additionalProperties": false, "required": ["goto"],
+      "properties": { "goto": { "oneOf": [{ "$ref": "#/$defs/identifier" }, { "const": "END" }], "description": "step id or 'END'." }, "set": { "$ref": "#/$defs/stateLiteralMap" } }
+    },
+    "resumeContractDef": {
+      "description": "Closed contract for host-delivered resume tokens. The embedded schema is validated as Draft 2020-12, may use only acyclic local references, and must close its object boundary.",
+      "type": "object", "additionalProperties": false,
+      "required": ["version", "schema", "correlation", "duplicate", "late"],
+      "properties": {
+        "version": { "type": "string", "pattern": "^[1-9][0-9]*(?:\\.[0-9]+){0,2}$" },
+        "schema": { "type": "object" },
+        "correlation": { "type": "string", "pattern": "^\\$token(?:\\.[A-Za-z][A-Za-z0-9_]*)+$" },
+        "duplicate": { "enum": ["ignore", "reject"] },
+        "late": { "enum": ["ignore", "reject"] }
+      }
+    },
+    "bindingLiteral": {
+      "description": "A bounded mapping value: a JSON scalar literal or a compiler-checked $token.* / $result.* reference.",
+      "type": ["string", "number", "boolean", "null"]
+    },
+    "stateBindingMap": {
+      "type": "object",
+      "propertyNames": { "$ref": "#/$defs/identifier" },
+      "additionalProperties": { "$ref": "#/$defs/bindingLiteral" }
+    },
+    "toolInputBindingMap": {
+      "type": "object",
+      "propertyNames": { "$ref": "#/$defs/fieldIdentifier" },
+      "additionalProperties": { "$ref": "#/$defs/bindingLiteral" }
+    },
+    "stateLiteralMap": {
+      "type": "object",
+      "propertyNames": { "$ref": "#/$defs/identifier" },
+      "additionalProperties": true
+    },
+    "enrichmentDef": {
+      "type": "object", "additionalProperties": false, "required": ["tool"],
+      "properties": {
+        "tool": { "$ref": "#/$defs/identifier" },
+        "optional": { "type": "boolean", "default": false, "description": "When true, a logged tool failure does not discard successfully resolved token mappings." },
+        "input": { "$ref": "#/$defs/toolInputBindingMap", "description": "Tool parameter -> literal or $token.path binding." },
+        "set": { "$ref": "#/$defs/stateBindingMap", "description": "State key -> literal or $result.path binding." }
+      }
+    }
+  }
+}