Rename evaluator API to ADProblems and fold autograd testing into the core interface.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Author: yebai

.claude/skills/inspect/SKILL.md

@@ -0,0 +1,87 @@
+---
+name: inspect
+description: Inspect the AD pipeline IR for a Julia function at each Mooncake compilation stage.
+---
+
+# Inspect
+
+Inspect IR transformations in Mooncake's AD pipeline for a given function.
+
+## Setup
+
+```julia
+using Mooncake, Mooncake.SkillUtils
+```
+
+## Gathering user intent
+
+Ask the user:
+
+ 1. **Function and arguments** — e.g. `sin, 1.0` or a custom function
+ 2. **Mode** — reverse (default) or forward
+ 3. **What to view** — all stages, a specific stage, a diff between two stages, or world age info
+
+Do not assume — ask the user to pick.
+
+## Pipeline stages
+
+### Reverse mode (default)
+
+| Stage             | Symbol           | Description                                          |
+|:----------------- |:---------------- |:---------------------------------------------------- |
+| Raw IR            | `:raw`           | optimised, type-inferred SSAIR from Julia's compiler |
+| Normalised        | `:normalized`    | after Mooncake's normalisation passes                |
+| BBCode            | `:bbcode`        | BBCode representation with stable IDs                |
+| Forward IR        | `:fwd_ir`        | generated forward-pass IR                            |
+| Reverse IR        | `:rvs_ir`        | generated pullback IR                                |
+| Optimised Forward | `:optimized_fwd` | forward pass after optimisation                      |
+| Optimised Reverse | `:optimized_rvs` | pullback after optimisation                          |
+
+### Forward mode
+
+| Stage      | Symbol        | Description                                                   |
+|:---------- |:------------- |:------------------------------------------------------------- |
+| Raw IR     | `:raw`        | optimised, type-inferred SSAIR from Julia's compiler          |
+| Normalised | `:normalized` | after Mooncake's normalisation passes                         |
+| BBCode     | `:bbcode`     | inspection-only — forward mode does not use BBCode internally |
+| Dual IR    | `:dual_ir`    | generated dual-number IR                                      |
+| Optimised  | `:optimized`  | after optimisation passes                                     |
+
+## Commands
+
+```julia
+# Full inspection
+ins = inspect_ir(f, args...; mode=:reverse)  # or mode=:forward
+
+# View stages
+show_ir(ins)                          # all stages
+show_stage(ins, :raw)                 # one stage
+
+# Diffs between stages
+show_diff(ins; from=:raw, to=:normalized)
+show_all_diffs(ins)
+
+# World age debugging
+show_world_info(ins)
+
+# Write everything to files
+write_ir(ins, "/tmp/ir_output")
+
+# Shorthand helpers
+ins = inspect_fwd(f, args...)         # forward mode
+ins = inspect_rvs(f, args...)         # reverse mode
+ins = quick_inspect(f, args...)       # inspect + display immediately
+
+# Options
+inspect_ir(f, args...; mode=:reverse, optimize=true, do_inline=true, debug_mode=false)
+```
+
+## Presenting results
+
+  - Run commands via Bash and present IR in fenced code blocks.
+  - When showing diffs, explain what changed and why the transformation matters.
+  - If errors occur, check that Mooncake is loaded and the function signature is valid.
+
+## Limitations
+
+Inspects Mooncake's internal AD pipeline only. For allocation, world-age, or compiler-boundary debugging, see `docs/src/developer_documentation/advanced_debugging.md`.

.claude/skills/minimise/SKILL.md

@@ -0,0 +1,46 @@
+---
+name: minimise
+description: Prune a bug fix or new tests down to the smallest correct diff through multiple elimination passes. Use before committing any fix or test addition.
+---
+
+# Minimise
+
+The goal is to remove every line that is not strictly required for correctness,
+then verify the result still passes the relevant tests.
+
+## Process
+
+Repeat the following until no further reductions are possible:
+
+ 1. **Read the diff.** Run `git diff HEAD` (or `git diff --cached` if staged) and
+    read every changed file in full.
+
+ 2. **Challenge each change.** For every changed line ask:
+    
+      + Would removing this line cause a test to fail or a bug to reappear?
+      + Is this a cleanup, rename, refactor, or comment that is not load-bearing?
+      + For new tests: does an existing test already cover this behaviour?
+        If so, drop the new test entirely.
+ 3. **Remove non-essential changes.** Delete anything that does not answer
+    "yes" to the first question above. Prefer shrinking an existing case over
+    adding a new one.
+ 4. **Run the minimal test group.** Use the smallest focused test group that
+    exercises the changed code (see `test/runtests.jl` for group names).
+    Confirm all tests pass before continuing.
+ 5. **Repeat** from step 1 until a full pass produces no further removals.
+
+## Heuristics
+
+  - A one-line fix is better than a five-line fix.
+  - A new test case added to an existing `@testset` is better than a new `@testset`.
+  - A new value constructor in `src/test_resources.jl` should be the minimum needed
+    to instantiate the type under test; no extra fields or variants.
+  - Comments and blank lines added alongside a fix are not load-bearing; remove them
+    unless they explain something non-obvious.
+  - Helper functions introduced solely for the fix are a red flag; inline them.
+
+## When to stop
+
+Stop when every remaining line answers "yes" to: *if I remove this, the targeted
+bug reappears or the targeted test fails*. At that point report the final diff and
+suggest committing.

.claude/skills/scrutinise/SKILL.md

@@ -0,0 +1,66 @@
+---
+name: scrutinise
+description: Scrutinise newly added or changed code on the current branch against main. Checks new types, methods, changed signatures, overloads, and helpers for necessity, correctness, clarity, consistency, robustness, and minimality. Reviews new tests for gap coverage, overlap with existing tests, minimality, and use of established testing patterns. Invoke with /scrutinise.
+tools: Bash, Glob, Grep, Read, Edit, Write
+---
+
+# Scrutinise
+
+Review all changes on the current branch relative to `main`. Cover source and tests separately, then simplify.
+
+## Step 1: Gather the diff
+
+```bash
+git diff main...HEAD --name-only
+git diff main...HEAD -- src/ ext/ test/
+```
+
+Read changed files in full before commenting.
+
+## Step 2: Source
+
+For every new type, method, changed signature, or overload:
+
+  - **Necessary?** Does existing infrastructure (`@zero_derivative`, `@from_rrule`, broader signatures) already cover this? Could an overload be eliminated by broadening an existing one?
+  - **Correct?** Tangent/cotangent types consistent with `tangent_type`? `@is_primitive` declared? For `rrule!!`: pullback restores mutations, aliasing handled. For `frule!!`: dual propagation correct, removable singularities handled.
+  - **Clear and consistent?** Names and structure match the surrounding file and `src/rules/`. `NoTangent`/`ZeroTangent` used correctly.
+  - **Robust?** Edge cases (empty arrays, zero-size structs, complex types) handled or explicitly excluded. Fails loudly on unsupported inputs.
+  - **Minimal?** No dead branches, unused arguments, or speculative generalisations.
+
+For every new helper: does it genuinely aid readability or reduce duplication, or can it be inlined? Does it belong in `src/utils.jl` or is it rule-local?
+
+For every new or changed **comment**:
+
+  - **WHY not WHAT?** Delete comments that restate what the code already says (variable names, types, control flow). Keep only non-obvious constraints, invariants, and design rationale.
+  - **Accurate?** Does the comment still match the code? Stale or contradictory comments are worse than none.
+  - **Brief?** Trim verbose multi-line blocks to the minimum that preserves the WHY. Cross-references (`see X for WHY`) are fine but the local comment should still give enough context to understand the constraint without chasing the reference.
+
+For every new or changed **docstring**:
+
+  - **Correct?** Does it accurately describe current behaviour, including any overloads (e.g. `Ptr` special cases)?
+  - **No leaking internals?** Docstrings are public-facing; do not refer users to internal comments or implementation details they cannot rely on.
+  - **Concise?** One sentence for simple functions; a short paragraph for complex ones. Avoid restating the signature.
+
+## Step 3: Tests
+
+For every new or changed test:
+
+  - **Real gap?** Would removing it leave a regression undetected, or is it duplicating interpreter-level coverage via `TestResources.generate_test_functions()`?
+  - **No overlap?** Check the corresponding test file and `test/front_matter.jl` for existing tests on the same rule/type.
+  - **Minimal?** Smallest example that exercises the gap; no redundant argument combinations.
+  - **Right pattern?** Rules → `test_rule`. Tangents → `test_tangent` / `test_tangent_type_and_tglob_type_agree`. Duals → `test_dual` / `test_fdata` / `test_rdata`. Allocations → `count_allocs`. Malformed rules → `DebugMode`. Flag any test reimplementing logic already in the test utilities.
+
+## Step 4: Output
+
+Findings grouped by file, labelled:
+
+  - **Unnecessary** / **Incorrect** / **Unclear** / **Inconsistent** / **Non-minimal** / **Fragile**
+  - **Comment: stale** / **Comment: explains WHAT** / **Comment: too verbose** / **Comment: missing WHY**
+  - **Docstring: incorrect** / **Docstring: leaks internals** / **Docstring: too verbose**
+  - **Test: redundant** / **Test: missing pattern** / **Test: weak gap**
+
+No issues in a section → write "No issues." Do not suggest additions beyond what the diff introduces.
+
+## Step 5: Simplify
+
+Invoke the `simplify` skill to apply code-quality and reuse fixes to the changed files.

docs/src/pplapi.md

@@ -26,5 +26,6 @@ DerivativeOrder
 capabilities
 prepare
 value_and_gradient
+test_autograd
 dimension
 ```

ext/AbstractPPLDifferentiationInterfaceExt.jl

@@ -8,18 +8,12 @@ struct DIPrepared{E,B,C}
     evaluator::E
     backend::B
     prep::C
-    dim::Int
 end
 
 AbstractPPL.capabilities(::Type{<:DIPrepared}) = DerivativeOrder{1}()
-AbstractPPL.dimension(p::DIPrepared) = p.dim
+AbstractPPL.dimension(p::DIPrepared) = AbstractPPL.dimension(p.evaluator)
 
-function (p::DIPrepared)(x::AbstractVector{<:AbstractFloat})
-    length(x) == p.dim || throw(
-        DimensionMismatch(
-            "Expected a vector of length $(p.dim), but got length $(length(x))."
-        ),
-    )
+function (p::DIPrepared)(x)
     return p.evaluator(x)
 end
 
@@ -29,19 +23,16 @@ end
 function AbstractPPL.prepare(
     adtype::ADTypes.AbstractADType, problem, x::AbstractVector{<:AbstractFloat}
 )
-    evaluator = AbstractPPL.prepare(problem, x)
+    evaluator = AbstractPPL.ADProblems.VectorEvaluator(
+        AbstractPPL.prepare(problem, x), length(x)
+    )
     prep = DI.prepare_gradient(evaluator, adtype, x)
-    return DIPrepared(evaluator, adtype, prep, length(x))
+    return DIPrepared(evaluator, adtype, prep)
 end
 
 @inline function AbstractPPL.value_and_gradient(
     p::DIPrepared, x::AbstractVector{<:AbstractFloat}
 )
-    length(x) == p.dim || throw(
-        DimensionMismatch(
-            "Expected a vector of length $(p.dim), but got length $(length(x))."
-        ),
-    )
     return DI.value_and_gradient(p.evaluator, p.prep, p.backend, x)
 end
 

ext/AbstractPPLEnzymeExt.jl

@@ -6,34 +6,25 @@ using Enzyme: Enzyme
 
 struct EnzymePrepared{E}
     evaluator::E
-    dim::Int
 end
 
 AbstractPPL.capabilities(::Type{<:EnzymePrepared}) = DerivativeOrder{1}()
-AbstractPPL.dimension(p::EnzymePrepared) = p.dim
+AbstractPPL.dimension(p::EnzymePrepared) = AbstractPPL.dimension(p.evaluator)
 
-function (p::EnzymePrepared)(x::AbstractVector{<:AbstractFloat})
-    length(x) == p.dim || throw(
-        DimensionMismatch(
-            "Expected a vector of length $(p.dim), but got length $(length(x))."
-        ),
-    )
+function (p::EnzymePrepared)(x)
     return p.evaluator(x)
 end
 
 function AbstractPPL.prepare(::AutoEnzyme, problem, x::AbstractVector{<:AbstractFloat})
-    evaluator = AbstractPPL.prepare(problem, x)
-    return EnzymePrepared(evaluator, length(x))
+    evaluator = AbstractPPL.ADProblems.VectorEvaluator(
+        AbstractPPL.prepare(problem, x), length(x)
+    )
+    return EnzymePrepared(evaluator)
 end
 
 @inline function AbstractPPL.value_and_gradient(
     p::EnzymePrepared, x::AbstractVector{<:AbstractFloat}
 )
-    length(x) == p.dim || throw(
-        DimensionMismatch(
-            "Expected a vector of length $(p.dim), but got length $(length(x))."
-        ),
-    )
     dx = zero(x)
     result = Enzyme.autodiff(
         Enzyme.set_runtime_activity(Enzyme.ReverseWithPrimal),