Decision: should Maestro `${}` interpolation evaluate JS expressions (GraalJS parity) or stay lookup-only?

[thymikee]

Decision to make

Should Maestro-compat ${...} interpolation evaluate JavaScript expressions (GraalJS parity), or remain variable-lookup-only with loud failure?

Context

The typed engine (ADR 0015) deliberately implements ${} as literal variable lookup: ${VAR} resolves from flow config/env/runFlow env/runScript output.*; anything unresolved throws INVALID_ARGS (fail-loud — a deliberate #1217 decision replacing an earlier silent pass-through). Upstream evaluates the full ${...} payload as a GraalJS expression: arithmetic, ternaries, string concat, maestro.* namespace, JS truthiness.

The conformance oracle (#1289) now names exactly where this bites real flows:

• ${0 + 1} as tapOn.index (corpus upstream/032_element_index)
• full assertTrue parity (corpus upstream/067_assertTrue_pass)
• repeat.while / runFlow.when.true beyond platform comparisons
• upstream's own 065_when_true.yaml exercises ${undefined}, ${0}, ${[]}, ${{...}} as truthy conditions

Lookup-scoped subsets are being handled separately and do NOT require this decision: numeric-field ${VAR} lookup, and assertTrue: ${VAR} truthiness (phase 1).

Options

1. Stay lookup-only (status quo), document as a permanent deviation in ADR 0015 + the oracle's DOCUMENTED_DEVIATIONS. Cheapest; keeps the engine free of a JS-eval surface; flows using expressions keep failing loud with source lines.
2. Bounded expression support via the existing Node vm sandbox used by runScript (arithmetic/comparison/truthiness, no maestro.* host API). Middle ground; needs a defined subset and its own conformance vectors.
3. Full GraalJS-semantics parity. Largest surface; effectively an embedded expression engine with upstream-matching semantics; only worth it if real suites demand it.

Whatever is decided, encode it: option 1 → DOCUMENTED_DEVIATIONS entry; options 2/3 → corpus flows + generated vectors so the subset boundary is mechanical, not prose.

[thymikee]

Decision (maintainer): Option 1 — stay lookup-only, fail loud, teach the workaround

Rationale:

• Upstream's evaluator is GraalJS on the JVM — nothing reusable; we'd hand-build a JS engine whose sole job is matching another engine's coercion semantics (${undefined}/${0}/${[]}, NaN arithmetic, maestro.*) forever, with its own conformance vectors. Permanent complexity + size for a niche idiom.
• Worst failure mode of options 2/3: an expression evaluated slightly differently than GraalJS is silently wrong behavior — the exact bug class the typed engine and this oracle exist to eliminate. Loud failure beats approximate evaluation.
• The escape hatch already exists: runScript runs full JS in the vm sandbox and exports output.* into ${} scope. With Maestro compat: numeric option fields accept ${VAR} lookup interpolation (extendedWaitUntil.timeout, tapOn.index, siblings) #1293 + Maestro compat: assertTrue phase 1 — literal/${VAR}-lookup truthiness (expressions gated on #1292) #1295, runScript (compute) → ${output.x} (consume) covers every real case the corpus surfaced.

Encoding checklist (this issue tracks it; close when all land)

• DOCUMENTED_DEVIATIONS entry in scripts/maestro-conformance/expected-divergence.ts: ${} is variable lookup only, by decision; expressions fail loud.
• ADR 0015: one sentence in Consequences recording the decision and the runScript escape hatch.
• Teach the workaround in the error: when a ${...} payload is expression-shaped (not a bare [A-Za-z_][A-Za-z0-9_.]* name), the INVALID_ARGS message adds: compute it in a runScript and reference ${output.x}.
• Narrow FLOW_DIVERGENCES wording for upstream/032_element_index (and 067 post-Maestro compat: assertTrue phase 1 — literal/${VAR}-lookup truthiness (expressions gated on #1292) #1295) to reference this decision rather than a pending gap.
• Docs: one short "expressions" note in the Maestro compat page showing the runScript → ${output.x} pattern.

[thymikee]

Addendum: pre-approved upgrade path (demand-gated), and one correction to the rationale above

Correction: the "matching another engine's coercion semantics forever" risk is overstated for plain expressions — V8 and GraalJS are both spec-conformant ECMAScript engines, so arithmetic/comparisons/ternaries/truthiness evaluate identically by spec. The real parity contract is the injected environment (which globals exist: flow vars, output.*, maestro.*; scope persistence across expressions; injected types) — which is controllable because we choose what to inject. The decision to stay lookup-only stands, but its honest basis is absent demand (two corpus flows; the 38-flow RN suite never needed an expression), not infeasibility.

Pre-approved design if real user suites hit this wall (so demand triggers a scoped implementation, not a reopened debate):

1. Same Node vm sandbox runScript already uses — no new trust model.
2. Injected environment: flow variables + output.* + a deliberately tiny maestro.* subset (start: platform only).
3. Loud edges, never silent: any ReferenceError/SyntaxError/unprovided global → the existing INVALID_ARGS + runScript hint. Best-effort means evaluates-or-fails-loud, never evaluates-to-something-guessy.
4. Extraction becomes brace-aware (upstream allows ${{field:'value'}} and mid-string expressions) — regex is no longer sufficient.
5. Oracle coverage first: vendor upstream's 065_when_true.yaml-style flows so environment parity is measured, not assumed.
6. Known documented divergence to accept: upstream's evaluation scope persists across expressions (side-effectful expressions mutate shared state); a per-evaluation vm context differs there — document, don't chase.

Until that demand signal exists, the checklist in the decision comment above is the work.