[ericmann]

Part of the 2026-10 maintenance pass. Merge after ext-template#2. Prepares v0.2.1 (not tagged).

Release headline: "Now loads Nanbeige4.2 and Spark-X2.5", plus a fix for long prompts aborting the PHP process.

What changed and why (one bump per commit)

1. chore: sync scaffold from ext-template@442aa21: setup-php unpinned (clears the <2.37.1 advisories), the PHP 8.5 × macos-14 leg restored, weekly schedule, ZTS legs, managed Dependabot.
2. chore: sync scaffold from ext-template@339f16f: ext-php-rs 0.15.13 → 0.16.3, thiserror 2.0.21. Binding adaptation: 0.16 converts #[php(defaults(...))] values into the parameter type, so chat()/raw() defaults became typed literals (128_u32, 0.0_f32). PHP defaults are unchanged (Reflection-verified).
3. chore(deps): llama-cpp-2 =0.1.146 → =0.1.160 (April → mid-October llama.cpp). Tokenization moved to LlamaVocab. A shared tokenize() keeps rejecting NUL bytes with the exact old message, since the new byte-slice tokenizer would otherwise accept them.
4. fix: size n_batch to n_ctx: llama.cpp's context n_batch defaults to 2048 and llama_decode asserts (abort, not an error) when a batch exceeds it. In v0.2.0, any chat()/raw() prompt between 2049 tokens and nCtx killed the process, and RerankModel did so with default options (n_ctx 4096). Reproduced on v0.2.0 and on 0.1.160; new model-gated PHPT 017-long-prompt.phpt fails on v0.2.0 and passes here. RSS unchanged (948 vs 949 MB at nCtx 2048; 1639 vs 1637 MB at 8192). This also breaks rag-over-markdown on larger corpora (bin/rag ask --k 8 over ~28 KB aborts).
5. Docs: models verified on the new llama.cpp; dead Qwen3-7B-Instruct links (Qwen3 has no 7B; HF 401) now point at Qwen/Qwen3-8B-GGUF; "v0.1.0 still in flight" notes removed; make stubs workflow; ZTS claims updated; Status section, stack table, writing links, a deliberately-out-of-scope section sourced from ARCHITECTURE.md's non-goals (the README had none); PLAN.md as design notes; CHANGELOG.md backfilled (v0.1.0-rc.1 → v0.2.0).

Re-verification of the load-bearing behaviours

A probe was run on the v0.2.0 build and on this branch, and the output is byte-identical: greedy chat text, reasoning split, raw completion, JSON-Schema output plus hard-fail on an unsupported keyword (pattern), raw GBNF, a ~1.4k-token prompt (past the old 512 batch), NUL rejection, last- vs mean-pooled Qwen3-Embedding cosine rankings with and without the query instruction prefix (last pooling ranks the right doc first; the prefix asymmetry holds), raw embedding floats, packed() parity, and Qwen3-Reranker yes/no scores and rank() rows. sample() still wraps llama_sampler_sample (which accepts), so the double-accept fix holds; grammar generation runs 160 tokens without the old GGML_ASSERT.

New architectures (llama.cpp PRs merged after mid-June; both fail to load on v0.2.0):

• Nanbeige4.2-3B (nanbeige, [Model] Add support for Nanbeige4.2 ggml-org/llama.cpp#25994, Jul 27): chat(), reasoning split (824-byte reasoning, answer "51"), schema output. ✅
• Spark-X2.5-1.7B (spark2_5, #27868, Sep 6): loads and runs raw(). Its Jinja-only chat template isn't recognised by llama.cpp's built-in matcher, so chat() throws apply_chat_template failed: ffi error -1. Documented; Jinja rendering is Render chat templates with Jinja (models llama.cpp's built-in matcher doesn't recognise) #2.
• Granite 4.2 3B chats on both versions (existing architecture).

Release-build performance on a Ryzen 5 3400G: prompt processing 12.66 s → 13.10 s for ~1k tokens; generation 34.4 → 33.7 tok/s. No regression. (The absolute prompt rate looks low; see #13.)

Gates

• Local (Linux x86_64, PHP 8.3, real models): 16/16 PHPTs; clippy -D warnings + fmt clean; cargo-about gate passes.
• CI: 9/9: lint; NTS 8.3/8.4/8.5 on macOS arm64 and Linux x86_64; ZTS 8.4/8.5 (PHP_ZTS=true confirmed). CI is model-free by design, so 12 of 16 PHPTs skip there; the model tier is the local run above.
• PHP surface: a ReflectionExtension dump of every class, method and parameter matches pre-pass except as noted below. cargo-php 0.2.1 stub output matches 0.1.21's except for fully-qualified extends.

⚠️ Needs your sign-off (PHP-visible, from ext-php-rs 0.16)

• A wrong-typed argument now throws \TypeError (e.g. maxTokens: 'x'), where 0.2.0 threw a plain \Exception (ext-php-rs 0.16.3 #820). It matches PHP's internal functions, but catch (\Exception) no longer catches it. If you'd rather not ship that in a patch, pinning EXT_PHP_RS_PIN to =0.16.2 avoids it.
• Trailing ?array $options parameters now report their null default via Reflection (isDefaultValueAvailable()), matching the stubs. Harmless, but visible.

Pre-existing findings (reported, not changed)

• Curated stubs vs registered classes: the stubs declare final on Embedding, Message, Prompt and Response, but the runtime classes aren't final (same in 0.2.0). The stubs also say array $options = [] where the runtime has ?array $options = null, and self where the runtime reports the class name. Matching them means either making the classes final at runtime (a PHP API change, out of scope here) or dropping final from the stubs. That's your call. Same pattern in ext-turbovec and ext-whisper.
• Exceptions thrown from Rust report getFile() === '' / getLine() === 0 (Exceptions thrown from the extension report an empty file and line 0 #14).

Draft release notes — v0.2.1

Now loads Nanbeige4.2 and Spark-X2.5. ext-infer 0.2.1 bundles an October 2026 llama.cpp (0.2.0 shipped an April one), so architectures added since then load. Verified: Nanbeige4.2-3B for chat, the reasoning split and schema output; Spark-X2.5-1.7B for raw completions (its Jinja-only chat template needs raw() for now).

Fixed: long prompts no longer abort the PHP process. On 0.2.0, any prompt between 2,049 tokens and nCtx, and any RerankModel query + document over 2,048 tokens with default options, tripped an assertion inside llama.cpp and killed the worker. Memory use is unchanged.

Changed: a wrong-typed argument now throws \TypeError (was \Exception), like PHP's own functions. Greedy chat, grammar, embedding and reranker output are byte-identical to 0.2.0 on the Qwen3 0.6B reference models. CI now runs weekly, on PHP 8.5 on macOS again, and on ZTS PHP 8.4/8.5.

Full details: CHANGELOG.