Audience: Contributor
Machine-readable scenarios under shared/ai/scenarios/ may embed variance expressions in prompt and expectation strings. At Play, the AI server resolves them to concrete text before asking the assistant. Bindings live on the run state so Play-all keeps the same picks. Catalog load only syntax-checks; goldens stay concrete strings.
| Function | What it does | What it must not do | When to use |
|---|---|---|---|
$choose(a, b, …) |
At Play, pick one listed token at random. Same expression text in prompt and expectation shares that pick for the whole run. No model call. | Invent tokens not in the list. Change verbs or entities outside the slot. | A bound detail that may change (color, a listed name) while the rest of the scenario keeps the same structural contract. |
$llmVariance('seed') |
Call the Play model once. Return one user-request string that is worded differently (structure, synonyms, sentence shape) but means the same task. | Change difficulty, add requirements, drop entities or constraints, or return the seed unchanged. | The whole request (or a clause) should not overfit one phrasing. |
Unknown $name( is a catalogue load error. The catalog is closed: only these two functions ship.
$choose — comma-separated options; each option is an unquoted token (primary) or a quoted string ('Harbor Home').$llmVariance — exactly one quoted seed string.Step 0 (paraphrase the whole request; entity stays elephants):
$llmVariance('Build me a page about elephants')
Step 1 (material color slot):
change toolbar color to $choose(primary, secondary, tertiary, light, medium, dark)
Expectation for step 1 repeats the same $choose(...) so the chip names the resolved color.
$llmVariance rulesThe model prompt and this page share the same contract:
{"text":"..."}.If the model fails or the output is empty / equal to the seed (case-insensitive), Play falls back to the seed and sets varianceError on the run. Explore continues.
resolvedPrompt and variance (and varianceError if any) onto the candidate cassette for debug. Promote goldens remain concrete.Extra model latency for $llmVariance before the real assistant run is expected.
$alias(Create, Build, Make) — closed synonym list that must not change the outcome (deterministic, cheaper than $llmVariance). Not implemented yet. Distinct from $choose: choose may change a bound token; alias must not.