Groovy 6 for humans and AI agents

The table understates the deal, because "read the body" was never the true price. deposit is three lines, but one of them calls log.add(…​), and proving that call can’t touch balance — the question @Modifies answers outright — means proving it for everything beneath it. In JDK 25’s sources the traversal runs

— six levels and about 460 CL100K tokens down one branch of one line, and still unfinished: Arrays.copyOf bottoms out in native code, the modCount semantics live in a superclass, and the GString.toString() on the same line opens a second subtree of its own. The @Modifies({ [this.balance, this.log] }) that settles the question is about a dozen tokens.

That is the real shape of the trade. Without declarations, reading cost compounds: a method with k callees, chased d levels deep, is k^d bodies. A verified declaration truncates the recursion — every annotated signature is a leaf the traversal stops at. It also answers the obvious objection that the annotations make the class bigger, which they do: annotating Account roughly triples it (74 CL100K tokens to 229). The extra tokens buy a constant-size wall in place of an unbounded subtree, on every path that would otherwise descend — a constant, traded for an exponential.

None of that is worth anything if the annotations are aspirational. A comment claiming purity is a claim you still have to verify, which puts you back where you started — and an agent that trusts an unverified claim is worse than one that reads the body, because it is confidently wrong.

The compile-time checkers are what make the declarations load-bearing. Add an undeclared field write and a mutation inside the @Pure method:

and the build stops:

The release notes put it plainly: without the guarantee, annotations would be just comments. With it, a Groovy 6 codebase is not merely easier to read — it is a verified specification something else can build on.

This is the one. A model asked for a parameterised query in Groovy will often produce this:

It looks right, because in most languages quoting an interpolated value inside SQL is what you do. In Groovy it is exactly wrong: the GString form is how groovy-sql binds a PreparedStatement parameter, and the quotes defeat it, splicing the value into the query text instead (CWE-89). The new SqlInjectionChecker (GROOVY-12187) refuses it:

Drop the quotes and it compiles — and the query is now correct as well as safe, since a bound parameter handles a name like O’Brien that the spliced form would choke on. groovy-sql also rejects the same pattern at runtime (GROOVY-12118), so the checker is a shift-left of a guarantee that exists either way.

Four more, each owning one narrow property. All activate the same way, and compose on one class:

NullChecker works from @Nullable/@NonNull — matched by simple name from any package, so whichever vendor’s annotations a library happened to pick, the checker sees them:

and a flow-sensitive strict mode needs no annotations at all:

RegexChecker and FormatStringChecker catch the two categories of string that look fine until they run:

CombinerChecker catches a genuinely subtle one — a parallel reduction with a combiner that isn’t associative. It compiles cleanly in Java and in Groovy without the checker, and shows up as a non-deterministic wrong answer under load:

Alongside these, Groovy 6 tightened annotation target validation (GROOVY-11884, GROOVY-11838) so misplaced annotations that used to compile silently now don’t:

Some risks can’t be settled statically, and Groovy 6 bounds them by default instead. That matters more than usual when the code writing the config isn’t the code reviewing it.

@SafeRegex (GROOVY-12122) puts a wall-clock bound on regex evaluation:

Worth being precise here: modern JDKs already defuse most of the textbook catastrophic-backtracking examples, so this is not "the (a+)+$ problem, solved". It is a bound on evaluation time regardless of which pattern and which input combine badly — the guarantee you want when the pattern arrived from somewhere you didn’t review.

The same instinct shows up in the parsers. JsonSlurper caps nesting depth by default from 6.0 (GROOVY-12064), MarkdownSlurper at 1000 (GROOVY-12183), and XML processing is secure by default with DTD declarations off. A pathological document is a clean exception rather than a StackOverflowError.

And for code that arrives from outside — the reproducer-from-the-tracker case later in this post — the long-standing gate is SecureASTCustomizer, a compile-time allow/deny list over what a script may contain. 6.0.0-beta-2 closed two routes around it: it now inspects constructors, initializer blocks and field initializers (GROOVY-12238), and authored code the compiler relocates into synthetic methods (GROOVY-12244) — places a hostile script could previously put code the customizer never looked at.

Demonstrating a checker with code that passes demonstrates nothing. The companion repo’s refuted module inverts it: each test compiles source that is expected to fail and asserts on the diagnostic.

Nine plausible-looking mistakes, nine compile-time refusals, each pinned to the wording that catches it. It doubles as documentation: the fastest way to learn what a checker actually does is to read what it rejects.

Model output is Markdown, and pulling the parts you want out of it with a regex is the usual approach and the usual source of bugs — fences inside fences, headings inside list items, indented blocks. The new groovy-markdown module (GROOVY-11940) parses it:

headings, codeBlocks, links and tables walk the tree recursively, so a fenced block nested inside a list item is still found. section(heading) is the one that makes structured agent replies tractable. (GFM tables need org.commonmark:commonmark-ext-gfm-tables on the classpath and the enableTables(true) opt-in; everything else works out of the box.)

A tool call arrives as JSON and has to become a typed value:

as coercion needs no extra dependency; typed parsing via Jackson-backed parseAs/parseTextAs is available across CSV, TOML, YAML and XML too, with java.time fidelity.

And then the contract is the validation — stated once, in a form the caller, the reader, and the model generating the call can all read:

If the snippet you extracted is code you intend to run, there is a Groovy-specific trap that is easy to get wrong, and apache/groovy’s own `AGENTS.md states it directly:

"Let me just compile it to see if it’s valid" is a natural move, and in Groovy it is equivalent to executing it. Whatever gate you put in front of running untrusted code belongs in front of compiling it too.

One of those vectors gained an off-switch in 6.0.0-beta-2: the groovy.asttest.enable system property (GROOVY-12236) lets a compile host disable @ASTTest outright, which a host that only ever compiles code it didn’t write has no reason to leave on. The gate itself stays — global transforms, static initializers and @Grab are still in play.

Take an unremarkable data-wrangling task — read 5,000 CSV rows, group by region, total the revenue, emit JSON:

That is 9 lines and 116 tokens. The equivalent Python — csv.DictReader, a defaultdict, an accumulation loop, json.dumps — is 12 lines and 149 tokens, and produces byte-identical output. Groovy is not paying a verbosity tax here; if anything it is slightly ahead, because groupBy/collectEntries/sum say in one expression what the loop says in five lines.

The other half is that the script needs nothing installed. Groovy 6’s new modules mean CSV, Markdown, JSON, YAML, TOML, XML, SQL and an HTTP client are all in the distribution, and @Grab fetches anything else inline from the script itself — no virtual environment, no lockfile, no separate install step for the agent to get wrong.

Now the number that matters. That CSV is 80,012 tokens. The script that processes it is 116, and the answer it prints is 146.

Roughly 300× less — and that understates it, because the two approaches are not equally good. An agent that reads 5,000 rows into context and totals them is doing arithmetic by prediction: it will usually be close and occasionally be wrong, silently. The script is right, and it is right the same way every time you run it. It can also be reviewed, checked into the repo, and re-run next quarter against different data.

This is the same argument the apache/groovy AGENTS.md makes about helper scripts, generalised: anything deterministic and well-trodden should be a script rather than something the model re-derives. Data reshaping is the most well-trodden path there is. The saving is not a tweak to a prompt; it is a decision not to spend the context at all.

Two things Python keeps.

Startup. The same script runs in about 0.75s on the JVM against 0.02s for Python. For a script an agent runs once, that is invisible. For a tight loop of hundreds of invocations, it is the whole cost, and Python wins outright. (For deployed tools, as opposed to ad-hoc scripts, native-image support new in 6.0.0-beta-2 rewrites this particular number — see below.)

Ecosystem and fluency. If the task wants pandas, numpy or a model library, Python is simply where those live. And a model has seen enormously more Python, so its first draft is more likely to be idiomatic and correct. That gap is real and is not closed by any feature list.

Where Groovy turns the tables is when the task touches the JVM — read a build, drive a JVM application, parse a POM, query a JDBC source, script something that already lives on the JVM. There the Python version has to shell out or reimplement, and Groovy is already home.

The same reasoning extends up a level, to the tools an agent calls rather than the scripts it writes. An MCP server is an ordinary program: a transport, some tool declarations, and the code behind them.

There is a worked example — an ASF Policy MCP server written in Groovy 6 on the Java MCP SDK, ported from an existing Python implementation, so the comparison is like-for-like rather than hypothetical. Overall the Groovy is 1.09× the tokens of the Python, but the breakdown is the interesting part:

On the code that does the work, Groovy is marginally more compact. The whole difference is in the wiring: Python’s FastMCP derives each tool’s JSON schema from a decorator and the function’s type hints, while the Java SDK wants the schema declared explicitly. That is an SDK maturity gap rather than a language one — and it is exactly the shape of problem an AST transform exists to solve, though nobody has written that one yet.

It is not all cost, either. Declaring the schema means it is there to read, as data, in the same spirit as the @NamedParams contract earlier — and Groovy’s map literals make JSON Schema pleasant to write:

And the validation story from earlier in this post is the same story here: a @Requires on the method behind a tool is that tool’s argument contract, stated once, enforced at the boundary, and readable by the thing generating the call.

One more result on this server, and the newest machinery in this post — it shipped in 6.0.0-beta-2. An MCP server is a process an agent may spawn per conversation, so startup is a tax on every session — exactly the number Python was winning on above. GraalVM native image removes it, but dynamic Groovy has never been able to come along: a native image cannot retarget an invokedynamic call site once linked, and retargeting is how Groovy’s dynamic dispatch installs its caches. The usual advice — @CompileStatic everything, compile with indy off — amounts to "stop being dynamic", and it does not even fully work, because dynamically-compiled code in dependencies (including Groovy’s own distribution modules) still crosses dynamic sites you cannot recompile.

The insight behind GROOVY-12234 (with GROOVY-12227 covering closures) is that retargeting only ever installs caches — the dispatch semantics live entirely in method selection. So under a native image each site links once, permanently, and cache freshness travels as data. The mode switches on automatically under a native-image build (there is a -Dgroovy.indy.aot.link=true diagnostic flag for trying it on a plain JVM), and because it changes linking rather than compilation, already-published indy-compiled jars become native-capable without being recompiled. With that in place, the policy server above builds as a native binary unmodified — fully dynamic source, stock compilation, no annotations, no flags:

The honest limit is steady-state dispatch: with no JIT, each dynamic call site crossed costs about 4µs natively. A tool that performs a few thousand dynamic operations answers in single-digit milliseconds, as above; this server’s search tool loops through roughly sixty thousand of them and takes 242ms against 79ms on the JVM. The arithmetic is simply operations × 4µs — and where it bites, @CompileStatic on the one hot method removes it entirely, since statically compiled code crosses no dynamic sites.

The reason it belongs in this post: it collapses a trade-off this section has been carefully stepping around. You no longer have to choose between the dynamic, Python-shaped code an agent writes most fluently and a deployable fast-startup binary. Same codebase — JVM while you develop, a 25ms binary when you ship the tool.

For the wider picture of calling models from Groovy — Ollama4j, LangChain4j, Spring AI, Embabel, Micronaut and Quarkus — see Exploring AI with Groovy, and for agentic patterns specifically, Groovy, Embabel, and Agentic Design Patterns.

GroovyDoc supports JEP 467 Markdown doc comments (GROOVY-11542) — a run of /// lines whose body is CommonMark:

Headings, lists, emphasis and fenced code render as you’d expect (headings shift down two levels to fit under the page structure); inline tags like {@link} still work inside a Markdown body. The plain point: this is the dialect every README, every issue tracker and every model’s training corpus already speaks. One less translation layer between what an author writes and what a reader — of either kind — parses.

JEP 413 {@snippet} is supported too (GROOVY-11938), inline or referencing a file under snippet-files/, with @highlight, @replace and @link markup. A sample marked as a snippet is a sample a tool can lift out intact.

The deeper idea is the doc analogue of the contract. Groovy documents its own GDK with <pre class="groovyTestCase"> blocks in the doc comments — and groovy.test.JavadocAssertionTestSuite extracts and runs them as JUnit tests:

The reference documentation works the same way: the AsciiDoc sources under src/spec/doc/ include:: real Groovy files from src/spec/test/, so the examples in the language specification are tests. This is why the examples in Groovy’s docs can be trusted — not because someone checks them, but because they fail the build when they rot. For a reader working from documentation it never verified, that property is worth more than any amount of prose.

It also has a contributor-facing consequence, and apache/groovy’s `AGENTS.md spells it out so tooling doesn’t get it wrong: adding such a block is adding a test, and a spec test is its own coverage — don’t demand a duplicate *Test.groovy for behaviour already covered.

Worth a note, since you are reading a site that does this: the Groovy 6 release notes are structured for retrieval — stable anchors on every section, feature-summary tables that pair each change with its JIRA ticket, and API references written through a gapi: macro rather than hand-rolled URLs so they can’t silently rot. A page that answers "what changed and where is the ticket" in a table is a page that answers it for a person skimming and for a tool fetching, without either needing to read the prose around it.

The root AGENTS.md is vendor-neutral — it names Claude Code, Codex, Cursor, Copilot, Gemini and Aider, and belongs to none of them. Its most important structural decision is in its second sentence: it supplements, it does not replace, the human-facing contributor docs. It points at README.adoc, CONTRIBUTING.md, ARCHITECTURE.md, COMPATIBILITY.md and GOVERNANCE.md and layers AI-specific guidance on top.

That is the difference between an agent guide that stays true and one that becomes a second, stale source of truth. The failure mode is obvious in hindsight — two documents describing the same conventions, diverging quietly — and the whole point of the layering is to avoid it.

The supporting documents were written for humans first, and several didn’t exist before:

THREAT_MODEL.md (GROOVY-12061) is the most immediately useful of the set, and its audience is stated up front: maintainers triaging reports, and automated code-scanning tools.

The problem it solves is specific. Groovy is a general-purpose language whose entire product is running the code it is given, so a pattern-based scanner sweeping it finds "vulnerabilities" everywhere — GroovyClassLoader, the Meta-Object Protocol, String.execute(), AST transforms executing at compile time. All by design. AI-assisted scanners generate these at a rate no volunteer PMC can hand-triage.

So §11a is a table of known non-findings, §11b a set of default-downgrade calibration rules, and §13 a closed list of triage dispositions — VALID, VALID-HARDENING, OUT-OF-MODEL: executes-supplied-code, KNOWN-NON-FINDING, MODEL-GAP and the rest — so a batched scan report can be answered as a table rather than as an essay. Every non-trivial claim carries a provenance tag: (documented), (inferred), or (maintainer).

And §14 ships threat-model.yaml, a machine-readable sidecar that mirrors it:

Note the discipline: the prose document is authoritative and the YAML mirrors it, every entry carrying its section anchor. The machine-readable form is a convenience for tooling, not a fork of the truth.

One row in §11a is worth quoting for how neatly it closes a loop: Groovy tool output that echoes attacker-controlled text — "or a dependency emitting agent-targeted text" — is dispositioned OUT-OF-MODEL: downstream-responsibility, because Groovy emits output faithfully and the consumer sanitizes for its sink. The sinks listed are shell, browser, SQL, and LLM agent. An agent is just another sink that has to treat what it reads as data.

Under .agents/skills/ sit ten task-specific guides, each in its own directory with a SKILL.md. They are loaded on demand, so none of them costs context until the task is actually about that area. They span the project’s actual chores — build conventions, compiler internals, test conventions, JIRA triage, safely handling reported reproducers — plus a groovy-skills meta-skill on how to write the others.

Two things about them are worth borrowing.

The first is that they are guardrails over existing human documentation, not new policy. groovy-tests layers AI-specific failure modes over the test conventions in CONTRIBUTING.md; groovy-internals over ARCHITECTURE.md. The meta-skill states the rule explicitly — a skill is "the working surface… it describes what the project does, not what it should do", and drafting one before the convention exists is listed as a failure mode. Skills are not a vehicle for unilateral policy changes.

The second is the standard on what goes in them. From groovy-skills:

That is the difference between a document that changes behaviour and one that reads as a vibe. Anyone who has written a CLAUDE.md full of "write clean code" has produced the second kind.

AGENTS.md carries a section on untrusted input and confirmation that is worth reading in full. Condensed:

The groovy-reproducer skill ships the operational half of this as two scripts: safety-prescreen.sh and run-reproducer-sandboxed.sh.

This one is unusual enough to quote. AGENTS.md has a section on helper mechanisms whose argument is not about efficiency:

The resulting guidance: prefer a vetted, stable mechanism over per-run re-derivation — a helper script for deterministic local transforms or fixed remote calls, a focused MCP server when the operation is stateful, authed or paginated. Default to the script, because it is cheaper to ship and review. With guardrails: version-robust and tested, ASF header, the equivalent manual call documented inline so it is never an opaque dependency, and only for genuinely stable operations — a helper for something that changes often rots and costs more than re-derivation. A helper that depends on a runtime version self-checks at startup and fails fast with a remediation message.

For an open-source project run by volunteers, "how many tokens does our recommended workflow burn per contributor per month" is a real question, and I haven’t seen another project write it down.

The website repository (apache/groovy-website, which serves this post) carries the same structure at a smaller scale: an AGENTS.md whose first section is a warning that asf-site is the live branch and every merge publishes immediately, plus one skill so far — release-notes, for drafting a per-release page.

The companion repo carries a minimal version for a project of ordinary size: a short AGENTS.md and a single groovy6-checkers skill. The AGENTS.md there is mostly a "what not to do" list, and its most useful entries are the ones specific to that repo — don’t "fix" the code in :refuted, each snippet is wrong on purpose; don’t remove a @TypeChecked(extensions = …​) to make something compile, the extension is the subject of the example. Two lines that would otherwise cost a wasted round trip every time.