Module book 

The book component (schema_version 2): its bounds, and the vocabulary that lets a caller be told a time.

Why a vocabulary exists at all

Every sound a flow makes is a clip. The daemon runs no text-to-speech: prompts are rendered when the flow is published and frozen as version assets, and playback is a file read. That is what makes a flow work with no network, and it is why book cannot simply “say the time” — the time is not known until a caller is on the line, hours or days after the last thing was rendered.

So the times a flow can ever offer are enumerated at publish and rendered then, exactly like its prompts. Two things make that a small finite set rather than an impossible one: starts snap to a half hour (BOOK_GRANULARITY_MINS), and the node already declares the only hours it books in. A business open 9–5 on weekdays therefore needs 16 time clips, not 1440 — and needs them regardless of which week the caller rings in, because “nine thirty” is the same two words on every one of those days.

Why it is split day + time

An utterance is two clips: a day phrase, then a time phrase (“Tuesday”, then “ten thirty a.m.”). One clip per (day, time) pair multiplies the render count by nine for no gain. Going finer the other way — composing “ten”, “thirty” and “a.m.” separately — is what a naive reading suggests and is wrong: word order and grammar differ across the languages this platform ships, and an engine concatenating fragments in English order produces something between odd and unintelligible elsewhere. Whole phrases keep each language’s grammar inside the phrase, where a translator can see it; day-before-time is the one ordering assumption left, and it holds across all of them.

The contract

These refs are the contract between the two sides: the platform renders exactly this set at publish and stores it with the version’s frozen assets; the daemon plays them and never asks what they mean. Both sides compute the set from the same node config with vocabulary_refs, so neither can render one thing and expect another. The refs join [crate::model_ext]’s required_assets, which puts them behind the daemon’s existing “don’t arm a flow whose audio hasn’t synced” gate with no new machinery.

Twin: packages/flow-schema/src/book.ts. Keep the two in lockstep — the conformance corpus pins the ref sets they produce.

Enums

VocabularyRef

What a vocabulary ref means — so the side that renders it can look up the words without re-deriving the ref format.

Constants

BOOK_DAY_KEYS

The day phrases, always required. today/tomorrow are how a person says a date this close to now, and a caller told “Monday” on a Monday has to work out which Monday.

BOOK_GRANULARITY_MINS

Every candidate appointment start lands on a half hour.

DEFAULT_BOOK_BUFFER_MINS

DEFAULT_BOOK_HORIZON_DAYS

DEFAULT_BOOK_LEAD_MINS

DEFAULT_BOOK_MAX_OFFERS

DEFAULT_BOOK_RETRIES

DEFAULT_BOOK_TIMEOUT_SECS

MAX_BOOK_BUFFER_MINS

Widest clear time that may be kept on each side of an appointment.

MAX_BOOK_DURATION_MINS

MAX_BOOK_HORIZON_DAYS

Furthest ahead a book node may look.

MAX_BOOK_LEAD_MINS

Furthest ahead a caller may be pushed before the first offer (30 days).

MAX_BOOK_OFFERS

How many times one caller may be offered — bounded by the keypad digits the vocabulary carries.

MIN_BOOK_DURATION_MINS

Shortest and longest one appointment may run.

Functions

day_key

The day key for a slot, given how many civil days away it falls and which weekday it lands on (0 = Monday, matching BOOK_DAY_KEYS’s weekday order). Today and tomorrow win over the weekday name.

day_ref

bkday_tue — the day half of an utterance.

offer_refs

The clips that offer one time: what it is, then which key takes it.

parse_vocabulary_ref

Read a ref back into what it says. None for anything that is not a vocabulary ref (an author’s clip, a filename), so a caller can filter a mixed asset list with it.

press_ref

bkpress_2 — “press two”, the digit that takes the offer.

taken_ref

The one fixed line the component speaks on its own account: the slot the caller chose was taken between hearing it and pressing the key. Everything else a caller hears is either the author’s prompt or a time.

time_ref

bktime_0930 — the time half, in the flow’s own timezone.

time_refs

The clips that say one appointment time, in order: the day phrase then the time phrase (“Tuesday” → “ten thirty a.m.”).

vocabulary_refs

Every asset ref a book node needs in order to speak: the nine day phrases, one clip per bookable time of day, one “press N” per offer it may make, and the taken line. Sorted and unique, so two callers of this compare equal.