feat: report which experimental definitions a run entered

[sotashimozono]

The package could say a name was unfinished. It could not say that this run went through one — which is the question a docstring structurally cannot answer, because it is asked after the run, about the run, often by somebody who wrote neither.

using ExperimentalAPI

@experimental "convergence not established below β ≈ 0.1" energy(β) = β * 1.0000001

energy(0.5)

$ julia sweep.jl
┌ ExperimentalAPI: this run entered 1 experimental definition
│   Main.energy — convergence not established below β ≈ 0.1
└ set ENV["EXPERIMENTALAPI_SUMMARY"] = "0" before `using` to silence this

On by default. Silent when nothing marked was entered — loading a package that has marks prints nothing. Carries the reason, not just the symbol. entered() returns the same thing as data.

What it costs, and why the design is what it is

10M calls of sqrt(abs(sin(x)cos(x) + exp(-|x|/1e6))), Julia 1.12.2, minimum of 7–9 trials:

emitted into the body	1 thread	8 threads	counts correctly?
nothing	1.00×	1.00×	—
the flag emitted here	1.03×	0.985×	yes
counter, plain shared Ref	1.03×	3.76×	no
counter, global atomic	1.17×	4.87×	yes
counter, per-thread atomic	1.12×	2.79×	yes
@warn, guarded so it fires once	5.65×	—	yes
@warn maxlog=1	59.57×	—	yes

Two rows decided it:

• A flag written once and only read afterwards stops dirtying the cache line, which is why it is free at eight threads while every counting scheme is not. The plain counter is also wrong: it recorded 95,406,048 of 160,000,000 calls, losing 40% to races.
• The guarded @warn costs 5.65× even though it fires once — what stops the definition inlining is the call being in the body at all, not the warning being printed. That is why the notice is a summary at exit rather than a warning at the call.

Counting, call sites and paths stay opt-in and are not built.

Scope, measured form by form

form	observed?
function f(x) … end, f(x) = …, f(x::T) where {T} = …, f(x)::R = …	yes
a name list, struct, const, assignment	no — declaration only
@generated function	refused outright, as any macro-produced definition is

The @generated row is a correction: the docstring first said "declaration only", and running it showed the macro rejects it and points at the name-list form.

What the case matrix did

Eight behaviours reported Unexpected Pass and were promoted. Nothing else moved — no collateral failures, which is the whole reason the spec was written first.

One assertion was inverted rather than promoted. The spec used to require the expansion be identical to the bare definition; it now requires exactly one more statement whose head is || — a short-circuit read, not a store. WrapControl.@wrapping adds one statement too and it is a store, so the control can fire.

Three claims that stopped being true

"Calls are untouched", "emits the definition unchanged plus one push! at load time", and "costs nothing at run time" were accurate before this change and are not now. They appeared in the README, the module docstring, the macro docstring and docs/src/index.md; all four are corrected.

The README example now runs

It referenced a Model and a correction that do not exist. It is now a program that runs, and test/test_readme.jl executes the first ```julia block verbatim and checks the output the README quotes — so it cannot rot. Confirmed by breaking the README and watching the test report UndefVarError: Model` not defined`.

New docs page Observing, and entered / Entry / marked_modules / detecting / summary_text are public and documented.

174 behaviours, 61 operating (was 54). Suite: 532 pass, 152 broken, 0 failing.

🤖 Generated with Claude Code

[github-actions]

📚 Docs preview: https://codes.sota-shimozono.com/ExperimentalAPI.jl/previews/PR9/

(updates on each push to this PR)

[codecov]

Codecov Report

❌ Patch coverage is 94.80519% with 4 lines in your changes missing coverage. Please review.

Files with missing lines	Patch %	Lines
src/detect.jl	93.65%	4 Missing ⚠️

📢 Thoughts on this report? Let us know!