[v0.5] Formula-derived variables: ADR + phased implementation

[DougManuel]

Part of the post-v0.4.0 development plan (development/post-v040-development-plan.md, Phase 2, Task 6). Design doc first; implementation gated on ADR approval.

Context

Derived variables are the core of the recodeflow ecosystem, but MockData detects and skips them (identify_derived_vars(), DerivedVar::/Func:: in variableStart) — mock data cannot exercise the pipelines it exists to test.

The hard part is already prototyped. The v0.4 spike (merged PR #27, later removed from the tree) implemented formula referent validation, dependency extraction via all.vars(str2lang(...)), topological ordering, and cycle detection. Recover it with:

git show f4f9b41:development/v04-simstudy-spike/prototype.R

And the spec shape already anticipates this: .new_mock_spec_variable() has unused formula and depends_on fields (R/mock_spec.R:94-145).

ADR must decide

1. Metadata syntax entry — how formulas enter from recodeflow metadata. Options: (a) new explicit MockData-extension column (e.g. mockFormula); (b) reuse variableStart DerivedVar::/Func:: notation. Plan recommendation: (a) — avoids overloading recodeflow semantics; cchsflow and chmsflow are CRAN-published downstreams, so any shared-column semantics change needs coordination.
2. Evaluation environment contract — restricted environment containing generated columns plus a whitelist of base math functions; no filesystem/network/global access. Define the whitelist.
3. Phasing — Phase A: algebraic formulas over generated columns (spike covers this). Phase B: Func:: dispatch to functions in the consuming package's namespace (define lookup + failure semantics).
4. Diagnostics — how derived columns appear in mockdata_diagnostics.

Sequencing

Land in the same minor release as the seed-contract ADR (companion v0.5 issue): dependency-ordered generation reshuffles draw order, so batch the two seeded-output breaks into one.

Acceptance

• development/adr/v05-formula-evaluator.md merged after maintainer review.
• Then: implementation plan written per the plan doc's instructions; spike promoted to R/ with tests (referent validation, cycle detection error message, deterministic ordering, seed reproducibility).

[DougManuel]

ADR accepted and committed to dev (c132ed4): development/adr/v05-formula-evaluator.md.

Decisions: Phase A (algebraic formulas) only — Func:: dispatch to consuming-package functions deferred to a separate future workstream. Formulas enter via a new mockFormula extension column on variable_details (DerivedVar::/Func:: recodeflow semantics untouched — safe for cchsflow/chmsflow). Evaluated as a post-baseline stage over generated data in a restricted sandbox (generated columns + a ratified base-function allow-list, validated before generation). Dependency ordering + cycle detection recovered from the v0.4 spike (git show f4f9b41:development/v04-simstudy-spike/prototype.R).

Key property: because formula variables depend on generated values (not generation order), the evaluator needs no whole-spec reorder — so #39 adds no seeded-output break beyond #38's. It co-releases with #38 in v0.5.

mockFormula present ⇒ MockData generates the variable; bare DerivedVar::/Func:: ⇒ still excluded (external derivation, backward compatible). Next: the #39 implementation plan (development/plans/), then execute → then tag v0.5. No implementation code written yet.