feat(variables): the engine evaluates parametric exercises (refs #220)

[astrapi69]

Summary

Part 1 of #220: the engine evaluates parametric exercises. Part 2, the grade lookup, waits for its first consumer, as the issue says; the issue stays open for it.

• resolveExerciseVariables(exercise, { random, values }), in the new src/resolve-variables.ts, on the package root.
  • It samples every sampled variable with the injected random source and evaluates computed variables in declaration order.
  • It rounds each value to its display precision and substitutes every reference to a declared variable in every string field.
  • It returns { exercise, values, toleranceByAcceptText }. values replays a previous attempt.
  • An exercise without variables comes back as the same object.
• evaluateExpression(expression, values) in variables.ts, on the parser the validator uses. The parser now builds a small syntax tree: parseVariableExpression reads the names from it and evaluateExpression computes it. One grammar, one implementation. The parse-error messages are unchanged, because E-VAR-EXPR passes them as parseError.
• The contract is the app's (adaptive-learner#3109 resolve-exercise-variables.ts), so the app can switch without changing its call site (ExerciseDispatcher.tsx).

Two differences from the app, both following from one grammar:

1. An expression the validator rejects (.5, a unary +) does not evaluate either. The app's tokenizer accepted both. Valid content never has them, because E-VAR-EXPR rejects them first.
2. A reference with spaces, {{ a }}, which the validator reads as a and accepts, is substituted. The app left it literal, so such content passed validation and showed raw braces to the learner. The same holds for a pure-reference accept entry {{ sum }} and its tolerance.

Division by zero gives the IEEE value (Infinity/NaN), as in the app. That is documented; a lint for it would be separate work.

Tests

• src/resolve-variables.test.ts, 39 tests, RED first (the module was missing).
  • 30 of them are the app's own test cases, ported unchanged as the parity oracle: sampleVariable, evaluateExpression, formatVariableValue and resolveExerciseVariables.
  • Plus: every expression the validator accepts evaluates; what it rejects throws, with the parse error in the message; division by zero; {{ a }} and {{ sum }} with spaces; {{...}} that is not a declared name stays; the variables block is kept; exports on the root.
• The existing variables.test.ts and issue-params.test.ts pass unchanged after the parser refactor.
• Differential check: the app's module (bundled from develop) and the engine function ran with the same seeded random stream on 8 synthetic parametric exercises × 50 seeds. 400 runs, 0 differences. A seeded probe with {{ a }} makes all 400 differ, so the check is not blind. There are no parametric exercises in the ten content repositories yet (0 found).
• make release-check, make prose-check, npm run docs:api:check and scripts/check-bundle-size.mjs pass. The core is at 88.1 of 90 kB gzip, so no budget raise was needed.

Docs

• lesson-format.md: the Variables section describes the resolver and drops "never samples or evaluates".
• README: API rows for the two functions and the types.
• architecture.md: open item for The engine evaluates what it defines: variable expressions now, the grade lookup with its first consumer #220.
• Blog "did we reinvent the wheel" (en and de): a dated update note on the old "never evaluates" statement.
• comparative-analysis.md §6.3.
• CHANGELOG.md.

Downstream (App lane)

The app replaces frontend/src/lib/exercises/variables/resolve-exercise-variables.ts with the engine's resolveExerciseVariables (same contract), and keeps its test file as a smoke test against the engine.

🤖 Generated with Claude Code