[AI] Curate the public API instead of blanket-reexporting dependencies

[ChrisRackauckas-Claude]

Please ignore until reviewed by @ChrisRackauckas. Opened as a draft. Breaking release across all 28 packages.

Independent of #1283 and #1284 — branched from master.

Why

run_qa's reexport audit has failed on master since SciMLTesting#28 enabled check_reexports by default (2026-07-21, SciMLTesting 2.4.0). The obvious fix is reexports_allow, but the check was pointing at something real, so this curates the API instead.

Every package @reexported its dependencies wholesale:

package	before	after
Optimization	263 public, 0 owned	39
OptimizationBase	262 public, 6 owned	38
OptimizationOptimJL	298 public, 0 owned	36

using OptimizationOptimJL brought in 298 names, not one of them its own: 155 from SciMLBase, 38 ADTypes, 34 from SciMLOperators (AddVector, BlockDiagonalOperator, update_coefficients!), 30 Optim, 16 SciMLLogging, 4 NLSolversBase, 4 CommonSolve. The surface included DynamicalSDEFunction, DDEProblem, EigenvalueProblem. Of the 263 names Optimization exported, the entire monorepo referenced 65.

What changed

• OptimizationBase — @reexport using SciMLBase, ADTypes, SciMLLogging becomes plain using plus explicit export lists: its own types, the problem/solution API (OptimizationProblem, OptimizationFunction, solve, init, solve!, remake, ReturnCode, senses, stats), and the nine Auto* types the repo actually uses.
• Optimization — re-exports that curated set and nothing else.
• 27 solver packages — stop passing OptimizationBase through. Every surviving @reexport surfaces the package's own backend solvers, which is the glue package's job. Also caught OptimizationODE reexporting all of SciMLBase and OptimizationNLPModels all of ADTypes.

Users write using Optimization, OptimizationOptimJL, already the documented pattern on every doc page but one (pycma.md, updated).

Five defects the reexports were masking

1. OptimizationMOI uses ADTypes.AutoSymbolics/AutoSparse in nlp.jl and never declared ADTypes.
2. OptimizationIpopt — same, in evaluator.jl. Both compiled only because the reexport chain bound the name.
3. OptimizationCMAEvolutionStrategy imported the SciMLBase module from OptimizationBase (using OptimizationBase: SciMLBase), which ExplicitImports flags as both ExplicitImportsFromNonOwnerException and NonPublicExplicitImportsException.
4. OptimizationLBFGSB took ReturnCode from OptimizationBase rather than SciMLBase, which owns it.
5. OptimizationPyCMA had all_qualified_accesses_via_owners marked @test_broken; it passes once accesses go to owners, so the stale marker is removed.

Separately, 17 packages used @SciMLMessage without depending on SciMLLogging and now declare it.

QA stays enabled, not allow-listed away

Nine glue packages allow exactly their backend module; the two umbrella packages list their curated re-surface explicitly; the remaining 18 need no allow-list at all. Adding a reexport is now a deliberate edit to a short list.

Versions

Breaking. Optimization 5.6.5→6.0.0, OptimizationBase 5.2.2→6.0.0, each sublibrary by its SemVer rule (0.x→0.(x+1), 1.x→2.0.0), with intra-monorepo compat bounds updated across all package, test and docs environments.

Test plan

Run locally on Julia 1.11, full sweep after the final change:

• Core — 28/28 pass (root + all 27 sublibraries)
• QA — 27/28 pass
• The one QA failure, OptimizationLBFGSB, is pre-existing: on a clean master checkout it fails 2 checks (JET and reexport); on this branch it fails only the JET one. Verified by stashing this branch and re-running.
• All 27 modified test files parse-checked (caught 2 that my edit had broken mid-continuation)
• Every [deps]/[extras]/[weakdeps] entry re-validated as a UUID
• Runic clean
• CI green

Follow-ups, deliberately not in this PR

• MaxSense/MinSense/ObjSense/OptimizationStats are core user-facing API that SciMLBase does not declare public. They are still re-exported here so nothing breaks, but the clean fix is a SciMLBase PR declaring and documenting them.
• OptimizationLBFGSB's JET failure on master.

🤖 Generated with Claude Code

https://claude.ai/code/session_014Uj4Pu1LKHYqLSTLfPYDPo

[SebastianM-C]

What should be the use cases when one uses Optimization vs OptimizationBase?

[SebastianM-C]

Should users have this or OptimizationBase?

[ChrisRackauckas]

I guess OptimizationBase

[ChrisRackauckas-Claude]

Done in a37c8f4 — the example is now using OptimizationBase, OptimizationPyCMA.

Verified locally on Julia 1.11 (fresh env, both packages deved from this branch): the block runs to ReturnCode.Success with sol.u = [0.8, 0.64], sol.objective = 0.04.

For the record, my PR description was wrong to call Optimization "the documented pattern on every doc page but one" — getting_started.md, lbfgsb.md, prima.md, sophia.md and the first ipopt.md example already use OptimizationBase. The docs are split roughly 30 Optimization / 6 OptimizationBase, with the front door (getting_started.md) on OptimizationBase. Harmonizing the remaining pages is a separate PR if you want it — say the word.

[ChrisRackauckas-Claude]

Followed up on the pycma thread by harmonizing the rest of the docs, and that turned up a build-breaking regression in this PR.

1. Docs entry package (2ac8c22)

The docs were split, not uniform — my PR description was wrong to say Optimization was the pattern on every page but one. getting_started.md, lbfgsb.md, prima.md, sophia.md and the first ipopt.md example were already on OptimizationBase. Everything in docs/src is now OptimizationBase: 54 lines, 22 files. Prose ("Optimization.jl"), README.md and docs/make.jl untouched.

Behaviour-preserving, verified on Julia 1.11:

names(Optimization)     = 39
names(OptimizationBase) = 38
EXPORTED ONLY BY Optimization:     [:Optimization]
EXPORTED ONLY BY OptimizationBase: Symbol[]

and solve, init, solve!, reinit!, AutoForwardDiff, OptimizationProblem are === identical through both.

2. This PR breaks the docs build (6788bd3)

@reexport using SciMLBase exports names(SciMLBase), and names(M) always contains M itself — so the module binding SciMLBase was landing in every using Optimization namespace. Curating the exports removes it. Measured on Julia 1.11:

	SciMLBase bound	ADTypes bound
master	true (all 4 entry x solver combos)	true
curate-exports	false	false

Two things depended on it:

• 21 calls to SciMLBase.OptimizationProblem/OptimizationFunction — optim.md (7), nlopt.md (4), gcmaes.md (2), multistartoptimization.md (2), plus blackboxoptim, cmaevolutionstrategy, evolutionary, mathoptinterface, metaheuristics, quaddirect. 18 are in executed @example blocks, which throw UndefVarError: SciMLBase and fail the build — @example errors are not in the existing warnonly = [:missing_docs, :cross_references]. Fixed by dropping the qualification, since OptimizationBase exports both names.
• 5 @docs entries under API/ naming SciMLBase types. No page sets CurrentModule, so Documenter resolves them in Main, and make.jl never did using SciMLBase. Now it does.

rosenbrock.md, linearandinteger.md and ode.md using SciMLBase for real and were left alone.

This slipped through because the test plan covers Core and QA; the docs build is in neither.

Doc blocks re-run verbatim after the fix, on Julia 1.11: nlopt.md NLopt1, optim.md Optim2, reusage_interface.md, polyopt.md all reach ReturnCode.Success. simpleoptimization.md returns MaxIters without throwing, so the build is unaffected — and it is bit-identical under Optimization and OptimizationBase (u = [-0.6215719347368793, 0.3907751561233206] both ways), so it is pre-existing non-convergence, not something this changes. Runic clean.

Still open

• The branch is conflicting with master (mergeStateStatus: DIRTY) — Sync package versions with the General registry #1287 and Correct OptimizationBase to the next sequential release #1290 landed after the merge base and collide with the version bumps in all 24 Project.toml files plus the root. Not resolved here: each conflict is a semver decision that has to be re-derived from the registry-synced baseline.
• After this, no doc example uses Optimization at all, while index.md still tells users to install it and says the top-level package "does not add any extra behavior". That probably wants a sentence saying which of the two to install. Not written — say the word.
• README.md still has using Optimization. Left deliberately: it is spliced in as the module docstring via DocStringExtensions.README.

[ChrisRackauckas-Claude]

Rebase + follow-up changes pushed. The branch is MERGEABLE again (was CONFLICTING).

Merge (f6be113)

Done as a merge rather than a rebase: this branch already contains a merge commit and has review comments anchored to it, so a rebase would mean force-pushing over a branch under review. Say the word if you want the literal rebase.

All 24 Project.toml conflicts were version-only — verified master touched nothing but the version = line in each. #1287/#1290 made patch bumps to sync with the registry; a major bump subsumes a patch bump, so the branch versions are already the correct next breaking release off master's and nothing is skipped:

	master	merged
Optimization	5.6.6	6.0.0
OptimizationBase	5.2.4	6.0.0
OptimizationBBO	0.4.10	0.5.0
OptimizationOptimJL	0.4.17	0.5.0

Three more things this branch broke

Running the suite rather than trusting the test plan turned up three defects, all the same root cause — deleting the reexports orphaned things that were only alive through them.

1. Master's new second_order_warning_test.jl does SciMLBase.requireshessian(...); its includer only does using OptimizationBase. Confirmed it throws UndefVarError: SciMLBase without a fix. Now says using SciMLBase explicitly.

2. OptimizationBase had a stale Reexport dep (96bd3a8) — every @reexport was removed, the dependency stayed. Aqua's stale-dependency check fails on it. QA: 19 pass/1 fail/1 broken → 20 pass/1 broken, exit 0.

3. OptimizationLBFGSB (5ec6b71). The PR description says its QA failure is pre-existing and that this branch "fails only the JET one". Both halves are wrong. On master, @reexport using OptimizationBase exported every name in names(OptimizationBase), OptimizationFunction among them — and exporting a name counts as using it, so using SciMLBase: OptimizationStats, OptimizationFunction was not stale. Remove the reexport and it is:

	master	branch before	branch after
ExplicitImports	5 pass, 1 broken	4 pass, 1 error, 1 broken	5 pass, 1 broken
No unapproved public reexports	1 fail	1 pass	1 pass
total	18 pass, 2 fail, 1 broken	19 pass, 1 fail, 1 error, 1 broken	19 pass, 1 fail, 1 broken

The one remaining fail is JET, byte-identical to master's (same 9 toplevel errors, from the LBFGSB struct colliding with the LBFGSB package binding).

QA sweep, all 28 packages

23/28 pass. Of the 5 failures, 4 (MOI, NLPModels, ODE, SimpleOptimization) are a local environment problem — BracketingNonlinearSolve depends on ChainRulesCore, but no such entry exists in the manifest — which reproduces identically on a clean master worktree, so it is not attributable to this PR. The 5th was LBFGSB, now fixed. So the PR body's "QA — 27/28 pass" was wrong in both directions and should be restated once CI gives a clean-environment number.

Docs

README.md and the index.md install section led users to Optimization while every example now loads OptimizationBase; both now lead with OptimizationBase, and index.md gains a short section on the relationship. Optimization re-exports OptimizationBase and adds nothing else — it pulls in Logging/ConsoleProgressMonitor/TerminalLoggers/LoggingExtras and never references them — so the text says the two are interchangeable rather than inventing a distinction. Those four unused deps are worth dropping separately.

Not done

17 packages still using Reexport with no @reexport left in them — Auglag, BBO, CMAEvolutionStrategy, GCMAES, Ipopt, LBFGSB, MadNLP, MOI, NOMAD, ODE, Polyalgorithms, PyCMA, QuadDIRECT, SciPy, Sophia, SpeedMapping, SimpleOptimization. They use plain export. Aqua does not flag it because using Reexport counts as loading the package, so nothing fails — it is dead code, not a broken check. Cleaning it means removing the using plus the dep/compat entries together in each; happy to do it here or as a follow-up. This also contradicts the description's "every surviving @reexport surfaces the package's own backend solvers" — there are no surviving @reexports in those 17.

Verified locally on Julia 1.11: OptimizationBase Core 54/54 · OptimizationIpopt Core 127 pass/1 broken · root Optimization Core pass · OptimizationBase QA 20 pass/1 broken · OptimizationLBFGSB QA 19 pass/1 broken · README example runs and matches its own documented objective. Every @test_broken encountered traces back to master; this branch adds none. Runic clean.