Phase 4: vals channel

[djdarcy]

Phase 4 of #65. Add capture_values parameter to find_matches() in grammar.py. Capture LHS/RHS values when vals channel active. Update format_match() in cli.py. Wire via channel_active('vals') in main.

[djdarcy]

Phase 4 — Complete

What was done

The vals channel annotates match output with evaluated LHS/RHS values. Unlike other channels that emit to stderr, vals controls what data gets captured during evaluation and included in stdout match output.

utils/grammar.py changes:

• ExpressionEvaluator.__init__() — Added capture_values: bool = False parameter. When True, stores comparison operand values after successful evaluation.
• Comparison evaluation — When capture_values=True and comparison succeeds, stores _last_comparison_values and _last_comparison_operators on the evaluator instance.
• find_matches() — Added capture_values: bool = False parameter. When True and evaluator has captured values, includes __vals__ and __ops__ keys in the yielded match dict.

utils/cli.py changes:

• format_match() — When __vals__ and __ops__ are present in match dict:
  • Text format: appends [666 == 666] or [1 < 5 < 10] (chained)
  • JSON format: adds "values": [666, 666] field
  • CSV format: appends value columns

prime-square-sum.py wiring:

evaluator = ExpressionEvaluator(registry, capture_values=out.channel_active('vals'))
for match in find_matches(ast, evaluator, bounds, iterator_factories,
                          capture_values=out.channel_active('vals')):

Opt-in behavior

vals is in OPT_IN_CHANNELS — it gets a default override of -1 (off). Activated with --show vals:

# Without vals (default)
$ python prime-square-sum.py --expr "does_exist primesum(n,2) == 666" --max n:20
Found: n=7

# With vals
$ python prime-square-sum.py --expr "does_exist primesum(n,2) == 666" --max n:20 --show vals
Found: n=7  [666 == 666]

Design rationale

From addendum discussion: vals is different from all other channels because it annotates stdout content (match lines) rather than writing to stderr. The implementation reflects this — channel_active('vals') gates whether values are captured, but the output flows through the normal stdout format_match() path, not through emit().

Analysis

See 2026-02-13__18-48-22__dev-workflow_issue65-implementation-plan.md for full design rationale.