Marten#4349: AOT publishing guide

[jeremydmiller]

Summary

Ticks the "AOT publishing guide specific to Marten" checkbox on #4349 (Marten 9.0 master plan). New page at docs/configuration/aot-publishing.md (259 lines, within the chip's 200-350 target).

Models after JasperFx's docs/codegen/aot.md (219 lines), adapted to Marten's surface. Main adaptation: the one-phase model — Marten 9 retired runtime code generation entirely in PR #4461, so there's no dotnet run -- codegen write step the JasperFx guide builds around. The Marten guide calls out the difference explicitly with a side-by-side mermaid diagram.

Sections

1. What AOT publishing buys you + when it's the right choice (and when it isn't)
2. Prerequisites — .NET 9/10, Marten 9.0+, STJ serializer, optional Marten.SourceGenerator for compiled queries
3. How Marten 9 differs from the broader Critter Stack — the one-phase model, what to delete if you have a pre-9 Internal/Generated/ folder, why services.AddRuntimeCompilation() doesn't exist anymore
4. Project setup walkthrough — concrete csproj, AddMarten with STJ, [JasperFxAssembly] marker, publish command
5. What works / annotated / doesn't work — honest about the ~15 cascading IL2026 / IL3050 warnings from Marten.Internal.ClosedShape.* construction sites that PR Marten#4349: Add Marten.AotSmoke + extension package IsAotCompatible audit #4468's audit surfaced; AOT-publishing apps will see these until the per-document-type source-generator extension lands (tracked on [Master] Marten 9.0 #4349)
6. The Newtonsoft.Json escape hatch — concrete migration from UseNewtonsoftForSerialization to UseSystemTextJsonForSerialization plus the gotchas (property casing, polymorphic types, DateTime formatting)
7. Verifying your app is AOT-clean — publish output scan + table mapping warning sources to fix paths + reference to src/Marten.AotSmoke as the canonical clean consumer
8. Troubleshooting — five common failure modes (missing [GeneratedEvolver], IL3050 on custom projection base, LINQ in AOT, Reflection.Emit secondary-store boot, slow publish)
9. Performance — cites the Marten.SourceGenerator README's compiled-query benchmark (~25× cold, ~31% steady-state); defers end-to-end AOT cold-start benchmarks to CritterStackScalability
10. References — JasperFx guide, Marten.SourceGenerator README, migration-guide anchor, MSFT trim-warning catalog, MSFT Native AOT docs

Sidebar

Added under "Configuration" between "Optimized Development Workflow" and "Multi-Tenancy with Database per Tenant" (docs/.vitepress/config.mts:144).

Test plan

• markdownlint clean on the new file
• markdownlint clean across all docs/**/*.md
• cspell clean on the new file
• All cross-references verified — src/Marten/DocumentStore.cs:84 line reference, PR numbers (Removing All Runtime Compilation From Marten. (Boom) #4461 / [#4454 Phase 3] Port ancillary stores off the codegen subclass path #4459 / Marten#4349: Add Marten.AotSmoke + extension package IsAotCompatible audit #4468), repo paths
• Heading-slug for the "Newtonsoft.Json escape hatch" anchor verified against markdownlint MD051

References: #4349 (master plan — not "Closes", this just ticks one box).

🤖 Generated with Claude Code