From efe479023f70933fa5393f55a84cb231d79f312a Mon Sep 17 00:00:00 2001 From: Eason WaveKat Date: Mon, 10 Aug 2026 20:25:00 +1200 Subject: [PATCH 1/2] docs(flow-schema): how to take a grid change safely MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The half-hour move is the first release where adopting the package in the wrong order breaks live calls, and the constraint lives in the platform's docs — where a consumer of this package will never look. Release-As: 0.0.11 --- packages/flow-schema/README.md | 17 +++++++++++++++++ 1 file changed, 17 insertions(+) diff --git a/packages/flow-schema/README.md b/packages/flow-schema/README.md index 9d82464..0c8b8ba 100644 --- a/packages/flow-schema/README.md +++ b/packages/flow-schema/README.md @@ -68,6 +68,23 @@ keys, implicit typing) and reports node-level source ranges for editor diagnostics. Validation covers what a schema can't: reachability, caller traps, exit-set exactness, hours math, DTMF and prompt rules. +## Upgrading when the booking grid moves + +`BOOK_GRANULARITY_MINS` decides which times a `book` node can ever say, so +changing it changes what `bookVocabularyRefs` — and therefore +`requiredAssets` — returns for a node nobody edited. + +A device computes that set from the version of the Rust crate **compiled +into it**, not from anything the flow document carries, and refuses to arm a +flow whose required assets aren't all on disk. So an authoring side that +adopts a narrower grid first publishes versions that older devices consider +incomplete, and they stop running the whole flow — not just its booking +step. + +Adopt in this order: release, then every device in the field, then the +authoring side. Narrowing leaves the published set a superset in the +meantime, which is the safe direction. + ## One format, two languages This package is the TypeScript (authoring) half of the format. Parsing, From 35dc8069df65c7f0cf12caad43825843ae4f0fa2 Mon Sep 17 00:00:00 2001 From: Eason WaveKat Date: Mon, 10 Aug 2026 20:25:00 +1200 Subject: [PATCH 2/2] docs(wavekat-flow): how to take a grid change safely The device half of the same note: this crate is what computes the required set, so it has to move first. Release-As: 0.0.8 --- crates/wavekat-flow/README.md | 17 +++++++++++++++++ 1 file changed, 17 insertions(+) diff --git a/crates/wavekat-flow/README.md b/crates/wavekat-flow/README.md index ce5c50d..a4549b2 100644 --- a/crates/wavekat-flow/README.md +++ b/crates/wavekat-flow/README.md @@ -67,6 +67,23 @@ if let Err(errors) = validate::validate(&flow) { } ``` +## Upgrading when the booking grid moves + +`BOOK_GRANULARITY_MINS` decides which times a `book` node can ever say, so +changing it changes what `vocabulary_refs` — and therefore +`required_assets` — returns for a node nobody edited. + +This crate is where a device answers that question, from the constant +compiled into it rather than from anything the flow document carries, and a +device refuses to arm a flow whose required assets aren't all on disk. So a +device left on an older grid, handed a version published by an authoring +side that already narrowed, asks for a clip that was never rendered and +stops running the whole flow — not just its booking step. + +Take this crate's upgrade **before** the authoring side takes the matching +`@wavekat/flow-schema`. Narrowing leaves the published set a superset in the +meantime, which is the safe direction. + ## One format, two languages This crate is the Rust half of the format. Authoring, comment-preserving