Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
5 changes: 4 additions & 1 deletion README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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 `2`). Each
- `schema_version` is a property of the **document** (currently `3`). 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.
Expand All @@ -78,6 +78,9 @@ code per language — **pinned by the shared corpus**, not generated. See
has to be able to say "I don't run that version" — which is what makes it
safe for the platform to hold back a document rather than hand over one that
would fail to parse. `book` is why version 2 exists.
- **A change in what a component does is a new version too.** A `transfer`
with a `whisper` is a screened transfer: an older build would ignore the
field and hand the call over blind. That is why version 3 exists.
- The npm package and the Rust crate version **independently** of
`schema_version` (they track implementation releases). A given package
release advertises which `schema_version`s it understands via
Expand Down
13 changes: 13 additions & 0 deletions conformance/canonical/screened-transfer.canonical.yaml
Original file line number Diff line number Diff line change
@@ -0,0 +1,13 @@
schema_version: 3
id: flow_screened_canon
name: Hand the call to a person
entry: person
nodes:
person:
kind: transfer
target: "+15551230100"
whisper: { audio: vprompt_whisper01, transcript: A caller asked to talk to someone. }
timeout_secs: 20
exits: { no_answer: bye }
bye:
kind: hangup
4 changes: 4 additions & 0 deletions conformance/canonical/screened-transfer.expected.json
Original file line number Diff line number Diff line change
@@ -0,0 +1,4 @@
{
"description": "A transfer carrying `whisper` and `timeout_secs` (schema_version 3) is written in schema property order (`target`, `whisper`, `timeout_secs`, `exits`), the whisper clip keeps its transcript, and the text is a fixed point. Neither field equals a default, so both are written.",
"comments": 2
}
15 changes: 15 additions & 0 deletions conformance/canonical/screened-transfer.input.yaml
Original file line number Diff line number Diff line change
@@ -0,0 +1,15 @@
# Screened transfer, written the way a person might: fields out of order,
# the whisper as a clip with its transcript, and a comment to drop.
schema_version: 3
name: Hand the call to a person
id: flow_screened_canon
entry: person
nodes:
person:
exits: { no_answer: bye }
timeout_secs: 20
whisper: { transcript: A caller asked to talk to someone., audio: vprompt_whisper01 }
target: "+15551230100"
kind: transfer
bye:
kind: hangup
5 changes: 5 additions & 0 deletions conformance/v2/invalid/v2-whisper-refused.expected.json
Original file line number Diff line number Diff line change
@@ -0,0 +1,5 @@
{
"description": "A version 2 document may not use `whisper` (or `timeout_secs`) on a transfer: an engine that only knows version 2 would ignore the whisper and hand the call over blind, so the field needs the version that has it. Added with version 3; the v2 cases around it are untouched.",
"structurallyValid": true,
"semantic": { "ok": false, "errors": ["field_requires_newer_schema"] }
}
12 changes: 12 additions & 0 deletions conformance/v2/invalid/v2-whisper-refused.yaml
Original file line number Diff line number Diff line change
@@ -0,0 +1,12 @@
schema_version: 2
id: flow_v2_whisper
name: Whisper in a version 2 document
entry: person
nodes:
person:
kind: transfer
target: "+15551230100"
whisper: A caller asked to talk to someone. Press any key to accept.
exits: { no_answer: bye }
bye:
kind: hangup
Original file line number Diff line number Diff line change
@@ -0,0 +1,5 @@
{
"description": "A screened transfer can fail to connect, so it must wire `no_answer`; without it a person who never picks up leaves the caller with nowhere to go. A blind transfer (no whisper) has no exits, which is why the shape alone cannot say so.",
"structurallyValid": true,
"semantic": { "ok": false, "errors": ["missing_exits"] }
}
Original file line number Diff line number Diff line change
@@ -0,0 +1,9 @@
schema_version: 3
id: flow_screened_no_exit
name: Screened transfer with no way out
entry: person
nodes:
person:
kind: transfer
target: "+15551230100"
whisper: A caller asked to talk to someone.
5 changes: 5 additions & 0 deletions conformance/v3/invalid/timeout-without-whisper.expected.json
Original file line number Diff line number Diff line change
@@ -0,0 +1,5 @@
{
"description": "`timeout_secs` is how long a screened transfer waits for the person to accept. A transfer with no `whisper` is blind and never waits, so the field means nothing there and is refused rather than ignored.",
"structurallyValid": true,
"semantic": { "ok": false, "errors": ["timeout_without_whisper"] }
}
9 changes: 9 additions & 0 deletions conformance/v3/invalid/timeout-without-whisper.yaml
Original file line number Diff line number Diff line change
@@ -0,0 +1,9 @@
schema_version: 3
id: flow_timeout_no_whisper
name: Timeout with nothing to screen
entry: person
nodes:
person:
kind: transfer
target: "+15551230100"
timeout_secs: 20
Original file line number Diff line number Diff line change
@@ -0,0 +1,5 @@
{
"description": "`timeout_secs` on a transfer is 5 to 120. The schema says so, and the validator says so again, so a caller that skips the structural pass still cannot publish a transfer that waits five minutes.",
"structurallyValid": false,
"semantic": { "ok": false, "errors": ["transfer_timeout_out_of_range"] }
}
13 changes: 13 additions & 0 deletions conformance/v3/invalid/transfer-timeout-out-of-range.yaml
Original file line number Diff line number Diff line change
@@ -0,0 +1,13 @@
schema_version: 3
id: flow_timeout_range
name: Waiting too long for a person
entry: person
nodes:
person:
kind: transfer
target: "+15551230100"
whisper: A caller asked to talk to someone.
timeout_secs: 300
exits: { no_answer: bye }
bye:
kind: hangup
5 changes: 5 additions & 0 deletions conformance/v3/outbound/invalid/blind-transfer.expected.json
Original file line number Diff line number Diff line change
@@ -0,0 +1,5 @@
{
"description": "Outbound calls may transfer from version 3, but only a screened transfer: the person who picks up hears a whisper first. A blind transfer would drop the callee on someone who did not know a call was coming. The same document is a valid inbound flow.",
"structurallyValid": true,
"semantic": { "ok": false, "errors": ["outbound_blind_transfer"] }
}
12 changes: 12 additions & 0 deletions conformance/v3/outbound/invalid/blind-transfer.yaml
Original file line number Diff line number Diff line change
@@ -0,0 +1,12 @@
schema_version: 3
id: flow_outbound_blind
name: Outbound blind transfer
entry: hello
nodes:
hello:
kind: greeting
prompt: Connecting you now.
exits: { next: forward }
forward:
kind: transfer
target: "+15551230100"
5 changes: 5 additions & 0 deletions conformance/v3/outbound/invalid/no-answer-loop.expected.json
Original file line number Diff line number Diff line change
@@ -0,0 +1,5 @@
{
"description": "`no_answer` happens without the callee, like a menu's `no_input`, so ring -> greeting -> ring never needs anyone to do anything and would redial for ever.",
"structurallyValid": true,
"semantic": { "ok": false, "errors": ["outbound_unbounded_loop"] }
}
13 changes: 13 additions & 0 deletions conformance/v3/outbound/invalid/no-answer-loop.yaml
Original file line number Diff line number Diff line change
@@ -0,0 +1,13 @@
schema_version: 3
id: flow_outbound_no_answer_loop
name: Outbound ring that retries for ever
entry: front
nodes:
front:
kind: ring
timeout_secs: 20
exits: { no_answer: again }
again:
kind: greeting
prompt: Nobody picked up, trying again.
exits: { next: front }
Original file line number Diff line number Diff line change
@@ -0,0 +1,5 @@
{
"description": "A reminder call that can hand the callee to a person: a menu, then a screened transfer, then a `ring` step as the second try, then a goodbye. Version 3 lets an outbound call use `ring` and a screened `transfer`; the loop back to the menu needs a key press, so it is bounded.",
"structurallyValid": true,
"semantic": { "ok": true, "errors": [] }
}
32 changes: 32 additions & 0 deletions conformance/v3/outbound/valid/interview-reminder.yaml
Original file line number Diff line number Diff line change
@@ -0,0 +1,32 @@
schema_version: 3
id: flow_interview_reminder
name: Interview reminder with a hand-off
entry: hello
nodes:
hello:
kind: greeting
prompt: This is a reminder about your interview tomorrow.
exits: { next: ask }
ask:
kind: menu
prompt: Press 1 to confirm, or 2 to speak to someone.
options: { "1": Confirm, "2": Speak to someone }
exits: { "1": thanks, "2": person, no_input: bye, invalid: ask }
person:
kind: transfer
target: "+15551230100"
whisper: Interview reminder call. The candidate asked to talk to someone.
timeout_secs: 20
exits: { no_answer: desk }
desk:
kind: ring
timeout_secs: 20
exits: { no_answer: sorry }
sorry:
kind: hangup
prompt: Sorry, nobody is free right now. We will call you back.
thanks:
kind: hangup
prompt: Thank you, see you tomorrow.
bye:
kind: hangup
5 changes: 5 additions & 0 deletions conformance/v3/valid/minimal.expected.json
Original file line number Diff line number Diff line change
@@ -0,0 +1,5 @@
{
"description": "Version 3 is version 2 plus optional `whisper` and `timeout_secs` on `transfer` and nothing else: a document that uses none of the new surface is the same document it was, and must still validate once its schema_version is bumped.",
"structurallyValid": true,
"semantic": { "ok": true, "errors": [] }
}
7 changes: 7 additions & 0 deletions conformance/v3/valid/minimal.yaml
Original file line number Diff line number Diff line change
@@ -0,0 +1,7 @@
schema_version: 3
id: flow_min3
name: Minimal, version 3
entry: bye
nodes:
bye:
kind: hangup
6 changes: 6 additions & 0 deletions conformance/v3/valid/screened-transfer.expected.json
Original file line number Diff line number Diff line change
@@ -0,0 +1,6 @@
{
"description": "A screened transfer: a `transfer` with a `whisper` calls the target first and connects only when they accept, so it needs a `no_answer` exit for the case where they don't. The whisper clip is part of the assets a daemon must have before it arms the flow.",
"structurallyValid": true,
"semantic": { "ok": true, "errors": [] },
"requiredAssets": ["vprompt_whisper01"]
}
27 changes: 27 additions & 0 deletions conformance/v3/valid/screened-transfer.yaml
Original file line number Diff line number Diff line change
@@ -0,0 +1,27 @@
schema_version: 3
id: flow_screened_transfer
name: Hand the call to a person
version: 1
entry: ask
nodes:
ask:
kind: menu
prompt: Press 1 to talk to a person.
options:
"1": A person
exits:
"1": person
no_input: goodbye
invalid: goodbye
person:
kind: transfer
target: "+15551230100"
whisper:
audio: vprompt_whisper01
transcript: A caller asked to talk to someone.
timeout_secs: 20
exits:
no_answer: goodbye
goodbye:
kind: hangup
prompt: Goodbye.
19 changes: 19 additions & 0 deletions crates/compat-old-readers/tests/old_readers.rs
Original file line number Diff line number Diff line change
Expand Up @@ -149,3 +149,22 @@ fn old_reader_refuses_versions_it_does_not_know() {
let flow = old_flow::Flow::from_yaml(yaml).expect("parses; the version gate is validate");
assert!(old_validate(&flow).is_err());
}

#[test]
fn old_reader_refuses_a_screened_transfer_rather_than_run_it_blind() {
// `whisper` is what makes a transfer screened. A reader that parses the
// document but does not know the field would drop it and hand the call
// over blind, so the document declares version 3 and the old reader must
// refuse that version. It parses (unknown keys are tolerated); the
// refusal is the validation gate.
let yaml = fs::read_to_string(corpus().join("v3/valid/screened-transfer.yaml")).unwrap();
let old = old_flow::Flow::from_yaml(&yaml).expect("parses; unknown keys are tolerated");
assert!(
!old_flow::SUPPORTED_SCHEMA_VERSIONS.contains(&schema_version(&yaml)),
"{OLDEST_READER} claims to read version 3"
);
assert!(old_validate(&old).is_err());
assert!(
wavekat_flow::validate::validate(&wavekat_flow::Flow::from_yaml(&yaml).unwrap()).is_ok()
);
}
2 changes: 1 addition & 1 deletion crates/wavekat-flow/build.rs
Original file line number Diff line number Diff line change
Expand Up @@ -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];
const VERSIONS: &[u32] = &[1, 2, 3];

fn main() {
println!("cargo:rerun-if-changed=build.rs");
Expand Down
Loading
Loading