Make cpp_options and stanc_options persistent across compile() calls for 1.0?

[jgabry]

Written with the assistance of both Claude and Codex based on my prompting

Problem

cpp_options and stanc_options supplied to cmdstan_model() or
$compile() are retained only until the first successful compilation consumes
them. A later $compile() call on the same object uses empty option lists unless
the options are supplied again.

This differs from include_paths and user_header, which are persistent model
configuration: when omitted from a later $compile() call, their most recently
supplied values are reused. The distinction is encoded as an explicit
specification in tests/testthat/test-model-compile.R (the tests beginning
"successful compilation consumes one-shot cpp and stanc options" and
"$compile() doesn't reuse cpp and stanc options supplied to
cmdstan_model()"), but no user-facing or architectural reason for the opposite
lifecycle is recorded.

For example, this currently compiles the second time without threading:

mod <- cmdstan_model(stan_file, compile = FALSE)
mod$compile(
  cpp_options = list(stan_threads = TRUE),
  force_recompile = TRUE
)
mod$compile(force_recompile = TRUE)

This is especially relevant to #1238. Once CmdStanR records build provenance
and automatically rebuilds when desired configuration differs from an artifact,
an omitted option must have an intentional meaning. Treating omission as an
empty configuration would make a bare $compile() remove options from the
previous build.

Proposed 1.0 behavior

Treat C++ and stanc options as persistent desired build configuration, like
include paths and the user header:

• Omitting cpp_options or stanc_options reuses the most recently configured
  value.
• Supplying a nonempty list replaces the corresponding configuration; it does
  not patch or merge with the previous list.
• Explicit cpp_options = list() or stanc_options = list() clears the
  corresponding configuration.
• A NULL element inside cpp_options, such as
  list(stan_threads = NULL), retains its current meaning: it emits an empty
  STAN_THREADS= assignment and overrides make/local.
• The desired configuration is updated before compilation and survives a failed
  build, while the installed artifact's recorded options change only after a
  successful executable installation.

R can distinguish omission from an explicitly supplied empty list with
missing(), so this does not require a new user-facing argument.

Internally, this would also remove the need for precompile_cpp_options_ and
precompile_stanc_options_: the fields currently exist to hold constructor
options until the one compilation that consumes them. It supports the state
model proposed in #1238: persistent desired configuration plus a committed
artifact snapshot.

Compatibility and scope

This is a breaking change to repeated $compile() calls on the same
CmdStanModel, and the existing tests intentionally specify the current
one-shot behavior. It should therefore be decided deliberately for 1.0 rather
than folded quietly into #1238 or described as a bug fix.

The ordinary cmdstan_model() path creates a fresh object and is unaffected.
The changed behavior requires multiple compilations through the same object,
which narrows the compatibility impact.

Related: #1234 established persistence for include_paths and user_header but
explicitly left the one-shot build-option behavior unchanged.

Questions to settle

1. Should both cpp_options and stanc_options persist, or is there a reason
   for different lifecycles?
2. Should an explicitly supplied list replace the previous configuration, as
   proposed, or merge with it?
3. How should the pedantic convenience argument interact with persistent
   stanc_options?
4. Should desired options be updated by dry_run = TRUE, consistently with
   other desired source configuration?

[jgabry]

Some additions from digging into the call sites, again with Claude's help.

Two of the open questions look answerable already, and there are two consequences worth
recording before anyone implements this.

Correction to the issue body

The test names quoted above don't exist. The two tests are:

• "$compile() doesn't reuse cpp and stanc options from the previous compilation"
  (tests/testthat/test-model-compile.R:268)
• "$compile() doesn't reuse cpp and stanc options supplied to cmdstan_model()"
  (:313)

The quoted string is closer to the comment at :283.

Q2 (replace vs. merge) is already settled by the option semantics

Merge cannot express removal, and the obvious sentinel is taken:
list(stan_threads = NULL) already means STAN_THREADS= — an empty assignment
that overrides make/local, not an absence. So under merge semantics there would
be no way to say "forget this option," short of inventing a second sentinel.

Replace isn't a preference here, it's forced. Worth closing the question rather
than leaving it open.

Q3 (pedantic) has an answer, and it generalizes

pedantic writes into stanc_options at R/model.R:670-671, after the
precompile fallback:

if (pedantic) {
  stanc_options[["warn-pedantic"]] <- TRUE
}

The injection only ever adds. So if the post-injection list is what gets stored as
the desired configuration, pedantic = TRUE becomes sticky forever, and a later
call with the default pedantic = FALSE cannot undo it — the user would have to
pass stanc_options = list() to clear something they never put there.

user_header has the identical shape: compile() injects the resolved header
into cpp_options at R/model.R:707, from private$user_header_, after the
argument has been read.

Both reduce to one rule this issue should state outright:

Arguments that inject into the option lists must be applied downstream of the
stored desired configuration, never folded into it.

Otherwise the convenience arguments quietly become one-way latches, which is a
worse version of the lifecycle problem this issue exists to fix. It also answers a
question not yet asked: clearing cpp_options should not clear the user header,
because the header is its own argument with its own persistence, and only its
injected copy ever lives in cpp_options.

A consequence not yet recorded

cpp_options_available <- length(cpp_options) > 0 at R/model.R:641 gates
whether the no-op path runs mismatch checking at all. Under persistent
configuration cpp_options is nearly always non-empty, so that check would begin
running on every no-op rather than only when options were passed on that call.

It shouldn't produce warnings — desired configuration and the recorded build agree
after a successful compile — but it changes which code path executes on the most
common call in the package, and that is where surprise warnings tend to come from.
Whoever implements this should check it deliberately rather than discover it.

Dependency framing

The issue relates this to #1238, but #1238 only records provenance. The reason
an omitted option needs a defined meaning is that something eventually rebuilds
on mismatch, which is #1019.

That matters for ordering: this is a prerequisite for #1019 and should be settled
before the sidecar rather than treated as downstream of it, since what the
sidecar's comparison means depends on the answer.

Q4 (dry_run)

Now open in two places — see #1249, which raises the same question for
cmdstan_version_, where a dry run currently assigns the configured CmdStan
version at R/model.R:950. Both are the same underlying question: whether a dry
run may write fields that describe an installed artifact. Probably worth one
answer rather than two.

[jgabry]

One more thing worth recording here, since it comes up as soon as anyone reads
this proposal: what is force_recompile = TRUE for afterwards?

Persistence itself doesn't touch it — persistence decides what you build with,
force_recompile decides whether you build. They're orthogonal.

But the combination of this issue and #1019 does remove its most common use today.
cmdstanr currently instructs users to reach for it as a workaround for its own
blindness (R/model.R:800-801):

"The executable was not rebuilt, so this call did not apply them. Use
'force_recompile = TRUE' to rebuild the model."

Once a rebuild happens automatically on recorded disagreement, $compile(cpp_options = X)
does the right thing on its own, and the $compile(cpp_options = X, force_recompile = TRUE)
idiom stops being necessary. That idiom is well established — 118 force_recompile = TRUE
call sites across the test suite, concentrated in test-model-compile.R (41) and
test-model-recompile-logic.R (21) — though many of those are legitimately forcing
a rebuild rather than working around the gap.

What remains is a real set, and none of it is served by anything else:

• Inputs nothing records. Compiler upgrades, CXXFLAGS edits in make/local,
  a changed system library. Record what an executable was built with, alongside the executable? #1238 deliberately keeps toolchain inputs outside the
  recorded set rather than chasing completeness, so this is permanent rather than
  a gap to be closed later.
• Include shadowing. A new higher-priority file shadowing an already-resolved
  include cannot be detected without re-running stanc. A documented limitation
  with force_recompile as the remedy.
• Distrust of the artifact. Never detectable, always legitimate.
• Establishing provenance deliberately on a pre-sidecar executable, rather
  than waiting for the one-time migration rebuild.
• Tests.

So the argument ends up better defined rather than redundant. Today it does two
jobs: genuinely forcing a rebuild, and compensating for cmdstanr not knowing
whether one is needed. #1019 takes the second job away, leaving the honest one —
rebuild even though the recorded facts say you don't have to.

Worth stating explicitly in whatever documentation comes out of this, because the
flag's meaning changes without its signature changing, which is the kind of drift
that goes unnoticed until someone proposes deleting it.

[jgabry]

Decision: yes, for 1.0

Recording this so the design work downstream has something definite to build on.
If you disagree, please say so here — this is a written decision precisely so
it is easier to argue with than an open question, and it is not too late.

What decided it

Not the "surprising behaviour" argument in the original post, which invites a
matter-of-taste discussion. Two things carried more weight:

It is a consistency defect, not a preference. include_paths and
user_header are already persistent desired configuration — omitted means reuse,
supplied means replace (R/model.R:646). cpp_options and stanc_options are
the same kind of input and get the opposite lifecycle, and no user-facing or
architectural reason for the difference is recorded anywhere. Four build inputs,
two lifecycles, one of them unjustified.

One-shot forces #1019 to invent a third lifecycle. Once cmdstanr rebuilds on
its own initiative — an include changed, options disagree with the artifact — it
has to build with something. Under one-shot the honest answer is "nothing, the
previous compile consumed them", so an automatic rebuild would silently drop the
user's threading. The user did not ask for that rebuild and gets no chance to
re-supply anything. The alternative is a special case where automatic rebuilds
reuse configuration and explicit ones do not, which is a third lifecycle in a
system that already has one too many.

So this is less a feature than a prerequisite: it is what makes the next thing
expressible without special-casing.

Honest about the size of the win

On its own the user-visible benefit is modest. The common path —
cmdstan_model() once per script — is unaffected either way, and both lifecycles
have a lose-your-configuration failure mode. Persistence mostly relocates it:

• one-shot bites on $compile() with no options, a very common call shape;
• persistence bites on $compile(cpp_options = list(X)) when Y was configured
  earlier, since replace discards Y — which needs two different option sets on
  one object and is much rarer.

Strictly rarer failure mode, so it is the better default, but "we moved the
footgun somewhere less trafficked" is a fairer claim than the original post makes.
If #1019 were off the table this would be close to a wash and probably not worth
spending a breaking change on. It is the combination that earns it, and 1.0 is
when both can land coherently.

Status of the four questions

1. Decided — both persist, same lifecycle.
2. Resolved: replace, and it is forced rather than chosen. Merge needs a
   deletion sentinel and NULL is already occupied by the meaningful empty
   assignment STAN_THREADS=. See the comment above.
3. Resolved: apply downstream, never fold in. pedantic (R/model.R:670)
   and user_header (:707) both inject into the option lists after the argument
   is read. Storing the post-injection list as desired configuration turns both
   into one-way latches that cannot be switched off. They stay their own desired
   fields and are injected during command construction.
4. Still open, and now open in two places — see $cmdstan_version() reports the installed CmdStan, not the version that built the executable #1249, where a dry run
   assigns cmdstan_version_ at R/model.R:950. Both are the same question:
   whether dry_run = TRUE may write fields describing an installed artifact.
   Worth one answer rather than two.

Sequencing

This should be settled before #1238 starts in earnest — not because any code
depends on it, but because the sidecar's comparison cannot be specified while
"omitted" is ambiguous. It is a decision rather than an implementation, so it can
run concurrently with #1230 and #1232.

[jgabry]

Two corrections to the comment above, from review.

"Its meaning changes" was the wrong framing. The lasting contract is stable:

Bypass cmdstanr's automatic up-to-date decision and perform a build using the
current desired configuration.

That sentence is as true after #1019 as before. What narrows is its role — one
workaround use disappears, not the meaning.

Worth noting the sentence is only stable because it is phrased in terms of desired
configuration, which this issue redefines. The observed behaviour of a bare
mod$compile(force_recompile = TRUE) after a configured build does change: today
it builds with nothing, afterwards it builds with the persisted configuration.

Two surviving uses were missing:

• Applying a changed opaque argument such as FOO+=x immediately. Record what an executable was built with, alongside the executable? #1238's
  design deliberately refuses to rebuild automatically on opaque differences, which
  makes force_recompile the only way to apply one.
• Regenerating C++ when the executable is valid but no generated C++ is held.
  Already documented at R/model.R:479-480: "Use force_recompile=TRUE to force
  generation of the C++ code."

And one example in that list was wrong. I cited CXXFLAGS edits in
make/local as an unrecorded input. If #1238 records a make/local fingerprint,
that edit is detected. Better examples of genuinely unrecorded inputs: Makefiles
included from make/local, environment variables, and compiler version changes.

That said, the fingerprint is currently listed as an optional field, and its
use is unspecified — which is worth settling in #1238 before leaning on it. The
obvious policy, "a changed fingerprint invalidates the record," would mean adding a
comment line to make/local invalidates every sidecar on the machine and rebuilds
every model. Recording it is cheap; deciding what a mismatch does is not, and the
answer is not obviously "invalidate."

[jgabry]

Closing as won't-do. The decision recorded in this issue is reversed. Design note: #1254.

Persistent cpp_options/stanc_options are replaced by one-shot configuration: cmdstan_model() is the only place a build is configured, every call states what it wants, and the model object carries no durable configuration at all.

The argument in this issue was not wrong, and it is worth saying how it is answered rather than just overruling it. The case for persistence was not convenience — it was that once cmdstanr rebuilds on its own initiative it has to build with something, and under one-shot semantics the honest answer is "nothing, the previous compile consumed the options." An automatic rebuild would then silently drop the user's threading. That is correct, and it is why this stayed open through several rounds.

It is answered by removing the premise rather than by persisting. An unrequested rebuild never replays stored configuration:

• the constructor rebuilds using the request on the call in front of it
• anything that would run a stale executable errors instead of rebuilding silently (§5 of the note)

So there is no point at which cmdstanr needs configuration it was not just given. The third lifecycle this issue was protecting against does not arise.

Two related changes make the lifecycle question moot rather than merely decided: $compile() is removed entirely (#1256), so there is no second call that could inherit or drop anything; and what an executable was built with lives in a record beside it (#1238) rather than in object state, so it is inspectable and cannot drift from the artifact.

§2 of the design note is the current specification.