Module spec 

SessionSpec — a whole Live session as one serializable JSON document.

Where Flow made the governance DAG data, SessionSpec makes the application data: session framing (instruction, greeting, modality), declarative tool bindings (mock, HTTP, MCP), schema-as-JSON extraction that fills the state guards read, data-driven phases and watchers over the same closed Guard vocabulary, reusable flow fragments, and an embedded test suite that replays scripted conversations through the real FlowMonitor offline.

The invariants:

• What serializes, runs. SessionSpec::apply configures a Live builder from the document; nothing in the document needs Rust.
• What can fail, fails at load time. SessionSpec::validate runs the flow compiler, cross-checks tool names, and diffs the state keys guards read against the keys the session writes — the flow-level analogue of compile_with_tools for the dominant silent failure in data-authored flows (a guard waiting on a key nothing sets).
• The escape hatches stay in code. Custom closures (guards, tools, callbacks) are added on the returned builder after apply, exactly as before; the spec never pretends to serialize them.

Structs

AudioSpec

Input-audio hardening: the measured mic chain (denoiser, noise gate), client input-VAD tuning, and interruption authority. Lowers to Live::mic_denoise / mic_noise_gate / input_vad / client_interruption_authority; see the hardening chapter for the benchmark behind each default.

ClientVadSpec

Client input-VAD tuning: start from a preset, override individual knobs.

ComputedSpec

A computed (derived) state variable authored as data: key is written to derived:{key} whenever the Expr evaluates to a value. Dependencies are inferred from the expression’s Expr::keys_read, so the runtime’s dependency-ordered ComputedRegistry invariants hold with nothing extra to declare. Guards read the result by its bare key (the derived: fallback).

ExtractSpec

Schema-as-JSON out-of-band extraction: an OOB model fills schema from the transcript, the result lands in state under name, and promote rules write individual fields to bare keys — closing the loop that lets a flow advance from speech alone (captured guards latch with no tool call).

HttpBinding

An HTTP binding for a declared tool: the call is executed as an HTTP request with {args.field} / {state.key} interpolation in the URL, headers, and body strings, and the JSON response is returned to the model.

MemorySlotSpec

Project one remembered fact into a governed state slot: when memory holds a value for predicate, it is written to the to state key — where needs, captured, and every other guard reads it exactly as if the caller had just said it.

MemorySpec

The session’s durable-memory declaration. Installing it wires the memory subsystem in through a MemoryBinding supplied in SpecResources: the recall_context / manage_memory tools (ambient, so step allow lists don’t switch recall off), turn ingestion, end-of-session reconciliation, and the slot projections below. EffectSpec::Remember writes through the same binding.

NoiseGateSpec

Noise-gate stage parameters.

PatternSpec

A data-driven temporal pattern: fire effects when a state condition holds continuously — for a duration (sustained_secs) or a number of consecutive turns (turns). Exactly one of the two must be set.

PhaseSpec

A data-driven conversation phase.

PromoteSpec

Promote one extracted field into a session state key, where flow guards (captured, is_true, …) read it.

RepairSpec

Conversation-repair thresholds (unmet phase needs).

RuntimeSpec

Control-plane and voice tuning — every session capability that is configuration rather than conversation, in one section. Everything here lowers to a Live builder setter; omitted fields keep the builder’s defaults.

SessionSpec

A complete Live session as one JSON document. See the module docs.

SimSnapshot

One per-event snapshot of the flow’s state during a scripted replay — the Studio’s Preview scrubber steps through these, lighting up the DAG exactly as a live session would, with no model and no API key.

SpecResources

External resources a spec cannot carry: model handles and capability bindings.

SpecTest

A named, scripted conformance test embedded in the spec.

SpecValidation

Structured result of validating a SessionSpec.

StateFieldSpec

One declared state key: its type, meaning, and optional starting value.

TestExpectation

Assertions at a checkpoint. Every listed item must hold; omitted fields are not checked.

TestReport

The outcome of one SpecTest.

TestStepResult

The outcome of one scripted event.

ToolSpec

A declared tool. Without an http binding it is a mock: it returns response (default {"ok": true}) and writes set_state — enough to model, validate, and demo a governed conversation before any real tool exists. With http it performs the request instead (and still applies set_state afterwards, so guards latch identically) — swap a mock for a binding without touching the flow.

TranscriptionSpec

Input/output transcription toggles.

TransitionSpec

A data-driven phase transition: fire when the guard holds over state.

UseFragment

Splice a named flow fragment into the session’s flow under a namespace.

VadSpec

Voice-activity-detection tuning — the knobs that decide how eagerly the session hears speech start and stop.

WatchSpec

A data-driven state watcher: when key satisfies the condition, run the effects. Watchers receive the live session writer, so the full EffectSpec vocabulary applies — a watcher can set state, inject context, prompt the model, or remember durably.

Enums

AuthoritySpec

Interruption authority (measured trade: client is ~2× faster to barge in; server posted zero false interruptions in every benchmark run).

ClientVadPreset

Named client-VAD starting points.

ContextDeliverySpec

When batched context turns hit the wire.

EffectSpec

A serializable side effect for phase entry, watcher, and pattern actions — the closed-effect counterpart to Guard’s closed predicates. One vocabulary, honored identically wherever effects fire.

PersistenceSpec

Session persistence backend.

PromotePolicy

How extracted fields are promoted into bare state keys.

SchedulingSpec

Delivery mode for a background tool’s response.

SensitivitySpec

Speech-detection sensitivity for VadSpec.

SimEvent

One scripted event in a SpecTest.

SpecModality

Output modality for a spec-driven session.

StateType

Declared JSON type of a state key.

SteeringSpec

How phase instructions are steered to the model.

TriggerSpec

When an extractor runs.

WatchCondition

A data-driven state watcher condition.

Constants

MEMORY_TOOL_NAMES

Tool names a MemoryBinding installs (ambient on the flow).

Traits

MemoryBinding

The seam through which a memory engine plugs into a spec-driven session.

Functions

trace_test

Replay one named test and return a snapshot after every event (plus an initial “start” snapshot), for scrubbing. Errors when the flow cannot be built or the test name is unknown.