diff --git a/README.md b/README.md index e67f0db..2a05dd0 100644 --- a/README.md +++ b/README.md @@ -69,7 +69,7 @@ code per language — **pinned by the shared corpus**, not generated. See ## Versioning -- `schema_version` is a property of the **document** (currently `3`). Each +- `schema_version` is a property of the **document** (currently `4`). Each version gets its own `schema/flow.vN.schema.json` and its own frozen `conformance/vN/` corpus. Growth is additive; an unsupported version is rejected, never silently migrated. diff --git a/conformance/README.md b/conformance/README.md index a43e001..01bad02 100644 --- a/conformance/README.md +++ b/conformance/README.md @@ -28,6 +28,13 @@ of the outbound gate, which includes the base validation. These cases stay out of the top-level `valid/`/`invalid/` buckets because a flow refused for outbound — one with a `ring` step, say — is a perfectly good inbound flow. +`fill/` pins `fill` (flow variables): per case, `.input.yaml` (a v4 flow +that passes `validate_outbound`), `.values.json` (the caller's values), +and either `.expected.yaml` (the filled flow, compared after canonical +serialization) or `.expected.json` = `{"errors": [codes]}` (the exact +refusal). A filled flow is a `schema_version: 3` document: both suites also +check that it passes `validate_outbound` on its own and reads back as itself. + Every `.yaml` has a sibling `.expected.json`: ```json diff --git a/conformance/canonical/prompt-template.canonical.yaml b/conformance/canonical/prompt-template.canonical.yaml new file mode 100644 index 0000000..615e1ae --- /dev/null +++ b/conformance/canonical/prompt-template.canonical.yaml @@ -0,0 +1,10 @@ +schema_version: 4 +id: flow_template_canon +name: Voiced with defaults +variables: + name: { default: there } +entry: ask +nodes: + ask: + kind: hangup + prompt: { audio: vprompt_abc123, transcript: Hi there, template: "Hi {{name}}" } diff --git a/conformance/canonical/prompt-template.expected.json b/conformance/canonical/prompt-template.expected.json new file mode 100644 index 0000000..bec01ec --- /dev/null +++ b/conformance/canonical/prompt-template.expected.json @@ -0,0 +1,4 @@ +{ + "description": "An audio prompt that keeps its `template` writes it after `transcript` (`audio`, `transcript`, `template`), the schema property order.", + "comments": 0 +} diff --git a/conformance/canonical/prompt-template.input.yaml b/conformance/canonical/prompt-template.input.yaml new file mode 100644 index 0000000..5fcf391 --- /dev/null +++ b/conformance/canonical/prompt-template.input.yaml @@ -0,0 +1,10 @@ +schema_version: 4 +name: Voiced with defaults +id: flow_template_canon +entry: ask +variables: + name: { default: there } +nodes: + ask: + kind: hangup + prompt: { template: "Hi {{name}}", transcript: Hi there, audio: vprompt_abc123 } diff --git a/conformance/canonical/variables.canonical.yaml b/conformance/canonical/variables.canonical.yaml new file mode 100644 index 0000000..8837d90 --- /dev/null +++ b/conformance/canonical/variables.canonical.yaml @@ -0,0 +1,11 @@ +schema_version: 4 +id: flow_vars_canon +name: Ask a question +variables: + question: { description: The question, default: Ready?, max_len: 300 } + note_to_self: { default: "" } +entry: ask +nodes: + ask: + kind: hangup + prompt: "{{question}}" diff --git a/conformance/canonical/variables.expected.json b/conformance/canonical/variables.expected.json new file mode 100644 index 0000000..4287f02 --- /dev/null +++ b/conformance/canonical/variables.expected.json @@ -0,0 +1,4 @@ +{ + "description": "Top-level `variables` is written right after `note` and before `entry`, each variable in schema property order (`description`, `default`, `max_len`). A `max_len` equal to its default (200) is dropped; an empty `default` is a value, and it stays.", + "comments": 1 +} diff --git a/conformance/canonical/variables.input.yaml b/conformance/canonical/variables.input.yaml new file mode 100644 index 0000000..5b6950e --- /dev/null +++ b/conformance/canonical/variables.input.yaml @@ -0,0 +1,12 @@ +# Variables, written out of order and with defaults spelled out. +schema_version: 4 +name: Ask a question +id: flow_vars_canon +entry: ask +variables: + question: { max_len: 300, default: Ready?, description: The question } + note_to_self: { max_len: 200, default: "" } +nodes: + ask: + kind: hangup + prompt: "{{question}}" diff --git a/conformance/fill/all-options-dropped.expected.json b/conformance/fill/all-options-dropped.expected.json new file mode 100644 index 0000000..9b79fa0 --- /dev/null +++ b/conformance/fill/all-options-dropped.expected.json @@ -0,0 +1 @@ +{"errors":["menu_without_options"]} diff --git a/conformance/fill/all-options-dropped.input.yaml b/conformance/fill/all-options-dropped.input.yaml new file mode 100644 index 0000000..718dbf4 --- /dev/null +++ b/conformance/fill/all-options-dropped.input.yaml @@ -0,0 +1,16 @@ +schema_version: 4 +id: flow_all_options_dropped +name: Every option optional +entry: ask +variables: + option1: { description: Answer for key 1, default: "", max_len: 80 } + option2: { description: Answer for key 2, default: "", max_len: 80 } +nodes: + ask: + kind: menu + prompt: "Pick one.{{#option1}} Press 1 for {{option1}}.{{/option1}}{{#option2}} Press 2 for {{option2}}.{{/option2}}" + options: { "1": "{{option1}}", "2": "{{option2}}" } + exits: { "1": bye, "2": bye, no_input: bye, invalid: bye } + bye: + kind: hangup + prompt: Goodbye. diff --git a/conformance/fill/all-options-dropped.values.json b/conformance/fill/all-options-dropped.values.json new file mode 100644 index 0000000..0967ef4 --- /dev/null +++ b/conformance/fill/all-options-dropped.values.json @@ -0,0 +1 @@ +{} diff --git a/conformance/fill/audio-kept.expected.yaml b/conformance/fill/audio-kept.expected.yaml new file mode 100644 index 0000000..b96dbf5 --- /dev/null +++ b/conformance/fill/audio-kept.expected.yaml @@ -0,0 +1,8 @@ +schema_version: 3 +id: flow_audio +name: Audio template +entry: hi +nodes: + hi: + kind: hangup + prompt: { audio: vprompt_a } diff --git a/conformance/fill/audio-kept.input.yaml b/conformance/fill/audio-kept.input.yaml new file mode 100644 index 0000000..da6506e --- /dev/null +++ b/conformance/fill/audio-kept.input.yaml @@ -0,0 +1,10 @@ +schema_version: 4 +id: flow_audio +name: Audio template +entry: hi +variables: + name: { default: there } +nodes: + hi: + kind: hangup + prompt: { audio: vprompt_a, template: "Hi {{name}}" } diff --git a/conformance/fill/audio-kept.values.json b/conformance/fill/audio-kept.values.json new file mode 100644 index 0000000..0967ef4 --- /dev/null +++ b/conformance/fill/audio-kept.values.json @@ -0,0 +1 @@ +{} diff --git a/conformance/fill/audio-text.expected.yaml b/conformance/fill/audio-text.expected.yaml new file mode 100644 index 0000000..5be5bd6 --- /dev/null +++ b/conformance/fill/audio-text.expected.yaml @@ -0,0 +1,8 @@ +schema_version: 3 +id: flow_audio +name: Audio template +entry: hi +nodes: + hi: + kind: hangup + prompt: Hi Ann diff --git a/conformance/fill/audio-text.input.yaml b/conformance/fill/audio-text.input.yaml new file mode 100644 index 0000000..da6506e --- /dev/null +++ b/conformance/fill/audio-text.input.yaml @@ -0,0 +1,10 @@ +schema_version: 4 +id: flow_audio +name: Audio template +entry: hi +variables: + name: { default: there } +nodes: + hi: + kind: hangup + prompt: { audio: vprompt_a, template: "Hi {{name}}" } diff --git a/conformance/fill/audio-text.values.json b/conformance/fill/audio-text.values.json new file mode 100644 index 0000000..361d405 --- /dev/null +++ b/conformance/fill/audio-text.values.json @@ -0,0 +1 @@ +{"name":"Ann"} diff --git a/conformance/fill/blank-unicode.expected.yaml b/conformance/fill/blank-unicode.expected.yaml new file mode 100644 index 0000000..e19c786 --- /dev/null +++ b/conformance/fill/blank-unicode.expected.yaml @@ -0,0 +1,18 @@ +schema_version: 3 +id: flow_ask_question +name: Ask a question +entry: ask +nodes: + ask: + kind: menu + prompt: "Claude has a question. Claude needs your input on screen. Press 1 for Yes. Press 2 for No. Press 9 to hear this again." + options: { "1": "Yes", "2": "No", "9": Repeat } + retries: 2 + timeout_secs: 8 + exits: { "1": thanks, "2": thanks, "9": ask, no_input: bye, invalid: bye } + thanks: + kind: hangup + prompt: Got it, thanks. Goodbye. + bye: + kind: hangup + prompt: No answer recorded. The question will wait on screen. Goodbye. diff --git a/conformance/fill/blank-unicode.input.yaml b/conformance/fill/blank-unicode.input.yaml new file mode 100644 index 0000000..41dd236 --- /dev/null +++ b/conformance/fill/blank-unicode.input.yaml @@ -0,0 +1,25 @@ +schema_version: 4 +id: flow_ask_question +name: Ask a question +entry: ask +variables: + intro: { description: Who is asking, default: "Claude has a question." , max_len: 120 } + question: { description: The question, default: "Claude needs your input on screen.", max_len: 300 } + option1: { description: Answer for key 1, default: "Yes", max_len: 80 } + option2: { description: Answer for key 2, default: "No", max_len: 80 } + option3: { description: Answer for key 3, default: "", max_len: 80 } + option4: { description: Answer for key 4, default: "", max_len: 80 } +nodes: + ask: + kind: menu + prompt: "{{intro}} {{question}} Press 1 for {{option1}}. Press 2 for {{option2}}.{{#option3}} Press 3 for {{option3}}.{{/option3}}{{#option4}} Press 4 for {{option4}}.{{/option4}} Press 9 to hear this again." + options: { "1": "{{option1}}", "2": "{{option2}}", "3": "{{option3}}", "4": "{{option4}}", "9": Repeat } + retries: 2 + timeout_secs: 8 + exits: { "1": thanks, "2": thanks, "3": thanks, "4": thanks, "9": ask, no_input: bye, invalid: bye } + thanks: + kind: hangup + prompt: Got it, thanks. Goodbye. + bye: + kind: hangup + prompt: No answer recorded. The question will wait on screen. Goodbye. diff --git a/conformance/fill/blank-unicode.values.json b/conformance/fill/blank-unicode.values.json new file mode 100644 index 0000000..05e62cf --- /dev/null +++ b/conformance/fill/blank-unicode.values.json @@ -0,0 +1 @@ +{"question":"\ufeff \u0085\u00a0\u2003"} diff --git a/conformance/fill/defaults.expected.yaml b/conformance/fill/defaults.expected.yaml new file mode 100644 index 0000000..e19c786 --- /dev/null +++ b/conformance/fill/defaults.expected.yaml @@ -0,0 +1,18 @@ +schema_version: 3 +id: flow_ask_question +name: Ask a question +entry: ask +nodes: + ask: + kind: menu + prompt: "Claude has a question. Claude needs your input on screen. Press 1 for Yes. Press 2 for No. Press 9 to hear this again." + options: { "1": "Yes", "2": "No", "9": Repeat } + retries: 2 + timeout_secs: 8 + exits: { "1": thanks, "2": thanks, "9": ask, no_input: bye, invalid: bye } + thanks: + kind: hangup + prompt: Got it, thanks. Goodbye. + bye: + kind: hangup + prompt: No answer recorded. The question will wait on screen. Goodbye. diff --git a/conformance/fill/defaults.input.yaml b/conformance/fill/defaults.input.yaml new file mode 100644 index 0000000..41dd236 --- /dev/null +++ b/conformance/fill/defaults.input.yaml @@ -0,0 +1,25 @@ +schema_version: 4 +id: flow_ask_question +name: Ask a question +entry: ask +variables: + intro: { description: Who is asking, default: "Claude has a question." , max_len: 120 } + question: { description: The question, default: "Claude needs your input on screen.", max_len: 300 } + option1: { description: Answer for key 1, default: "Yes", max_len: 80 } + option2: { description: Answer for key 2, default: "No", max_len: 80 } + option3: { description: Answer for key 3, default: "", max_len: 80 } + option4: { description: Answer for key 4, default: "", max_len: 80 } +nodes: + ask: + kind: menu + prompt: "{{intro}} {{question}} Press 1 for {{option1}}. Press 2 for {{option2}}.{{#option3}} Press 3 for {{option3}}.{{/option3}}{{#option4}} Press 4 for {{option4}}.{{/option4}} Press 9 to hear this again." + options: { "1": "{{option1}}", "2": "{{option2}}", "3": "{{option3}}", "4": "{{option4}}", "9": Repeat } + retries: 2 + timeout_secs: 8 + exits: { "1": thanks, "2": thanks, "3": thanks, "4": thanks, "9": ask, no_input: bye, invalid: bye } + thanks: + kind: hangup + prompt: Got it, thanks. Goodbye. + bye: + kind: hangup + prompt: No answer recorded. The question will wait on screen. Goodbye. diff --git a/conformance/fill/defaults.values.json b/conformance/fill/defaults.values.json new file mode 100644 index 0000000..0967ef4 --- /dev/null +++ b/conformance/fill/defaults.values.json @@ -0,0 +1 @@ +{} diff --git a/conformance/fill/dropped-option-only-path.expected.yaml b/conformance/fill/dropped-option-only-path.expected.yaml new file mode 100644 index 0000000..29773dd --- /dev/null +++ b/conformance/fill/dropped-option-only-path.expected.yaml @@ -0,0 +1,13 @@ +schema_version: 3 +id: flow_dropped_path +name: An option with its own ending +entry: ask +nodes: + ask: + kind: menu + prompt: "Press 1 for yes. Press 2 for no." + options: { "1": "Yes", "2": "No" } + exits: { "1": thanks, "2": thanks, no_input: thanks, invalid: thanks } + thanks: + kind: hangup + prompt: Thanks. Goodbye. diff --git a/conformance/fill/dropped-option-only-path.input.yaml b/conformance/fill/dropped-option-only-path.input.yaml new file mode 100644 index 0000000..c9701c6 --- /dev/null +++ b/conformance/fill/dropped-option-only-path.input.yaml @@ -0,0 +1,18 @@ +schema_version: 4 +id: flow_dropped_path +name: An option with its own ending +entry: ask +variables: + option3: { description: Answer for key 3, default: "", max_len: 80 } +nodes: + ask: + kind: menu + prompt: "Press 1 for yes. Press 2 for no.{{#option3}} Press 3 for {{option3}}.{{/option3}}" + options: { "1": "Yes", "2": "No", "3": "{{option3}}" } + exits: { "1": thanks, "2": thanks, "3": only3, no_input: thanks, invalid: thanks } + only3: + kind: hangup + prompt: You picked the third answer. Goodbye. + thanks: + kind: hangup + prompt: Thanks. Goodbye. diff --git a/conformance/fill/dropped-option-only-path.values.json b/conformance/fill/dropped-option-only-path.values.json new file mode 100644 index 0000000..0967ef4 --- /dev/null +++ b/conformance/fill/dropped-option-only-path.values.json @@ -0,0 +1 @@ +{} diff --git a/conformance/fill/option3.expected.yaml b/conformance/fill/option3.expected.yaml new file mode 100644 index 0000000..662c274 --- /dev/null +++ b/conformance/fill/option3.expected.yaml @@ -0,0 +1,18 @@ +schema_version: 3 +id: flow_ask_question +name: Ask a question +entry: ask +nodes: + ask: + kind: menu + prompt: "Claude has a question. Claude needs your input on screen. Press 1 for Yes. Press 2 for No. Press 3 for Both. Press 9 to hear this again." + options: { "1": "Yes", "2": "No", "3": Both, "9": Repeat } + retries: 2 + timeout_secs: 8 + exits: { "1": thanks, "2": thanks, "3": thanks, "9": ask, no_input: bye, invalid: bye } + thanks: + kind: hangup + prompt: Got it, thanks. Goodbye. + bye: + kind: hangup + prompt: No answer recorded. The question will wait on screen. Goodbye. diff --git a/conformance/fill/option3.input.yaml b/conformance/fill/option3.input.yaml new file mode 100644 index 0000000..41dd236 --- /dev/null +++ b/conformance/fill/option3.input.yaml @@ -0,0 +1,25 @@ +schema_version: 4 +id: flow_ask_question +name: Ask a question +entry: ask +variables: + intro: { description: Who is asking, default: "Claude has a question." , max_len: 120 } + question: { description: The question, default: "Claude needs your input on screen.", max_len: 300 } + option1: { description: Answer for key 1, default: "Yes", max_len: 80 } + option2: { description: Answer for key 2, default: "No", max_len: 80 } + option3: { description: Answer for key 3, default: "", max_len: 80 } + option4: { description: Answer for key 4, default: "", max_len: 80 } +nodes: + ask: + kind: menu + prompt: "{{intro}} {{question}} Press 1 for {{option1}}. Press 2 for {{option2}}.{{#option3}} Press 3 for {{option3}}.{{/option3}}{{#option4}} Press 4 for {{option4}}.{{/option4}} Press 9 to hear this again." + options: { "1": "{{option1}}", "2": "{{option2}}", "3": "{{option3}}", "4": "{{option4}}", "9": Repeat } + retries: 2 + timeout_secs: 8 + exits: { "1": thanks, "2": thanks, "3": thanks, "4": thanks, "9": ask, no_input: bye, invalid: bye } + thanks: + kind: hangup + prompt: Got it, thanks. Goodbye. + bye: + kind: hangup + prompt: No answer recorded. The question will wait on screen. Goodbye. diff --git a/conformance/fill/option3.values.json b/conformance/fill/option3.values.json new file mode 100644 index 0000000..751a63d --- /dev/null +++ b/conformance/fill/option3.values.json @@ -0,0 +1 @@ +{"option3":"Both"} diff --git a/conformance/fill/prompt-too-long.expected.json b/conformance/fill/prompt-too-long.expected.json new file mode 100644 index 0000000..ae7cce0 --- /dev/null +++ b/conformance/fill/prompt-too-long.expected.json @@ -0,0 +1 @@ +{"errors":["prompt_too_long"]} diff --git a/conformance/fill/prompt-too-long.input.yaml b/conformance/fill/prompt-too-long.input.yaml new file mode 100644 index 0000000..cb1f66a --- /dev/null +++ b/conformance/fill/prompt-too-long.input.yaml @@ -0,0 +1,10 @@ +schema_version: 4 +id: flow_prompt_too_long +name: A prompt that grows past the limit +entry: say +variables: + detail: { description: Read out five times, default: "", max_len: 500 } +nodes: + say: + kind: hangup + prompt: "{{detail}} {{detail}} {{detail}} {{detail}} {{detail}}" diff --git a/conformance/fill/prompt-too-long.values.json b/conformance/fill/prompt-too-long.values.json new file mode 100644 index 0000000..f7ee735 --- /dev/null +++ b/conformance/fill/prompt-too-long.values.json @@ -0,0 +1 @@ +{"detail": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"} diff --git a/conformance/fill/too-long.expected.json b/conformance/fill/too-long.expected.json new file mode 100644 index 0000000..eb02174 --- /dev/null +++ b/conformance/fill/too-long.expected.json @@ -0,0 +1 @@ +{"errors":["variable_too_long"]} diff --git a/conformance/fill/too-long.input.yaml b/conformance/fill/too-long.input.yaml new file mode 100644 index 0000000..41dd236 --- /dev/null +++ b/conformance/fill/too-long.input.yaml @@ -0,0 +1,25 @@ +schema_version: 4 +id: flow_ask_question +name: Ask a question +entry: ask +variables: + intro: { description: Who is asking, default: "Claude has a question." , max_len: 120 } + question: { description: The question, default: "Claude needs your input on screen.", max_len: 300 } + option1: { description: Answer for key 1, default: "Yes", max_len: 80 } + option2: { description: Answer for key 2, default: "No", max_len: 80 } + option3: { description: Answer for key 3, default: "", max_len: 80 } + option4: { description: Answer for key 4, default: "", max_len: 80 } +nodes: + ask: + kind: menu + prompt: "{{intro}} {{question}} Press 1 for {{option1}}. Press 2 for {{option2}}.{{#option3}} Press 3 for {{option3}}.{{/option3}}{{#option4}} Press 4 for {{option4}}.{{/option4}} Press 9 to hear this again." + options: { "1": "{{option1}}", "2": "{{option2}}", "3": "{{option3}}", "4": "{{option4}}", "9": Repeat } + retries: 2 + timeout_secs: 8 + exits: { "1": thanks, "2": thanks, "3": thanks, "4": thanks, "9": ask, no_input: bye, invalid: bye } + thanks: + kind: hangup + prompt: Got it, thanks. Goodbye. + bye: + kind: hangup + prompt: No answer recorded. The question will wait on screen. Goodbye. diff --git a/conformance/fill/too-long.values.json b/conformance/fill/too-long.values.json new file mode 100644 index 0000000..473f628 --- /dev/null +++ b/conformance/fill/too-long.values.json @@ -0,0 +1 @@ +{"question": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"} diff --git a/conformance/fill/two-options.expected.yaml b/conformance/fill/two-options.expected.yaml new file mode 100644 index 0000000..f572165 --- /dev/null +++ b/conformance/fill/two-options.expected.yaml @@ -0,0 +1,18 @@ +schema_version: 3 +id: flow_ask_question +name: Ask a question +entry: ask +nodes: + ask: + kind: menu + prompt: "Claude has a question. Which database? Press 1 for Postgres. Press 2 for SQLite. Press 9 to hear this again." + options: { "1": Postgres, "2": SQLite, "9": Repeat } + retries: 2 + timeout_secs: 8 + exits: { "1": thanks, "2": thanks, "9": ask, no_input: bye, invalid: bye } + thanks: + kind: hangup + prompt: Got it, thanks. Goodbye. + bye: + kind: hangup + prompt: No answer recorded. The question will wait on screen. Goodbye. diff --git a/conformance/fill/two-options.input.yaml b/conformance/fill/two-options.input.yaml new file mode 100644 index 0000000..41dd236 --- /dev/null +++ b/conformance/fill/two-options.input.yaml @@ -0,0 +1,25 @@ +schema_version: 4 +id: flow_ask_question +name: Ask a question +entry: ask +variables: + intro: { description: Who is asking, default: "Claude has a question." , max_len: 120 } + question: { description: The question, default: "Claude needs your input on screen.", max_len: 300 } + option1: { description: Answer for key 1, default: "Yes", max_len: 80 } + option2: { description: Answer for key 2, default: "No", max_len: 80 } + option3: { description: Answer for key 3, default: "", max_len: 80 } + option4: { description: Answer for key 4, default: "", max_len: 80 } +nodes: + ask: + kind: menu + prompt: "{{intro}} {{question}} Press 1 for {{option1}}. Press 2 for {{option2}}.{{#option3}} Press 3 for {{option3}}.{{/option3}}{{#option4}} Press 4 for {{option4}}.{{/option4}} Press 9 to hear this again." + options: { "1": "{{option1}}", "2": "{{option2}}", "3": "{{option3}}", "4": "{{option4}}", "9": Repeat } + retries: 2 + timeout_secs: 8 + exits: { "1": thanks, "2": thanks, "3": thanks, "4": thanks, "9": ask, no_input: bye, invalid: bye } + thanks: + kind: hangup + prompt: Got it, thanks. Goodbye. + bye: + kind: hangup + prompt: No answer recorded. The question will wait on screen. Goodbye. diff --git a/conformance/fill/two-options.values.json b/conformance/fill/two-options.values.json new file mode 100644 index 0000000..e9b8f5b --- /dev/null +++ b/conformance/fill/two-options.values.json @@ -0,0 +1 @@ +{"question":"Which database?","option1":"Postgres","option2":"SQLite"} diff --git a/conformance/fill/unknown-variable.expected.json b/conformance/fill/unknown-variable.expected.json new file mode 100644 index 0000000..d8d8aa6 --- /dev/null +++ b/conformance/fill/unknown-variable.expected.json @@ -0,0 +1 @@ +{"errors":["variable_unknown"]} diff --git a/conformance/fill/unknown-variable.input.yaml b/conformance/fill/unknown-variable.input.yaml new file mode 100644 index 0000000..41dd236 --- /dev/null +++ b/conformance/fill/unknown-variable.input.yaml @@ -0,0 +1,25 @@ +schema_version: 4 +id: flow_ask_question +name: Ask a question +entry: ask +variables: + intro: { description: Who is asking, default: "Claude has a question." , max_len: 120 } + question: { description: The question, default: "Claude needs your input on screen.", max_len: 300 } + option1: { description: Answer for key 1, default: "Yes", max_len: 80 } + option2: { description: Answer for key 2, default: "No", max_len: 80 } + option3: { description: Answer for key 3, default: "", max_len: 80 } + option4: { description: Answer for key 4, default: "", max_len: 80 } +nodes: + ask: + kind: menu + prompt: "{{intro}} {{question}} Press 1 for {{option1}}. Press 2 for {{option2}}.{{#option3}} Press 3 for {{option3}}.{{/option3}}{{#option4}} Press 4 for {{option4}}.{{/option4}} Press 9 to hear this again." + options: { "1": "{{option1}}", "2": "{{option2}}", "3": "{{option3}}", "4": "{{option4}}", "9": Repeat } + retries: 2 + timeout_secs: 8 + exits: { "1": thanks, "2": thanks, "3": thanks, "4": thanks, "9": ask, no_input: bye, invalid: bye } + thanks: + kind: hangup + prompt: Got it, thanks. Goodbye. + bye: + kind: hangup + prompt: No answer recorded. The question will wait on screen. Goodbye. diff --git a/conformance/fill/unknown-variable.values.json b/conformance/fill/unknown-variable.values.json new file mode 100644 index 0000000..a6e7a62 --- /dev/null +++ b/conformance/fill/unknown-variable.values.json @@ -0,0 +1 @@ +{"colour":"red"} diff --git a/conformance/fill/value-with-braces.expected.yaml b/conformance/fill/value-with-braces.expected.yaml new file mode 100644 index 0000000..141834a --- /dev/null +++ b/conformance/fill/value-with-braces.expected.yaml @@ -0,0 +1,18 @@ +schema_version: 3 +id: flow_ask_question +name: Ask a question +entry: ask +nodes: + ask: + kind: menu + prompt: "Claude has a question. Is {{option1}} a {x}? Press 1 for Yes. Press 2 for No. Press 9 to hear this again." + options: { "1": "Yes", "2": "No", "9": Repeat } + retries: 2 + timeout_secs: 8 + exits: { "1": thanks, "2": thanks, "9": ask, no_input: bye, invalid: bye } + thanks: + kind: hangup + prompt: Got it, thanks. Goodbye. + bye: + kind: hangup + prompt: No answer recorded. The question will wait on screen. Goodbye. diff --git a/conformance/fill/value-with-braces.input.yaml b/conformance/fill/value-with-braces.input.yaml new file mode 100644 index 0000000..41dd236 --- /dev/null +++ b/conformance/fill/value-with-braces.input.yaml @@ -0,0 +1,25 @@ +schema_version: 4 +id: flow_ask_question +name: Ask a question +entry: ask +variables: + intro: { description: Who is asking, default: "Claude has a question." , max_len: 120 } + question: { description: The question, default: "Claude needs your input on screen.", max_len: 300 } + option1: { description: Answer for key 1, default: "Yes", max_len: 80 } + option2: { description: Answer for key 2, default: "No", max_len: 80 } + option3: { description: Answer for key 3, default: "", max_len: 80 } + option4: { description: Answer for key 4, default: "", max_len: 80 } +nodes: + ask: + kind: menu + prompt: "{{intro}} {{question}} Press 1 for {{option1}}. Press 2 for {{option2}}.{{#option3}} Press 3 for {{option3}}.{{/option3}}{{#option4}} Press 4 for {{option4}}.{{/option4}} Press 9 to hear this again." + options: { "1": "{{option1}}", "2": "{{option2}}", "3": "{{option3}}", "4": "{{option4}}", "9": Repeat } + retries: 2 + timeout_secs: 8 + exits: { "1": thanks, "2": thanks, "3": thanks, "4": thanks, "9": ask, no_input: bye, invalid: bye } + thanks: + kind: hangup + prompt: Got it, thanks. Goodbye. + bye: + kind: hangup + prompt: No answer recorded. The question will wait on screen. Goodbye. diff --git a/conformance/fill/value-with-braces.values.json b/conformance/fill/value-with-braces.values.json new file mode 100644 index 0000000..3ddf43a --- /dev/null +++ b/conformance/fill/value-with-braces.values.json @@ -0,0 +1 @@ +{"question":"Is {{option1}} a {x}?"} diff --git a/conformance/v3/invalid/template-in-v3.expected.json b/conformance/v3/invalid/template-in-v3.expected.json new file mode 100644 index 0000000..6d0b0bd --- /dev/null +++ b/conformance/v3/invalid/template-in-v3.expected.json @@ -0,0 +1,5 @@ +{ + "description": "A version 3 document may not give an audio prompt a `template`: an older engine would ignore it and play the clip with the defaults it was voiced from, so the field needs the version that has it.", + "structurallyValid": true, + "semantic": { "ok": false, "errors": ["field_requires_newer_schema"] } +} diff --git a/conformance/v3/invalid/template-in-v3.yaml b/conformance/v3/invalid/template-in-v3.yaml new file mode 100644 index 0000000..33d4679 --- /dev/null +++ b/conformance/v3/invalid/template-in-v3.yaml @@ -0,0 +1,12 @@ +schema_version: 3 +id: flow_template_in_v3 +name: Template in a version 3 document +entry: ask +nodes: + ask: + kind: greeting + prompt: { audio: vprompt_abc123, template: "Hi {{name}}" } + exits: { next: bye } + bye: + kind: hangup + prompt: Goodbye. diff --git a/conformance/v3/invalid/variables-in-v3.expected.json b/conformance/v3/invalid/variables-in-v3.expected.json new file mode 100644 index 0000000..be405ec --- /dev/null +++ b/conformance/v3/invalid/variables-in-v3.expected.json @@ -0,0 +1,5 @@ +{ + "description": "A version 3 document may not declare `variables`: an engine that only knows version 3 would ignore them and speak the `{{name}}` placeholders as written, so the field needs the version that has it. The declaration is itself valid structurally; only the version rule refuses it.", + "structurallyValid": true, + "semantic": { "ok": false, "errors": ["field_requires_newer_schema"] } +} diff --git a/conformance/v3/invalid/variables-in-v3.yaml b/conformance/v3/invalid/variables-in-v3.yaml new file mode 100644 index 0000000..13e767e --- /dev/null +++ b/conformance/v3/invalid/variables-in-v3.yaml @@ -0,0 +1,25 @@ +schema_version: 3 +id: flow_variables_in_v3 +name: Ask a question +entry: ask +variables: + intro: { description: Who is asking, default: "Claude has a question." , max_len: 120 } + question: { description: The question, default: "Claude needs your input on screen.", max_len: 300 } + option1: { description: Answer for key 1, default: "Yes", max_len: 80 } + option2: { description: Answer for key 2, default: "No", max_len: 80 } + option3: { description: Answer for key 3, default: "", max_len: 80 } + option4: { description: Answer for key 4, default: "", max_len: 80 } +nodes: + ask: + kind: menu + prompt: "{{intro}} {{question}} Press 1 for {{option1}}. Press 2 for {{option2}}.{{#option3}} Press 3 for {{option3}}.{{/option3}}{{#option4}} Press 4 for {{option4}}.{{/option4}} Press 9 to hear this again." + options: { "1": "{{option1}}", "2": "{{option2}}", "3": "{{option3}}", "4": "{{option4}}", "9": Repeat } + retries: 2 + timeout_secs: 8 + exits: { "1": thanks, "2": thanks, "3": thanks, "4": thanks, "9": ask, no_input: bye, invalid: bye } + thanks: + kind: hangup + prompt: Got it, thanks. Goodbye. + bye: + kind: hangup + prompt: No answer recorded. The question will wait on screen. Goodbye. diff --git a/conformance/v3/valid/braces-in-prompt.expected.json b/conformance/v3/valid/braces-in-prompt.expected.json new file mode 100644 index 0000000..f8f9d79 --- /dev/null +++ b/conformance/v3/valid/braces-in-prompt.expected.json @@ -0,0 +1,5 @@ +{ + "description": "Before version 4 a `{{` in a prompt is ordinary text, spoken as written. Existing flows that happen to contain braces keep working.", + "structurallyValid": true, + "semantic": { "ok": true, "errors": [] } +} diff --git a/conformance/v3/valid/braces-in-prompt.yaml b/conformance/v3/valid/braces-in-prompt.yaml new file mode 100644 index 0000000..0d36ce9 --- /dev/null +++ b/conformance/v3/valid/braces-in-prompt.yaml @@ -0,0 +1,12 @@ +schema_version: 3 +id: flow_braces +name: Braces are just text +entry: say +nodes: + say: + kind: greeting + prompt: "Press {{1}} now, or {{ stay on the line }}." + exits: { next: bye } + bye: + kind: hangup + prompt: Goodbye. diff --git a/conformance/v3/valid/empty-variables.expected.json b/conformance/v3/valid/empty-variables.expected.json new file mode 100644 index 0000000..126f8a6 --- /dev/null +++ b/conformance/v3/valid/empty-variables.expected.json @@ -0,0 +1,5 @@ +{ + "description": "An empty `variables` map declares nothing, so it is the same as no map: a version 3 document may carry it. Only a non-empty map needs version 4.", + "structurallyValid": true, + "semantic": { "ok": true, "errors": [] } +} diff --git a/conformance/v3/valid/empty-variables.yaml b/conformance/v3/valid/empty-variables.yaml new file mode 100644 index 0000000..529f00d --- /dev/null +++ b/conformance/v3/valid/empty-variables.yaml @@ -0,0 +1,8 @@ +schema_version: 3 +id: flow_empty_vars +name: Empty variables in version 3 +entry: bye +variables: {} +nodes: + bye: + kind: hangup diff --git a/conformance/v4/invalid/placeholder-in-transfer-target.expected.json b/conformance/v4/invalid/placeholder-in-transfer-target.expected.json new file mode 100644 index 0000000..0f30cd3 --- /dev/null +++ b/conformance/v4/invalid/placeholder-in-transfer-target.expected.json @@ -0,0 +1,5 @@ +{ + "description": "Placeholders are only for a prompt, an audio prompt's template and a menu label. A transfer target is never filled in, so a `{{` there is refused rather than dialled.", + "structurallyValid": true, + "semantic": { "ok": false, "errors": ["placeholder_not_allowed"] } +} diff --git a/conformance/v4/invalid/placeholder-in-transfer-target.yaml b/conformance/v4/invalid/placeholder-in-transfer-target.yaml new file mode 100644 index 0000000..717c881 --- /dev/null +++ b/conformance/v4/invalid/placeholder-in-transfer-target.yaml @@ -0,0 +1,10 @@ +schema_version: 4 +id: flow_placeholder_target +name: Placeholder in a phone number +entry: go +variables: + number: { description: Who to ring, default: "+6491234567", max_len: 20 } +nodes: + go: + kind: transfer + target: "{{number}}" diff --git a/conformance/v4/invalid/unknown-variable.expected.json b/conformance/v4/invalid/unknown-variable.expected.json new file mode 100644 index 0000000..e68c671 --- /dev/null +++ b/conformance/v4/invalid/unknown-variable.expected.json @@ -0,0 +1,5 @@ +{ + "description": "A `{{name}}` placeholder must name a variable the flow declares; otherwise the call would speak the braces or nothing. Unknown names are refused.", + "structurallyValid": true, + "semantic": { "ok": false, "errors": ["unknown_variable"] } +} diff --git a/conformance/v4/invalid/unknown-variable.yaml b/conformance/v4/invalid/unknown-variable.yaml new file mode 100644 index 0000000..7763fc2 --- /dev/null +++ b/conformance/v4/invalid/unknown-variable.yaml @@ -0,0 +1,14 @@ +schema_version: 4 +id: flow_unknown_variable +name: Placeholder with no variable +entry: ask +variables: + question: { description: The question, default: "Anything?", max_len: 100 } +nodes: + ask: + kind: greeting + prompt: "{{question}} Also {{ghost}}." + exits: { next: bye } + bye: + kind: hangup + prompt: Goodbye. diff --git a/conformance/v4/invalid/variable-default-too-long.expected.json b/conformance/v4/invalid/variable-default-too-long.expected.json new file mode 100644 index 0000000..789960d --- /dev/null +++ b/conformance/v4/invalid/variable-default-too-long.expected.json @@ -0,0 +1,5 @@ +{ + "description": "A variable's `default` is held to its own `max_len`, counted in characters like a caller's value. A default that would itself be refused as a value is refused when the flow is checked, not first noticed on a call.", + "structurallyValid": true, + "semantic": { "ok": false, "errors": ["variable_default_too_long"] } +} diff --git a/conformance/v4/invalid/variable-default-too-long.yaml b/conformance/v4/invalid/variable-default-too-long.yaml new file mode 100644 index 0000000..c450fa4 --- /dev/null +++ b/conformance/v4/invalid/variable-default-too-long.yaml @@ -0,0 +1,10 @@ +schema_version: 4 +id: flow_default_too_long +name: Default longer than its limit +entry: bye +variables: + question: { description: The question, default: "Is this too long?", max_len: 10 } +nodes: + bye: + kind: hangup + prompt: "{{question}}" diff --git a/conformance/v4/invalid/variable-without-default.expected.json b/conformance/v4/invalid/variable-without-default.expected.json new file mode 100644 index 0000000..d7c29f6 --- /dev/null +++ b/conformance/v4/invalid/variable-without-default.expected.json @@ -0,0 +1,5 @@ +{ + "description": "Every variable declares a `default`, so a flow called with no values still plays. A variable without one is refused at the shape level; the default may be an empty string.", + "structurallyValid": false, + "semantic": { "ok": false, "errors": [] } +} diff --git a/conformance/v4/invalid/variable-without-default.yaml b/conformance/v4/invalid/variable-without-default.yaml new file mode 100644 index 0000000..4f579de --- /dev/null +++ b/conformance/v4/invalid/variable-without-default.yaml @@ -0,0 +1,10 @@ +schema_version: 4 +id: flow_var_no_default +name: Variable with no default +entry: bye +variables: + question: { description: The question, max_len: 300 } +nodes: + bye: + kind: hangup + prompt: "{{question}}" diff --git a/conformance/v4/valid/ask-question.expected.json b/conformance/v4/valid/ask-question.expected.json new file mode 100644 index 0000000..7bc8b1b --- /dev/null +++ b/conformance/v4/valid/ask-question.expected.json @@ -0,0 +1,5 @@ +{ + "description": "Flow variables: a top-level `variables` map declares details filled per call. The prompt and menu labels use `{{name}}` placeholders and `{{#name}}…{{/name}}` blocks, and each one names a declared variable, so the flow is accepted. The empty defaults of option3 and option4 make those keys optional: filled with no values, their blocks are dropped from the prompt and their bare `{{option3}}`/`{{option4}}` labels remove the options and their exits. The 9 key loops back to the same menu, which waits for a key and so is not an unbounded loop.", + "structurallyValid": true, + "semantic": { "ok": true, "errors": [] } +} diff --git a/conformance/v4/valid/ask-question.yaml b/conformance/v4/valid/ask-question.yaml new file mode 100644 index 0000000..41dd236 --- /dev/null +++ b/conformance/v4/valid/ask-question.yaml @@ -0,0 +1,25 @@ +schema_version: 4 +id: flow_ask_question +name: Ask a question +entry: ask +variables: + intro: { description: Who is asking, default: "Claude has a question." , max_len: 120 } + question: { description: The question, default: "Claude needs your input on screen.", max_len: 300 } + option1: { description: Answer for key 1, default: "Yes", max_len: 80 } + option2: { description: Answer for key 2, default: "No", max_len: 80 } + option3: { description: Answer for key 3, default: "", max_len: 80 } + option4: { description: Answer for key 4, default: "", max_len: 80 } +nodes: + ask: + kind: menu + prompt: "{{intro}} {{question}} Press 1 for {{option1}}. Press 2 for {{option2}}.{{#option3}} Press 3 for {{option3}}.{{/option3}}{{#option4}} Press 4 for {{option4}}.{{/option4}} Press 9 to hear this again." + options: { "1": "{{option1}}", "2": "{{option2}}", "3": "{{option3}}", "4": "{{option4}}", "9": Repeat } + retries: 2 + timeout_secs: 8 + exits: { "1": thanks, "2": thanks, "3": thanks, "4": thanks, "9": ask, no_input: bye, invalid: bye } + thanks: + kind: hangup + prompt: Got it, thanks. Goodbye. + bye: + kind: hangup + prompt: No answer recorded. The question will wait on screen. Goodbye. diff --git a/conformance/v4/valid/placeholder-in-note.expected.json b/conformance/v4/valid/placeholder-in-note.expected.json new file mode 100644 index 0000000..bfbf23a --- /dev/null +++ b/conformance/v4/valid/placeholder-in-note.expected.json @@ -0,0 +1,5 @@ +{ + "description": "A `note` is a comment for people and is never read by the engine, so it is never scanned for placeholders: a `{{q}}` there, declared or not, and even a malformed `{{#`, changes no verdict. This holds for the flow's top-level note and for every step's note.", + "structurallyValid": true, + "semantic": { "ok": true, "errors": [] } +} diff --git a/conformance/v4/valid/placeholder-in-note.yaml b/conformance/v4/valid/placeholder-in-note.yaml new file mode 100644 index 0000000..1d64136 --- /dev/null +++ b/conformance/v4/valid/placeholder-in-note.yaml @@ -0,0 +1,17 @@ +schema_version: 4 +id: flow_placeholder_note +name: Placeholders in notes +note: "Fill {{question}} per call; {{q}} is not a variable, and {{#half open is fine here." +entry: ask +variables: + question: { description: The question, default: "Anything?", max_len: 100 } +nodes: + ask: + kind: greeting + note: "Speaks {{question}}. {{q}} in a note is never read." + prompt: "{{question}}" + exits: { next: bye } + bye: + kind: hangup + note: "{{q}}" + prompt: Goodbye. diff --git a/conformance/v4/valid/rendered-template-prompt.expected.json b/conformance/v4/valid/rendered-template-prompt.expected.json new file mode 100644 index 0000000..ee96e34 --- /dev/null +++ b/conformance/v4/valid/rendered-template-prompt.expected.json @@ -0,0 +1,6 @@ +{ + "description": "An audio prompt may keep the `template` it was voiced from, so a call that overrides a variable can speak the filled text instead of the clip. The clip is a required asset as ever; its placeholders are checked like a text prompt's, so `{{name}}` must be declared. A reader that does not fill ignores `template` and plays the clip.", + "structurallyValid": true, + "semantic": { "ok": true, "errors": [] }, + "requiredAssets": ["vprompt_abc123"] +} diff --git a/conformance/v4/valid/rendered-template-prompt.yaml b/conformance/v4/valid/rendered-template-prompt.yaml new file mode 100644 index 0000000..b412b12 --- /dev/null +++ b/conformance/v4/valid/rendered-template-prompt.yaml @@ -0,0 +1,14 @@ +schema_version: 4 +id: flow_rendered_template +name: A prompt voiced with its defaults +entry: ask +variables: + name: { description: Who is called, default: "there", max_len: 40 } +nodes: + ask: + kind: greeting + prompt: { audio: vprompt_abc123, template: "Hi {{name}}" } + exits: { next: bye } + bye: + kind: hangup + prompt: Goodbye. diff --git a/crates/compat-old-readers/tests/old_readers.rs b/crates/compat-old-readers/tests/old_readers.rs index 41330a3..ac80858 100644 --- a/crates/compat-old-readers/tests/old_readers.rs +++ b/crates/compat-old-readers/tests/old_readers.rs @@ -168,3 +168,33 @@ fn old_reader_refuses_a_screened_transfer_rather_than_run_it_blind() { wavekat_flow::validate::validate(&wavekat_flow::Flow::from_yaml(&yaml).unwrap()).is_ok() ); } + +#[test] +fn old_reader_refuses_a_flow_with_variables_rather_than_speak_the_braces() { + // `variables` is what gives a `{{name}}` placeholder its meaning. A + // reader that does not know it would speak the braces as written, so + // the document declares version 4 and the old reader must refuse it + // with an error. A panic would take the daemon down with it, so every + // v4 document is read inside `catch_unwind`. + for name in [ + "ask-question", + "rendered-template-prompt", + "placeholder-in-note", + ] { + let yaml = fs::read_to_string(corpus().join(format!("v4/valid/{name}.yaml"))).unwrap(); + assert!( + !old_flow::SUPPORTED_SCHEMA_VERSIONS.contains(&schema_version(&yaml)), + "{OLDEST_READER} claims to read version 4" + ); + let refused = std::panic::catch_unwind(|| match old_flow::Flow::from_yaml(&yaml) { + Err(_) => true, + Ok(old) => old_validate(&old).is_err(), + }) + .unwrap_or_else(|_| panic!("{OLDEST_READER} panicked on v4/valid/{name}")); + assert!(refused, "{OLDEST_READER} accepted v4/valid/{name}"); + assert!( + wavekat_flow::validate::validate(&wavekat_flow::Flow::from_yaml(&yaml).unwrap()) + .is_ok() + ); + } +} diff --git a/crates/wavekat-flow/README.md b/crates/wavekat-flow/README.md index c9d8bcb..ab14dc6 100644 --- a/crates/wavekat-flow/README.md +++ b/crates/wavekat-flow/README.md @@ -32,7 +32,8 @@ this crate. | `edit` | Load a document to edit it: `edit::load` refuses unknown fields (a save would delete them) and unsupported versions, and returns the YAML comments a save drops; `edit::load_draft` fills a new draft's missing `id`/`name` | | `Flow::to_yaml` | The canonical text of a flow, byte for byte what the TypeScript `serializeFlow` writes. Edit by parsing, changing the flow, and calling this | | `hours` | Business-hours / timezone math (IANA zones, holiday exceptions) | -| `engine` | The flow interpreter + the `FlowEffects` async trait your runtime implements | +| `vars` | Flow variables (v4): the `{{name}}` / `{{#name}}…{{/name}}` placeholder syntax, and `vars::fill`, which turns a flow plus a call's values into a plain v3 flow that validates on its own | +| `engine` | The flow interpreter + the `FlowEffects` async trait your runtime implements; a flow that still declares variables is filled with its defaults before it runs | | `trace` | Serializable run traces emitted by the engine | | `FLOW_V1_SCHEMA` | The normative JSON Schema, bundled as a string for structural validation | diff --git a/crates/wavekat-flow/build.rs b/crates/wavekat-flow/build.rs index ff26a94..3ef6f9e 100644 --- a/crates/wavekat-flow/build.rs +++ b/crates/wavekat-flow/build.rs @@ -20,7 +20,7 @@ use std::{env, fs, path::Path}; /// Oldest first; the last entry is the one the model is generated from. -const VERSIONS: &[u32] = &[1, 2, 3]; +const VERSIONS: &[u32] = &[1, 2, 3, 4]; fn main() { println!("cargo:rerun-if-changed=build.rs"); diff --git a/crates/wavekat-flow/schema/flow.v4.schema.json b/crates/wavekat-flow/schema/flow.v4.schema.json new file mode 100644 index 0000000..eef6d91 --- /dev/null +++ b/crates/wavekat-flow/schema/flow.v4.schema.json @@ -0,0 +1,307 @@ +{ + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://schema.wavekat.com/flow/v4.json", + "title": "Flow", + "description": "The WaveKat call-flow (\"Receptionist\") document, schema_version 4. Version 4 is version 3 plus flow variables: a top-level `variables` map declares details filled in per call. Every version-3 document is a valid version-4 document once its `schema_version` is bumped, and nothing else changed. This file is the single source of truth for the document SHAPE, and — being the newest version — it is also the file both consumers generate their model types from, so one model covers every supported version. Semantic rules that a JSON Schema cannot express (graph reachability, exit-set exactness, hours/timezone math, DTMF digit validity, prompt length, per-component numeric bounds, and which components a given schema_version may use) are NOT encoded here — they live in each language's validator and are pinned by the shared conformance corpus. Unknown fields are permitted structurally, matching both implementations (Rust serde ignores them; the TS parser surfaces a non-blocking warning).", + "type": "object", + "required": ["schema_version", "id", "name", "entry", "nodes"], + "properties": { + "schema_version": { + "description": "Document format version. This file describes version 4 only; a document declaring another version validates against that version's schema file, not this one. (The type generators relax this constant to a plain integer so the generated model can hold any supported version — see scripts/generate.mjs and build.rs.)", + "type": "integer", + "const": 4 + }, + "id": { + "description": "Opaque platform-assigned id (flow_…). Treated as a label; appears in traces.", + "type": "string" + }, + "name": { + "description": "Human name shown in the editor and the read-only viewer.", + "type": "string" + }, + "version": { + "description": "Platform-assigned publish counter, bumped on publish. Defaults to 1 for a hand-written or generated pre-publish document. Distinct from schema_version.", + "type": "integer", + "minimum": 0, + "default": 1 + }, + "note": { + "description": "The author's note about the whole flow: free text for people reading it, in place of a YAML comment. Never read by the engine.", + "type": "string" + }, + "variables": { + "description": "Details a caller of this flow fills in per call, declared by name (a lowercase letter, then up to 31 lowercase letters, digits or underscores; the validators check the form, not the schema, so a reader never has to compile a pattern). A text prompt, an audio prompt's `template` and a menu option label refer to them with `{{name}}` placeholders and `{{#name}}…{{/name}}` blocks (the block's text is kept only when the value is non-empty; blocks do not nest). The validators check that every placeholder is well formed and names a declared variable, and refuse `{{` in any other field; a `note` is a comment and is never scanned. Before a call runs, the flow is filled: each placeholder becomes the call's value, or the default when the call gives none or a blank one, and the result is a schema_version 3 document with no variables. Needs schema_version 4: a reader that ignored the map would speak the placeholders as written.", + "type": "object", + "additionalProperties": { "$ref": "#/$defs/Variable" } + }, + "entry": { + "description": "Node id where execution begins.", + "type": "string" + }, + "nodes": { + "description": "The flat node set, keyed by human-meaningful node id and string-referenced by exits. Order is irrelevant to execution, but it is the author's reading order and is kept on save.", + "type": "object", + "additionalProperties": { "$ref": "#/$defs/Node" } + }, + "ui": { + "description": "Presentation metadata (canvas positions, annotations). Preserved on round-trip, never read by the engine. Opaque by design so a canvas editor can add layout fields without a schema bump." + } + }, + "$defs": { + "Variable": { + "description": "One declared variable.", + "type": "object", + "required": ["default"], + "properties": { + "description": { + "description": "What the value is, shown to whoever fills it in.", + "type": "string" + }, + "default": { + "description": "The value used when a call supplies none, so a flow always plays with no values given. May be an empty string, for a slot that is optional.", + "type": "string" + }, + "max_len": { + "description": "Longest a value may be, in Unicode characters.", + "type": "integer", + "minimum": 1, + "maximum": 500, + "default": 200 + } + } + }, + "Prompt": { + "description": "What a component speaks: TTS text (a bare string) or a reference to a pre-rendered audio asset shipped alongside the flow.", + "oneOf": [ + { "title": "Text", "type": "string" }, + { + "title": "Audio", + "type": "object", + "required": ["audio"], + "properties": { + "audio": { + "description": "Audio asset ref. A generated-clip ref is a voice_prompts id matching ^vprompt_[a-z0-9]+$.", + "type": "string" + }, + "transcript": { + "description": "The words this pre-rendered clip speaks — the text it was synthesized from — carried so a viewer can show what a caller hears, and for traces. Advisory only: playback always uses `audio`, never this. Optional and forward-added: absent on older documents and on refs the platform did not generate from text.", + "type": "string" + }, + "template": { + "description": "The text with `{{name}}` placeholders that `audio` was voiced from using the variables' defaults. A call that overrides a variable speaks the filled template instead of the clip; a call that does not plays `audio`. Only on an audio prompt, and only from schema_version 4: an older reader ignores it and plays the clip.", + "type": "string" + } + } + } + ] + }, + "MessageTone": { + "description": "The cue a message node plays between its prompt and the start of recording.", + "type": "string", + "enum": ["beep", "none"] + }, + "Exits": { + "description": "Wired exits: exit name → target node id. Which names are valid is a property of the node's kind and is checked by the validator, not by this schema.", + "type": "object", + "additionalProperties": { "type": "string" } + }, + "TimeRange": { + "description": "One open window: open–close as \"HH:MM\" (24-hour). Ordering and overnight rules are enforced by the validator.", + "type": "object", + "required": ["open", "close"], + "properties": { + "open": { "type": "string" }, + "close": { "type": "string" } + } + }, + "WeeklySchedule": { + "description": "Open ranges per weekday; a missing or empty day means closed all day.", + "type": "object", + "properties": { + "mon": { "type": "array", "items": { "$ref": "#/$defs/TimeRange" } }, + "tue": { "type": "array", "items": { "$ref": "#/$defs/TimeRange" } }, + "wed": { "type": "array", "items": { "$ref": "#/$defs/TimeRange" } }, + "thu": { "type": "array", "items": { "$ref": "#/$defs/TimeRange" } }, + "fri": { "type": "array", "items": { "$ref": "#/$defs/TimeRange" } }, + "sat": { "type": "array", "items": { "$ref": "#/$defs/TimeRange" } }, + "sun": { "type": "array", "items": { "$ref": "#/$defs/TimeRange" } } + } + }, + "HoursException": { + "description": "A single-date override of the weekly schedule (holiday / special hours).", + "type": "object", + "required": ["date"], + "properties": { + "date": { "description": "\"YYYY-MM-DD\" in the flow's timezone.", "type": "string" }, + "closed": { "description": "Closed all day regardless of ranges.", "type": "boolean", "default": false }, + "ranges": { "type": "array", "items": { "$ref": "#/$defs/TimeRange" } } + } + }, + "Node": { + "description": "One node: a component (kind + its config) plus its wired exits. An internally-tagged union on `kind`.", + "oneOf": [ + { "$ref": "#/$defs/GreetingNode" }, + { "$ref": "#/$defs/HoursNode" }, + { "$ref": "#/$defs/MenuNode" }, + { "$ref": "#/$defs/RingNode" }, + { "$ref": "#/$defs/MessageNode" }, + { "$ref": "#/$defs/TransferNode" }, + { "$ref": "#/$defs/HangupNode" }, + { "$ref": "#/$defs/BookNode" } + ] + }, + "GreetingNode": { + "description": "Speak a prompt, then continue. Exit: next.", + "type": "object", + "required": ["kind", "prompt"], + "properties": { + "kind": { "const": "greeting" }, + "note": { "description": "The author's note about this step: free text for people reading the flow, in place of a YAML comment. Never read by the engine.", "type": "string" }, + "prompt": { "$ref": "#/$defs/Prompt" }, + "exits": { "$ref": "#/$defs/Exits" } + } + }, + "HoursNode": { + "description": "Branch on the business's weekly schedule + holiday overrides. Exits: open, closed.", + "type": "object", + "required": ["kind", "schedule", "timezone"], + "properties": { + "kind": { "const": "hours" }, + "note": { "description": "The author's note about this step: free text for people reading the flow, in place of a YAML comment. Never read by the engine.", "type": "string" }, + "schedule": { "$ref": "#/$defs/WeeklySchedule" }, + "timezone": { "description": "IANA zone (America/New_York). Validated to resolve at load.", "type": "string" }, + "exceptions": { "type": "array", "items": { "$ref": "#/$defs/HoursException" } }, + "exits": { "$ref": "#/$defs/Exits" } + } + }, + "MenuNode": { + "description": "Speak a prompt and collect a DTMF choice. Exits: one per digit in options, plus no_input and invalid.", + "type": "object", + "required": ["kind", "prompt", "options"], + "properties": { + "kind": { "const": "menu" }, + "note": { "description": "The author's note about this step: free text for people reading the flow, in place of a YAML comment. Never read by the engine.", "type": "string" }, + "prompt": { "$ref": "#/$defs/Prompt" }, + "options": { + "description": "Digit key → human label. The exit for a digit is exits[digit]. Valid digit keys are enforced by the validator. A label may hold placeholders; one that is exactly a bare `{{name}}` whose filled value is empty removes the option, its exit, and any step only that exit led to, from the call.", + "type": "object", + "additionalProperties": { "type": "string" } + }, + "retries": { "type": "integer", "minimum": 0, "default": 1 }, + "timeout_secs": { "type": "integer", "minimum": 0, "default": 5 }, + "exits": { "$ref": "#/$defs/Exits" } + } + }, + "RingNode": { + "description": "Ring the human for a window. answered is an implicit terminal; the only wired exit is no_answer.", + "type": "object", + "required": ["kind", "timeout_secs"], + "properties": { + "kind": { "const": "ring" }, + "note": { "description": "The author's note about this step: free text for people reading the flow, in place of a YAML comment. Never read by the engine.", "type": "string" }, + "timeout_secs": { "type": "integer", "minimum": 0 }, + "exits": { "$ref": "#/$defs/Exits" } + } + }, + "MessageNode": { + "description": "Voicemail: speak a prompt, record, transcribe, notify. Terminal.", + "type": "object", + "required": ["kind", "prompt"], + "properties": { + "kind": { "const": "message" }, + "note": { "description": "The author's note about this step: free text for people reading the flow, in place of a YAML comment. Never read by the engine.", "type": "string" }, + "prompt": { "$ref": "#/$defs/Prompt" }, + "max_secs": { "type": "integer", "minimum": 0, "default": 120 }, + "tone": { "allOf": [{ "$ref": "#/$defs/MessageTone" }], "default": "beep" }, + "exits": { "$ref": "#/$defs/Exits" } + } + }, + "TransferNode": { + "description": "Hand the call to an external number. With `whisper`, a screened transfer: call the target first, play the whisper, and connect only when they accept; otherwise take `no_answer`. Without it, a blind transfer (terminal). `whisper` is spoken to the person at the target before they are connected, and `timeout_secs` is how long to let the target ring or decide. Both apply only to a screened transfer.", + "type": "object", + "required": ["kind", "target"], + "properties": { + "kind": { "const": "transfer" }, + "note": { "description": "The author's note about this step: free text for people reading the flow, in place of a YAML comment. Never read by the engine.", "type": "string" }, + "target": { "type": "string" }, + "whisper": { "$ref": "#/$defs/Prompt" }, + "timeout_secs": { "type": "integer", "minimum": 5, "maximum": 120 }, + "exits": { "$ref": "#/$defs/Exits" } + } + }, + "HangupNode": { + "description": "Speak an optional goodbye and end the call. Terminal.", + "type": "object", + "required": ["kind"], + "properties": { + "kind": { "const": "hangup" }, + "note": { "description": "The author's note about this step: free text for people reading the flow, in place of a YAML comment. Never read by the engine.", "type": "string" }, + "prompt": { "$ref": "#/$defs/Prompt" }, + "exits": { "$ref": "#/$defs/Exits" } + } + }, + "BookNode": { + "description": "Offer the caller open appointment times and book the one they choose, before the call ends. New in schema_version 2. The bookable grid is described here (weekly schedule + timezone + how long an appointment is); which times are actually free comes from the connected calendar at call time, and the engine never sees a credential. Exits: booked, no_slots, no_input, unavailable. Three fields carry more meaning than their types show, and are described here because a `$ref` with a sibling description makes the type generators emit a duplicate type instead of reusing the named one. `prompt` is spoken once before the open times are offered (\"I can book you in — here are the next available times\"); the times themselves are never part of it, since they are not known until the call. `confirm_prompt` is spoken immediately after a successful booking and directly BEFORE the booked time (\"You're booked for\" → \"Tuesday\" → \"ten thirty a.m.\"); it deliberately takes no placeholder, because a prompt is frozen audio by the time a call runs and nothing can be interpolated into the middle of it — anything that should follow the time belongs on the booked exit. `schedule` is when this business takes appointments, the `hours` node's weekly shape reused verbatim; it is not the same question `hours` answers, because a business can answer the phone at times it will not book.", + "type": "object", + "required": ["kind", "prompt", "confirm_prompt", "schedule", "timezone", "duration_mins"], + "properties": { + "kind": { "const": "book" }, + "note": { "description": "The author's note about this step: free text for people reading the flow, in place of a YAML comment. Never read by the engine.", "type": "string" }, + "prompt": { "$ref": "#/$defs/Prompt" }, + "confirm_prompt": { "$ref": "#/$defs/Prompt" }, + "schedule": { "$ref": "#/$defs/WeeklySchedule" }, + "timezone": { + "description": "IANA zone (America/New_York) the schedule is written in. Validated to resolve at load.", + "type": "string" + }, + "exceptions": { + "description": "Single-date overrides of the weekly schedule (holidays, one-off clinics), as on `hours`.", + "type": "array", + "items": { "$ref": "#/$defs/HoursException" } + }, + "duration_mins": { + "description": "How long one appointment runs. Bounds are the validator's (see each language's validate module), not this schema's.", + "type": "integer", + "minimum": 0 + }, + "buffer_mins": { + "description": "Clear time kept on BOTH sides of an appointment, so a slot is not offered flush against a busy interval.", + "type": "integer", + "minimum": 0, + "default": 0 + }, + "lead_mins": { + "description": "Nothing sooner than this many minutes from now is offered — the caller cannot book the next five minutes.", + "type": "integer", + "minimum": 0, + "default": 120 + }, + "horizon_days": { + "description": "How far ahead to look for open times.", + "type": "integer", + "minimum": 0, + "default": 14 + }, + "max_offers": { + "description": "How many times to offer the caller. Each offered time gets one keypad digit, counting from 1.", + "type": "integer", + "minimum": 0, + "default": 3 + }, + "retries": { + "description": "Extra attempts to collect a keypress after the first, as on `menu`.", + "type": "integer", + "minimum": 0, + "default": 1 + }, + "timeout_secs": { + "description": "How long to wait for a keypress on each attempt, as on `menu`.", + "type": "integer", + "minimum": 0, + "default": 5 + }, + "exits": { "$ref": "#/$defs/Exits" } + } + } + } +} diff --git a/crates/wavekat-flow/src/canonical.rs b/crates/wavekat-flow/src/canonical.rs index 769b369..39d9ec0 100644 --- a/crates/wavekat-flow/src/canonical.rs +++ b/crates/wavekat-flow/src/canonical.rs @@ -12,12 +12,12 @@ use std::sync::OnceLock; use serde_json::{Map, Value}; -use crate::{Flow, FLOW_V3_SCHEMA}; +use crate::{Flow, FLOW_V4_SCHEMA}; /// The newest schema, which the model is generated from. pub(crate) fn schema() -> &'static Value { static SCHEMA: OnceLock = OnceLock::new(); - SCHEMA.get_or_init(|| serde_json::from_str(FLOW_V3_SCHEMA).expect("bundled schema is JSON")) + SCHEMA.get_or_init(|| serde_json::from_str(FLOW_V4_SCHEMA).expect("bundled schema is JSON")) } /// Follow `$ref` (and a single-entry `allOf`, the schema's way of putting a diff --git a/crates/wavekat-flow/src/engine.rs b/crates/wavekat-flow/src/engine.rs index dd1d234..4fb1742 100644 --- a/crates/wavekat-flow/src/engine.rs +++ b/crates/wavekat-flow/src/engine.rs @@ -28,6 +28,7 @@ use crate::book; use crate::hours::{self, HoursError}; use crate::model::{Flow, HoursException, MessageTone, Node, Prompt, WeeklySchedule}; use crate::trace::{FlowOutcome, StepDetail, Trace}; +use crate::vars::{self, FillError}; use crate::NodeId; /// Backstop against a cycle in a flow that somehow reached the engine @@ -245,6 +246,8 @@ enum EngineError { MissingExit { node: NodeId, exit: String }, #[error("hours evaluation at {node:?} failed: {source}")] Hours { node: NodeId, source: HoursError }, + #[error("the flow's variables could not be filled with their defaults: {}", .0.iter().map(|e| format!("{} ({e})", e.code())).collect::>().join(", "))] + Fill(Vec), } impl EngineError { @@ -277,7 +280,25 @@ enum Step { /// caller hangs up mid-flow — still holds the steps executed so far. A /// cancelled run never writes `outcome`; it keeps the [`FlowOutcome::Defect`] /// placeholder. +/// +/// A flow that still declares `variables` is never run as written: it is +/// first filled with its defaults ([`vars::fill`] with no values), so the +/// caller never hears a placeholder. Fill the flow yourself to run it with a +/// call's values. A flow that cannot be filled ends as a defect before any +/// node runs. pub async fn run(flow: &Flow, fx: &mut E, trace: &mut Trace) { + let filled; + let flow = if flow.variables.is_empty() { + flow + } else { + match vars::fill(flow, &std::collections::BTreeMap::new()) { + Ok(f) => { + filled = f; + &filled + } + Err(errs) => return abort(trace, EngineError::Fill(errs)), + } + }; let mut current = flow.entry.clone(); for _ in 0..MAX_STEPS { @@ -580,6 +601,7 @@ async fn run_book( fx.speak(&Prompt::Audio { audio: reference, transcript: None, + template: None, }) .await .map_err(EngineError::Effect)?; @@ -598,6 +620,7 @@ async fn run_book( fx.speak(&Prompt::Audio { audio: book::taken_ref(), transcript: None, + template: None, }) .await .map_err(EngineError::Effect)?; @@ -643,6 +666,7 @@ async fn collect_offer_choice( fx.speak(&Prompt::Audio { audio: reference, transcript: None, + template: None, }) .await .map_err(EngineError::Effect)?; @@ -698,6 +722,7 @@ async fn run_menu( "menu", StepDetail::MenuChoice { digit: digit.as_key().to_string(), + label: options.get(digit.as_key()).cloned(), }, ); return goto(id, node, digit.as_key()); @@ -1068,7 +1093,10 @@ nodes: assert_eq!(trace.steps[1].detail, StepDetail::Hours { open: false }); assert_eq!( trace.steps[2].detail, - StepDetail::MenuChoice { digit: "1".into() } + StepDetail::MenuChoice { + digit: "1".into(), + label: Some("Hours".into()) + } ); // The caller heard the opening-hours greeting. assert!(fx @@ -1077,6 +1105,98 @@ nodes: .any(|s| s.contains("open Tuesday to Sunday"))); } + #[tokio::test] + async fn menu_choice_carries_its_label() { + let mut fx = MockEffects::new(closed_time()) + .digits([Some(Digit::D1)]) + .message_secs(5); + let trace = run_trace(&luigis(), &mut fx).await; + assert_eq!( + trace.steps[2].detail, + StepDetail::MenuChoice { + digit: "1".into(), + label: Some("Hours".into()) + } + ); + let json = serde_json::to_value(&trace.steps[2].detail).unwrap(); + assert_eq!(json["label"], "Hours"); + } + + const ASK: &str = include_str!("../../../conformance/v4/valid/ask-question.yaml"); + + #[tokio::test] + async fn an_unfilled_flow_runs_with_its_defaults() { + // Handed the v4 flow as written, not a filled one: the engine fills + // it with the defaults rather than speak the braces. + let flow = Flow::from_yaml(ASK).unwrap(); + let mut fx = MockEffects::new(open_time()).digits([Some(Digit::D1)]); + let trace = run_trace(&flow, &mut fx).await; + assert_eq!(trace.outcome, FlowOutcome::HungUp); + assert_eq!( + trace.steps[0].detail, + StepDetail::MenuChoice { + digit: "1".into(), + label: Some("Yes".into()) + } + ); + assert!(fx.spoken[0].contains("Press 1 for Yes."), "{:?}", fx.spoken); + assert!( + fx.spoken.iter().all(|s| !s.contains("{{")), + "{:?}", + fx.spoken + ); + } + + #[tokio::test] + async fn an_unfilled_flow_drops_an_empty_option() { + // option3's default is empty, so key 3 is not an option: every press + // is invalid (retries: 2, so three tries) and the call ends at `bye`. + let flow = Flow::from_yaml(ASK).unwrap(); + let mut fx = MockEffects::new(open_time()).digits([ + Some(Digit::D3), + Some(Digit::D3), + Some(Digit::D3), + ]); + let trace = run_trace(&flow, &mut fx).await; + assert_eq!(trace.steps[0].detail, StepDetail::MenuInvalid); + assert_eq!(trace.outcome, FlowOutcome::HungUp); + assert!(fx.spoken.iter().any(|s| s.contains("No answer recorded"))); + } + + #[tokio::test] + async fn a_flow_that_cannot_be_filled_is_a_defect() { + let flow = Flow::from_yaml( + "schema_version: 4\nid: f\nname: F\nentry: m\nvariables:\n a: { default: \"\" }\nnodes:\n m:\n kind: menu\n prompt: Pick\n options: { \"1\": \"{{a}}\" }\n exits: { \"1\": m, no_input: m, invalid: m }\n", + ) + .unwrap(); + let mut fx = MockEffects::new(open_time()); + let trace = run_trace(&flow, &mut fx).await; + assert_eq!(trace.outcome, FlowOutcome::Defect); + assert!(trace.steps.is_empty()); + assert!(fx.spoken.is_empty()); + assert!(trace + .error + .as_deref() + .unwrap() + .contains("menu_without_options")); + } + + #[test] + fn old_menu_choice_json_still_reads() { + let d: StepDetail = + serde_json::from_str(r#"{"detail":"menu_choice","digit":"1"}"#).unwrap(); + assert_eq!( + d, + StepDetail::MenuChoice { + digit: "1".into(), + label: None + } + ); + // No label key is written when there is none. + let json = serde_json::to_value(&d).unwrap(); + assert!(json.get("label").is_none()); + } + #[tokio::test] async fn closed_silence_takes_no_input_exit() { // No digits scripted → every collect times out → no_input. @@ -1118,7 +1238,10 @@ nodes: assert_eq!( trace.steps[2].detail, - StepDetail::MenuChoice { digit: "1".into() } + StepDetail::MenuChoice { + digit: "1".into(), + label: Some("Hours".into()) + } ); assert_eq!(trace.outcome, FlowOutcome::MessageLeft); } diff --git a/crates/wavekat-flow/src/lib.rs b/crates/wavekat-flow/src/lib.rs index be38055..f0bba06 100644 --- a/crates/wavekat-flow/src/lib.rs +++ b/crates/wavekat-flow/src/lib.rs @@ -41,6 +41,7 @@ pub mod engine; pub mod hours; pub mod trace; pub mod validate; +pub mod vars; /// Re-exported so callers name the generated maps' type without a matching /// `indexmap` dependency of their own. @@ -62,16 +63,21 @@ pub const FLOW_V1_SCHEMA: &str = include_str!("../schema/flow.v1.schema.json"); pub const FLOW_V2_SCHEMA: &str = include_str!("../schema/flow.v2.schema.json"); /// Format version 3 — version 2 plus the screened transfer (`transfer` -/// gains `whisper` and `timeout_secs`). This is also the file the model -/// types are generated from, being the newest. +/// gains `whisper` and `timeout_secs`). pub const FLOW_V3_SCHEMA: &str = include_str!("../schema/flow.v3.schema.json"); +/// Format version 4 — version 3 plus flow variables (a top-level +/// `variables` map). This is also the file the model types are generated +/// from, being the newest. +pub const FLOW_V4_SCHEMA: &str = include_str!("../schema/flow.v4.schema.json"); + /// The schema for a declared version, or `None` if this build has none. pub fn flow_schema(version: u32) -> Option<&'static str> { match version { 1 => Some(FLOW_V1_SCHEMA), 2 => Some(FLOW_V2_SCHEMA), 3 => Some(FLOW_V3_SCHEMA), + 4 => Some(FLOW_V4_SCHEMA), _ => None, } } @@ -82,9 +88,9 @@ pub fn flow_schema(version: u32) -> Option<&'static str> { /// This is what a daemon advertises and the platform refuses to serve /// past: a device that only knows version 1 must never be handed a /// document that uses a component it has no code for. -pub const SUPPORTED_SCHEMA_VERSIONS: &[u32] = &[1, 2, 3]; +pub const SUPPORTED_SCHEMA_VERSIONS: &[u32] = &[1, 2, 3, 4]; /// The newest version this build authors. Reading stays broad /// ([`SUPPORTED_SCHEMA_VERSIONS`]); writing is deliberately one number. /// Twin: `model.ts` `CURRENT_SCHEMA_VERSION`. -pub const CURRENT_SCHEMA_VERSION: u32 = 3; +pub const CURRENT_SCHEMA_VERSION: u32 = 4; diff --git a/crates/wavekat-flow/src/model_ext.rs b/crates/wavekat-flow/src/model_ext.rs index 63ffe08..1429d14 100644 --- a/crates/wavekat-flow/src/model_ext.rs +++ b/crates/wavekat-flow/src/model_ext.rs @@ -274,6 +274,16 @@ impl Prompt { Prompt::Audio { transcript, .. } => transcript.as_deref(), } } + + /// The `{{name}}` text an audio prompt was voiced from with its + /// variables' defaults, `None` for a text prompt or a plain clip. The + /// text itself is not scanned here. Twin: `model.ts` `promptTemplate`. + pub fn template(&self) -> Option<&str> { + match self { + Prompt::Text(_) => None, + Prompt::Audio { template, .. } => template.as_deref(), + } + } } impl Flow { @@ -372,10 +382,25 @@ nodes: let audio = Prompt::Audio { audio: "vprompt_ab12cd34".into(), transcript: Some("open eleven to ten".into()), + template: None, }; assert_eq!(audio.as_text(), None); } + #[test] + fn template_is_only_on_an_audio_prompt() { + assert_eq!(Prompt::Text("Hi {{name}}".into()).template(), None); + let plain: Prompt = serde_yaml_ng::from_str("{ audio: vprompt_ff00ee11 }").unwrap(); + assert_eq!(plain.template(), None); + let voiced: Prompt = + serde_yaml_ng::from_str("{ audio: vprompt_ff00ee11, template: \"Hi {{name}}\" }") + .unwrap(); + assert_eq!(voiced.template(), Some("Hi {{name}}")); + let yaml = serde_yaml_ng::to_string(&voiced).unwrap(); + let again: Prompt = serde_yaml_ng::from_str(&yaml).unwrap(); + assert_eq!(again.template(), Some("Hi {{name}}")); + } + #[test] fn transcript_is_the_spoken_words_regardless_of_voicing() { // Text prompt is its own transcript. @@ -386,6 +411,7 @@ nodes: let with_text = Prompt::Audio { audio: "vprompt_ab12cd34".into(), transcript: Some("open eleven to ten".into()), + template: None, }; assert_eq!(with_text.transcript(), Some("open eleven to ten")); @@ -393,6 +419,7 @@ nodes: let without_text = Prompt::Audio { audio: "vprompt_ff00ee11".into(), transcript: None, + template: None, }; assert_eq!(without_text.transcript(), None); } diff --git a/crates/wavekat-flow/src/trace.rs b/crates/wavekat-flow/src/trace.rs index 2e878ee..57796ed 100644 --- a/crates/wavekat-flow/src/trace.rs +++ b/crates/wavekat-flow/src/trace.rs @@ -12,7 +12,7 @@ use std::time::Instant; -use serde::Serialize; +use serde::{Deserialize, Serialize}; use crate::NodeId; @@ -88,7 +88,7 @@ pub struct TraceStep { /// The per-node outcome. Tagged so it serializes to a self-describing object /// the renderer can switch on. -#[derive(Debug, Clone, PartialEq, Serialize)] +#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)] #[serde(tag = "detail", rename_all = "snake_case")] pub enum StepDetail { /// A greeting/`say_hours` spoke and continued. @@ -96,7 +96,13 @@ pub enum StepDetail { /// An `hours` branch resolved. Hours { open: bool }, /// A menu caller pressed a mapped option. - MenuChoice { digit: String }, + /// `label` is the pressed option's label from the flow (absent in + /// traces written before labels were reported). + MenuChoice { + digit: String, + #[serde(default, skip_serializing_if = "Option::is_none")] + label: Option, + }, /// A menu exhausted its retries with no input at all. MenuNoInput, /// A menu exhausted its retries hearing only unmapped keys. diff --git a/crates/wavekat-flow/src/validate.rs b/crates/wavekat-flow/src/validate.rs index 563af81..38d7598 100644 --- a/crates/wavekat-flow/src/validate.rs +++ b/crates/wavekat-flow/src/validate.rs @@ -18,13 +18,14 @@ use crate::book::{self}; use crate::hours::{self, HoursError}; use crate::model::{Flow, Node, Prompt}; use crate::model_ext::NodeId; +use crate::vars::{self, TemplateError}; use crate::SUPPORTED_SCHEMA_VERSIONS; /// Longest a spoken (text) prompt may be. A backstop against a pasted-essay /// prompt that would trap a caller under minutes of TTS; generous enough that /// no real greeting hits it. Audio-asset prompts are unbounded here. Twin: /// `packages/flow-schema/src/model.ts` `MAX_PROMPT_CHARS`. -const MAX_PROMPT_CHARS: usize = 2000; +pub(crate) const MAX_PROMPT_CHARS: usize = 2000; /// The DTMF keys a `menu` option may be keyed by. Twin: /// `packages/flow-schema/src/model.ts` `VALID_DIGITS`. @@ -40,6 +41,19 @@ const MAX_TRANSFER_TIMEOUT_SECS: i64 = 120; /// on a `transfer`. Twin: `model.ts` `TRANSFER_FIELDS_MIN_SCHEMA_VERSION`. const TRANSFER_FIELDS_MIN_SCHEMA_VERSION: u32 = 3; +/// The oldest `schema_version` that may declare `variables`. Twin: +/// `model.ts` `VARIABLES_MIN_SCHEMA_VERSION`. +const VARIABLES_MIN_SCHEMA_VERSION: u32 = 4; + +/// The oldest `schema_version` that may give an audio prompt a `template`. +/// Twin: `model.ts` `TEMPLATE_MIN_SCHEMA_VERSION`. +const TEMPLATE_MIN_SCHEMA_VERSION: u32 = 4; + +/// The longest a variable's `max_len` may be, in characters. The schema +/// carries the same cap; the validators re-check it so a value built in +/// code is held to it too. Twin: `model.ts` `MAX_VARIABLE_LEN`. +const MAX_VARIABLE_LEN: u64 = 500; + /// One thing wrong with a flow document. Carries enough context (node id, /// exit name, offending value) for the editor to point at it. #[derive(Debug, Clone, PartialEq, Eq, thiserror::Error)] @@ -129,6 +143,44 @@ pub enum ValidationError { declared: i64, }, + #[error("{field} needs schema_version {required} (this document declares {declared})")] + VariablesRequireNewerSchema { + field: &'static str, + required: u32, + declared: i64, + }, + + #[error("variable name {name:?} must be a lowercase letter, then up to 31 lowercase letters, digits or underscores")] + VariableBadName { node: Option, name: String }, + + #[error("variable {name:?} max_len is {value} (allowed: 1-{MAX_VARIABLE_LEN})")] + VariableMaxLenOutOfRange { name: String, value: u64 }, + + #[error("variable {name:?} default is {len} characters; its max_len is {max}")] + VariableDefaultTooLong { name: String, max: u64, len: u64 }, + + #[error("node {node:?} {field} has a malformed placeholder: {reason}")] + TemplateSyntax { + node: NodeId, + field: String, + reason: String, + }, + + #[error( + "node {node:?} {field} uses {name:?}, which the flow does not declare under variables" + )] + UnknownVariable { + node: NodeId, + field: String, + name: String, + }, + + #[error("{} holds a {{{{ placeholder, which is only allowed in a prompt, a prompt template or a menu label", .node.as_ref().map(|n| format!("node {n:?} {fields:?}")).unwrap_or_else(|| format!("{fields:?}")))] + PlaceholderNotAllowed { + node: Option, + fields: Vec, + }, + #[error("transfer node {node:?} sets timeout_secs but has no whisper to screen with")] TimeoutWithoutWhisper { node: NodeId }, @@ -181,6 +233,13 @@ impl ValidationError { ValidationError::BookNeverOpen { .. } => "book_never_open", ValidationError::KindRequiresNewerSchema { .. } => "kind_requires_newer_schema", ValidationError::FieldRequiresNewerSchema { .. } => "field_requires_newer_schema", + ValidationError::VariablesRequireNewerSchema { .. } => "field_requires_newer_schema", + ValidationError::VariableBadName { .. } => "variable_bad_name", + ValidationError::VariableMaxLenOutOfRange { .. } => "variable_max_len_out_of_range", + ValidationError::VariableDefaultTooLong { .. } => "variable_default_too_long", + ValidationError::TemplateSyntax { .. } => "template_syntax", + ValidationError::UnknownVariable { .. } => "unknown_variable", + ValidationError::PlaceholderNotAllowed { .. } => "placeholder_not_allowed", ValidationError::TimeoutWithoutWhisper { .. } => "timeout_without_whisper", ValidationError::TransferTimeoutOutOfRange { .. } => "transfer_timeout_out_of_range", ValidationError::OutboundNodeNotAllowed { .. } => "outbound_node_not_allowed", @@ -213,6 +272,11 @@ fn kind_min_schema_version(kind: &str) -> i64 { /// /// Twin: `model.ts` `requiredSchemaVersion`. pub fn required_schema_version(flow: &Flow) -> i64 { + let variables = if !flow.variables.is_empty() { + i64::from(VARIABLES_MIN_SCHEMA_VERSION) + } else { + 1 + }; flow.nodes .values() .map(|node| { @@ -226,10 +290,18 @@ pub fn required_schema_version(flow: &Flow) -> i64 { } _ => 1, }; - kind_min_schema_version(node.kind()).max(fields) + let template = if node.prompts().iter().any(|p| p.template().is_some()) { + i64::from(TEMPLATE_MIN_SCHEMA_VERSION) + } else { + 1 + }; + kind_min_schema_version(node.kind()) + .max(fields) + .max(template) }) .max() .unwrap_or(1) + .max(variables) } /// Validate a parsed flow. `Ok(())` means safe to publish / execute; `Err` @@ -246,6 +318,16 @@ pub fn validate(flow: &Flow) -> Result<(), Vec> { )); } + if !flow.variables.is_empty() && flow.schema_version < i64::from(VARIABLES_MIN_SCHEMA_VERSION) { + errs.push(ValidationError::VariablesRequireNewerSchema { + field: "variables", + required: VARIABLES_MIN_SCHEMA_VERSION, + declared: flow.schema_version, + }); + } + + check_variables(flow, &mut errs); + if flow.nodes.is_empty() { errs.push(ValidationError::EmptyFlow); return Err(errs); // graph checks below would be meaningless @@ -260,6 +342,8 @@ pub fn validate(flow: &Flow) -> Result<(), Vec> { check_exits(id, node, flow, &mut errs); check_node(id, node, &mut errs); check_transfer_fields_version(id, node, flow.schema_version, &mut errs); + check_template_version(id, node, flow.schema_version, &mut errs); + check_placeholders(id, node, flow, &mut errs); // A component the document's own version doesn't have. Checked // per node rather than once per flow so the editor points at the @@ -290,6 +374,148 @@ pub fn validate(flow: &Flow) -> Result<(), Vec> { } } +/// Declared variable names, `max_len`s and defaults, and placeholder-looking +/// text in the flow's own `id` and `name` (its `note` is a comment and never +/// scanned). Only on a v4 document: before that `{{` is ordinary text and +/// `variables` is refused as a whole. +fn check_variables(flow: &Flow, errs: &mut Vec) { + if flow.schema_version < i64::from(VARIABLES_MIN_SCHEMA_VERSION) { + return; + } + let mut names: Vec<&String> = flow.variables.keys().collect(); + names.sort(); + for name in names { + if !vars::is_variable_name(name) { + errs.push(ValidationError::VariableBadName { + node: None, + name: name.clone(), + }); + } + let max_len = flow.variables[name].max_len.get(); + if max_len > MAX_VARIABLE_LEN { + errs.push(ValidationError::VariableMaxLenOutOfRange { + name: name.clone(), + value: max_len, + }); + } + // A default is held to the same limit as a caller's value. + let len = flow.variables[name].default.chars().count() as u64; + if len > max_len { + errs.push(ValidationError::VariableDefaultTooLong { + name: name.clone(), + max: max_len, + len, + }); + } + } + let mut fields: Vec = [("id", &flow.id), ("name", &flow.name)] + .into_iter() + .filter(|(_, v)| v.contains("{{")) + .map(|(k, _)| k.to_string()) + .collect(); + fields.sort(); + if !fields.is_empty() { + errs.push(ValidationError::PlaceholderNotAllowed { node: None, fields }); + } +} + +/// Check every place a node may hold a placeholder (string prompts, an +/// audio prompt's `template`, menu option labels) against the declared +/// variables, and refuse `{{` in any other string field. A v1-v3 document +/// is skipped entirely: there `{{` is text to be spoken as written. +fn check_placeholders(id: &NodeId, node: &Node, flow: &Flow, errs: &mut Vec) { + if flow.schema_version < i64::from(VARIABLES_MIN_SCHEMA_VERSION) { + return; + } + let mut scan = |field: String, text: &str| match vars::parse_template(text) { + Ok(_) => { + for name in vars::template_names(text) { + if !flow.variables.contains_key(&name) { + errs.push(ValidationError::UnknownVariable { + node: id.clone(), + field: field.clone(), + name, + }); + } + } + } + Err(TemplateError::BadName(name)) => errs.push(ValidationError::VariableBadName { + node: Some(id.clone()), + name, + }), + Err(e) => errs.push(ValidationError::TemplateSyntax { + node: id.clone(), + field, + reason: e.to_string(), + }), + }; + for (field, prompt) in node.prompt_slots() { + match prompt { + Prompt::Text(text) => scan(field.to_string(), text), + Prompt::Audio { .. } => { + if let Some(template) = prompt.template() { + scan(format!("{field}.template"), template); + } + } + } + } + if let Node::Menu { options, .. } = node { + let mut keys: Vec<&String> = options.keys().collect(); + keys.sort(); + for key in keys { + scan(format!("options.{key}"), &options[key]); + } + } + + // Everything else: any string value holding `{{` is out of place. A + // `note` is a comment for people, never read by the engine, so it is + // never scanned (nor is the flow's own note, see `check_variables`). + let Ok(serde_json::Value::Object(map)) = serde_json::to_value(node) else { + return; + }; + let mut bad = Vec::new(); + for (key, value) in &map { + if !matches!(key.as_str(), "exits" | "kind" | "note") { + collect_stray_braces(key, value, &mut bad); + } + } + bad.sort(); + if !bad.is_empty() { + errs.push(ValidationError::PlaceholderNotAllowed { + node: Some(id.clone()), + fields: bad, + }); + } +} + +/// Paths of string values under `value` that hold `{{`, apart from the +/// slots where a placeholder is allowed: a plain-string `prompt`, +/// `confirm_prompt` or `whisper`, any `.template`, and menu `options`. +fn collect_stray_braces(path: &str, value: &serde_json::Value, out: &mut Vec) { + use serde_json::Value; + match value { + Value::String(s) => { + let allowed = matches!(path, "prompt" | "confirm_prompt" | "whisper") + || path.ends_with(".template") + || path.starts_with("options."); + if s.contains("{{") && !allowed { + out.push(path.to_string()); + } + } + Value::Array(items) => { + for (i, item) in items.iter().enumerate() { + collect_stray_braces(&format!("{path}.{i}"), item, out); + } + } + Value::Object(map) => { + for (key, item) in map { + collect_stray_braces(&format!("{path}.{key}"), item, out); + } + } + _ => {} + } +} + /// `whisper` and `timeout_secs` on a document older than the version that /// has them. Reported per field, so the editor can say which one to drop /// or which version to raise. @@ -325,6 +551,27 @@ fn check_transfer_fields_version( } } +/// `template` on an audio prompt of a document older than the version that +/// has it. One error per node, whichever prompt carries it. +fn check_template_version( + id: &NodeId, + node: &Node, + declared: i64, + errs: &mut Vec, +) { + if declared >= i64::from(TEMPLATE_MIN_SCHEMA_VERSION) { + return; + } + if node.prompts().iter().any(|p| p.template().is_some()) { + errs.push(ValidationError::FieldRequiresNewerSchema { + node: id.clone(), + field: "template", + required: TEMPLATE_MIN_SCHEMA_VERSION, + declared, + }); + } +} + /// The kinds a flow may use on a call the app *places*, as of /// `schema_version` 2 and earlier: no person is standing by. Kept for /// compatibility; [`outbound_kinds`] is the version-aware list. Twin: @@ -465,7 +712,7 @@ fn unbounded_loop_nodes(flow: &Flow) -> Vec<&str> { /// Node ids reachable from `entry` over exit edges (`entry` included when /// it exists). -fn reachable_from_entry(flow: &Flow) -> BTreeSet<&str> { +pub(crate) fn reachable_from_entry(flow: &Flow) -> BTreeSet<&str> { let mut reachable: BTreeSet<&str> = BTreeSet::new(); let Some((entry, _)) = flow.nodes.get_key_value(&flow.entry) else { return reachable; @@ -1523,4 +1770,175 @@ nodes: assert_eq!(validate(&parse(&src)), Ok(())); assert_eq!(validate_outbound(&parse(&src)), Ok(())); } + // ── flow variables ─────────────────────────────────────────────────── + const WITH_VARIABLES: &str = "schema_version: 4\nid: f\nname: F\nentry: a\nvariables:\n q: { default: hi }\nnodes:\n a:\n kind: hangup\n prompt: \"{{q}}\"\n"; + + #[test] + fn variables_need_v4() { + let flow = parse(WITH_VARIABLES); + assert_eq!(required_schema_version(&flow), 4); + assert_eq!(validate(&flow), Ok(())); + } + + #[test] + fn variables_in_v3_are_refused() { + let src = WITH_VARIABLES.replace("schema_version: 4", "schema_version: 3"); + let errs = validate(&parse(&src)).unwrap_err(); + assert_eq!( + errs, + vec![ValidationError::VariablesRequireNewerSchema { + field: "variables", + required: 4, + declared: 3, + }] + ); + assert_eq!(errs[0].code(), "field_requires_newer_schema"); + } + + #[test] + fn empty_variables_are_no_variables() { + let src = WITH_VARIABLES + .replace("schema_version: 4", "schema_version: 3") + .replace(" q: { default: hi }\n", "") + .replace("variables:\n", "variables: {}\n"); + let flow = parse(&src); + assert_eq!(required_schema_version(&flow), 1); + assert_eq!(validate(&flow), Ok(())); + } + + const WITH_TEMPLATE: &str = "schema_version: 4\nid: f\nname: F\nentry: a\nnodes:\n a:\n kind: hangup\n prompt: { audio: vprompt_abc123, template: \"Hi {{name}}\" }\n"; + + #[test] + fn template_needs_v4() { + let declared = + WITH_TEMPLATE.replace("nodes:", "variables:\n name: { default: there }\nnodes:"); + let flow = parse(&declared); + assert_eq!(required_schema_version(&flow), 4); + assert_eq!(validate(&flow), Ok(())); + let plain = WITH_TEMPLATE.replace(", template: \"Hi {{name}}\"", ""); + assert_eq!(required_schema_version(&parse(&plain)), 1); + } + + #[test] + fn template_in_v3_is_refused() { + let src = WITH_TEMPLATE.replace("schema_version: 4", "schema_version: 3"); + let errs = validate(&parse(&src)).unwrap_err(); + assert_eq!( + errs, + vec![ValidationError::FieldRequiresNewerSchema { + node: "a".into(), + field: "template", + required: 4, + declared: 3, + }] + ); + assert_eq!(errs[0].code(), "field_requires_newer_schema"); + } + + fn v4_flow(vars: &str, nodes: &str) -> String { + format!("schema_version: 4\nid: f\nname: F\nentry: a\nvariables:\n{vars}\nnodes:\n{nodes}") + } + + const Q: &str = " q: { default: \"x\" }\n"; + + #[test] + fn v4_placeholder_must_be_declared() { + let f = v4_flow( + Q, + " a:\n kind: hangup\n prompt: \"Hi {{q}} {{ghost}}\"\n", + ); + assert_eq!(codes(&f), vec!["unknown_variable"]); + let ok = v4_flow(Q, " a:\n kind: hangup\n prompt: \"Hi {{q}}\"\n"); + assert_eq!(validate(&parse(&ok)), Ok(())); + } + + #[test] + fn v4_menu_labels_and_templates_are_scanned() { + let f = v4_flow( + Q, + " a:\n kind: menu\n prompt: { audio: vprompt_ab12, template: \"{{nope}}\" }\n options: { \"1\": \"{{q}}\", \"2\": \"{{bad}}\" }\n exits: { \"1\": b, \"2\": b, no_input: b, invalid: b }\n b:\n kind: hangup\n prompt: bye\n", + ); + assert_eq!(codes(&f), vec!["unknown_variable", "unknown_variable"]); + } + + #[test] + fn v4_bad_template_syntax_and_names() { + let f = v4_flow(Q, " a:\n kind: hangup\n prompt: \"{{#q}} open\"\n"); + assert_eq!(codes(&f), vec!["template_syntax"]); + let f = v4_flow(Q, " a:\n kind: hangup\n prompt: \"{{Q}}\"\n"); + assert_eq!(codes(&f), vec!["variable_bad_name"]); + } + + #[test] + fn v4_declared_names_must_fit_the_pattern() { + let f = v4_flow( + " Bad: { default: \"\" }\n", + " a:\n kind: hangup\n prompt: bye\n", + ); + assert_eq!(codes(&f), vec!["variable_bad_name"]); + } + + #[test] + fn v4_max_len_is_capped() { + let f = v4_flow( + " q: { default: \"\", max_len: 501 }\n", + " a:\n kind: hangup\n prompt: bye\n", + ); + assert_eq!(codes(&f), vec!["variable_max_len_out_of_range"]); + } + + #[test] + fn v4_default_must_fit_max_len() { + // Counted in characters, like a caller's value. + let f = v4_flow( + " q: { default: \"问问问\", max_len: 2 }\n", + " a:\n kind: hangup\n prompt: \"{{q}}\"\n", + ); + let errs = validate(&parse(&f)).unwrap_err(); + assert_eq!( + errs, + vec![ValidationError::VariableDefaultTooLong { + name: "q".into(), + max: 2, + len: 3 + }] + ); + assert_eq!(errs[0].code(), "variable_default_too_long"); + let ok = v4_flow( + " q: { default: \"问问\", max_len: 2 }\n", + " a:\n kind: hangup\n prompt: \"{{q}}\"\n", + ); + assert_eq!(validate(&parse(&ok)), Ok(())); + } + + #[test] + fn notes_are_never_scanned_for_placeholders() { + let f = parse(&format!( + "schema_version: 4\nid: f\nname: F\nnote: \"{{{{ghost}}}} {{{{#x\"\nentry: a\nvariables:\n{Q}nodes:\n a:\n kind: hangup\n note: \"{{{{ghost}}}} {{{{#x\"\n prompt: \"{{{{q}}}}\"\n" + )); + assert_eq!(validate(&f), Ok(())); + } + + #[test] + fn placeholder_in_transfer_target_is_refused() { + let f = v4_flow(Q, " a:\n kind: transfer\n target: \"{{q}}\"\n"); + assert_eq!(codes(&f), vec!["placeholder_not_allowed"]); + } + + #[test] + fn placeholder_in_a_transcript_is_refused() { + let f = v4_flow( + Q, + " a:\n kind: hangup\n prompt: { audio: vprompt_ab12, transcript: \"Hi {{q}}\" }\n", + ); + assert_eq!(codes(&f), vec!["placeholder_not_allowed"]); + } + + #[test] + fn v3_braces_are_plain_text() { + let f = parse( + "schema_version: 3\nid: f\nname: F\nentry: a\nnodes:\n a:\n kind: hangup\n prompt: \"Press {{1}} now }} {{#x\"\n", + ); + assert_eq!(validate(&f), Ok(())); + } } diff --git a/crates/wavekat-flow/src/vars.rs b/crates/wavekat-flow/src/vars.rs new file mode 100644 index 0000000..62a4935 --- /dev/null +++ b/crates/wavekat-flow/src/vars.rs @@ -0,0 +1,749 @@ +//! Placeholder syntax shared by validation and filling. +//! +//! A template is text with `{{name}}` placeholders and `{{#name}}…{{/name}}` +//! conditional blocks (kept only when the variable's value is non-empty). +//! Blocks do not nest and have no else. Names are `[a-z][a-z0-9_]{0,31}`. +//! +//! [`fill`] gives each name an effective value: the caller's, cleaned, or +//! the variable's default when the caller gives none or a blank one. So a +//! blank value falls back to the default; it cannot clear a default. Only a +//! menu option whose label is exactly a bare `{{name}}` is dropped when its +//! effective value is empty; any other text that holds an empty placeholder +//! is kept, with the placeholder filled as nothing. +//! Twin: `packages/flow-schema/src/vars.ts`. + +use std::collections::BTreeMap; + +use crate::model::{Exits, Flow, Node, Prompt}; + +/// One piece of a parsed template. +#[derive(Debug, Clone, PartialEq, Eq)] +pub enum Segment<'a> { + /// Literal text, spoken as written. + Text(&'a str), + /// A `{{name}}` placeholder. + Var(&'a str), + /// A `{{#name}}…{{/name}}` block; `body` holds only `Text` and `Var`. + Block { + name: &'a str, + body: Vec>, + }, +} + +/// Why a template could not be parsed. +#[derive(Debug, Clone, PartialEq, Eq, thiserror::Error)] +pub enum TemplateError { + #[error("a `{{{{` or block is never closed")] + Unclosed, + #[error("blocks cannot be nested")] + Nested, + #[error("{0:?} is not a valid variable name (a lowercase letter, then up to 31 lowercase letters, digits or underscores)")] + BadName(String), + #[error("block close {{{{/{0}}}}} does not match an open block")] + Mismatched(String), +} + +/// Whether `name` fits `[a-z][a-z0-9_]{0,31}`. Twin: `isVariableName`. +pub fn is_variable_name(name: &str) -> bool { + let mut chars = name.chars(); + matches!(chars.next(), Some('a'..='z')) + && name.len() <= 32 + && chars.all(|c| matches!(c, 'a'..='z' | '0'..='9' | '_')) +} + +enum Tok<'a> { + Text(&'a str), + Var(&'a str), + Open(&'a str), + Close(&'a str), +} + +/// Split `s` into tokens. The flag is true when a `{{` has no `}}`. +fn tokens(s: &str) -> (Vec>, bool) { + let mut out = Vec::new(); + let mut rest = s; + while let Some(start) = rest.find("{{") { + if start > 0 { + out.push(Tok::Text(&rest[..start])); + } + let after = &rest[start + 2..]; + let Some(end) = after.find("}}") else { + return (out, true); + }; + let inner = &after[..end]; + out.push(if let Some(name) = inner.strip_prefix('#') { + Tok::Open(name) + } else if let Some(name) = inner.strip_prefix('/') { + Tok::Close(name) + } else { + Tok::Var(inner) + }); + rest = &after[end + 2..]; + } + if !rest.is_empty() { + out.push(Tok::Text(rest)); + } + (out, false) +} + +/// Parse `s` into segments. +pub fn parse_template(s: &str) -> Result>, TemplateError> { + let (toks, unclosed) = tokens(s); + let mut out = Vec::new(); + // The open block: its name and the body gathered so far. + let mut open: Option<(&str, Vec>)> = None; + for tok in toks { + match tok { + Tok::Text(t) => match &mut open { + Some((_, body)) => body.push(Segment::Text(t)), + None => out.push(Segment::Text(t)), + }, + Tok::Var(n) => { + if !is_variable_name(n) { + return Err(TemplateError::BadName(n.to_string())); + } + match &mut open { + Some((_, body)) => body.push(Segment::Var(n)), + None => out.push(Segment::Var(n)), + } + } + Tok::Open(n) => { + if !is_variable_name(n) { + return Err(TemplateError::BadName(n.to_string())); + } + if open.is_some() { + return Err(TemplateError::Nested); + } + open = Some((n, Vec::new())); + } + Tok::Close(n) => { + if !is_variable_name(n) { + return Err(TemplateError::BadName(n.to_string())); + } + match open.take() { + Some((name, body)) if name == n => out.push(Segment::Block { name, body }), + _ => return Err(TemplateError::Mismatched(n.to_string())), + } + } + } + } + if unclosed || open.is_some() { + return Err(TemplateError::Unclosed); + } + Ok(out) +} + +/// Every variable name `s` mentions, first-mention order, no repeats. +/// Best effort on a malformed template: the well-formed names it holds. +pub fn template_names(s: &str) -> Vec { + let mut names: Vec = Vec::new(); + for tok in tokens(s).0 { + if let Tok::Var(n) | Tok::Open(n) = tok { + if is_variable_name(n) && !names.iter().any(|x| x == n) { + names.push(n.to_string()); + } + } + } + names +} + +/// Why [`fill`] refused the values. +#[derive(Debug, Clone, PartialEq, Eq, thiserror::Error)] +pub enum FillError { + #[error("the flow declares no variable named {0:?}")] + Unknown(String), + #[error("variable {name:?} is {len} characters; its max_len is {max}")] + TooLong { name: String, max: u64, len: u64 }, + #[error("filling leaves menu {node:?} with no options")] + NoOptions { node: String }, + #[error( + "filling makes a prompt of node {node:?} longer than {} characters", + crate::validate::MAX_PROMPT_CHARS + )] + PromptTooLong { node: String }, +} + +impl FillError { + /// The stable code, shared with the TypeScript twin. + pub fn code(&self) -> &'static str { + match self { + FillError::Unknown(_) => "variable_unknown", + FillError::TooLong { .. } => "variable_too_long", + FillError::NoOptions { .. } => "menu_without_options", + FillError::PromptTooLong { .. } => "prompt_too_long", + } + } +} + +/// A caller's value with control characters stripped, then trimmed of +/// Unicode White_Space plus U+FEFF. Twin: `clean` in `vars.ts`. +fn clean(value: &str) -> String { + value + .chars() + .filter(|c| !c.is_control()) + .collect::() + .trim_matches(|c: char| c.is_whitespace() || c == '\u{FEFF}') + .to_string() +} + +fn render(segments: &[Segment<'_>], effective: &dyn Fn(&str) -> String, out: &mut String) { + for seg in segments { + match seg { + Segment::Text(t) => out.push_str(t), + Segment::Var(n) => out.push_str(&effective(n)), + Segment::Block { name, body } => { + if !effective(name).is_empty() { + render(body, effective, out); + } + } + } + } +} + +/// Turn a flow with variables plus a caller's values into a plain flow the +/// engine can run: every placeholder replaced, `variables` and every audio +/// prompt's `template` gone, and a declared `schema_version` of 4 or more +/// set to 3. Twin: `vars.ts` `fill`. +/// +/// A name's effective value is the caller's (trimmed, control characters +/// stripped) when that is non-empty, else the variable's default; so a blank +/// value falls back to the default and cannot clear it. Values are inserted +/// as text and never parsed again. A menu option whose label is exactly a +/// bare `{{name}}` with an empty effective value is removed, with its exit; +/// any other label is filled and kept; a node left unreachable from `entry` +/// once those exits are gone is removed too. An audio prompt with a `template` +/// stays audio (dropping the template) unless a variable it names got a +/// non-default value; then it becomes the filled text. A v1-v3 flow without +/// variables comes back as a clone. A malformed template is left as written +/// (validation rejects those before fill is reached). +/// +/// Contract: validate the source flow first (`validate_outbound`). The result +/// is a v3 document that validates on its own: a value holding `{{` is plain +/// text in v3, and `fill` keeps options and exits consistent. Errors: +/// `variable_unknown`, `variable_too_long`, `menu_without_options` when every +/// option of a menu would be dropped, and `prompt_too_long` when a filled +/// prompt is longer than validation allows. +pub fn fill(flow: &Flow, values: &BTreeMap) -> Result> { + // No variables before v4: `{{` is ordinary text, so there is nothing to fill. + if flow.variables.is_empty() && values.is_empty() && flow.schema_version < 4 { + return Ok(flow.clone()); + } + let mut errors = Vec::new(); + let mut given: BTreeMap<&str, String> = BTreeMap::new(); + for (name, raw) in values { + let Some(var) = flow.variables.get(name) else { + errors.push(FillError::Unknown(name.clone())); + continue; + }; + let value = clean(raw); + let len = value.chars().count() as u64; + if len > var.max_len.get() { + errors.push(FillError::TooLong { + name: name.clone(), + max: var.max_len.get(), + len, + }); + } else if !value.is_empty() { + given.insert(name, value); + } + } + if !errors.is_empty() { + return Err(errors); + } + let effective = |name: &str| -> String { + given + .get(name) + .cloned() + .or_else(|| flow.variables.get(name).map(|v| v.default.clone())) + .unwrap_or_default() + }; + let fill_text = |text: &str| -> String { + match parse_template(text) { + Ok(segments) => { + let mut out = String::new(); + render(&segments, &effective, &mut out); + out + } + Err(_) => text.to_string(), + } + }; + + let mut out = flow.clone(); + out.variables.clear(); + // Variables and templates are gone, so what is left is a v3 document. + if out.schema_version >= 4 { + out.schema_version = 3; + } + for (node_id, node) in out.nodes.iter_mut() { + let mut too_long = false; + for (_, prompt) in node.prompt_slots_mut() { + match prompt { + Prompt::Text(text) => *text = fill_text(text), + Prompt::Audio { template, .. } => { + let Some(t) = template.take() else { continue }; + let overridden = template_names(&t).iter().any(|n| { + given + .get(n.as_str()) + .is_some_and(|v| flow.variables.get(n).is_none_or(|d| &d.default != v)) + }); + if overridden { + *prompt = Prompt::Text(fill_text(&t)); + } + } + } + if let Prompt::Text(text) = prompt { + too_long |= text.chars().count() > crate::validate::MAX_PROMPT_CHARS; + } + } + if too_long { + errors.push(FillError::PromptTooLong { + node: node_id.clone(), + }); + } + if let Node::Menu { options, exits, .. } = node { + let mut dropped = Vec::new(); + for (key, label) in options.iter_mut() { + let bare = label + .strip_prefix("{{") + .and_then(|l| l.strip_suffix("}}")) + .filter(|n| is_variable_name(n)); + if bare.is_some_and(|n| effective(n).is_empty()) { + dropped.push(key.clone()); + } else { + *label = fill_text(label); + } + } + if !dropped.is_empty() && dropped.len() == options.len() { + errors.push(FillError::NoOptions { + node: node_id.clone(), + }); + continue; + } + for key in dropped { + options.shift_remove(&key); + if let Some(Exits(map)) = exits { + map.shift_remove(&key); + } + } + } + } + if !errors.is_empty() { + return Err(errors); + } + // A dropped option can leave the nodes only it led to unreachable; a + // caller could never get there, so they go too and the result still + // validates on its own. + let reachable: std::collections::BTreeSet = crate::validate::reachable_from_entry(&out) + .into_iter() + .map(str::to_string) + .collect(); + out.nodes.retain(|id, _| reachable.contains(id.as_str())); + Ok(out) +} + +#[cfg(test)] +mod tests { + use super::*; + + #[test] + fn parses_text_vars_and_blocks() { + assert_eq!( + parse_template("Hi {{a}}.{{#b}} B={{b}}{{/b}}").unwrap(), + vec![ + Segment::Text("Hi "), + Segment::Var("a"), + Segment::Text("."), + Segment::Block { + name: "b", + body: vec![Segment::Text(" B="), Segment::Var("b")] + }, + ] + ); + } + + #[test] + fn plain_text_and_stray_closers_pass_through() { + assert_eq!(parse_template("").unwrap(), vec![]); + assert_eq!( + parse_template("a }} b").unwrap(), + vec![Segment::Text("a }} b")] + ); + } + + #[test] + fn rejects_nested_and_unclosed_blocks() { + assert_eq!( + parse_template("{{#a}}{{#b}}{{/b}}{{/a}}"), + Err(TemplateError::Nested) + ); + assert_eq!(parse_template("{{#a}} x"), Err(TemplateError::Unclosed)); + assert_eq!(parse_template("{{a"), Err(TemplateError::Unclosed)); + } + + #[test] + fn rejects_mismatched_closers() { + assert_eq!( + parse_template("{{/a}}"), + Err(TemplateError::Mismatched("a".into())) + ); + assert_eq!( + parse_template("{{#a}}{{/b}}"), + Err(TemplateError::Mismatched("b".into())) + ); + } + + #[test] + fn rejects_bad_names() { + assert_eq!( + parse_template("{{A}}"), + Err(TemplateError::BadName("A".into())) + ); + assert_eq!( + parse_template("{{1a}}"), + Err(TemplateError::BadName("1a".into())) + ); + assert_eq!( + parse_template("{{}}"), + Err(TemplateError::BadName(String::new())) + ); + assert!(parse_template(&format!("{{{{{}}}}}", "a".repeat(32))).is_ok()); + assert!(parse_template(&format!("{{{{{}}}}}", "a".repeat(33))).is_err()); + } + + #[test] + fn brace_edge_cases() { + assert_eq!( + parse_template("{{{a}}}"), + Err(TemplateError::BadName("{a".into())) + ); + assert_eq!( + parse_template("{ {a} }").unwrap(), + vec![Segment::Text("{ {a} }")] + ); + assert_eq!(parse_template("}}").unwrap(), vec![Segment::Text("}}")]); + assert_eq!(parse_template("{{#a}} x {{"), Err(TemplateError::Unclosed)); + } + + #[test] + fn names_are_listed_once_in_order() { + assert_eq!( + template_names("{{b}} {{#a}}{{a}}{{/a}} {{b}}"), + vec!["b".to_string(), "a".to_string()] + ); + } + + const ASK: &str = include_str!("../../../conformance/v4/valid/ask-question.yaml"); + + fn ask() -> Flow { + Flow::from_yaml(ASK).unwrap() + } + + fn vals(pairs: &[(&str, &str)]) -> BTreeMap { + pairs + .iter() + .map(|(k, v)| (k.to_string(), v.to_string())) + .collect() + } + + fn menu(flow: &Flow) -> (String, Vec<(String, String)>, Vec) { + let Node::Menu { + prompt, + options, + exits, + .. + } = &flow.nodes["ask"] + else { + panic!("ask is a menu") + }; + let Prompt::Text(text) = prompt else { + panic!("text prompt") + }; + ( + text.clone(), + options + .iter() + .map(|(k, v)| (k.clone(), v.clone())) + .collect(), + exits.as_ref().unwrap().keys().cloned().collect(), + ) + } + + fn pairs(list: &[(&str, &str)]) -> Vec<(String, String)> { + list.iter() + .map(|(k, v)| (k.to_string(), v.to_string())) + .collect() + } + + #[test] + fn fills_question_and_two_options() { + let filled = fill( + &ask(), + &vals(&[ + ("question", "Which database?"), + ("option1", "Postgres"), + ("option2", "SQLite"), + ]), + ) + .unwrap(); + let (prompt, options, exits) = menu(&filled); + assert_eq!( + prompt, + "Claude has a question. Which database? Press 1 for Postgres. Press 2 for SQLite. Press 9 to hear this again." + ); + assert_eq!( + options, + pairs(&[("1", "Postgres"), ("2", "SQLite"), ("9", "Repeat")]) + ); + assert!(!exits.contains(&"3".to_string()) && !exits.contains(&"4".to_string())); + assert!(filled.variables.is_empty()); + assert_eq!(filled.schema_version, 3); + } + + #[test] + fn keeps_option3_when_given() { + let filled = fill(&ask(), &vals(&[("option3", "Both")])).unwrap(); + let (prompt, options, exits) = menu(&filled); + assert!(prompt.contains(" Press 3 for Both."), "{prompt}"); + assert!(options.contains(&("3".to_string(), "Both".to_string()))); + let Node::Menu { exits: e, .. } = &filled.nodes["ask"] else { + unreachable!() + }; + assert_eq!(e.as_ref().unwrap()["3"], "thanks"); + assert!(!exits.contains(&"4".to_string())); + } + + #[test] + fn no_values_plays_the_defaults() { + let filled = fill(&ask(), &BTreeMap::new()).unwrap(); + let (prompt, options, exits) = menu(&filled); + assert_eq!( + prompt, + "Claude has a question. Claude needs your input on screen. Press 1 for Yes. Press 2 for No. Press 9 to hear this again." + ); + assert_eq!( + options, + pairs(&[("1", "Yes"), ("2", "No"), ("9", "Repeat")]) + ); + assert!(!exits.contains(&"3".to_string()) && !exits.contains(&"4".to_string())); + } + + #[test] + fn rendered_prompt_stays_audio_when_defaults_kept() { + let flow = Flow::from_yaml( + "schema_version: 4\nid: f\nname: F\nentry: a\nvariables:\n name: { default: there }\nnodes:\n a:\n kind: hangup\n prompt: { audio: vprompt_a, template: \"Hi {{name}}\" }\n", + ) + .unwrap(); + let filled = fill(&flow, &BTreeMap::new()).unwrap(); + let Node::Hangup { prompt, .. } = &filled.nodes["a"] else { + unreachable!() + }; + assert!(matches!( + prompt, + Some(Prompt::Audio { audio, template: None, .. }) if audio == "vprompt_a" + )); + // Giving the default itself changes nothing. + let same = fill(&flow, &vals(&[("name", "there")])).unwrap(); + assert!(matches!( + &same.nodes["a"], + Node::Hangup { + prompt: Some(Prompt::Audio { .. }), + .. + } + )); + let filled = fill(&flow, &vals(&[("name", "Ann")])).unwrap(); + let Node::Hangup { prompt, .. } = &filled.nodes["a"] else { + unreachable!() + }; + assert!(matches!(prompt, Some(Prompt::Text(t)) if t == "Hi Ann")); + } + + #[test] + fn blank_value_falls_back_to_default() { + let filled = fill(&ask(), &vals(&[("question", " ")])).unwrap(); + assert!(menu(&filled) + .0 + .contains("Claude needs your input on screen.")); + } + + #[test] + fn control_characters_are_stripped() { + let filled = fill(&ask(), &vals(&[("question", " Hi\u{7}\n there ")])).unwrap(); + assert!(menu(&filled) + .0 + .contains("Claude has a question. Hi there Press")); + } + + #[test] + fn unknown_value_is_an_error() { + let errs = fill(&ask(), &vals(&[("colour", "red")])).unwrap_err(); + assert_eq!(errs, vec![FillError::Unknown("colour".into())]); + assert_eq!(errs[0].code(), "variable_unknown"); + } + + #[test] + fn values_are_not_expanded() { + let filled = fill(&ask(), &vals(&[("question", "{{option1}} {x}")])).unwrap(); + assert!(menu(&filled).0.contains("{{option1}} {x}")); + } + + #[test] + fn max_len_counts_characters() { + let mut flow = ask(); + flow.variables.get_mut("question").unwrap().max_len = 300.try_into().unwrap(); + assert!(fill(&flow, &vals(&[("question", &"问".repeat(150))])).is_ok()); + assert!(fill(&flow, &vals(&[("question", &"问".repeat(300))])).is_ok()); + let errs = fill(&flow, &vals(&[("question", &"问".repeat(301))])).unwrap_err(); + assert_eq!( + errs, + vec![FillError::TooLong { + name: "question".into(), + max: 300, + len: 301 + }] + ); + assert_eq!(errs[0].code(), "variable_too_long"); + } + + #[test] + fn source_validates_and_fill_keeps_hostile_values_literal() { + crate::validate::validate_outbound(&ask()).unwrap(); + let filled = fill(&ask(), &vals(&[("question", "{{option1}} {x}")])).unwrap(); + assert!(menu(&filled).0.contains("{{option1}} {x}")); + } + + #[test] + fn filled_flow_with_braces_in_a_value_validates_as_v3() { + let filled = fill(&ask(), &vals(&[("question", "Is {{x}} {{#y}} ok?")])).unwrap(); + assert_eq!(filled.schema_version, 3); + assert!(menu(&filled).0.contains("Is {{x}} {{#y}} ok?")); + crate::validate::validate_outbound(&filled).unwrap(); + // And it reads back as itself: in v3 the braces are plain text. + let text = filled.to_yaml(); + let back = Flow::from_yaml(&text).unwrap(); + assert_eq!(back.to_yaml(), text); + crate::validate::validate_outbound(&back).unwrap(); + } + + #[test] + fn a_v4_flow_without_variables_still_comes_back_as_v3() { + let flow = Flow::from_yaml( + "schema_version: 4\nid: f\nname: F\nentry: a\nnodes:\n a:\n kind: hangup\n prompt: { audio: vprompt_a, template: Hello }\n", + ) + .unwrap(); + crate::validate::validate_outbound(&flow).unwrap(); + let filled = fill(&flow, &BTreeMap::new()).unwrap(); + assert_eq!(filled.schema_version, 3); + assert!(matches!( + &filled.nodes["a"], + Node::Hangup { + prompt: Some(Prompt::Audio { template: None, .. }), + .. + } + )); + crate::validate::validate_outbound(&filled).unwrap(); + } + + #[test] + fn a_filled_prompt_over_the_limit_is_an_error() { + let flow = Flow::from_yaml( + "schema_version: 4\nid: f\nname: F\nentry: a\nvariables:\n d: { default: \"\", max_len: 500 }\nnodes:\n a:\n kind: hangup\n prompt: \"{{d}}{{d}}{{d}}{{d}}\"\n", + ) + .unwrap(); + // 4 x 500 = 2000: exactly the limit is fine. + assert!(fill(&flow, &vals(&[("d", &"问".repeat(500))])).is_ok()); + let mut over = flow.clone(); + let Node::Hangup { + prompt: Some(Prompt::Text(t)), + .. + } = &mut over.nodes["a"] + else { + unreachable!() + }; + t.push('!'); + let errs = fill(&over, &vals(&[("d", &"问".repeat(500))])).unwrap_err(); + assert_eq!(errs, vec![FillError::PromptTooLong { node: "a".into() }]); + assert_eq!(errs[0].code(), "prompt_too_long"); + } + + #[test] + fn nodes_only_a_dropped_option_reached_are_pruned() { + let flow = Flow::from_yaml( + "schema_version: 4\nid: f\nname: F\nentry: m\nvariables:\n c: { default: \"\" }\nnodes:\n m:\n kind: menu\n prompt: Pick\n options: { \"1\": One, \"3\": \"{{c}}\" }\n exits: { \"1\": end, \"3\": only3, no_input: end, invalid: end }\n only3:\n kind: greeting\n prompt: Three\n exits: { next: deeper }\n deeper:\n kind: hangup\n end:\n kind: hangup\n", + ) + .unwrap(); + crate::validate::validate_outbound(&flow).unwrap(); + let filled = fill(&flow, &BTreeMap::new()).unwrap(); + let ids: Vec<&str> = filled.nodes.keys().map(String::as_str).collect(); + assert_eq!(ids, vec!["m", "end"]); + crate::validate::validate_outbound(&filled).unwrap(); + // Given a value, key 3 and everything behind it stay. + let kept = fill(&flow, &vals(&[("c", "Three")])).unwrap(); + assert_eq!(kept.nodes.len(), 4); + } + + #[test] + fn dropping_every_option_is_an_error() { + let flow = Flow::from_yaml( + "schema_version: 4\nid: f\nname: F\nentry: m\nvariables:\n a: { default: \"\" }\nnodes:\n m:\n kind: menu\n prompt: Pick\n options: { \"1\": \"{{a}}\" }\n exits: { \"1\": m, no_input: m, invalid: m }\n", + ) + .unwrap(); + let errs = fill(&flow, &BTreeMap::new()).unwrap_err(); + assert_eq!(errs, vec![FillError::NoOptions { node: "m".into() }]); + assert_eq!(errs[0].code(), "menu_without_options"); + assert!(fill(&flow, &vals(&[("a", "Yes")])).is_ok()); + } + + #[test] + fn odd_flows_never_panic() { + let base = "schema_version: 4\nid: f\nname: F\nentry: m\nvariables:\n a: { default: \"\" }\n b: { default: x }\nnodes:\n m:\n kind: menu\n"; + // A menu with no exits block at all. + let no_exits = Flow::from_yaml(&format!( + "{base} prompt: Pick\n options: {{ \"1\": \"{{{{a}}}}\", \"2\": Two }}\n" + )) + .unwrap(); + let filled = fill(&no_exits, &BTreeMap::new()).unwrap(); + assert_eq!(menu_options(&filled), vec!["2"]); + // An options key with no matching exit. + let stray = Flow::from_yaml(&format!( + "{base} prompt: Pick\n options: {{ \"1\": \"{{{{a}}}}\", \"2\": Two }}\n exits: {{ no_input: m }}\n" + )) + .unwrap(); + assert_eq!( + menu_options(&fill(&stray, &BTreeMap::new()).unwrap()), + vec!["2"] + ); + // Malformed templates are left as written. + let bad = Flow::from_yaml(&format!( + "{base} prompt: \"Hi {{{{b\"\n options: {{ \"1\": \"{{{{#b}}}}\" }}\n exits: {{ \"1\": m, no_input: m, invalid: m }}\n" + )) + .unwrap(); + let filled = fill(&bad, &vals(&[("b", "y")])).unwrap(); + let Node::Menu { + prompt, options, .. + } = &filled.nodes["m"] + else { + unreachable!() + }; + assert!(matches!(prompt, Prompt::Text(t) if t == "Hi {{b")); + assert_eq!(options["1"], "{{#b}}"); + } + + fn menu_options(flow: &Flow) -> Vec<&str> { + let Node::Menu { options, .. } = &flow.nodes["m"] else { + unreachable!() + }; + options.keys().map(String::as_str).collect() + } + + #[test] + fn a_flow_without_variables_is_returned_unchanged() { + let plain = Flow::from_yaml( + "schema_version: 3\nid: f\nname: F\nentry: a\nnodes:\n a:\n kind: hangup\n prompt: Hi {{x}}\n", + ) + .unwrap(); + assert_eq!( + fill(&plain, &BTreeMap::new()).unwrap().to_yaml(), + plain.to_yaml() + ); + } +} diff --git a/crates/wavekat-flow/tests/canonical.rs b/crates/wavekat-flow/tests/canonical.rs index 92dc629..7d9677d 100644 --- a/crates/wavekat-flow/tests/canonical.rs +++ b/crates/wavekat-flow/tests/canonical.rs @@ -153,6 +153,7 @@ fn voicing_through_prompt_slots() { *prompt = Prompt::Audio { audio: format!("vprompt_{n}"), transcript: Some(text.clone()), + template: None, }; n += 1; } diff --git a/crates/wavekat-flow/tests/conformance.rs b/crates/wavekat-flow/tests/conformance.rs index 7345f36..0d372d6 100644 --- a/crates/wavekat-flow/tests/conformance.rs +++ b/crates/wavekat-flow/tests/conformance.rs @@ -285,3 +285,61 @@ fn outbound_corpus_matches_expectations() { } assert!(ran > 0, "the outbound corpus has no cases"); } + +// The fill corpus: `conformance/fill/.input.yaml` + `.values.json` +// run through `fill`. A success case has `.expected.yaml`, compared with +// the filled flow after canonical serialization; a refusal has +// `.expected.json` = `{"errors": [codes]}` (exact list, in order). +#[test] +fn corpus_fill_matches_expectations() { + let dir = corpus_root().join("fill"); + let mut ran = 0; + for (stem, path) in yaml_cases_in(&dir) { + let Some(case) = stem.strip_suffix(".input") else { + continue; + }; + let flow = Flow::from_yaml(&fs::read_to_string(&path).unwrap()).unwrap(); + let values: std::collections::BTreeMap = serde_json::from_str( + &fs::read_to_string(dir.join(format!("{case}.values.json"))).unwrap(), + ) + .unwrap(); + // Every source is a flow that passes the gate fill expects in front of it. + wavekat_flow::validate::validate_outbound(&flow) + .unwrap_or_else(|e| panic!("fill/{case} source should validate: {e:?}")); + let result = wavekat_flow::vars::fill(&flow, &values); + let expected_yaml = dir.join(format!("{case}.expected.yaml")); + if expected_yaml.exists() { + let filled = result.unwrap_or_else(|e| panic!("fill/{case} should succeed: {e:?}")); + let want = Flow::from_yaml(&fs::read_to_string(expected_yaml).unwrap()).unwrap(); + let text = filled.to_yaml(); + assert_eq!(text, want.to_yaml(), "fill/{case}"); + // The result is a v3 document that validates on its own and + // reads back as itself. + assert_eq!(filled.schema_version, 3, "fill/{case}"); + wavekat_flow::validate::validate_outbound(&filled) + .unwrap_or_else(|e| panic!("fill/{case} result should validate: {e:?}")); + assert_eq!( + Flow::from_yaml(&text).unwrap().to_yaml(), + text, + "fill/{case}" + ); + } else { + #[derive(serde::Deserialize)] + struct Refusal { + errors: Vec, + } + let want: Refusal = serde_json::from_str( + &fs::read_to_string(dir.join(format!("{case}.expected.json"))).unwrap(), + ) + .unwrap(); + let got: Vec = result + .expect_err(&format!("fill/{case} should be refused")) + .iter() + .map(|e| e.code().to_string()) + .collect(); + assert_eq!(got, want.errors, "fill/{case}"); + } + ran += 1; + } + assert!(ran > 0, "the fill corpus has no cases"); +} diff --git a/docs/ROADMAP.md b/docs/ROADMAP.md index d49d6fd..cb83709 100644 --- a/docs/ROADMAP.md +++ b/docs/ROADMAP.md @@ -187,5 +187,5 @@ Trigger: the format is stable enough and the repo is ready to be public. validation dispatches on the document's declared version, and a per-kind minimum version in both validators is what tells an author "bump the version" instead of "fix the typo". `assistant` becomes - version 4: version 3 went to the screened transfer (`transfer` gains - `whisper` and `timeout_secs`). + version 5: version 3 went to the screened transfer (`transfer` gains + `whisper` and `timeout_secs`) and version 4 to flow variables. diff --git a/packages/flow-schema/scripts/generate.mjs b/packages/flow-schema/scripts/generate.mjs index 6134f17..68e357e 100644 --- a/packages/flow-schema/scripts/generate.mjs +++ b/packages/flow-schema/scripts/generate.mjs @@ -24,7 +24,7 @@ const repoRoot = resolve(pkg, '..', '..'); const genDir = resolve(pkg, 'src', 'generated'); // Oldest first; the last entry is the one the model is generated from. -const VERSIONS = [1, 2, 3]; +const VERSIONS = [1, 2, 3, 4]; const schemaPathFor = (v) => resolve(repoRoot, 'schema', `flow.v${v}.schema.json`); await mkdir(genDir, { recursive: true }); diff --git a/packages/flow-schema/src/generated/flow.v4.schema.json b/packages/flow-schema/src/generated/flow.v4.schema.json new file mode 100644 index 0000000..eef6d91 --- /dev/null +++ b/packages/flow-schema/src/generated/flow.v4.schema.json @@ -0,0 +1,307 @@ +{ + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://schema.wavekat.com/flow/v4.json", + "title": "Flow", + "description": "The WaveKat call-flow (\"Receptionist\") document, schema_version 4. Version 4 is version 3 plus flow variables: a top-level `variables` map declares details filled in per call. Every version-3 document is a valid version-4 document once its `schema_version` is bumped, and nothing else changed. This file is the single source of truth for the document SHAPE, and — being the newest version — it is also the file both consumers generate their model types from, so one model covers every supported version. Semantic rules that a JSON Schema cannot express (graph reachability, exit-set exactness, hours/timezone math, DTMF digit validity, prompt length, per-component numeric bounds, and which components a given schema_version may use) are NOT encoded here — they live in each language's validator and are pinned by the shared conformance corpus. Unknown fields are permitted structurally, matching both implementations (Rust serde ignores them; the TS parser surfaces a non-blocking warning).", + "type": "object", + "required": ["schema_version", "id", "name", "entry", "nodes"], + "properties": { + "schema_version": { + "description": "Document format version. This file describes version 4 only; a document declaring another version validates against that version's schema file, not this one. (The type generators relax this constant to a plain integer so the generated model can hold any supported version — see scripts/generate.mjs and build.rs.)", + "type": "integer", + "const": 4 + }, + "id": { + "description": "Opaque platform-assigned id (flow_…). Treated as a label; appears in traces.", + "type": "string" + }, + "name": { + "description": "Human name shown in the editor and the read-only viewer.", + "type": "string" + }, + "version": { + "description": "Platform-assigned publish counter, bumped on publish. Defaults to 1 for a hand-written or generated pre-publish document. Distinct from schema_version.", + "type": "integer", + "minimum": 0, + "default": 1 + }, + "note": { + "description": "The author's note about the whole flow: free text for people reading it, in place of a YAML comment. Never read by the engine.", + "type": "string" + }, + "variables": { + "description": "Details a caller of this flow fills in per call, declared by name (a lowercase letter, then up to 31 lowercase letters, digits or underscores; the validators check the form, not the schema, so a reader never has to compile a pattern). A text prompt, an audio prompt's `template` and a menu option label refer to them with `{{name}}` placeholders and `{{#name}}…{{/name}}` blocks (the block's text is kept only when the value is non-empty; blocks do not nest). The validators check that every placeholder is well formed and names a declared variable, and refuse `{{` in any other field; a `note` is a comment and is never scanned. Before a call runs, the flow is filled: each placeholder becomes the call's value, or the default when the call gives none or a blank one, and the result is a schema_version 3 document with no variables. Needs schema_version 4: a reader that ignored the map would speak the placeholders as written.", + "type": "object", + "additionalProperties": { "$ref": "#/$defs/Variable" } + }, + "entry": { + "description": "Node id where execution begins.", + "type": "string" + }, + "nodes": { + "description": "The flat node set, keyed by human-meaningful node id and string-referenced by exits. Order is irrelevant to execution, but it is the author's reading order and is kept on save.", + "type": "object", + "additionalProperties": { "$ref": "#/$defs/Node" } + }, + "ui": { + "description": "Presentation metadata (canvas positions, annotations). Preserved on round-trip, never read by the engine. Opaque by design so a canvas editor can add layout fields without a schema bump." + } + }, + "$defs": { + "Variable": { + "description": "One declared variable.", + "type": "object", + "required": ["default"], + "properties": { + "description": { + "description": "What the value is, shown to whoever fills it in.", + "type": "string" + }, + "default": { + "description": "The value used when a call supplies none, so a flow always plays with no values given. May be an empty string, for a slot that is optional.", + "type": "string" + }, + "max_len": { + "description": "Longest a value may be, in Unicode characters.", + "type": "integer", + "minimum": 1, + "maximum": 500, + "default": 200 + } + } + }, + "Prompt": { + "description": "What a component speaks: TTS text (a bare string) or a reference to a pre-rendered audio asset shipped alongside the flow.", + "oneOf": [ + { "title": "Text", "type": "string" }, + { + "title": "Audio", + "type": "object", + "required": ["audio"], + "properties": { + "audio": { + "description": "Audio asset ref. A generated-clip ref is a voice_prompts id matching ^vprompt_[a-z0-9]+$.", + "type": "string" + }, + "transcript": { + "description": "The words this pre-rendered clip speaks — the text it was synthesized from — carried so a viewer can show what a caller hears, and for traces. Advisory only: playback always uses `audio`, never this. Optional and forward-added: absent on older documents and on refs the platform did not generate from text.", + "type": "string" + }, + "template": { + "description": "The text with `{{name}}` placeholders that `audio` was voiced from using the variables' defaults. A call that overrides a variable speaks the filled template instead of the clip; a call that does not plays `audio`. Only on an audio prompt, and only from schema_version 4: an older reader ignores it and plays the clip.", + "type": "string" + } + } + } + ] + }, + "MessageTone": { + "description": "The cue a message node plays between its prompt and the start of recording.", + "type": "string", + "enum": ["beep", "none"] + }, + "Exits": { + "description": "Wired exits: exit name → target node id. Which names are valid is a property of the node's kind and is checked by the validator, not by this schema.", + "type": "object", + "additionalProperties": { "type": "string" } + }, + "TimeRange": { + "description": "One open window: open–close as \"HH:MM\" (24-hour). Ordering and overnight rules are enforced by the validator.", + "type": "object", + "required": ["open", "close"], + "properties": { + "open": { "type": "string" }, + "close": { "type": "string" } + } + }, + "WeeklySchedule": { + "description": "Open ranges per weekday; a missing or empty day means closed all day.", + "type": "object", + "properties": { + "mon": { "type": "array", "items": { "$ref": "#/$defs/TimeRange" } }, + "tue": { "type": "array", "items": { "$ref": "#/$defs/TimeRange" } }, + "wed": { "type": "array", "items": { "$ref": "#/$defs/TimeRange" } }, + "thu": { "type": "array", "items": { "$ref": "#/$defs/TimeRange" } }, + "fri": { "type": "array", "items": { "$ref": "#/$defs/TimeRange" } }, + "sat": { "type": "array", "items": { "$ref": "#/$defs/TimeRange" } }, + "sun": { "type": "array", "items": { "$ref": "#/$defs/TimeRange" } } + } + }, + "HoursException": { + "description": "A single-date override of the weekly schedule (holiday / special hours).", + "type": "object", + "required": ["date"], + "properties": { + "date": { "description": "\"YYYY-MM-DD\" in the flow's timezone.", "type": "string" }, + "closed": { "description": "Closed all day regardless of ranges.", "type": "boolean", "default": false }, + "ranges": { "type": "array", "items": { "$ref": "#/$defs/TimeRange" } } + } + }, + "Node": { + "description": "One node: a component (kind + its config) plus its wired exits. An internally-tagged union on `kind`.", + "oneOf": [ + { "$ref": "#/$defs/GreetingNode" }, + { "$ref": "#/$defs/HoursNode" }, + { "$ref": "#/$defs/MenuNode" }, + { "$ref": "#/$defs/RingNode" }, + { "$ref": "#/$defs/MessageNode" }, + { "$ref": "#/$defs/TransferNode" }, + { "$ref": "#/$defs/HangupNode" }, + { "$ref": "#/$defs/BookNode" } + ] + }, + "GreetingNode": { + "description": "Speak a prompt, then continue. Exit: next.", + "type": "object", + "required": ["kind", "prompt"], + "properties": { + "kind": { "const": "greeting" }, + "note": { "description": "The author's note about this step: free text for people reading the flow, in place of a YAML comment. Never read by the engine.", "type": "string" }, + "prompt": { "$ref": "#/$defs/Prompt" }, + "exits": { "$ref": "#/$defs/Exits" } + } + }, + "HoursNode": { + "description": "Branch on the business's weekly schedule + holiday overrides. Exits: open, closed.", + "type": "object", + "required": ["kind", "schedule", "timezone"], + "properties": { + "kind": { "const": "hours" }, + "note": { "description": "The author's note about this step: free text for people reading the flow, in place of a YAML comment. Never read by the engine.", "type": "string" }, + "schedule": { "$ref": "#/$defs/WeeklySchedule" }, + "timezone": { "description": "IANA zone (America/New_York). Validated to resolve at load.", "type": "string" }, + "exceptions": { "type": "array", "items": { "$ref": "#/$defs/HoursException" } }, + "exits": { "$ref": "#/$defs/Exits" } + } + }, + "MenuNode": { + "description": "Speak a prompt and collect a DTMF choice. Exits: one per digit in options, plus no_input and invalid.", + "type": "object", + "required": ["kind", "prompt", "options"], + "properties": { + "kind": { "const": "menu" }, + "note": { "description": "The author's note about this step: free text for people reading the flow, in place of a YAML comment. Never read by the engine.", "type": "string" }, + "prompt": { "$ref": "#/$defs/Prompt" }, + "options": { + "description": "Digit key → human label. The exit for a digit is exits[digit]. Valid digit keys are enforced by the validator. A label may hold placeholders; one that is exactly a bare `{{name}}` whose filled value is empty removes the option, its exit, and any step only that exit led to, from the call.", + "type": "object", + "additionalProperties": { "type": "string" } + }, + "retries": { "type": "integer", "minimum": 0, "default": 1 }, + "timeout_secs": { "type": "integer", "minimum": 0, "default": 5 }, + "exits": { "$ref": "#/$defs/Exits" } + } + }, + "RingNode": { + "description": "Ring the human for a window. answered is an implicit terminal; the only wired exit is no_answer.", + "type": "object", + "required": ["kind", "timeout_secs"], + "properties": { + "kind": { "const": "ring" }, + "note": { "description": "The author's note about this step: free text for people reading the flow, in place of a YAML comment. Never read by the engine.", "type": "string" }, + "timeout_secs": { "type": "integer", "minimum": 0 }, + "exits": { "$ref": "#/$defs/Exits" } + } + }, + "MessageNode": { + "description": "Voicemail: speak a prompt, record, transcribe, notify. Terminal.", + "type": "object", + "required": ["kind", "prompt"], + "properties": { + "kind": { "const": "message" }, + "note": { "description": "The author's note about this step: free text for people reading the flow, in place of a YAML comment. Never read by the engine.", "type": "string" }, + "prompt": { "$ref": "#/$defs/Prompt" }, + "max_secs": { "type": "integer", "minimum": 0, "default": 120 }, + "tone": { "allOf": [{ "$ref": "#/$defs/MessageTone" }], "default": "beep" }, + "exits": { "$ref": "#/$defs/Exits" } + } + }, + "TransferNode": { + "description": "Hand the call to an external number. With `whisper`, a screened transfer: call the target first, play the whisper, and connect only when they accept; otherwise take `no_answer`. Without it, a blind transfer (terminal). `whisper` is spoken to the person at the target before they are connected, and `timeout_secs` is how long to let the target ring or decide. Both apply only to a screened transfer.", + "type": "object", + "required": ["kind", "target"], + "properties": { + "kind": { "const": "transfer" }, + "note": { "description": "The author's note about this step: free text for people reading the flow, in place of a YAML comment. Never read by the engine.", "type": "string" }, + "target": { "type": "string" }, + "whisper": { "$ref": "#/$defs/Prompt" }, + "timeout_secs": { "type": "integer", "minimum": 5, "maximum": 120 }, + "exits": { "$ref": "#/$defs/Exits" } + } + }, + "HangupNode": { + "description": "Speak an optional goodbye and end the call. Terminal.", + "type": "object", + "required": ["kind"], + "properties": { + "kind": { "const": "hangup" }, + "note": { "description": "The author's note about this step: free text for people reading the flow, in place of a YAML comment. Never read by the engine.", "type": "string" }, + "prompt": { "$ref": "#/$defs/Prompt" }, + "exits": { "$ref": "#/$defs/Exits" } + } + }, + "BookNode": { + "description": "Offer the caller open appointment times and book the one they choose, before the call ends. New in schema_version 2. The bookable grid is described here (weekly schedule + timezone + how long an appointment is); which times are actually free comes from the connected calendar at call time, and the engine never sees a credential. Exits: booked, no_slots, no_input, unavailable. Three fields carry more meaning than their types show, and are described here because a `$ref` with a sibling description makes the type generators emit a duplicate type instead of reusing the named one. `prompt` is spoken once before the open times are offered (\"I can book you in — here are the next available times\"); the times themselves are never part of it, since they are not known until the call. `confirm_prompt` is spoken immediately after a successful booking and directly BEFORE the booked time (\"You're booked for\" → \"Tuesday\" → \"ten thirty a.m.\"); it deliberately takes no placeholder, because a prompt is frozen audio by the time a call runs and nothing can be interpolated into the middle of it — anything that should follow the time belongs on the booked exit. `schedule` is when this business takes appointments, the `hours` node's weekly shape reused verbatim; it is not the same question `hours` answers, because a business can answer the phone at times it will not book.", + "type": "object", + "required": ["kind", "prompt", "confirm_prompt", "schedule", "timezone", "duration_mins"], + "properties": { + "kind": { "const": "book" }, + "note": { "description": "The author's note about this step: free text for people reading the flow, in place of a YAML comment. Never read by the engine.", "type": "string" }, + "prompt": { "$ref": "#/$defs/Prompt" }, + "confirm_prompt": { "$ref": "#/$defs/Prompt" }, + "schedule": { "$ref": "#/$defs/WeeklySchedule" }, + "timezone": { + "description": "IANA zone (America/New_York) the schedule is written in. Validated to resolve at load.", + "type": "string" + }, + "exceptions": { + "description": "Single-date overrides of the weekly schedule (holidays, one-off clinics), as on `hours`.", + "type": "array", + "items": { "$ref": "#/$defs/HoursException" } + }, + "duration_mins": { + "description": "How long one appointment runs. Bounds are the validator's (see each language's validate module), not this schema's.", + "type": "integer", + "minimum": 0 + }, + "buffer_mins": { + "description": "Clear time kept on BOTH sides of an appointment, so a slot is not offered flush against a busy interval.", + "type": "integer", + "minimum": 0, + "default": 0 + }, + "lead_mins": { + "description": "Nothing sooner than this many minutes from now is offered — the caller cannot book the next five minutes.", + "type": "integer", + "minimum": 0, + "default": 120 + }, + "horizon_days": { + "description": "How far ahead to look for open times.", + "type": "integer", + "minimum": 0, + "default": 14 + }, + "max_offers": { + "description": "How many times to offer the caller. Each offered time gets one keypad digit, counting from 1.", + "type": "integer", + "minimum": 0, + "default": 3 + }, + "retries": { + "description": "Extra attempts to collect a keypress after the first, as on `menu`.", + "type": "integer", + "minimum": 0, + "default": 1 + }, + "timeout_secs": { + "description": "How long to wait for a keypress on each attempt, as on `menu`.", + "type": "integer", + "minimum": 0, + "default": 5 + }, + "exits": { "$ref": "#/$defs/Exits" } + } + } + } +} diff --git a/packages/flow-schema/src/generated/model.ts b/packages/flow-schema/src/generated/model.ts index 06966e4..4746d00 100644 --- a/packages/flow-schema/src/generated/model.ts +++ b/packages/flow-schema/src/generated/model.ts @@ -1,4 +1,4 @@ -// GENERATED from schema/flow.v{1,2,3}.schema.json by scripts/generate.mjs — do not edit. +// GENERATED from schema/flow.v{1,2,3,4}.schema.json by scripts/generate.mjs — do not edit. // Run `pnpm gen` after changing a schema; CI fails on drift. /** @@ -16,11 +16,11 @@ export type Text = string; export type MessageTone = 'beep' | 'none'; /** - * The WaveKat call-flow ("Receptionist") document, schema_version 3. Version 3 is version 2 plus the screened transfer: the `transfer` node gains `whisper` and `timeout_secs`. Every version-2 document is a valid version-3 document once its `schema_version` is bumped, and nothing else changed. This file is the single source of truth for the document SHAPE, and — being the newest version — it is also the file both consumers generate their model types from, so one model covers every supported version. Semantic rules that a JSON Schema cannot express (graph reachability, exit-set exactness, hours/timezone math, DTMF digit validity, prompt length, per-component numeric bounds, and which components a given schema_version may use) are NOT encoded here — they live in each language's validator and are pinned by the shared conformance corpus. Unknown fields are permitted structurally, matching both implementations (Rust serde ignores them; the TS parser surfaces a non-blocking warning). + * The WaveKat call-flow ("Receptionist") document, schema_version 4. Version 4 is version 3 plus flow variables: a top-level `variables` map declares details filled in per call. Every version-3 document is a valid version-4 document once its `schema_version` is bumped, and nothing else changed. This file is the single source of truth for the document SHAPE, and — being the newest version — it is also the file both consumers generate their model types from, so one model covers every supported version. Semantic rules that a JSON Schema cannot express (graph reachability, exit-set exactness, hours/timezone math, DTMF digit validity, prompt length, per-component numeric bounds, and which components a given schema_version may use) are NOT encoded here — they live in each language's validator and are pinned by the shared conformance corpus. Unknown fields are permitted structurally, matching both implementations (Rust serde ignores them; the TS parser surfaces a non-blocking warning). */ export interface Flow { /** - * Document format version. This file describes version 3 only; a document declaring another version validates against that version's schema file, not this one. (The type generators relax this constant to a plain integer so the generated model can hold any supported version — see scripts/generate.mjs and build.rs.) (Relaxed from a constant to a plain integer for type generation: one model type covers every supported version.) + * Document format version. This file describes version 4 only; a document declaring another version validates against that version's schema file, not this one. (The type generators relax this constant to a plain integer so the generated model can hold any supported version — see scripts/generate.mjs and build.rs.) (Relaxed from a constant to a plain integer for type generation: one model type covers every supported version.) */ schema_version: number; /** @@ -39,6 +39,12 @@ export interface Flow { * The author's note about the whole flow: free text for people reading it, in place of a YAML comment. Never read by the engine. */ note?: string; + /** + * Details a caller of this flow fills in per call, declared by name (a lowercase letter, then up to 31 lowercase letters, digits or underscores; the validators check the form, not the schema, so a reader never has to compile a pattern). A text prompt, an audio prompt's `template` and a menu option label refer to them with `{{name}}` placeholders and `{{#name}}…{{/name}}` blocks (the block's text is kept only when the value is non-empty; blocks do not nest). The validators check that every placeholder is well formed and names a declared variable, and refuse `{{` in any other field; a `note` is a comment and is never scanned. Before a call runs, the flow is filled: each placeholder becomes the call's value, or the default when the call gives none or a blank one, and the result is a schema_version 3 document with no variables. Needs schema_version 4: a reader that ignored the map would speak the placeholders as written. + */ + variables?: { + [k: string]: Variable; + }; /** * Node id where execution begins. */ @@ -57,6 +63,24 @@ export interface Flow { }; [k: string]: unknown; } +/** + * One declared variable. + */ +export interface Variable { + /** + * What the value is, shown to whoever fills it in. + */ + description?: string; + /** + * The value used when a call supplies none, so a flow always plays with no values given. May be an empty string, for a slot that is optional. + */ + default: string; + /** + * Longest a value may be, in Unicode characters. + */ + max_len?: number; + [k: string]: unknown; +} /** * Speak a prompt, then continue. Exit: next. */ @@ -79,6 +103,10 @@ export interface Audio { * The words this pre-rendered clip speaks — the text it was synthesized from — carried so a viewer can show what a caller hears, and for traces. Advisory only: playback always uses `audio`, never this. Optional and forward-added: absent on older documents and on refs the platform did not generate from text. */ transcript?: string; + /** + * The text with `{{name}}` placeholders that `audio` was voiced from using the variables' defaults. A call that overrides a variable speaks the filled template instead of the clip; a call that does not plays `audio`. Only on an audio prompt, and only from schema_version 4: an older reader ignores it and plays the clip. + */ + template?: string; [k: string]: unknown; } /** @@ -152,7 +180,7 @@ export interface MenuNode { note?: string; prompt: Prompt; /** - * Digit key → human label. The exit for a digit is exits[digit]. Valid digit keys are enforced by the validator. + * Digit key → human label. The exit for a digit is exits[digit]. Valid digit keys are enforced by the validator. A label may hold placeholders; one that is exactly a bare `{{name}}` whose filled value is empty removes the option, its exit, and any step only that exit led to, from the call. */ options: { [k: string]: string; diff --git a/packages/flow-schema/src/generated/schema.ts b/packages/flow-schema/src/generated/schema.ts index 9d804ae..5758af6 100644 --- a/packages/flow-schema/src/generated/schema.ts +++ b/packages/flow-schema/src/generated/schema.ts @@ -1,4 +1,4 @@ -// GENERATED from schema/flow.v{1,2,3}.schema.json by scripts/generate.mjs — do not edit. +// GENERATED from schema/flow.v{1,2,3,4}.schema.json by scripts/generate.mjs — do not edit. // Run `pnpm gen` after changing a schema; CI fails on drift. export const flowV1Schema = { @@ -1427,5 +1427,550 @@ export const flowV3Schema = { } } as const; +export const flowV4Schema = { + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://schema.wavekat.com/flow/v4.json", + "title": "Flow", + "description": "The WaveKat call-flow (\"Receptionist\") document, schema_version 4. Version 4 is version 3 plus flow variables: a top-level `variables` map declares details filled in per call. Every version-3 document is a valid version-4 document once its `schema_version` is bumped, and nothing else changed. This file is the single source of truth for the document SHAPE, and — being the newest version — it is also the file both consumers generate their model types from, so one model covers every supported version. Semantic rules that a JSON Schema cannot express (graph reachability, exit-set exactness, hours/timezone math, DTMF digit validity, prompt length, per-component numeric bounds, and which components a given schema_version may use) are NOT encoded here — they live in each language's validator and are pinned by the shared conformance corpus. Unknown fields are permitted structurally, matching both implementations (Rust serde ignores them; the TS parser surfaces a non-blocking warning).", + "type": "object", + "required": [ + "schema_version", + "id", + "name", + "entry", + "nodes" + ], + "properties": { + "schema_version": { + "description": "Document format version. This file describes version 4 only; a document declaring another version validates against that version's schema file, not this one. (The type generators relax this constant to a plain integer so the generated model can hold any supported version — see scripts/generate.mjs and build.rs.)", + "type": "integer", + "const": 4 + }, + "id": { + "description": "Opaque platform-assigned id (flow_…). Treated as a label; appears in traces.", + "type": "string" + }, + "name": { + "description": "Human name shown in the editor and the read-only viewer.", + "type": "string" + }, + "version": { + "description": "Platform-assigned publish counter, bumped on publish. Defaults to 1 for a hand-written or generated pre-publish document. Distinct from schema_version.", + "type": "integer", + "minimum": 0, + "default": 1 + }, + "note": { + "description": "The author's note about the whole flow: free text for people reading it, in place of a YAML comment. Never read by the engine.", + "type": "string" + }, + "variables": { + "description": "Details a caller of this flow fills in per call, declared by name (a lowercase letter, then up to 31 lowercase letters, digits or underscores; the validators check the form, not the schema, so a reader never has to compile a pattern). A text prompt, an audio prompt's `template` and a menu option label refer to them with `{{name}}` placeholders and `{{#name}}…{{/name}}` blocks (the block's text is kept only when the value is non-empty; blocks do not nest). The validators check that every placeholder is well formed and names a declared variable, and refuse `{{` in any other field; a `note` is a comment and is never scanned. Before a call runs, the flow is filled: each placeholder becomes the call's value, or the default when the call gives none or a blank one, and the result is a schema_version 3 document with no variables. Needs schema_version 4: a reader that ignored the map would speak the placeholders as written.", + "type": "object", + "additionalProperties": { + "$ref": "#/$defs/Variable" + } + }, + "entry": { + "description": "Node id where execution begins.", + "type": "string" + }, + "nodes": { + "description": "The flat node set, keyed by human-meaningful node id and string-referenced by exits. Order is irrelevant to execution, but it is the author's reading order and is kept on save.", + "type": "object", + "additionalProperties": { + "$ref": "#/$defs/Node" + } + }, + "ui": { + "description": "Presentation metadata (canvas positions, annotations). Preserved on round-trip, never read by the engine. Opaque by design so a canvas editor can add layout fields without a schema bump." + } + }, + "$defs": { + "Variable": { + "description": "One declared variable.", + "type": "object", + "required": [ + "default" + ], + "properties": { + "description": { + "description": "What the value is, shown to whoever fills it in.", + "type": "string" + }, + "default": { + "description": "The value used when a call supplies none, so a flow always plays with no values given. May be an empty string, for a slot that is optional.", + "type": "string" + }, + "max_len": { + "description": "Longest a value may be, in Unicode characters.", + "type": "integer", + "minimum": 1, + "maximum": 500, + "default": 200 + } + } + }, + "Prompt": { + "description": "What a component speaks: TTS text (a bare string) or a reference to a pre-rendered audio asset shipped alongside the flow.", + "oneOf": [ + { + "title": "Text", + "type": "string" + }, + { + "title": "Audio", + "type": "object", + "required": [ + "audio" + ], + "properties": { + "audio": { + "description": "Audio asset ref. A generated-clip ref is a voice_prompts id matching ^vprompt_[a-z0-9]+$.", + "type": "string" + }, + "transcript": { + "description": "The words this pre-rendered clip speaks — the text it was synthesized from — carried so a viewer can show what a caller hears, and for traces. Advisory only: playback always uses `audio`, never this. Optional and forward-added: absent on older documents and on refs the platform did not generate from text.", + "type": "string" + }, + "template": { + "description": "The text with `{{name}}` placeholders that `audio` was voiced from using the variables' defaults. A call that overrides a variable speaks the filled template instead of the clip; a call that does not plays `audio`. Only on an audio prompt, and only from schema_version 4: an older reader ignores it and plays the clip.", + "type": "string" + } + } + } + ] + }, + "MessageTone": { + "description": "The cue a message node plays between its prompt and the start of recording.", + "type": "string", + "enum": [ + "beep", + "none" + ] + }, + "Exits": { + "description": "Wired exits: exit name → target node id. Which names are valid is a property of the node's kind and is checked by the validator, not by this schema.", + "type": "object", + "additionalProperties": { + "type": "string" + } + }, + "TimeRange": { + "description": "One open window: open–close as \"HH:MM\" (24-hour). Ordering and overnight rules are enforced by the validator.", + "type": "object", + "required": [ + "open", + "close" + ], + "properties": { + "open": { + "type": "string" + }, + "close": { + "type": "string" + } + } + }, + "WeeklySchedule": { + "description": "Open ranges per weekday; a missing or empty day means closed all day.", + "type": "object", + "properties": { + "mon": { + "type": "array", + "items": { + "$ref": "#/$defs/TimeRange" + } + }, + "tue": { + "type": "array", + "items": { + "$ref": "#/$defs/TimeRange" + } + }, + "wed": { + "type": "array", + "items": { + "$ref": "#/$defs/TimeRange" + } + }, + "thu": { + "type": "array", + "items": { + "$ref": "#/$defs/TimeRange" + } + }, + "fri": { + "type": "array", + "items": { + "$ref": "#/$defs/TimeRange" + } + }, + "sat": { + "type": "array", + "items": { + "$ref": "#/$defs/TimeRange" + } + }, + "sun": { + "type": "array", + "items": { + "$ref": "#/$defs/TimeRange" + } + } + } + }, + "HoursException": { + "description": "A single-date override of the weekly schedule (holiday / special hours).", + "type": "object", + "required": [ + "date" + ], + "properties": { + "date": { + "description": "\"YYYY-MM-DD\" in the flow's timezone.", + "type": "string" + }, + "closed": { + "description": "Closed all day regardless of ranges.", + "type": "boolean", + "default": false + }, + "ranges": { + "type": "array", + "items": { + "$ref": "#/$defs/TimeRange" + } + } + } + }, + "Node": { + "description": "One node: a component (kind + its config) plus its wired exits. An internally-tagged union on `kind`.", + "oneOf": [ + { + "$ref": "#/$defs/GreetingNode" + }, + { + "$ref": "#/$defs/HoursNode" + }, + { + "$ref": "#/$defs/MenuNode" + }, + { + "$ref": "#/$defs/RingNode" + }, + { + "$ref": "#/$defs/MessageNode" + }, + { + "$ref": "#/$defs/TransferNode" + }, + { + "$ref": "#/$defs/HangupNode" + }, + { + "$ref": "#/$defs/BookNode" + } + ] + }, + "GreetingNode": { + "description": "Speak a prompt, then continue. Exit: next.", + "type": "object", + "required": [ + "kind", + "prompt" + ], + "properties": { + "kind": { + "const": "greeting" + }, + "note": { + "description": "The author's note about this step: free text for people reading the flow, in place of a YAML comment. Never read by the engine.", + "type": "string" + }, + "prompt": { + "$ref": "#/$defs/Prompt" + }, + "exits": { + "$ref": "#/$defs/Exits" + } + } + }, + "HoursNode": { + "description": "Branch on the business's weekly schedule + holiday overrides. Exits: open, closed.", + "type": "object", + "required": [ + "kind", + "schedule", + "timezone" + ], + "properties": { + "kind": { + "const": "hours" + }, + "note": { + "description": "The author's note about this step: free text for people reading the flow, in place of a YAML comment. Never read by the engine.", + "type": "string" + }, + "schedule": { + "$ref": "#/$defs/WeeklySchedule" + }, + "timezone": { + "description": "IANA zone (America/New_York). Validated to resolve at load.", + "type": "string" + }, + "exceptions": { + "type": "array", + "items": { + "$ref": "#/$defs/HoursException" + } + }, + "exits": { + "$ref": "#/$defs/Exits" + } + } + }, + "MenuNode": { + "description": "Speak a prompt and collect a DTMF choice. Exits: one per digit in options, plus no_input and invalid.", + "type": "object", + "required": [ + "kind", + "prompt", + "options" + ], + "properties": { + "kind": { + "const": "menu" + }, + "note": { + "description": "The author's note about this step: free text for people reading the flow, in place of a YAML comment. Never read by the engine.", + "type": "string" + }, + "prompt": { + "$ref": "#/$defs/Prompt" + }, + "options": { + "description": "Digit key → human label. The exit for a digit is exits[digit]. Valid digit keys are enforced by the validator. A label may hold placeholders; one that is exactly a bare `{{name}}` whose filled value is empty removes the option, its exit, and any step only that exit led to, from the call.", + "type": "object", + "additionalProperties": { + "type": "string" + } + }, + "retries": { + "type": "integer", + "minimum": 0, + "default": 1 + }, + "timeout_secs": { + "type": "integer", + "minimum": 0, + "default": 5 + }, + "exits": { + "$ref": "#/$defs/Exits" + } + } + }, + "RingNode": { + "description": "Ring the human for a window. answered is an implicit terminal; the only wired exit is no_answer.", + "type": "object", + "required": [ + "kind", + "timeout_secs" + ], + "properties": { + "kind": { + "const": "ring" + }, + "note": { + "description": "The author's note about this step: free text for people reading the flow, in place of a YAML comment. Never read by the engine.", + "type": "string" + }, + "timeout_secs": { + "type": "integer", + "minimum": 0 + }, + "exits": { + "$ref": "#/$defs/Exits" + } + } + }, + "MessageNode": { + "description": "Voicemail: speak a prompt, record, transcribe, notify. Terminal.", + "type": "object", + "required": [ + "kind", + "prompt" + ], + "properties": { + "kind": { + "const": "message" + }, + "note": { + "description": "The author's note about this step: free text for people reading the flow, in place of a YAML comment. Never read by the engine.", + "type": "string" + }, + "prompt": { + "$ref": "#/$defs/Prompt" + }, + "max_secs": { + "type": "integer", + "minimum": 0, + "default": 120 + }, + "tone": { + "allOf": [ + { + "$ref": "#/$defs/MessageTone" + } + ], + "default": "beep" + }, + "exits": { + "$ref": "#/$defs/Exits" + } + } + }, + "TransferNode": { + "description": "Hand the call to an external number. With `whisper`, a screened transfer: call the target first, play the whisper, and connect only when they accept; otherwise take `no_answer`. Without it, a blind transfer (terminal). `whisper` is spoken to the person at the target before they are connected, and `timeout_secs` is how long to let the target ring or decide. Both apply only to a screened transfer.", + "type": "object", + "required": [ + "kind", + "target" + ], + "properties": { + "kind": { + "const": "transfer" + }, + "note": { + "description": "The author's note about this step: free text for people reading the flow, in place of a YAML comment. Never read by the engine.", + "type": "string" + }, + "target": { + "type": "string" + }, + "whisper": { + "$ref": "#/$defs/Prompt" + }, + "timeout_secs": { + "type": "integer", + "minimum": 5, + "maximum": 120 + }, + "exits": { + "$ref": "#/$defs/Exits" + } + } + }, + "HangupNode": { + "description": "Speak an optional goodbye and end the call. Terminal.", + "type": "object", + "required": [ + "kind" + ], + "properties": { + "kind": { + "const": "hangup" + }, + "note": { + "description": "The author's note about this step: free text for people reading the flow, in place of a YAML comment. Never read by the engine.", + "type": "string" + }, + "prompt": { + "$ref": "#/$defs/Prompt" + }, + "exits": { + "$ref": "#/$defs/Exits" + } + } + }, + "BookNode": { + "description": "Offer the caller open appointment times and book the one they choose, before the call ends. New in schema_version 2. The bookable grid is described here (weekly schedule + timezone + how long an appointment is); which times are actually free comes from the connected calendar at call time, and the engine never sees a credential. Exits: booked, no_slots, no_input, unavailable. Three fields carry more meaning than their types show, and are described here because a `$ref` with a sibling description makes the type generators emit a duplicate type instead of reusing the named one. `prompt` is spoken once before the open times are offered (\"I can book you in — here are the next available times\"); the times themselves are never part of it, since they are not known until the call. `confirm_prompt` is spoken immediately after a successful booking and directly BEFORE the booked time (\"You're booked for\" → \"Tuesday\" → \"ten thirty a.m.\"); it deliberately takes no placeholder, because a prompt is frozen audio by the time a call runs and nothing can be interpolated into the middle of it — anything that should follow the time belongs on the booked exit. `schedule` is when this business takes appointments, the `hours` node's weekly shape reused verbatim; it is not the same question `hours` answers, because a business can answer the phone at times it will not book.", + "type": "object", + "required": [ + "kind", + "prompt", + "confirm_prompt", + "schedule", + "timezone", + "duration_mins" + ], + "properties": { + "kind": { + "const": "book" + }, + "note": { + "description": "The author's note about this step: free text for people reading the flow, in place of a YAML comment. Never read by the engine.", + "type": "string" + }, + "prompt": { + "$ref": "#/$defs/Prompt" + }, + "confirm_prompt": { + "$ref": "#/$defs/Prompt" + }, + "schedule": { + "$ref": "#/$defs/WeeklySchedule" + }, + "timezone": { + "description": "IANA zone (America/New_York) the schedule is written in. Validated to resolve at load.", + "type": "string" + }, + "exceptions": { + "description": "Single-date overrides of the weekly schedule (holidays, one-off clinics), as on `hours`.", + "type": "array", + "items": { + "$ref": "#/$defs/HoursException" + } + }, + "duration_mins": { + "description": "How long one appointment runs. Bounds are the validator's (see each language's validate module), not this schema's.", + "type": "integer", + "minimum": 0 + }, + "buffer_mins": { + "description": "Clear time kept on BOTH sides of an appointment, so a slot is not offered flush against a busy interval.", + "type": "integer", + "minimum": 0, + "default": 0 + }, + "lead_mins": { + "description": "Nothing sooner than this many minutes from now is offered — the caller cannot book the next five minutes.", + "type": "integer", + "minimum": 0, + "default": 120 + }, + "horizon_days": { + "description": "How far ahead to look for open times.", + "type": "integer", + "minimum": 0, + "default": 14 + }, + "max_offers": { + "description": "How many times to offer the caller. Each offered time gets one keypad digit, counting from 1.", + "type": "integer", + "minimum": 0, + "default": 3 + }, + "retries": { + "description": "Extra attempts to collect a keypress after the first, as on `menu`.", + "type": "integer", + "minimum": 0, + "default": 1 + }, + "timeout_secs": { + "description": "How long to wait for a keypress on each attempt, as on `menu`.", + "type": "integer", + "minimum": 0, + "default": 5 + }, + "exits": { + "$ref": "#/$defs/Exits" + } + } + } + } +} as const; + /** Newest supported version's schema. */ -export default flowV3Schema; +export default flowV4Schema; diff --git a/packages/flow-schema/src/index.ts b/packages/flow-schema/src/index.ts index 4c7e3dd..70dcef5 100644 --- a/packages/flow-schema/src/index.ts +++ b/packages/flow-schema/src/index.ts @@ -21,14 +21,14 @@ // which crashes code-gen-disallowed runtimes (Cloudflare Workers) at // import time. It lives behind the `@wavekat/flow-schema/structure` // subpath so this barrel stays Ajv-free and safe to bundle on the edge. -import { flowV1Schema, flowV2Schema, flowV3Schema } from './generated/schema.js'; +import { flowV1Schema, flowV2Schema, flowV3Schema, flowV4Schema } from './generated/schema.js'; // Model: generated types + hand-written constants & helpers. export * from './model.js'; // The `book` component: its bounds, and the vocabulary a frozen-audio // device speaks a time with. export * from './book.js'; -export { flowV1Schema, flowV2Schema, flowV3Schema }; +export { flowV1Schema, flowV2Schema, flowV3Schema, flowV4Schema }; // Structural diff between two flows (authoring-only, TS-only — like mutate.ts). export type { FieldChange, FlowDiff, FlowDiffStatus, NodeDiff } from './diff.js'; @@ -64,3 +64,14 @@ export { setSchemaVersion, stampIdentity, } from './mutate.js'; + +export { + fill, + isVariableName, + parseTemplate, + templateErrorCode, + templateIssues, + templateNames, + tryParseTemplate, +} from './vars.js'; +export type { FillError, Segment, TemplateError } from './vars.js'; diff --git a/packages/flow-schema/src/model.ts b/packages/flow-schema/src/model.ts index fa417a2..45c31b1 100644 --- a/packages/flow-schema/src/model.ts +++ b/packages/flow-schema/src/model.ts @@ -27,6 +27,7 @@ export type { RingNode, TimeRange, TransferNode, + Variable, WeeklySchedule, } from './generated/model.js'; @@ -52,13 +53,13 @@ export type Component = Node; /** Schema versions this validator understands. Twin: `lib.rs` * `SUPPORTED_SCHEMA_VERSIONS`. */ -export const SUPPORTED_SCHEMA_VERSIONS: readonly number[] = [1, 2, 3]; +export const SUPPORTED_SCHEMA_VERSIONS: readonly number[] = [1, 2, 3, 4]; /** The newest version this build authors — what a new document should * declare. Reading stays broad ({@link SUPPORTED_SCHEMA_VERSIONS}); * writing is deliberately one number. Twin: `lib.rs` * `CURRENT_SCHEMA_VERSION`. */ -export const CURRENT_SCHEMA_VERSION = 3; +export const CURRENT_SCHEMA_VERSION = 4; /** The shortest and longest a screened transfer may ring the person's * phone, in seconds. Twin: `validate.rs` `MIN_TRANSFER_TIMEOUT_SECS` / @@ -70,6 +71,17 @@ export const MAX_TRANSFER_TIMEOUT_SECS = 120; * a `transfer`. Twin: `validate.rs` `TRANSFER_FIELDS_MIN_SCHEMA_VERSION`. */ export const TRANSFER_FIELDS_MIN_SCHEMA_VERSION = 3; +/** The oldest `schema_version` that may declare `variables`. Twin: + * `validate.rs` `VARIABLES_MIN_SCHEMA_VERSION`. */ +export const VARIABLES_MIN_SCHEMA_VERSION = 4; + +/** The longest a variable's `max_len` may be, in characters. The schema + * carries the same cap. Twin: `validate.rs` `MAX_VARIABLE_LEN`. */ +export const MAX_VARIABLE_LEN = 500; + +/** A variable's `max_len` when it gives none; the schema's default. */ +export const DEFAULT_VARIABLE_MAX_LEN = 200; + /** Longest a spoken (text) prompt may be — see `validate.ts`. Twin: * `validate.rs` `MAX_PROMPT_CHARS`. */ export const MAX_PROMPT_CHARS = 2000; @@ -133,6 +145,15 @@ export const KIND_MIN_SCHEMA_VERSION: Record = { book: 2, }; +/** The oldest `schema_version` that may give an audio prompt a `template`. + * Twin: `validate.rs` `TEMPLATE_MIN_SCHEMA_VERSION`. */ +export const TEMPLATE_MIN_SCHEMA_VERSION = 4; + +/** An empty `variables` map declares nothing, so it is the same as none. */ +export function hasVariables(flow: Flow): boolean { + return flow.variables !== undefined && Object.keys(flow.variables).length > 0; +} + /** * The lowest `schema_version` that can carry this document's components — * the version it *needs*, as against the one it declares. @@ -152,9 +173,11 @@ export const KIND_MIN_SCHEMA_VERSION: Record = { export function requiredSchemaVersion(flow: Flow): number { return Math.max( 1, + hasVariables(flow) ? VARIABLES_MIN_SCHEMA_VERSION : 1, ...Object.values(flow.nodes).map((node) => Math.max( KIND_MIN_SCHEMA_VERSION[node.kind], + nodePrompts(node).some((p) => promptTemplate(p) !== null) ? TEMPLATE_MIN_SCHEMA_VERSION : 1, node.kind === 'transfer' && (node.whisper !== undefined || node.timeout_secs !== undefined) ? TRANSFER_FIELDS_MIN_SCHEMA_VERSION : 1, @@ -275,6 +298,16 @@ export function promptTranscript(prompt: Prompt): string | null { return typeof prompt.transcript === 'string' ? prompt.transcript : null; } +/** + * The `{{name}}` text an audio prompt was voiced from with its variables' + * defaults, `null` for a text prompt or a plain clip. Not scanned here. + * Twin: `model_ext.rs` `Prompt::template`. + */ +export function promptTemplate(prompt: Prompt): string | null { + if (typeof prompt === 'string') return null; + return typeof prompt.template === 'string' ? prompt.template : null; +} + /** * A generated-clip ref is a `voice_prompts` id (`vprompt_`) — a clip the * platform produced and owns. Anything else in an `audio:` field is a ref the @@ -307,6 +340,27 @@ export function nodePrompts(node: Node): Prompt[] { } } +/** The prompt slots of a node with the field each comes from. */ +export function nodePromptSlots(node: Node): [string, Prompt][] { + switch (node.kind) { + case 'greeting': + case 'menu': + case 'message': + return [['prompt', node.prompt]]; + case 'hangup': + return node.prompt === undefined ? [] : [['prompt', node.prompt]]; + case 'book': + return [ + ['prompt', node.prompt], + ['confirm_prompt', node.confirm_prompt], + ]; + case 'transfer': + return node.whisper === undefined ? [] : [['whisper', node.whisper]]; + default: + return []; + } +} + /** * Every audio asset the flow needs on the device, sorted and unique: * the refs its prompts point at, plus — for a `book` node — the diff --git a/packages/flow-schema/src/parse.ts b/packages/flow-schema/src/parse.ts index ac8b787..e74633e 100644 --- a/packages/flow-schema/src/parse.ts +++ b/packages/flow-schema/src/parse.ts @@ -24,6 +24,7 @@ import type { MessageTone, Prompt, TimeRange, + Variable, Weekday, WeeklySchedule, } from './model.js'; @@ -190,6 +191,43 @@ function warnUnknownFields( } } +/** The `variables` map: each entry declares one value filled in per call. */ +function decodeVariables( + value: unknown, + issues: Issue[], +): Record | undefined { + if (!isMap(value)) { + error(issues, 'expected_map', '"variables" must be a mapping of variable names', value); + return undefined; + } + const out: Record = {}; + for (const [name, field] of fieldsOf(value, 'variables', issues)) { + const context = `variable "${name}"`; + if (!isMap(field.value)) { + error(issues, 'expected_map', `${context} must be a mapping`, field.value); + continue; + } + const entry = fieldsOf(field.value, context, issues); + warnUnknownFields(entry, ['description', 'default', 'max_len'], context, issues); + const dflt = required(entry, 'default', context, issues, field.value); + const defaultValue = dflt && asString(dflt.value, `${context} default`, issues); + if (defaultValue === undefined) continue; + const variable: Variable = { default: defaultValue }; + const description = entry.get('description'); + if (description) { + const v = asString(description.value, `${context} description`, issues); + if (v !== undefined) variable.description = v; + } + const maxLen = entry.get('max_len'); + if (maxLen) { + const v = asU32(maxLen.value, `${context} max_len`, issues); + if (v !== undefined) variable.max_len = v; + } + out[name] = variable; + } + return out; +} + function decodePrompt(value: unknown, label: string, issues: Issue[]): Prompt | undefined { if (isScalar(value) && typeof value.value === 'string') return value.value; if (isMap(value)) { @@ -197,15 +235,25 @@ function decodePrompt(value: unknown, label: string, issues: Issue[]): Prompt | // `transcript` is the words the clip speaks, carried for display and // traces (model `Audio.transcript`); advisory only — playback still uses // `audio`. Known here so it neither warns nor gets dropped on decode. - warnUnknownFields(fields, ['audio', 'transcript'], label, issues); + warnUnknownFields(fields, ['audio', 'transcript', 'template'], label, issues); const audio = fields.get('audio'); if (audio) { const ref = asString(audio.value, `${label} audio`, issues); if (ref === undefined) return undefined; + const out: { audio: string; transcript?: string; template?: string } = { audio: ref }; const transcriptField = fields.get('transcript'); - if (!transcriptField) return { audio: ref }; - const transcript = asString(transcriptField.value, `${label} transcript`, issues); - return transcript === undefined ? undefined : { audio: ref, transcript }; + if (transcriptField) { + const transcript = asString(transcriptField.value, `${label} transcript`, issues); + if (transcript === undefined) return undefined; + out.transcript = transcript; + } + const templateField = fields.get('template'); + if (templateField) { + const template = asString(templateField.value, `${label} template`, issues); + if (template === undefined) return undefined; + out.template = template; + } + return out; } } error(issues, 'bad_prompt', `${label} must be text or { audio: ref }`, value); @@ -640,7 +688,7 @@ export function parseFlow(source: string): ParseResult { const fields = fieldsOf(root, 'flow document', issues); warnUnknownFields( fields, - ['schema_version', 'id', 'name', 'version', 'note', 'entry', 'nodes', 'ui'], + ['schema_version', 'id', 'name', 'version', 'note', 'variables', 'entry', 'nodes', 'ui'], 'flow document', issues, ); @@ -656,6 +704,8 @@ export function parseFlow(source: string): ParseResult { const version = versionField ? asU32(versionField.value, 'version', issues) : 1; const noteField = fields.get('note'); const note = noteField ? asString(noteField.value, 'note', issues) : undefined; + const variablesField = fields.get('variables'); + const variables = variablesField ? decodeVariables(variablesField.value, issues) : undefined; const entryField = required(fields, 'entry', 'flow document', issues, root); const entry = entryField && asString(entryField.value, 'entry', issues); @@ -704,6 +754,9 @@ export function parseFlow(source: string): ParseResult { name, version, ...(note === undefined ? {} : { note }), + // An empty map declares nothing; drop it so it round-trips (the Rust + // twin skips an empty map when writing). + ...(variables === undefined || Object.keys(variables).length === 0 ? {} : { variables }), entry, nodes, ui: ui as Flow['ui'], diff --git a/packages/flow-schema/src/serialize.ts b/packages/flow-schema/src/serialize.ts index 2a3f6ef..4177c34 100644 --- a/packages/flow-schema/src/serialize.ts +++ b/packages/flow-schema/src/serialize.ts @@ -8,13 +8,13 @@ // are required, and their defaults all come from there, so a schema change // needs no change here. -import { flowV3Schema } from './generated/schema.js'; +import { flowV4Schema } from './generated/schema.js'; import type { Flow } from './model.js'; type Json = null | boolean | number | string | Json[] | { [key: string]: Json }; type Schema = { [key: string]: unknown }; -const ROOT = flowV3Schema as unknown as Schema; +const ROOT = flowV4Schema as unknown as Schema; /** Follow `$ref` (and a single-entry `allOf`, the schema's way of putting * a default next to a ref) to the schema that describes a value. */ diff --git a/packages/flow-schema/src/structure.ts b/packages/flow-schema/src/structure.ts index 9c12d7f..019f69e 100644 --- a/packages/flow-schema/src/structure.ts +++ b/packages/flow-schema/src/structure.ts @@ -18,7 +18,7 @@ import { Ajv2020 } from 'ajv/dist/2020.js'; import type { ErrorObject, ValidateFunction } from 'ajv'; -import { flowV1Schema, flowV2Schema, flowV3Schema } from './generated/schema.js'; +import { flowV1Schema, flowV2Schema, flowV3Schema, flowV4Schema } from './generated/schema.js'; const ajv = new Ajv2020({ allErrors: true, strict: false }); @@ -33,6 +33,7 @@ const validators = new Map([ [1, ajv.compile(flowV1Schema)], [2, ajv.compile(flowV2Schema)], [3, ajv.compile(flowV3Schema)], + [4, ajv.compile(flowV4Schema)], ]); export type StructuralResult = diff --git a/packages/flow-schema/src/validate.ts b/packages/flow-schema/src/validate.ts index 65e5681..c834b55 100644 --- a/packages/flow-schema/src/validate.ts +++ b/packages/flow-schema/src/validate.ts @@ -12,17 +12,25 @@ // and menu/hours sanity caps. All problems are collected (not // fail-fast) so the editor can show every one at once. -import type { BookNode, ComponentKind, Flow, Prompt, TransferNode } from './model.js'; +import type { BookNode, ComponentKind, Flow, Node, Prompt, TransferNode } from './model.js'; import { + DEFAULT_VARIABLE_MAX_LEN, KIND_MIN_SCHEMA_VERSION, MAX_PROMPT_CHARS, + MAX_VARIABLE_LEN, MAX_TRANSFER_TIMEOUT_SECS, MIN_TRANSFER_TIMEOUT_SECS, SUPPORTED_SCHEMA_VERSIONS, TRANSFER_FIELDS_MIN_SCHEMA_VERSION, + TEMPLATE_MIN_SCHEMA_VERSION, + VARIABLES_MIN_SCHEMA_VERSION, + hasVariables, VALID_DIGITS, isScreenedTransfer, isTerminal, + nodePromptSlots, + nodePrompts, + promptTemplate, promptText, requiredExits, } from './model.js'; @@ -41,6 +49,7 @@ import { parseBookVocabularyRef, } from './book.js'; import type { Issue } from './issues.js'; +import { isVariableName, templateNames, tryParseTemplate } from './vars.js'; import { validateHours } from './hours.js'; type NodeRanges = Record; @@ -67,9 +76,31 @@ export function validateFlow(flow: Flow, nodeRanges: NodeRanges = {}): Issue[] { }); } + // Flow-level, so it carries no node. Same code as a transfer field on an + // older document: the field needs a newer version than the one declared. + if (hasVariables(flow) && flow.schema_version < VARIABLES_MIN_SCHEMA_VERSION) { + issues.push({ + severity: 'error', + code: 'field_requires_newer_schema', + message: `variables needs schema_version ${VARIABLES_MIN_SCHEMA_VERSION} (this document declares ${flow.schema_version})`, + params: { + field: 'variables', + required: VARIABLES_MIN_SCHEMA_VERSION, + declared: flow.schema_version, + }, + }); + } + + const mentioned = new Set(); + checkVariables(flow, issues); + const nodeIds = Object.keys(flow.nodes); if (nodeIds.length === 0) { - issues.push({ severity: 'error', code: 'empty_flow', message: 'flow has no nodes' }); + issues.push({ + severity: 'error', + code: 'empty_flow', + message: 'flow has no nodes', + }); return issues; // graph checks below would be meaningless } @@ -152,10 +183,12 @@ export function validateFlow(flow: Flow, nodeRanges: NodeRanges = {}): Issue[] { } case 'hours': issues.push( - ...validateHours(id, node.schedule, node.timezone, node.exceptions ?? []).map((issue) => ({ - ...issue, - range: nodeRanges[id], - })), + ...validateHours(id, node.schedule, node.timezone, node.exceptions ?? []).map( + (issue) => ({ + ...issue, + range: nodeRanges[id], + }), + ), ); break; case 'transfer': @@ -175,10 +208,12 @@ export function validateFlow(flow: Flow, nodeRanges: NodeRanges = {}): Issue[] { checkPrompt(id, node.prompt, issues, at); checkPrompt(id, node.confirm_prompt, issues, at); issues.push( - ...validateHours(id, node.schedule, node.timezone, node.exceptions ?? []).map((issue) => ({ - ...issue, - range: nodeRanges[id], - })), + ...validateHours(id, node.schedule, node.timezone, node.exceptions ?? []).map( + (issue) => ({ + ...issue, + range: nodeRanges[id], + }), + ), ); checkBookBounds(id, node, issues, at); break; @@ -186,6 +221,23 @@ export function validateFlow(flow: Flow, nodeRanges: NodeRanges = {}): Issue[] { break; } + if ( + flow.schema_version < TEMPLATE_MIN_SCHEMA_VERSION && + nodePrompts(node).some((p) => promptTemplate(p) !== null) + ) { + issues.push({ + ...at(id), + code: 'field_requires_newer_schema', + message: `node "${id}" gives a prompt a template, which needs schema_version ${TEMPLATE_MIN_SCHEMA_VERSION} (this document declares ${flow.schema_version})`, + params: { + field: 'template', + required: TEMPLATE_MIN_SCHEMA_VERSION, + declared: flow.schema_version, + }, + }); + } + checkPlaceholders(id, node, flow, issues, at, mentioned); + // A component the document's own version doesn't have. Checked per // node rather than once per flow so the editor points at the step // that has to change, and separate from `unknown_kind` (which a @@ -197,12 +249,30 @@ export function validateFlow(flow: Flow, nodeRanges: NodeRanges = {}): Issue[] { ...at(id), code: 'kind_requires_newer_schema', message: `node "${id}" is a ${node.kind} step, which needs schema_version ${minVersion} (this document declares ${flow.schema_version})`, - params: { kind: node.kind, required: minVersion, declared: flow.schema_version }, + params: { + kind: node.kind, + required: minVersion, + declared: flow.schema_version, + }, }); } } // Reachability and trap analysis need a real entry to walk from. + // TS-only: a declared variable no placeholder mentions is dead weight. + if (flow.schema_version >= VARIABLES_MIN_SCHEMA_VERSION) { + for (const name of Object.keys(flow.variables ?? {})) { + if (!mentioned.has(name)) { + issues.push({ + severity: 'warning', + code: 'unused_variable', + message: `variable "${name}" is declared but no prompt or menu label uses it`, + params: { name }, + }); + } + } + } + if (entryExists) checkGraph(flow, issues, at); return issues; @@ -250,7 +320,11 @@ function checkTransferFields( ...at(id), code: 'field_requires_newer_schema', message: `transfer node "${id}" sets ${field}, which needs schema_version ${TRANSFER_FIELDS_MIN_SCHEMA_VERSION} (this document declares ${declared})`, - params: { field, required: TRANSFER_FIELDS_MIN_SCHEMA_VERSION, declared }, + params: { + field, + required: TRANSFER_FIELDS_MIN_SCHEMA_VERSION, + declared, + }, }); } } @@ -302,6 +376,153 @@ function checkBookBounds( } } +/** Declared variable names, `max_len`s and defaults, and placeholder-looking + * text in the flow's own `id` and `name` (its `note` is a comment and never + * scanned). Only on a v4 document: before that `{{` is ordinary text and + * `variables` is refused as a whole. Twin: `check_variables`. */ +function checkVariables(flow: Flow, issues: Issue[]): void { + if (flow.schema_version < VARIABLES_MIN_SCHEMA_VERSION) return; + for (const name of Object.keys(flow.variables ?? {}).sort()) { + if (!isVariableName(name)) { + issues.push({ + severity: 'error', + code: 'variable_bad_name', + message: `variable name "${name}" must be a lowercase letter, then up to 31 lowercase letters, digits or underscores`, + params: { name }, + }); + } + const maxLen = flow.variables?.[name]?.max_len; + if ( + maxLen !== undefined && + (!Number.isInteger(maxLen) || maxLen < 1 || maxLen > MAX_VARIABLE_LEN) + ) { + issues.push({ + severity: 'error', + code: 'variable_max_len_out_of_range', + message: `variable "${name}" max_len is ${maxLen} (allowed: 1-${MAX_VARIABLE_LEN})`, + params: { name, value: maxLen }, + }); + } + // A default is held to the same limit as a caller's value. + const max = maxLen ?? DEFAULT_VARIABLE_MAX_LEN; + const len = [...(flow.variables?.[name]?.default ?? '')].length; + if (len > max) { + issues.push({ + severity: 'error', + code: 'variable_default_too_long', + message: `variable "${name}" default is ${len} characters; its max_len is ${max}`, + params: { name, max, len }, + }); + } + } + const fields = (['id', 'name'] as const).filter((k) => flow[k].includes('{{')).sort(); + if (fields.length > 0) { + issues.push({ + severity: 'error', + code: 'placeholder_not_allowed', + message: `${JSON.stringify(fields)} holds a {{ placeholder, which is only allowed in a prompt, a prompt template or a menu label`, + params: { fields }, + }); + } +} + +/** Check every place a node may hold a placeholder (string prompts, an audio + * prompt's `template`, menu option labels) against the declared variables, + * and refuse `{{` in any other string field. A v1-v3 document is skipped: + * there `{{` is text to be spoken as written. Twin: `check_placeholders`. */ +function checkPlaceholders( + id: string, + node: Node, + flow: Flow, + issues: Issue[], + at: (node: string) => Pick, + mentioned: Set, +): void { + if (flow.schema_version < VARIABLES_MIN_SCHEMA_VERSION) return; + const scan = (field: string, text: string) => { + const { error } = tryParseTemplate(text); + for (const name of templateNames(text)) mentioned.add(name); + if (error === null) { + for (const name of templateNames(text)) { + if (!Object.hasOwn(flow.variables ?? {}, name)) { + issues.push({ + ...at(id), + code: 'unknown_variable', + message: `node "${id}" ${field} uses "${name}", which the flow does not declare under variables`, + params: { field, name }, + }); + } + } + } else if (error.kind === 'bad_name') { + issues.push({ + ...at(id), + code: 'variable_bad_name', + message: `variable name "${error.name}" must be a lowercase letter, then up to 31 lowercase letters, digits or underscores`, + params: { name: error.name }, + }); + } else { + issues.push({ + ...at(id), + code: 'template_syntax', + message: `node "${id}" ${field} has a malformed placeholder: ${TEMPLATE_REASONS[error.kind]}`, + params: { field, reason: TEMPLATE_REASONS[error.kind] }, + }); + } + }; + for (const [field, prompt] of nodePromptSlots(node)) { + if (typeof prompt === 'string') scan(field, prompt); + else if (typeof prompt.template === 'string') scan(`${field}.template`, prompt.template); + } + if (node.kind === 'menu') { + for (const key of Object.keys(node.options).sort()) { + scan(`options.${key}`, node.options[key] ?? ''); + } + } + + // Everything else: any string value holding `{{` is out of place. A + // `note` is a comment for people, never read by the engine, so it is + // never scanned (nor is the flow's own note, see `checkVariables`). + const bad: string[] = []; + for (const [key, value] of Object.entries(node)) { + if (key !== 'exits' && key !== 'kind' && key !== 'note') collectStrayBraces(key, value, bad); + } + bad.sort(); + if (bad.length > 0) { + issues.push({ + ...at(id), + code: 'placeholder_not_allowed', + message: `node "${id}" ${JSON.stringify(bad)} holds a {{ placeholder, which is only allowed in a prompt, a prompt template or a menu label`, + params: { fields: bad }, + }); + } +} + +const TEMPLATE_REASONS = { + unclosed: 'a `{{` or block is never closed', + nested: 'blocks cannot be nested', + mismatched: 'a block close does not match an open block', +} as const; + +/** Paths of string values under `value` that hold `{{`, apart from the slots + * where a placeholder is allowed: a plain-string `prompt`, `confirm_prompt` + * or `whisper`, any `.template`, and menu `options`. */ +function collectStrayBraces(path: string, value: unknown, out: string[]): void { + if (typeof value === 'string') { + const allowed = + path === 'prompt' || + path === 'confirm_prompt' || + path === 'whisper' || + path.endsWith('.template') || + path.startsWith('options.'); + if (value.includes('{{') && !allowed) out.push(path); + } else if (Array.isArray(value)) { + value.forEach((item, i) => collectStrayBraces(`${path}.${i}`, item, out)); + } else if (value !== null && typeof value === 'object') { + for (const [key, item] of Object.entries(value)) + collectStrayBraces(`${path}.${key}`, item, out); + } +} + function checkPrompt( id: string, prompt: Prompt, @@ -375,7 +596,7 @@ function checkGraph( /** Node ids reachable from `entry` over exit edges (`entry` included when * it exists). */ -function reachableFromEntry(flow: Flow): Set { +export function reachableFromEntry(flow: Flow): Set { const reachable = new Set(); if (!(flow.entry in flow.nodes)) return reachable; reachable.add(flow.entry); diff --git a/packages/flow-schema/src/vars.ts b/packages/flow-schema/src/vars.ts new file mode 100644 index 0000000..1e93453 --- /dev/null +++ b/packages/flow-schema/src/vars.ts @@ -0,0 +1,256 @@ +// Placeholder syntax shared by validation and filling. Twin of +// `crates/wavekat-flow/src/vars.rs`; keep the two in lockstep. +// +// A template is text with `{{name}}` placeholders and `{{#name}}…{{/name}}` +// conditional blocks (kept only when the variable's value is non-empty). +// Blocks do not nest and have no else. Names are `[a-z][a-z0-9_]{0,31}`. +// +// `fill` gives each name an effective value: the caller's, cleaned, or the +// variable's default when the caller gives none or a blank one. So a blank +// value falls back to the default; it cannot clear a default. Only a menu +// option whose label is exactly a bare `{{name}}` is dropped when its +// effective value is empty; any other text that holds an empty placeholder is +// kept, with the placeholder filled as nothing. + +import type { Flow } from './model.js'; +import { DEFAULT_VARIABLE_MAX_LEN, MAX_PROMPT_CHARS, nodePromptSlots } from './model.js'; +import { reachableFromEntry } from './validate.js'; + +/** One piece of a parsed template. A block's body holds only text and vars. */ +export type Segment = + | { kind: 'text'; text: string } + | { kind: 'var'; name: string } + | { kind: 'block'; name: string; body: Segment[] }; + +/** Why a template could not be parsed. */ +export type TemplateError = + | { kind: 'unclosed' } + | { kind: 'nested' } + | { kind: 'bad_name'; name: string } + | { kind: 'mismatched'; name: string }; + +const NAME_RE = /^[a-z][a-z0-9_]{0,31}$/; + +/** Whether `name` fits `[a-z][a-z0-9_]{0,31}`. Twin: `is_variable_name`. */ +export function isVariableName(name: string): boolean { + return NAME_RE.test(name); +} + +type Tok = { t: 'text'; v: string } | { t: 'var' | 'open' | 'close'; v: string }; + +/** Split `s` into tokens. `unclosed` is true when a `{{` has no `}}`. */ +function tokens(s: string): { toks: Tok[]; unclosed: boolean } { + const toks: Tok[] = []; + let rest = s; + for (;;) { + const start = rest.indexOf('{{'); + if (start < 0) break; + if (start > 0) toks.push({ t: 'text', v: rest.slice(0, start) }); + const after = rest.slice(start + 2); + const end = after.indexOf('}}'); + if (end < 0) return { toks, unclosed: true }; + const inner = after.slice(0, end); + if (inner.startsWith('#')) toks.push({ t: 'open', v: inner.slice(1) }); + else if (inner.startsWith('/')) toks.push({ t: 'close', v: inner.slice(1) }); + else toks.push({ t: 'var', v: inner }); + rest = after.slice(end + 2); + } + if (rest.length > 0) toks.push({ t: 'text', v: rest }); + return { toks, unclosed: false }; +} + +/** Parse `s`; the first defect, if any, comes back as `error`. */ +export function tryParseTemplate(s: string): { segments: Segment[]; error: TemplateError | null } { + const { toks, unclosed } = tokens(s); + const segments: Segment[] = []; + let open: { name: string; body: Segment[] } | null = null; + const fail = (error: TemplateError) => ({ segments: [], error }); + for (const tok of toks) { + const into = open ? open.body : segments; + if (tok.t === 'text') { + into.push({ kind: 'text', text: tok.v }); + continue; + } + if (!isVariableName(tok.v)) return fail({ kind: 'bad_name', name: tok.v }); + if (tok.t === 'var') { + into.push({ kind: 'var', name: tok.v }); + } else if (tok.t === 'open') { + if (open) return fail({ kind: 'nested' }); + open = { name: tok.v, body: [] }; + } else { + if (!open || open.name !== tok.v) return fail({ kind: 'mismatched', name: tok.v }); + segments.push({ kind: 'block', name: open.name, body: open.body }); + open = null; + } + } + if (unclosed || open) return fail({ kind: 'unclosed' }); + return { segments, error: null }; +} + +/** Parse `s` into segments; empty when the template is malformed. Throws nothing. */ +export function parseTemplate(s: string): Segment[] { + return tryParseTemplate(s).segments; +} + +/** The validator code for a template defect. */ +export function templateErrorCode(error: TemplateError): 'template_syntax' | 'variable_bad_name' { + return error.kind === 'bad_name' ? 'variable_bad_name' : 'template_syntax'; +} + +/** Codes for what is wrong with `s`: empty when well formed, else one code. */ +export function templateIssues(s: string): string[] { + const { error } = tryParseTemplate(s); + return error === null ? [] : [templateErrorCode(error)]; +} + +/** Every variable name `s` mentions, first-mention order, no repeats. + * Best effort on a malformed template: the well-formed names it holds. */ +export function templateNames(s: string): string[] { + const names: string[] = []; + for (const tok of tokens(s).toks) { + if ((tok.t === 'var' || tok.t === 'open') && isVariableName(tok.v) && !names.includes(tok.v)) { + names.push(tok.v); + } + } + return names; +} + +/** Why `fill` refused a value. */ +export type FillError = { + code: 'variable_unknown' | 'variable_too_long' | 'menu_without_options' | 'prompt_too_long'; + /** The variable, or for `menu_without_options` and `prompt_too_long` the + * node id. */ + name: string; +}; + +/** A caller's value with control characters stripped, then trimmed of Unicode + * White_Space plus U+FEFF (JS `\s` covers FEFF but not U+0085). Twin: `clean` + * in `vars.rs`. */ +function clean(value: string): string { + return value.replace(/\p{Cc}/gu, '').replace(/^[\s\u0085]+|[\s\u0085]+$/g, ''); +} + +function render(segments: Segment[], effective: (name: string) => string): string { + let out = ''; + for (const seg of segments) { + if (seg.kind === 'text') out += seg.text; + else if (seg.kind === 'var') out += effective(seg.name); + else if (effective(seg.name) !== '') out += render(seg.body, effective); + } + return out; +} + +/** + * Turn a flow with variables plus a caller's values into a plain flow the + * engine can run: every placeholder replaced, `variables` and every audio + * prompt's `template` gone, and a declared `schema_version` of 4 or more set + * to 3. The input is not modified. Twin: `vars.rs` `fill`. + * + * A name's effective value is the caller's (trimmed, control characters + * stripped) when that is non-empty, else the variable's default; so a blank + * value falls back to the default and cannot clear it. Values are inserted as + * text and never parsed again. A menu option whose label is exactly a bare + * `{{name}}` with an empty effective value is removed, with its exit; any + * other label is filled and kept; a node left unreachable from `entry` once + * those exits are gone is removed too. An audio prompt with a `template` stays + * audio (dropping the template) unless a variable it names got a non-default + * value; then it becomes the filled text. A v1-v3 flow without variables + * comes back as a clone. A malformed template is left as written (validation + * rejects those before fill is reached). + * + * Contract: validate the SOURCE flow first (`validateOutbound`). The result is + * a v3 document that validates on its own: a value holding `{{` is plain text + * in v3, and `fill` keeps options and exits consistent. Errors: + * `variable_unknown`, `variable_too_long`, `menu_without_options` when every + * option of a menu would be dropped, and `prompt_too_long` when a filled + * prompt is longer than validation allows. + */ +export function fill( + flow: Flow, + values: Record, +): { flow: Flow } | { errors: FillError[] } { + const declared = flow.variables ?? {}; + const out = structuredClone(flow); + if ( + Object.keys(declared).length === 0 && + Object.keys(values).length === 0 && + flow.schema_version < 4 + ) { + return { flow: out }; + } + + const errors: FillError[] = []; + const given = new Map(); + for (const name of Object.keys(values).sort()) { + const variable = Object.hasOwn(declared, name) ? declared[name] : undefined; + if (variable === undefined) { + errors.push({ code: 'variable_unknown', name }); + continue; + } + const value = clean(values[name] ?? ''); + if ([...value].length > (variable.max_len ?? DEFAULT_VARIABLE_MAX_LEN)) { + errors.push({ code: 'variable_too_long', name }); + } else if (value !== '') { + given.set(name, value); + } + } + if (errors.length > 0) return { errors }; + + const defaultOf = (name: string): string => + Object.hasOwn(declared, name) ? (declared[name]?.default ?? '') : ''; + const effective = (name: string): string => given.get(name) ?? defaultOf(name); + const fillText = (text: string): string => { + const { segments, error } = tryParseTemplate(text); + return error === null ? render(segments, effective) : text; + }; + + delete out.variables; + // Variables and templates are gone, so what is left is a v3 document. + if (out.schema_version >= 4) out.schema_version = 3; + for (const [id, node] of Object.entries(out.nodes)) { + let tooLong = false; + for (const [field, prompt] of nodePromptSlots(node)) { + let next: typeof prompt = prompt; + if (typeof prompt === 'string') { + next = fillText(prompt); + } else if (typeof prompt.template === 'string') { + const { template, ...clip } = prompt; + const overridden = templateNames(template).some( + (n) => given.has(n) && given.get(n) !== defaultOf(n), + ); + next = overridden ? fillText(template) : clip; + } + if (typeof next === 'string' && [...next].length > MAX_PROMPT_CHARS) tooLong = true; + (node as unknown as Record)[field] = next; + } + if (tooLong) errors.push({ code: 'prompt_too_long', name: id }); + if (node.kind === 'menu') { + const dropped: string[] = []; + for (const [key, label] of Object.entries(node.options)) { + const bare = /^\{\{([^{}]*)\}\}$/.exec(label)?.[1]; + if (bare !== undefined && isVariableName(bare) && effective(bare) === '') { + dropped.push(key); + } else { + node.options[key] = fillText(label); + } + } + if (dropped.length > 0 && dropped.length === Object.keys(node.options).length) { + errors.push({ code: 'menu_without_options', name: id }); + continue; + } + for (const key of dropped) { + delete node.options[key]; + if (node.exits) delete node.exits[key]; + } + } + } + if (errors.length > 0) return { errors }; + // A dropped option can leave the nodes only it led to unreachable; a caller + // could never get there, so they go too and the result still validates on + // its own. + const reachable = reachableFromEntry(out); + for (const id of Object.keys(out.nodes)) { + if (!reachable.has(id)) delete out.nodes[id]; + } + return { flow: out }; +} diff --git a/packages/flow-schema/test/conformance.test.ts b/packages/flow-schema/test/conformance.test.ts index 2e135a0..df97dc0 100644 --- a/packages/flow-schema/test/conformance.test.ts +++ b/packages/flow-schema/test/conformance.test.ts @@ -18,7 +18,15 @@ import { fileURLToPath } from 'node:url'; import { describe, expect, it } from 'vitest'; import { parse } from 'yaml'; -import { checkFlow, hasErrors, parseFlow, requiredAssets, validateOutbound } from '../src/index.js'; +import { + checkFlow, + fill, + hasErrors, + parseFlow, + requiredAssets, + serializeFlow, + validateOutbound, +} from '../src/index.js'; import { validateStructure } from '../src/structure.js'; const here = dirname(fileURLToPath(import.meta.url)); @@ -189,3 +197,52 @@ describe('conformance corpus — outbound (validateOutbound)', () => { }); } }); + +// The fill corpus: `conformance/fill/.input.yaml` + `.values.json` +// run through `fill`. A success case has `.expected.yaml`, compared with +// the filled flow after canonical serialization; a refusal has +// `.expected.json` = `{"errors": [codes]}` (exact list, in order). The +// Rust crate runs the same cases (`corpus_fill_matches_expectations`). +const FILL_DIR = resolve(corpusRoot, 'fill'); +const FILL_CASES = readdirSync(FILL_DIR) + .filter((f) => f.endsWith('.input.yaml')) + .map((f) => f.slice(0, -'.input.yaml'.length)) + .sort(); + +function decode(src: string, label: string) { + const { flow, issues } = parseFlow(src); + if (!flow) throw new Error(`${label}: ${JSON.stringify(issues)}`); + return flow; +} + +describe('conformance corpus — fill', () => { + it('has cases', () => { + expect(FILL_CASES.length).toBeGreaterThan(0); + }); + + for (const name of FILL_CASES) { + it(name, () => { + const read = (ext: string) => readFileSync(resolve(FILL_DIR, `${name}.${ext}`), 'utf8'); + const flow = decode(read('input.yaml'), name); + const values = JSON.parse(read('values.json')) as Record; + // Every source is a flow that passes the gate fill expects in front of it. + expect(validateOutbound(flow).filter((i) => i.severity === 'error')).toEqual([]); + const result = fill(flow, values); + if (existsSync(resolve(FILL_DIR, `${name}.expected.yaml`))) { + if (!('flow' in result)) throw new Error(JSON.stringify(result.errors)); + const want = decode(read('expected.yaml'), name); + const text = serializeFlow(result.flow); + expect(text).toBe(serializeFlow(want)); + // The result is a v3 document that validates on its own and + // reads back as itself. + expect(result.flow.schema_version).toBe(3); + expect(validateOutbound(result.flow).filter((i) => i.severity === 'error')).toEqual([]); + expect(serializeFlow(decode(text, name))).toBe(text); + } else { + const want = JSON.parse(read('expected.json')) as { errors: string[] }; + if (!('errors' in result)) throw new Error('expected fill to be refused'); + expect(result.errors.map((e) => e.code)).toEqual(want.errors); + } + }); + } +}); diff --git a/packages/flow-schema/test/model.test.ts b/packages/flow-schema/test/model.test.ts index 9d0f02e..c9600c4 100644 --- a/packages/flow-schema/test/model.test.ts +++ b/packages/flow-schema/test/model.test.ts @@ -47,6 +47,26 @@ nodes: `; describe('requiredSchemaVersion', () => { + it('is 4 for an audio prompt that keeps a template', () => { + const flow = parsed(V1_ONLY); + const bye = flow.nodes.bye; + if (bye?.kind !== 'hangup') throw new Error('fixture'); + bye.prompt = { audio: 'vprompt_abc123', template: 'Hi {{name}}' }; + expect(requiredSchemaVersion(flow)).toBe(4); + bye.prompt = { audio: 'vprompt_abc123' }; + expect(requiredSchemaVersion(flow)).toBe(1); + }); + + it('is 4 once the document declares variables, and 1 when the map is empty', () => { + const flow = parsed(V1_ONLY); + flow.variables = { q: { default: 'hi' } }; + expect(requiredSchemaVersion(flow)).toBe(4); + flow.variables = {}; + expect(requiredSchemaVersion(flow)).toBe(1); + delete flow.variables; + expect(requiredSchemaVersion(flow)).toBe(1); + }); + it('is 1 for a document built only from components v1 had', () => { expect(requiredSchemaVersion(parsed(V1_ONLY))).toBe(1); }); diff --git a/packages/flow-schema/test/parse.test.ts b/packages/flow-schema/test/parse.test.ts index f66d4f8..78d37de 100644 --- a/packages/flow-schema/test/parse.test.ts +++ b/packages/flow-schema/test/parse.test.ts @@ -414,3 +414,68 @@ describe('known fields follow the schema', () => { } }); }); + +describe('parseFlow variables', () => { + const doc = (variables: string) => + `schema_version: 4\nid: f\nname: F\nentry: a\nvariables:${variables}\nnodes:\n a:\n kind: hangup\n`; + const codes = (source: string) => + parseFlow(source) + .issues.filter((i) => i.severity === 'error') + .map((i) => i.code); + + it('decodes every field of a variable', () => { + const { flow, issues } = parseFlow( + doc('\n q: { description: Ask, default: hi, max_len: 30 }'), + ); + expect(issues).toEqual([]); + expect(flow?.variables).toEqual({ + q: { description: 'Ask', default: 'hi', max_len: 30 }, + }); + }); + + it('refuses variables that is not a mapping', () => { + const r = parseFlow(doc(' [a, b]')); + expect(r.flow).toBeNull(); + expect(codes(doc(' [a, b]'))).toEqual(['expected_map']); + }); + + it('refuses an entry that is not a mapping', () => { + expect(codes(doc('\n q: nope'))).toEqual(['expected_map']); + }); + + it('refuses a variable with no default', () => { + expect(codes(doc('\n q: { max_len: 30 }'))).toEqual(['missing_field']); + }); + + it('refuses a default that is not text', () => { + expect(codes(doc('\n q: { default: [a] }'))).toEqual(['expected_string']); + }); + + it('accepts an empty default', () => { + expect(parseFlow(doc('\n q: { default: "" }')).flow?.variables).toEqual({ q: { default: '' } }); + }); + + it('refuses a max_len that is not an integer', () => { + expect(codes(doc('\n q: { default: x, max_len: lots }'))).toEqual(['expected_integer']); + }); +}); + +describe('parseFlow prompt template', () => { + const doc = (prompt: string) => + `schema_version: 4\nid: f\nname: F\nentry: a\nnodes:\n a:\n kind: hangup\n prompt: ${prompt}\n`; + + it('keeps the template after the transcript', () => { + const { flow, issues } = parseFlow( + doc('{ audio: vprompt_abc123, transcript: Hi there, template: "Hi {{name}}" }'), + ); + expect(issues).toEqual([]); + expect(flow?.nodes.a).toMatchObject({ + prompt: { audio: 'vprompt_abc123', transcript: 'Hi there', template: 'Hi {{name}}' }, + }); + }); + + it('refuses a template that is not text', () => { + const r = parseFlow(doc('{ audio: vprompt_abc123, template: [a] }')); + expect(r.issues.map((i) => i.code)).toContain('expected_string'); + }); +}); diff --git a/packages/flow-schema/test/vars.test.ts b/packages/flow-schema/test/vars.test.ts new file mode 100644 index 0000000..2478530 --- /dev/null +++ b/packages/flow-schema/test/vars.test.ts @@ -0,0 +1,428 @@ +import { describe, expect, it } from 'vitest'; + +import { readFileSync } from 'node:fs'; +import { fileURLToPath } from 'node:url'; + +import { checkFlow } from '../src/check.js'; +import type { Flow } from '../src/model.js'; +import { parseFlow } from '../src/parse.js'; +import { serializeFlow } from '../src/serialize.js'; +import { validateOutbound } from '../src/validate.js'; +import { + fill, + parseTemplate, + templateIssues, + templateNames, + tryParseTemplate, +} from '../src/vars.js'; + +describe('parseTemplate', () => { + it('parses text, vars and blocks', () => { + expect(parseTemplate('Hi {{a}}.{{#b}} B={{b}}{{/b}}')).toEqual([ + { kind: 'text', text: 'Hi ' }, + { kind: 'var', name: 'a' }, + { kind: 'text', text: '.' }, + { + kind: 'block', + name: 'b', + body: [ + { kind: 'text', text: ' B=' }, + { kind: 'var', name: 'b' }, + ], + }, + ]); + }); + + it('passes plain text and stray closers through', () => { + expect(parseTemplate('')).toEqual([]); + expect(parseTemplate('a }} b')).toEqual([{ kind: 'text', text: 'a }} b' }]); + }); + + it('rejects nested and unclosed blocks', () => { + expect(tryParseTemplate('{{#a}}{{#b}}{{/b}}{{/a}}').error).toEqual({ + kind: 'nested', + }); + expect(tryParseTemplate('{{#a}} x').error).toEqual({ kind: 'unclosed' }); + expect(tryParseTemplate('{{a').error).toEqual({ kind: 'unclosed' }); + }); + + it('rejects mismatched closers', () => { + expect(tryParseTemplate('{{/a}}').error).toEqual({ + kind: 'mismatched', + name: 'a', + }); + expect(tryParseTemplate('{{#a}}{{/b}}').error).toEqual({ + kind: 'mismatched', + name: 'b', + }); + }); + + it('rejects bad names', () => { + expect(tryParseTemplate('{{A}}').error).toEqual({ + kind: 'bad_name', + name: 'A', + }); + expect(tryParseTemplate('{{1a}}').error).toEqual({ + kind: 'bad_name', + name: '1a', + }); + expect(tryParseTemplate('{{}}').error).toEqual({ + kind: 'bad_name', + name: '', + }); + expect(tryParseTemplate(`{{${'a'.repeat(32)}}}`).error).toBeNull(); + expect(tryParseTemplate(`{{${'a'.repeat(33)}}}`).error).not.toBeNull(); + }); + + it('handles brace edge cases like the Rust twin', () => { + expect(tryParseTemplate('{{{a}}}').error).toEqual({ + kind: 'bad_name', + name: '{a', + }); + expect(parseTemplate('{ {a} }')).toEqual([{ kind: 'text', text: '{ {a} }' }]); + expect(parseTemplate('}}')).toEqual([{ kind: 'text', text: '}}' }]); + expect(tryParseTemplate('{{#a}} x {{').error).toEqual({ kind: 'unclosed' }); + }); + + it('reports codes and names', () => { + expect(templateIssues('{{a}}')).toEqual([]); + expect(templateIssues('{{a')).toEqual(['template_syntax']); + expect(templateIssues('{{A}}')).toEqual(['variable_bad_name']); + expect(templateNames('{{b}} {{#a}}{{a}}{{/a}} {{b}}')).toEqual(['b', 'a']); + }); +}); + +const flow = (version: number, vars: string, body: string) => + `schema_version: ${version}\nid: f\nname: F\nentry: a\n${vars}nodes:\n${body}`; + +function errorCodes(src: string): string[] { + return checkFlow(src) + .issues.filter((i) => i.severity === 'error') + .map((i) => i.code); +} + +const Q = 'variables:\n q: { default: x }\n'; +const HANGUP = (prompt: string) => ` a:\n kind: hangup\n prompt: ${prompt}\n`; + +describe('placeholders in a flow', () => { + it('v4 placeholder must be declared', () => { + expect(errorCodes(flow(4, Q, HANGUP('"Hi {{q}} {{ghost}}"')))).toEqual(['unknown_variable']); + expect(errorCodes(flow(4, Q, HANGUP('"Hi {{q}}"')))).toEqual([]); + }); + + it('scans menu labels and templates', () => { + const body = + ' a:\n kind: menu\n prompt: { audio: vprompt_ab12, template: "{{nope}}" }\n options: { "1": "{{q}}", "2": "{{bad}}" }\n exits: { "1": b, "2": b, no_input: b, invalid: b }\n b:\n kind: hangup\n prompt: bye\n'; + expect(errorCodes(flow(4, Q, body))).toEqual(['unknown_variable', 'unknown_variable']); + }); + + it('reports bad syntax and names', () => { + expect(errorCodes(flow(4, Q, HANGUP('"{{#q}} open"')))).toEqual(['template_syntax']); + expect(errorCodes(flow(4, Q, HANGUP('"{{Q}}"')))).toEqual(['variable_bad_name']); + }); + + it('checks declared names and max_len', () => { + const body = HANGUP('bye'); + expect(errorCodes(flow(4, 'variables:\n Bad: { default: "" }\n', body))).toEqual([ + 'variable_bad_name', + ]); + expect(errorCodes(flow(4, 'variables:\n q: { default: "", max_len: 501 }\n', body))).toContain( + 'variable_max_len_out_of_range', + ); + }); + + it('refuses a default longer than its max_len, counted in characters', () => { + const body = HANGUP('"{{q}}"'); + expect(errorCodes(flow(4, 'variables:\n q: { default: "问问问", max_len: 2 }\n', body))).toEqual( + ['variable_default_too_long'], + ); + expect(errorCodes(flow(4, 'variables:\n q: { default: "问问", max_len: 2 }\n', body))).toEqual( + [], + ); + }); + + it('never scans a note, on the flow or on a step', () => { + const src = + 'schema_version: 4\nid: f\nname: F\nnote: "{{ghost}} {{#x"\nentry: a\n' + + Q + + 'nodes:\n a:\n kind: hangup\n note: "{{ghost}} {{#x"\n prompt: "{{q}}"\n'; + expect(errorCodes(src)).toEqual([]); + }); + + it('refuses placeholders in a transfer target and a transcript', () => { + expect(errorCodes(flow(4, Q, ' a:\n kind: transfer\n target: "{{q}}"\n'))).toEqual([ + 'placeholder_not_allowed', + ]); + expect( + errorCodes(flow(4, Q, HANGUP('{ audio: vprompt_ab12, transcript: "Hi {{q}}" }'))), + ).toEqual(['placeholder_not_allowed']); + }); + + it('treats braces as plain text before v4', () => { + expect(errorCodes(flow(3, '', HANGUP('"Press {{1}} now }} {{#x"')))).toEqual([]); + }); + + it('warns about a variable nothing uses', () => { + const issues = checkFlow(flow(4, Q, HANGUP('bye'))).issues; + expect(issues.filter((i) => i.code === 'unused_variable')).toMatchObject([ + { severity: 'warning', params: { name: 'q' } }, + ]); + expect( + checkFlow(flow(4, Q, HANGUP('"{{#q}}x{{/q}}"'))).issues.some( + (i) => i.code === 'unused_variable', + ), + ).toBe(false); + }); +}); + +const ASK_PATH = fileURLToPath( + new URL('../../../conformance/v4/valid/ask-question.yaml', import.meta.url), +); + +function load(source: string): Flow { + const { flow, issues } = parseFlow(source); + if (!flow) throw new Error(JSON.stringify(issues)); + return flow; +} + +const ask = (): Flow => load(readFileSync(ASK_PATH, 'utf8')); + +function filled(flow: Flow, values: Record): Flow { + const result = fill(flow, values); + if (!('flow' in result)) throw new Error(JSON.stringify(result.errors)); + return result.flow; +} + +function askMenu(flow: Flow) { + const node = flow.nodes.ask; + if (node?.kind !== 'menu') throw new Error('ask is a menu'); + return node; +} + +const VOICED: Flow = load( + [ + 'schema_version: 4', + 'id: f', + 'name: F', + 'entry: a', + 'variables:', + ' name: { default: there }', + 'nodes:', + ' a:', + ' kind: hangup', + ' prompt: { audio: vprompt_a, template: "Hi {{name}}" }', + '', + ].join('\n'), +); + +describe('fill', () => { + it('fills_question_and_two_options', () => { + const flow = filled(ask(), { + question: 'Which database?', + option1: 'Postgres', + option2: 'SQLite', + }); + const menu = askMenu(flow); + expect(menu.prompt).toBe( + 'Claude has a question. Which database? Press 1 for Postgres. Press 2 for SQLite. Press 9 to hear this again.', + ); + expect(menu.options).toEqual({ '1': 'Postgres', '2': 'SQLite', '9': 'Repeat' }); + expect(menu.exits).not.toHaveProperty('3'); + expect(menu.exits).not.toHaveProperty('4'); + expect(flow.variables).toBeUndefined(); + expect(flow.schema_version).toBe(3); + }); + + it('keeps_option3_when_given', () => { + const menu = askMenu(filled(ask(), { option3: 'Both' })); + expect(menu.prompt as string).toContain(' Press 3 for Both.'); + expect(menu.options['3']).toBe('Both'); + expect(menu.exits?.['3']).toBe('thanks'); + expect(menu.exits).not.toHaveProperty('4'); + }); + + it('no_values_plays_the_defaults', () => { + const menu = askMenu(filled(ask(), {})); + expect(menu.prompt).toBe( + 'Claude has a question. Claude needs your input on screen. Press 1 for Yes. Press 2 for No. Press 9 to hear this again.', + ); + expect(menu.options).toEqual({ '1': 'Yes', '2': 'No', '9': 'Repeat' }); + expect(menu.exits).not.toHaveProperty('3'); + }); + + it('rendered_prompt_stays_audio_when_defaults_kept', () => { + const kept = filled(VOICED, {}).nodes.a; + expect(kept).toMatchObject({ prompt: { audio: 'vprompt_a' } }); + expect(kept).not.toHaveProperty('prompt.template'); + expect(filled(VOICED, { name: 'there' }).nodes.a).toMatchObject({ + prompt: { audio: 'vprompt_a' }, + }); + expect(filled(VOICED, { name: 'Ann' }).nodes.a).toMatchObject({ prompt: 'Hi Ann' }); + }); + + it('blank_value_falls_back_to_default', () => { + expect(askMenu(filled(ask(), { question: ' ' })).prompt as string).toContain( + 'Claude needs your input on screen.', + ); + }); + + it('strips control characters', () => { + expect(askMenu(filled(ask(), { question: ' Hi\u0007\n there ' })).prompt as string).toContain( + 'Claude has a question. Hi there Press', + ); + }); + + it('unknown_value_is_an_error', () => { + expect(fill(ask(), { colour: 'red' })).toEqual({ + errors: [{ code: 'variable_unknown', name: 'colour' }], + }); + }); + + it('values_are_not_expanded', () => { + expect(askMenu(filled(ask(), { question: '{{option1}} {x}' })).prompt as string).toContain( + '{{option1}} {x}', + ); + }); + + it('max_len_counts_characters', () => { + const flow = ask(); + flow.variables!.question!.max_len = 300; + expect('flow' in fill(flow, { question: '问'.repeat(150) })).toBe(true); + expect('flow' in fill(flow, { question: '问'.repeat(300) })).toBe(true); + expect(fill(flow, { question: '问'.repeat(301) })).toEqual({ + errors: [{ code: 'variable_too_long', name: 'question' }], + }); + // Emoji outside the BMP are one character each, not two UTF-16 units. + expect('flow' in fill(flow, { question: '😀'.repeat(300) })).toBe(true); + }); + + it('source validates and fill keeps hostile values literal', () => { + const issues = validateOutbound(ask()); + expect(issues.filter((i) => i.severity === 'error')).toEqual([]); + const menu = askMenu(filled(ask(), { question: '{{option1}} {x}' })); + expect(menu.prompt as string).toContain('{{option1}} {x}'); + }); + + it('filled flow with braces in a value validates as v3', () => { + const flow = filled(ask(), { question: 'Is {{x}} {{#y}} ok?' }); + expect(flow.schema_version).toBe(3); + expect(askMenu(flow).prompt as string).toContain('Is {{x}} {{#y}} ok?'); + expect(validateOutbound(flow).filter((i) => i.severity === 'error')).toEqual([]); + // And it reads back as itself: in v3 the braces are plain text. + const text = serializeFlow(flow); + const back = load(text); + expect(serializeFlow(back)).toBe(text); + expect(validateOutbound(back).filter((i) => i.severity === 'error')).toEqual([]); + }); + + it('a v4 flow without variables still comes back as v3', () => { + const flow = load( + 'schema_version: 4\nid: f\nname: F\nentry: a\nnodes:\n a:\n kind: hangup\n prompt: { audio: vprompt_a, template: Hello }\n', + ); + expect(validateOutbound(flow).filter((i) => i.severity === 'error')).toEqual([]); + const out = filled(flow, {}); + expect(out.schema_version).toBe(3); + expect(out.nodes.a).toMatchObject({ prompt: { audio: 'vprompt_a' } }); + expect(out.nodes.a).not.toHaveProperty('prompt.template'); + expect(validateOutbound(out).filter((i) => i.severity === 'error')).toEqual([]); + }); + + it('a filled prompt over the limit is an error', () => { + const src = (prompt: string) => + load( + `schema_version: 4\nid: f\nname: F\nentry: a\nvariables:\n d: { default: "", max_len: 500 }\nnodes:\n a:\n kind: hangup\n prompt: "${prompt}"\n`, + ); + // 4 x 500 = 2000: exactly the limit is fine; counted in characters. + const value = { d: '😀'.repeat(500) }; + expect('flow' in fill(src('{{d}}{{d}}{{d}}{{d}}'), value)).toBe(true); + expect(fill(src('{{d}}{{d}}{{d}}{{d}}!'), value)).toEqual({ + errors: [{ code: 'prompt_too_long', name: 'a' }], + }); + }); + + it('prunes nodes only a dropped option reached', () => { + const flow = load( + [ + 'schema_version: 4', + 'id: f', + 'name: F', + 'entry: m', + 'variables:', + ' c: { default: "" }', + 'nodes:', + ' m:', + ' kind: menu', + ' prompt: Pick', + ' options: { "1": One, "3": "{{c}}" }', + ' exits: { "1": end, "3": only3, no_input: end, invalid: end }', + ' only3:', + ' kind: greeting', + ' prompt: Three', + ' exits: { next: deeper }', + ' deeper:', + ' kind: hangup', + ' end:', + ' kind: hangup', + '', + ].join('\n'), + ); + expect(validateOutbound(flow).filter((i) => i.severity === 'error')).toEqual([]); + const out = filled(flow, {}); + expect(Object.keys(out.nodes)).toEqual(['m', 'end']); + expect(validateOutbound(out).filter((i) => i.severity === 'error')).toEqual([]); + // Given a value, key 3 and everything behind it stay. + expect(Object.keys(filled(flow, { c: 'Three' }).nodes)).toHaveLength(4); + }); + + it('dropping_every_option_is_an_error', () => { + const flow = load( + [ + 'schema_version: 4', + 'id: f', + 'name: F', + 'entry: m', + 'variables:', + ' a: { default: "" }', + 'nodes:', + ' m:', + ' kind: menu', + ' prompt: Pick', + ' options: { "1": "{{a}}" }', + ' exits: { "1": m, no_input: m, invalid: m }', + '', + ].join('\n'), + ); + expect(fill(flow, {})).toEqual({ errors: [{ code: 'menu_without_options', name: 'm' }] }); + expect('flow' in fill(flow, { a: 'Yes' })).toBe(true); + }); + + it('leaves a malformed template as written', () => { + const flow = load( + [ + 'schema_version: 4', + 'id: f', + 'name: F', + 'entry: a', + 'variables:', + ' b: { default: x }', + 'nodes:', + ' a:', + ' kind: hangup', + ' prompt: "Hi {{b"', + '', + ].join('\n'), + ); + expect(filled(flow, { b: 'y' }).nodes.a).toMatchObject({ prompt: 'Hi {{b' }); + }); + + it('does not touch the input and returns a flow without variables unchanged', () => { + const flow = ask(); + const before = serializeFlow(flow); + filled(flow, { option3: 'Both' }); + expect(serializeFlow(flow)).toBe(before); + const plain = load( + 'schema_version: 3\nid: f\nname: F\nentry: a\nnodes:\n a:\n kind: hangup\n prompt: Hi {{x}}\n', + ); + expect(serializeFlow(filled(plain, {}))).toBe(serializeFlow(plain)); + }); +}); diff --git a/schema/README.md b/schema/README.md index 7ee4ef0..5f8f001 100644 --- a/schema/README.md +++ b/schema/README.md @@ -10,6 +10,7 @@ version it declares, and no other. | `flow.v1.schema.json` | `schema_version: 1` | the original seven components | | `flow.v2.schema.json` | `schema_version: 2` | `book` — appointment booking over the phone | | `flow.v3.schema.json` | `schema_version: 3` | `transfer` gains `whisper` and `timeout_secs` — a screened transfer | +| `flow.v4.schema.json` | `schema_version: 4` | top-level `variables` (each with a required `default`) — details a caller fills in per call, used through `{{name}}` placeholders; an audio prompt may keep the `template` it was voiced from | Version 2 is version 1 plus one component: every v1 document is a valid v2 document once its `schema_version` is bumped, and nothing else changed. @@ -17,6 +18,15 @@ Version 3 is version 2 plus two optional fields on `transfer`: every v2 document is a valid v3 document once its `schema_version` is bumped. The bump is for what the fields do, not for their shape. A reader that ignored `whisper` would hand the call over without calling the target first. +Version 4 is version 3 plus an optional top-level field, `variables`, and an +optional `template` on an audio prompt. Unlike the earlier bumps, `{{` now +means something: in a v4 document every `{{name}}` in a prompt, a `template` +or a menu label must be a well-formed placeholder naming a declared variable, +and `{{` anywhere else (apart from a `note`) is refused. So a v3 document is a +valid v4 document once bumped only if it holds no `{{`. The bump is again for +what the fields do: a reader that ignored `variables` would speak the +placeholders as written. Filling a v4 document with a call's values +(`fill`) gives back a v3 document, which every v3 reader runs. Everything downstream is generated or checked against these files: @@ -45,8 +55,10 @@ The schema owns **structure only**: - the field set and types of `Flow` and every node kind, - the `kind` discriminated union (`greeting`, `hours`, `menu`, `ring`, `message`, `transfer`, `hangup`, and `book` from v2), -- enums (`MessageTone`), the `Prompt` = `string | { audio, transcript? }` shape - (`transcript` is the optional text an audio clip was synthesized from), +- enums (`MessageTone`), the `Prompt` = `string | { audio, transcript?, template? }` + shape (`transcript` is the optional text an audio clip was synthesized from; + `template`, from v4, the text with placeholders it was voiced from), +- the `variables` map and each variable's `default` and `max_len` (v4), - required vs. optional fields and their defaults, - `schema_version` pinned to that file's version (a document declaring another version does not validate against it — it validates against that version's @@ -66,6 +78,7 @@ validator and are pinned by the shared `conformance/` corpus: | `book` numeric bounds, and whether its schedule leaves room for one appointment | arithmetic over the node's own schedule | | Which components a `schema_version` may carry | a rule *about* versions, not expressible inside one | | Safe-subset YAML (reject anchors, aliases, tags, duplicate keys) | concrete-syntax concern; anchors don't survive parsing | +| Placeholders (v4): well formed, naming a declared variable, only in a prompt, a `template` or a menu label; a default within its `max_len` | a parse of free text, checked against the flow's own `variables` | ## Unknown fields diff --git a/schema/flow.v4.schema.json b/schema/flow.v4.schema.json new file mode 100644 index 0000000..eef6d91 --- /dev/null +++ b/schema/flow.v4.schema.json @@ -0,0 +1,307 @@ +{ + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://schema.wavekat.com/flow/v4.json", + "title": "Flow", + "description": "The WaveKat call-flow (\"Receptionist\") document, schema_version 4. Version 4 is version 3 plus flow variables: a top-level `variables` map declares details filled in per call. Every version-3 document is a valid version-4 document once its `schema_version` is bumped, and nothing else changed. This file is the single source of truth for the document SHAPE, and — being the newest version — it is also the file both consumers generate their model types from, so one model covers every supported version. Semantic rules that a JSON Schema cannot express (graph reachability, exit-set exactness, hours/timezone math, DTMF digit validity, prompt length, per-component numeric bounds, and which components a given schema_version may use) are NOT encoded here — they live in each language's validator and are pinned by the shared conformance corpus. Unknown fields are permitted structurally, matching both implementations (Rust serde ignores them; the TS parser surfaces a non-blocking warning).", + "type": "object", + "required": ["schema_version", "id", "name", "entry", "nodes"], + "properties": { + "schema_version": { + "description": "Document format version. This file describes version 4 only; a document declaring another version validates against that version's schema file, not this one. (The type generators relax this constant to a plain integer so the generated model can hold any supported version — see scripts/generate.mjs and build.rs.)", + "type": "integer", + "const": 4 + }, + "id": { + "description": "Opaque platform-assigned id (flow_…). Treated as a label; appears in traces.", + "type": "string" + }, + "name": { + "description": "Human name shown in the editor and the read-only viewer.", + "type": "string" + }, + "version": { + "description": "Platform-assigned publish counter, bumped on publish. Defaults to 1 for a hand-written or generated pre-publish document. Distinct from schema_version.", + "type": "integer", + "minimum": 0, + "default": 1 + }, + "note": { + "description": "The author's note about the whole flow: free text for people reading it, in place of a YAML comment. Never read by the engine.", + "type": "string" + }, + "variables": { + "description": "Details a caller of this flow fills in per call, declared by name (a lowercase letter, then up to 31 lowercase letters, digits or underscores; the validators check the form, not the schema, so a reader never has to compile a pattern). A text prompt, an audio prompt's `template` and a menu option label refer to them with `{{name}}` placeholders and `{{#name}}…{{/name}}` blocks (the block's text is kept only when the value is non-empty; blocks do not nest). The validators check that every placeholder is well formed and names a declared variable, and refuse `{{` in any other field; a `note` is a comment and is never scanned. Before a call runs, the flow is filled: each placeholder becomes the call's value, or the default when the call gives none or a blank one, and the result is a schema_version 3 document with no variables. Needs schema_version 4: a reader that ignored the map would speak the placeholders as written.", + "type": "object", + "additionalProperties": { "$ref": "#/$defs/Variable" } + }, + "entry": { + "description": "Node id where execution begins.", + "type": "string" + }, + "nodes": { + "description": "The flat node set, keyed by human-meaningful node id and string-referenced by exits. Order is irrelevant to execution, but it is the author's reading order and is kept on save.", + "type": "object", + "additionalProperties": { "$ref": "#/$defs/Node" } + }, + "ui": { + "description": "Presentation metadata (canvas positions, annotations). Preserved on round-trip, never read by the engine. Opaque by design so a canvas editor can add layout fields without a schema bump." + } + }, + "$defs": { + "Variable": { + "description": "One declared variable.", + "type": "object", + "required": ["default"], + "properties": { + "description": { + "description": "What the value is, shown to whoever fills it in.", + "type": "string" + }, + "default": { + "description": "The value used when a call supplies none, so a flow always plays with no values given. May be an empty string, for a slot that is optional.", + "type": "string" + }, + "max_len": { + "description": "Longest a value may be, in Unicode characters.", + "type": "integer", + "minimum": 1, + "maximum": 500, + "default": 200 + } + } + }, + "Prompt": { + "description": "What a component speaks: TTS text (a bare string) or a reference to a pre-rendered audio asset shipped alongside the flow.", + "oneOf": [ + { "title": "Text", "type": "string" }, + { + "title": "Audio", + "type": "object", + "required": ["audio"], + "properties": { + "audio": { + "description": "Audio asset ref. A generated-clip ref is a voice_prompts id matching ^vprompt_[a-z0-9]+$.", + "type": "string" + }, + "transcript": { + "description": "The words this pre-rendered clip speaks — the text it was synthesized from — carried so a viewer can show what a caller hears, and for traces. Advisory only: playback always uses `audio`, never this. Optional and forward-added: absent on older documents and on refs the platform did not generate from text.", + "type": "string" + }, + "template": { + "description": "The text with `{{name}}` placeholders that `audio` was voiced from using the variables' defaults. A call that overrides a variable speaks the filled template instead of the clip; a call that does not plays `audio`. Only on an audio prompt, and only from schema_version 4: an older reader ignores it and plays the clip.", + "type": "string" + } + } + } + ] + }, + "MessageTone": { + "description": "The cue a message node plays between its prompt and the start of recording.", + "type": "string", + "enum": ["beep", "none"] + }, + "Exits": { + "description": "Wired exits: exit name → target node id. Which names are valid is a property of the node's kind and is checked by the validator, not by this schema.", + "type": "object", + "additionalProperties": { "type": "string" } + }, + "TimeRange": { + "description": "One open window: open–close as \"HH:MM\" (24-hour). Ordering and overnight rules are enforced by the validator.", + "type": "object", + "required": ["open", "close"], + "properties": { + "open": { "type": "string" }, + "close": { "type": "string" } + } + }, + "WeeklySchedule": { + "description": "Open ranges per weekday; a missing or empty day means closed all day.", + "type": "object", + "properties": { + "mon": { "type": "array", "items": { "$ref": "#/$defs/TimeRange" } }, + "tue": { "type": "array", "items": { "$ref": "#/$defs/TimeRange" } }, + "wed": { "type": "array", "items": { "$ref": "#/$defs/TimeRange" } }, + "thu": { "type": "array", "items": { "$ref": "#/$defs/TimeRange" } }, + "fri": { "type": "array", "items": { "$ref": "#/$defs/TimeRange" } }, + "sat": { "type": "array", "items": { "$ref": "#/$defs/TimeRange" } }, + "sun": { "type": "array", "items": { "$ref": "#/$defs/TimeRange" } } + } + }, + "HoursException": { + "description": "A single-date override of the weekly schedule (holiday / special hours).", + "type": "object", + "required": ["date"], + "properties": { + "date": { "description": "\"YYYY-MM-DD\" in the flow's timezone.", "type": "string" }, + "closed": { "description": "Closed all day regardless of ranges.", "type": "boolean", "default": false }, + "ranges": { "type": "array", "items": { "$ref": "#/$defs/TimeRange" } } + } + }, + "Node": { + "description": "One node: a component (kind + its config) plus its wired exits. An internally-tagged union on `kind`.", + "oneOf": [ + { "$ref": "#/$defs/GreetingNode" }, + { "$ref": "#/$defs/HoursNode" }, + { "$ref": "#/$defs/MenuNode" }, + { "$ref": "#/$defs/RingNode" }, + { "$ref": "#/$defs/MessageNode" }, + { "$ref": "#/$defs/TransferNode" }, + { "$ref": "#/$defs/HangupNode" }, + { "$ref": "#/$defs/BookNode" } + ] + }, + "GreetingNode": { + "description": "Speak a prompt, then continue. Exit: next.", + "type": "object", + "required": ["kind", "prompt"], + "properties": { + "kind": { "const": "greeting" }, + "note": { "description": "The author's note about this step: free text for people reading the flow, in place of a YAML comment. Never read by the engine.", "type": "string" }, + "prompt": { "$ref": "#/$defs/Prompt" }, + "exits": { "$ref": "#/$defs/Exits" } + } + }, + "HoursNode": { + "description": "Branch on the business's weekly schedule + holiday overrides. Exits: open, closed.", + "type": "object", + "required": ["kind", "schedule", "timezone"], + "properties": { + "kind": { "const": "hours" }, + "note": { "description": "The author's note about this step: free text for people reading the flow, in place of a YAML comment. Never read by the engine.", "type": "string" }, + "schedule": { "$ref": "#/$defs/WeeklySchedule" }, + "timezone": { "description": "IANA zone (America/New_York). Validated to resolve at load.", "type": "string" }, + "exceptions": { "type": "array", "items": { "$ref": "#/$defs/HoursException" } }, + "exits": { "$ref": "#/$defs/Exits" } + } + }, + "MenuNode": { + "description": "Speak a prompt and collect a DTMF choice. Exits: one per digit in options, plus no_input and invalid.", + "type": "object", + "required": ["kind", "prompt", "options"], + "properties": { + "kind": { "const": "menu" }, + "note": { "description": "The author's note about this step: free text for people reading the flow, in place of a YAML comment. Never read by the engine.", "type": "string" }, + "prompt": { "$ref": "#/$defs/Prompt" }, + "options": { + "description": "Digit key → human label. The exit for a digit is exits[digit]. Valid digit keys are enforced by the validator. A label may hold placeholders; one that is exactly a bare `{{name}}` whose filled value is empty removes the option, its exit, and any step only that exit led to, from the call.", + "type": "object", + "additionalProperties": { "type": "string" } + }, + "retries": { "type": "integer", "minimum": 0, "default": 1 }, + "timeout_secs": { "type": "integer", "minimum": 0, "default": 5 }, + "exits": { "$ref": "#/$defs/Exits" } + } + }, + "RingNode": { + "description": "Ring the human for a window. answered is an implicit terminal; the only wired exit is no_answer.", + "type": "object", + "required": ["kind", "timeout_secs"], + "properties": { + "kind": { "const": "ring" }, + "note": { "description": "The author's note about this step: free text for people reading the flow, in place of a YAML comment. Never read by the engine.", "type": "string" }, + "timeout_secs": { "type": "integer", "minimum": 0 }, + "exits": { "$ref": "#/$defs/Exits" } + } + }, + "MessageNode": { + "description": "Voicemail: speak a prompt, record, transcribe, notify. Terminal.", + "type": "object", + "required": ["kind", "prompt"], + "properties": { + "kind": { "const": "message" }, + "note": { "description": "The author's note about this step: free text for people reading the flow, in place of a YAML comment. Never read by the engine.", "type": "string" }, + "prompt": { "$ref": "#/$defs/Prompt" }, + "max_secs": { "type": "integer", "minimum": 0, "default": 120 }, + "tone": { "allOf": [{ "$ref": "#/$defs/MessageTone" }], "default": "beep" }, + "exits": { "$ref": "#/$defs/Exits" } + } + }, + "TransferNode": { + "description": "Hand the call to an external number. With `whisper`, a screened transfer: call the target first, play the whisper, and connect only when they accept; otherwise take `no_answer`. Without it, a blind transfer (terminal). `whisper` is spoken to the person at the target before they are connected, and `timeout_secs` is how long to let the target ring or decide. Both apply only to a screened transfer.", + "type": "object", + "required": ["kind", "target"], + "properties": { + "kind": { "const": "transfer" }, + "note": { "description": "The author's note about this step: free text for people reading the flow, in place of a YAML comment. Never read by the engine.", "type": "string" }, + "target": { "type": "string" }, + "whisper": { "$ref": "#/$defs/Prompt" }, + "timeout_secs": { "type": "integer", "minimum": 5, "maximum": 120 }, + "exits": { "$ref": "#/$defs/Exits" } + } + }, + "HangupNode": { + "description": "Speak an optional goodbye and end the call. Terminal.", + "type": "object", + "required": ["kind"], + "properties": { + "kind": { "const": "hangup" }, + "note": { "description": "The author's note about this step: free text for people reading the flow, in place of a YAML comment. Never read by the engine.", "type": "string" }, + "prompt": { "$ref": "#/$defs/Prompt" }, + "exits": { "$ref": "#/$defs/Exits" } + } + }, + "BookNode": { + "description": "Offer the caller open appointment times and book the one they choose, before the call ends. New in schema_version 2. The bookable grid is described here (weekly schedule + timezone + how long an appointment is); which times are actually free comes from the connected calendar at call time, and the engine never sees a credential. Exits: booked, no_slots, no_input, unavailable. Three fields carry more meaning than their types show, and are described here because a `$ref` with a sibling description makes the type generators emit a duplicate type instead of reusing the named one. `prompt` is spoken once before the open times are offered (\"I can book you in — here are the next available times\"); the times themselves are never part of it, since they are not known until the call. `confirm_prompt` is spoken immediately after a successful booking and directly BEFORE the booked time (\"You're booked for\" → \"Tuesday\" → \"ten thirty a.m.\"); it deliberately takes no placeholder, because a prompt is frozen audio by the time a call runs and nothing can be interpolated into the middle of it — anything that should follow the time belongs on the booked exit. `schedule` is when this business takes appointments, the `hours` node's weekly shape reused verbatim; it is not the same question `hours` answers, because a business can answer the phone at times it will not book.", + "type": "object", + "required": ["kind", "prompt", "confirm_prompt", "schedule", "timezone", "duration_mins"], + "properties": { + "kind": { "const": "book" }, + "note": { "description": "The author's note about this step: free text for people reading the flow, in place of a YAML comment. Never read by the engine.", "type": "string" }, + "prompt": { "$ref": "#/$defs/Prompt" }, + "confirm_prompt": { "$ref": "#/$defs/Prompt" }, + "schedule": { "$ref": "#/$defs/WeeklySchedule" }, + "timezone": { + "description": "IANA zone (America/New_York) the schedule is written in. Validated to resolve at load.", + "type": "string" + }, + "exceptions": { + "description": "Single-date overrides of the weekly schedule (holidays, one-off clinics), as on `hours`.", + "type": "array", + "items": { "$ref": "#/$defs/HoursException" } + }, + "duration_mins": { + "description": "How long one appointment runs. Bounds are the validator's (see each language's validate module), not this schema's.", + "type": "integer", + "minimum": 0 + }, + "buffer_mins": { + "description": "Clear time kept on BOTH sides of an appointment, so a slot is not offered flush against a busy interval.", + "type": "integer", + "minimum": 0, + "default": 0 + }, + "lead_mins": { + "description": "Nothing sooner than this many minutes from now is offered — the caller cannot book the next five minutes.", + "type": "integer", + "minimum": 0, + "default": 120 + }, + "horizon_days": { + "description": "How far ahead to look for open times.", + "type": "integer", + "minimum": 0, + "default": 14 + }, + "max_offers": { + "description": "How many times to offer the caller. Each offered time gets one keypad digit, counting from 1.", + "type": "integer", + "minimum": 0, + "default": 3 + }, + "retries": { + "description": "Extra attempts to collect a keypress after the first, as on `menu`.", + "type": "integer", + "minimum": 0, + "default": 1 + }, + "timeout_secs": { + "description": "How long to wait for a keypress on each attempt, as on `menu`.", + "type": "integer", + "minimum": 0, + "default": 5 + }, + "exits": { "$ref": "#/$defs/Exits" } + } + } + } +}