feat(LlamaContext): expose ubatchSize separately from batchSize

[andreinknv]

Summary

Adds a ubatchSize?: number option on LlamaContextOptions, plumbing through to llama_context_params.n_ubatch. When unset, the existing default (n_ubatch = n_batch) is preserved exactly.

Why

Today llama/addon/AddonContext.cpp always sets n_ubatch = n_batch inside the batchSize handler — the JS-side batch queue is the reason. That's a reasonable default, but it prevents callers from ever asking for a smaller physical micro-batch than the logical batch. The C++ value is the same one llama-server exposes as --ubatch-size, and decoupling them serves two real use cases:

1. Per-ubatch VRAM headroom. On hardware that's sensitive to VRAM peaks during the forward pass (some Metal models, low-end CUDA), a smaller n_ubatch lets a larger total n_batch fit. Today this is unreachable from node-llama-cpp.
2. Throughput characterization. Sweeping n_ubatch independently of n_batch is the canonical way to characterize a model+hardware combo for sustained-load deployments. Matches what llama-server --batch-size N --ubatch-size M already permits.

Plumbing

• src/evaluator/LlamaContext/types.ts — new ubatchSize?: number field on LlamaContextOptions with docstring noting the ≤ batchSize constraint and the link to llama.cpp's --ubatch-size.
• src/evaluator/LlamaContext/LlamaContext.ts — destructured from the options bag, forwarded into the AddonContext options.
• llama/addon/AddonContext.cpp — if (options.Has("ubatchSize")) overrides context_params.n_ubatch, placed AFTER the batchSize handler so the explicit value wins over the default.

Compatibility

• ubatchSize is optional. When unset, n_ubatch = n_batch exactly as today.
• No public-API breakage.

Test plan

• Local build + smoke test on Qwen2.5-Coder-3B-Instruct Q4_K_M (Metal, batchSize: 512, ubatchSize: 256) — context constructs cleanly; per-decode logs confirm n_ubatch=256 reaches llama.cpp.
• Existing tests pass locally (no change with ubatchSize unset).
• CI on this PR.

🤖 Generated with Claude Code