[ChrisRackauckas-Claude]

Summary

Makes the umbrella and sublibrary GROUP=QA lanes green for the issue #55 findings (implicit imports, undocumented public API, unapproved reexports) without QA opt-outs: SciMLTesting 2 in QA envs, explicit @random_variables import, real docstrings/docs, and intended reexports_allow lists. Round-2 corrected false quadratic stability claims. Round-3 fixes the @random_variables scalar-bounds docstring example (literals only; macro unchanged) and asserts the documented bounds.

What changed and why

SciMLTesting failed on main with an implicit import of @random_variables, missing docstrings on the reexported public API, and unapproved public reexports. This PR bumps QA envs to SciMLTesting 2, documents the public API, and approves intentional reexports. Aqua ambiguities stay unmodified (0 broken); root fix is #59.

Round-3: the scalar docstring example used bounds = (lo, hi), which the existing macro splices as AST literals and stores as (:lo, :hi). The example now uses numeric literals, the docstring states that the scalar form requires literal bounds (the multivariable form evaluates expressions), and tests assert getbounds on the documented example.

Risk assessment

• Risk: Low for the round-3 docstring/test fix; medium for the earlier SciMLTesting-2 / docs / reexport work.
• Blast radius: Public @random_variables docstring wording; new QA assertions only. Runtime macro unchanged. No promote_symtype changes.
• Evidence: Local CM QA 21/21; umbrella QA 47/47; OUQBase QA 20/1/0 (ambiguity only); docs build exit 0; docstring example probe below.
• Independent review: Codex gpt-6-astra rounds 1 and 3 CHANGES and Opus round 2 CHANGES (each fixed); Claude Code claude-opus-5-5 (a different harness from the Cursor author) round 4 on head a53d56e: VERDICT MERGE. The remaining OUQBase QA/Core failures are fixed by Fix OUQBase 𝔼/ℙ SymbolicUtils Operator ambiguity (separate from #54 floor) #59 and OUQBase: evaluate Inequality probability events as Bool comparisons #60.
• Merge: needs review; merge Fix OUQBase 𝔼/ℙ SymbolicUtils Operator ambiguity (separate from #54 floor) #59 first, then rebase this PR and re-run OUQBase QA.

Pre-existing OUQBase ambiguity (not fixed here; fixed by #59)

Aqua still reports promote_symtype ambiguities for 𝔼_ / ℙ_. This PR leaves the check unmodified (0 broken). OUQBase QA / Core stay red until #59 lands; the umbrella CI / QA lane targeted by #55 is green.

Docstring examples run (only runnable example we added)

Other new docstrings are signature/prose only (no executable snippets). The sole executable example is @random_variables:

using OptimalUncertaintyQuantification
import Symbolics
rv = @random_variables begin
    Independent(X, bounds = (0.0, 1.0))
    Independent([Y, Z], bounds = ((2.0, 3.0), (4.0, 5.0)))
end
OUQBase.getbounds(rv[:_X])
OUQBase.getbounds(rv[:_YZ][1])
OUQBase.getbounds(rv[:_YZ][2])

Observed (scratch/docstring_examples_r4.txt):

collect(keys(rv)) = [:_X, :_YZ]
OUQBase.getbounds(rv[:_X]) = (0.0, 1.0)
OUQBase.getbounds((rv[:_YZ])[1]) = (2.0, 3.0)
OUQBase.getbounds((rv[:_YZ])[2]) = (4.0, 5.0)
docstring example: OK

Documented scalar pitfall (named bindings are not evaluated):

lo, hi = 0.0, 1.0
@random_variables Independent(Bad, bounds = (lo, hi))
OUQBase.getbounds(Bad) = (:lo, :hi)
named scalar stores symbols: OK

Verification

After (local, head a53d56e)

CanonicalMoments QA: Quality Assurance | 21 21 — passed.

OUQBase QA — expected fail on pre-existing ambiguity:

Quality Assurance | 20 1 21
Method ambiguity  |    1  1
20 passed, 1 failed, 0 errored, 0 broken.

Umbrella QA (GROUP=QA):

QA | 47 47
Testing OptimalUncertaintyQuantification tests passed

(includes the new @random_variables scalar bounds are numeric literals testset)

Docs (julia --project=docs docs/make.jl): exit 0; existing warnonly reports 56 docstrings not in the manual; local deploy skipped.

What I did NOT verify

• Full Core / FloodProblem numerical suites
• DiscreteMeasures QA in isolation
• That Fix OUQBase 𝔼/ℙ SymbolicUtils Operator ambiguity (separate from #54 floor) #59 has already landed on main

What a reviewer should push back on

• Merge order vs Fix OUQBase 𝔼/ℙ SymbolicUtils Operator ambiguity (separate from #54 floor) #59
• Whether scalar macro should eventually evaluate named bounds (out of scope here; docs-only fix as required)

Closes #55

Please ignore this draft until reviewed by @ChrisRackauckas.

Harness: Cursor Agent CLI 2026.09.26-dd393fe; model: auto; transcript: /home/crackauc/sandbox/agent-jobs/OptimalUncertaintyQuantification.jl/jobs/55-cursor/log.txt on amdci2.julia.csail.mit.edu

Risk assessment

• Risk: medium
• Blast radius: Umbrella, OUQBase, and CanonicalMoments QA environments and documentation. No public-API or runtime behavior change requiring a SemVer major bump. New tests access the non-public OUQBase.getbounds binding; existing dependency-internal QA exemptions remain.
• Evidence: Head a53d56e has five failures, all pre-existing: sublibraries / lib/OUQBase / Julia lts / Tests - Core (Julia lts), sublibraries / lib/OUQBase / Julia 1 / Tests - Core (Julia 1), and sublibraries / lib/OUQBase [QA] / Julia 1 / Tests - QA (Julia 1) reproduce the same promote_symtype ambiguities on default-branch commit acadcec (head, baseline); newer default-branch runs skipped these jobs. Downgrade Sublibraries / test (lib/OUQBase) and Downgrade Sublibraries / test (lib/DiscreteMeasures) reproduce, respectively, that ambiguity and unsupported interval intersect errors on latest main, 013f14a (head, baseline). No test regressions found. No assertions were removed, skipped, or loosened; reexport allow-lists exempt specified existing exports from leakage checks. GitHub has no submitted reviews or review comments.
• Independent review: Codex CLI 0.156.1 (Mac) / gpt-6-astra rated it medium, high confidence: CI failures match default-branch failures, but new tests depend on a non-public dependency binding and the description incompletely reports CI.
• Merge: needs human review (use the public owner’s API instead of OUQBase.getbounds; disclose both downgrade failures and retained dependency-internal exemptions; reconcile the description’s merge prerequisite with still-open Fix OUQBase 𝔼/ℙ SymbolicUtils Operator ambiguity (separate from #54 floor) #59).

---

🤖 Risk assessment posted by an AI agent (fleet master) — harness: Codex CLI 0.156.1 (Mac) / gpt-6-astra; dispatched by Claude Code head, model claude-opus-5-5[1m]
Conversation: local Claude Code session 3cd6500a-1f81-46b5-ac0b-c466e15b6a53 on Chris's Mac (session ID, no URL)