[rmorozov]

Requested by Ruslan · project thread

Before: the 2.0 API document said nothing about where Jinja2C++ allocates, what it keeps per thread, how out-of-memory surfaces, or how output can go anywhere but an ostream or a fresh string.

After: docs/api-2.0.md section 3.9 states the memory contract Ruslan approved on 2026-10-18, and four implementation tasks carry it out.

Decisions (all as recommended in the plan):

• R1: no allocator parameters in 2.0. Value and its containers stay on std::allocator. A later hook would be an additive TemplateEnv method taking a std::pmr::memory_resource&.
• R2: std::bad_alloc is only for system out-of-memory. Every limit and every spent budget is ResourceLimitExceeded, matching 0250 (docs: 2.0 error contract (0250) and untrusted-input mode tasks #584).
• R3: Render(ostream&) stays all-or-nothing.
• R4: new RenderTo(StringType&) and RenderTo(BasicOutputSink&) overloads, plus a header-only ContainerSink that also covers fmt::memory_buffer. fmt stays a private dependency.
• ReleaseThreadCaches(): frees what renders keep on a thread, including the last environment's globals, which are currently retained after the TemplateEnv is destroyed.

How: this is a docs-only PR.

• docs/api-2.0.md gets 3.9, decision 7 and an entry in section 10.
• The architect plan is added as docs/design/0252-memory-contract-plan.md.
• 0252 is marked done.
• New tasks:
  • 0256: Load and Render crash at some allocation-failure points (a probe found 4/24 in Load and 8/96 in Render); fix them and add an OOM sweep test.
  • 0257: RenderTo and the sink.
  • 0275: ReleaseThreadCaches.
  • 0276: user docs.

Notes for the merge steward:

• docs/tasks/README.md is not regenerated here.
• 0256, 0257 and 0275 belong in the G1 API-wave list in docs/release-2.0.md (the 0221 thread owns that file).
• Task numbers 0269-0273 were skipped in case another thread holds them.
• Number collision: Markup from C++: jinja2::Markup / WMarkup in Value (0180) #590 and docs: 2.0 error contract (0250) and untrusted-input mode tasks #584 both add a docs/tasks/0253-* file.

Roles: architect (plan, with an OOM fault-injection probe). Verifier not run (docs only). Pushes red in CI: none so far.

---

Generated by Claude Code