Declare and document developer interfaces

[ChrisRackauckas-Claude]

Ignore this PR until reviewed by @ChrisRackauckas.

Prerequisite #132 is merged. This branch is rebased onto eb4bf95 (current main, which includes #134) and contains one focused audit commit.

Summary

• Declare the documented, nonexported developer interface as public while retaining Julia 1.10 load compatibility.
• Document the abstract problem/template contracts and solve methods at their definition sites, and render the canonical signatures in the manual.
• Add generic external-client interface tests that depend only on public API.
• Upgrade the strict SciMLTesting harness to >= 2.4, remove broad QA exceptions, and synchronize root test extras/targets.
• Bump the package version to 1.3.0 for additive public API. (Sync package versions with the General registry #134 moved main to 1.2.4; 1.3.0 supersedes it and is the correct minor bump.)

Verification

Local, on the rebased head 41d4406:

Core, Julia 1.12.6 — JULIA_NUM_THREADS=4 julia --project=. -e 'using Pkg; Pkg.test()':

Test Summary: |    Pass    Total       Time
Core          | 1288234  1288234  140m08.8s
     Testing FiniteVolumeMethod tests passed

Core, Julia 1.10.11 (LTS), same command:

Test Summary: |    Pass    Total      Time
Core          | 1288232  1288232  98m27.2s
     Testing FiniteVolumeMethod tests passed

QA — GROUP=QA julia --project=. -e 'using Pkg; Pkg.test()':

Julia 1.12.6:   QA | 21  21  48.2s   Testing FiniteVolumeMethod tests passed
Julia 1.10.11:  QA | 19  19  42.8s   Testing FiniteVolumeMethod tests passed

Docs, strict — CI=true julia --project=docs docs/make.jl, exit 0:

[ Info: Doctest: running doctests.
[ Info: ExpandTemplates: expanding markdown templates.
[ Info: CrossReferences: building cross-references.
[ Info: CheckDocument: running document checks.
[ Info: Populate: populating indices.
[ Info: RenderDocument: rendering document.
[ Info: HTMLWriter: rendering HTML pages.
[ Info: Automatic `version="1.3.0"` for inventory from ../Project.toml

Runic 1.7.0: clean over all 52 tracked .jl files. typos: clean. git diff --check: clean.

CI on 41d4406 is fully green, including the three core jobs that previously failed: https://github.com/SciML/FiniteVolumeMethod.jl/actions/runs/31217120410 (Core julia 1 1h14m50s, Core lts 53m53s, Core pre 1h43m17s, QA 11m30s), plus Documentation, Downgrade, Runic, and Spell Check.

About the earlier core-job failures

The three core failures on the previous head 3d92f7e were an 8 GB runner-pool problem, not a defect here. All three ran on self-hosted-4vcpu-8gb-nh4np-*, died mid-Run tests (step conclusion null), and never uploaded logs (BlobNotFound). Unmodified main failed the same way on the same pool the same day (https://github.com/SciML/FiniteVolumeMethod.jl/actions/runs/31102010097), and passes now that the pool is 4vcpu-16gb. Locally the core test process reaches ~6.7 GiB RSS on Julia 1.12.6 — no headroom on an 8 GB runner. No source change was needed; the rebase re-ran CI on the 16 GB pool. Detail: #133 (comment)

What a reviewer should push back on

• The public list in src/FiniteVolumeMethod.jl is declared via eval(Expr(:public, ...)) behind a VERSION >= v"1.11.0-DEV.469" guard, because Julia 1.10 cannot parse a public statement. This makes those names public API on 1.11+ only, and locks the package into supporting them going forward.
• Several @doc raw""" docstrings in src/specific_problems/abstract_templates.jl became plain """ with escaped LaTeX backslashes. Equivalent output, larger diff.
• Root [extras]/[targets] now mirror test/Project.toml. test/Project.toml still takes precedence for Pkg.test(); the root entries exist to satisfy Aqua's project-extras check. They are two lists that must be kept in sync.
• 1.2.4 -> 1.3.0 skips no registered version, but it does mean 1.2.4 (bumped by Sync package versions with the General registry #134) never ships on its own.

Not verified locally

• No GPU or downstream-package testing was run; this repo has no such lanes.
• The Documentation deploy step is untestable locally (needs DOCUMENTER_KEY). Note that deploy currently fails on main at eb4bf95 with Git failed to fetch git@github.com:SciML/FiniteVolumeMethod.jl (https://github.com/SciML/FiniteVolumeMethod.jl/actions/runs/31197940930) — a pre-existing credential problem unrelated to this PR. The build itself passes here.

Clean-main findings

• Clean origin/main local documentation generation failure is tracked separately in Local docs generation fails on multiline Literate #src blocks #131.
• The MatrixOperator load regression begins with SciMLBase commit 8e770b8d8a4bf0fc7d5c3d2909139fb275ab335d (SciMLBase#1476); the focused owner-import fix merged in Fix strict documentation build prerequisites #132.

[ChrisRackauckas-Claude]

CI infrastructure blocker on the validated tree:

• On 901bde1, release and LTS core passed; prerelease core was terminated because the self-hosted runner lost communication.
• The fork token cannot rerun a single failed Actions job (403 Must have admin rights), so 920a7b0 is an empty, co-authored retry commit with an identical tree.
• On 920a7b0, release, LTS, and prerelease core all received the identical self-hosted-runner communication-loss annotation. No test assertion or package error was reported.
• On 920a7b0, documentation, downgrade, QA, Runic, spelling, suggestions, and detection all passed.
• Local full suites pass on Julia 1.12.6 release (1,288,234 / 1,288,234) and Julia 1.10.11 (1,288,232 / 1,288,232).

Maintainer action required: restore/restart the self-hosted runner and rerun the failed core jobs. No source change is warranted for these failures.

[ChrisRackauckas-Claude]

Final focused SHA 3d92f7ee5eb925466d8077e60fcf72a44aa9b118 CI status:

• Documentation, downgrade, QA, Runic, spelling, suggestions, and detection passed.
• Release core, Julia LTS core, and Julia prerelease core each ended with the identical GitHub annotation: The self-hosted runner lost communication with the server.
• No Julia exception, assertion failure, or package test error was reported by any of those jobs.
• The exact current tree is byte-identical to the locally validated tree; full local release and Julia 1.10 suites pass.
• This fork token cannot rerun Actions jobs (403 Must have admin rights).

Maintainer action required: restore/restart the self-hosted runner, then rerun the three failed core jobs. Further source or empty-commit retries would not address this infrastructure failure.

[ChrisRackauckas-Claude]

Rebased onto current main (eb4bf95, which includes #134) and re-validated locally. New head: 41d4406.

Rebase

Single conflict, in Project.toml: main moved 1.2.3 -> 1.2.4 in #134 while this branch moved 1.2.3 -> 1.3.0. Resolved to 1.3.0 (still the correct minor bump for additive public API, and still ahead of 1.2.4).

git diff 3d92f7e 41d4406 is empty — the rebased tree is byte-identical to the previously validated one (227fb741d66f7529a04b02de149331c089e656e1).

The three failed core jobs were an 8 GB runner-pool problem, not this PR

Correcting my earlier comment, which called it a generic "runner lost communication" and asked for a rerun without saying why. Evidence:

• The failing run https://github.com/SciML/FiniteVolumeMethod.jl/actions/runs/31102600402 put all three core jobs on self-hosted-4vcpu-8gb-nh4np-* runners. All three died mid-Run tests (that step's conclusion is null, not failure), and the logs were never uploaded — GET /actions/jobs/92619885577/logs returns BlobNotFound. There is no Julia error to read because the runner never got to upload one.
• The same failure hit unmodified main on the same day and the same 8 GB pool: https://github.com/SciML/FiniteVolumeMethod.jl/actions/runs/31102010097 (f8124b9) failed Core lts and Core pre on self-hosted-4vcpu-8gb-nh4np-*. Its Core julia-1 job happened to land on a GitHub-hosted runner (GitHub Actions 1001068224) and passed. So the discriminator is the runner, not the branch.
• Since the pool moved to self-hosted-4vcpu-16gb-*, main core jobs pass: https://github.com/SciML/FiniteVolumeMethod.jl/actions/runs/31184476778 (all green) and https://github.com/SciML/FiniteVolumeMethod.jl/actions/runs/31197950202.
• Consistent with memory pressure: running the Core group locally, the test process reached ~6.7 GiB RSS on Julia 1.12.6 and ~3.1 GiB on 1.10.11. 6.7 GiB leaves no headroom on a 4vcpu/8gb runner.

No source change was needed for this; the rebase re-runs CI on the 16 GB pool.

Local validation of 41d4406

Core, Julia 1.12.6 (julia --project=. -e 'using Pkg; Pkg.test()', JULIA_NUM_THREADS=4):

Test Summary: |    Pass    Total       Time
Core          | 1288234  1288234  140m08.8s
     Testing FiniteVolumeMethod tests passed

Core, Julia 1.10.11 (LTS):

Test Summary: |    Pass    Total      Time
Core          | 1288232  1288232  98m27.2s
     Testing FiniteVolumeMethod tests passed

QA, GROUP=QA:

Julia 1.12.6:   QA | 21  21  48.2s   Testing FiniteVolumeMethod tests passed
Julia 1.10.11:  QA | 19  19  42.8s   Testing FiniteVolumeMethod tests passed

Docs, strict, CI=true julia --project=docs docs/make.jl — exit 0:

[ Info: Doctest: running doctests.
[ Info: ExpandTemplates: expanding markdown templates.
[ Info: CrossReferences: building cross-references.
[ Info: CheckDocument: running document checks.
[ Info: Populate: populating indices.
[ Info: RenderDocument: rendering document.
[ Info: HTMLWriter: rendering HTML pages.
[ Info: Automatic `version="1.3.0"` for inventory from ../Project.toml

Runic 1.7.0: clean over all 52 tracked .jl files. typos: clean.

Not verified locally

• The julia pre lane (1.13.0-rc1) — CI only.
• Downgrade job — CI only.

Unrelated, for the record

Documentation on main at eb4bf95 fails at deploy, not build: Git failed to fetch git@github.com:SciML/FiniteVolumeMethod.jl / Failed to push (https://github.com/SciML/FiniteVolumeMethod.jl/actions/runs/31197940930). That is a DOCUMENTER_KEY/deploy-credential problem on push-to-main, independent of this PR; the PR's Documentation job builds and passes.