Document the dependencies cmdstanr does not track

[jgabry]

Document the dependencies cmdstanr does not track

Part of the design described in #1254. I asked Claude to write the text below based on that.

---

The build record (#1238) tracks the Stan program, its includes, the user header, make/local and the CmdStan installation. What it leaves untracked is #1254 §6 ("Provenance we cannot complete" and "What no record can fix"): toolchain drift, compiler include-path environment variables, Make variables set in the environment, CmdStan or Stan Math modified in place, a make/local that includes another makefile, and headers the user header includes. force_recompile = TRUE is the remedy for every one of them, and nobody reaches for it without being told.

Checklist

Stage 3 (#1258)

• Both detectors: ^\s*(?:-?include|sinclude)\b on make/local, ^\s*#\s*include\s*" on the user header. They establish that a gap exists, never that none does, which is why the field is known_untracked_dependencies and not provenance_complete (Design note: v1.0 compilation state and C++ options #1254 §6, "Provenance we cannot complete")
• One line at compile time when a detector fires, naming the exposure and the remedy. Nothing on construction and nothing in pre-operation validation (Design note: v1.0 compilation state and C++ options #1254 §6)

Stage 4

• User-facing documentation of the untracked list and the remedy
• Angle-bracket includes named as the documented blind spot: a user-supplied -I is what makes #include <helpers.hpp> work, and the regex is not widened to [<"] because it would fire on <vector>

Compiler depfiles: the right mechanism, not in v1

Measured against CmdStan 2.39. CmdStan does not supply a depfile for models: make/program:106-108 sets up -include for one and :68 has a %.d: %.hpp rule, but the model's .hpp is an intermediate CmdStan deletes after linking, so make <model>.d gives No rule to make target.

cmdstanr could produce one itself:

c++ -std=c++17 <cmdstan -D flags> -MM -MG -MP -MF out.d user_header.hpp

About 150 ms warm. -MG makes it self-scoping: real paths are the user's files, <stan/math.hpp> and friends come back as bare names to discard. It would also close the angle-bracket blind spot. Costs: user -I flags must be forwarded or the closure is silently incomplete, an #ifdef on a macro defined inside stan/math evaluates differently during the scan, and .d parsing wants its own tests.

Not in v1 because it couples record validation to compiler flag construction, which can drift quietly, and puts a compiler invocation on a path that today only reads files and runs stanc. A release that adds it decides then whether records written before it still justify reuse.

Also worth documenting

Options that need CmdStan itself rebuilt are not an issue. CmdStan selects flag-specific main objects and precompiled headers by filename (makefile:97-118, :135, make/program:8), so flipping STAN_THREADS, STAN_MPI, STAN_OPENCL or STAN_NO_RANGE_CHECKS builds the right objects on demand.