feat(native): vectors of native data as a template over a PHP string

[lisachenko]

What

Lisachenko\Generics\Native\NativeVector — a placeholder-form generic template whose storage is a PHP string acting as a raw block of memory:

$samples = new (NativeVector::of('int'))($blobFromTheWire);  // "cast" a binary string
$first   = $samples[0];          // zend_long read straight from the block
$samples[1] = 42;                // in-place native store
$samples->append(7);             // growth = string concatenation
$bytes = $samples->toBinary();   // hand the block back
$samples->destroy();             // explicit release

• Type arguments are PHP builtins — NativeVector<int> maps elements to zend_long, NativeVector<float> to double (8 bytes each, naturally aligned in zend_string.val). Anything else is rejected at construction.
• No pack()/unpack() anywhere on the hot path. Reads dereference a cached typed pointer (Core::cast('zend_long *'|'double *', $zstr->val)) so FFI initializes the PHP value straight from memory; writes store the value in place. Tests use pack() only as ground truth.
• The engine enforces the element type. get(int): T, set(int, T) and append(T) are declared with the type parameter itself, so $intVector->append(1.5) is a real TypeError thrown by the Zend Engine — the ArrayAccess sugar delegates to those methods rather than re-checking anything.
• Copy-on-write discipline. A write only goes in place when the buffer's zend_string is exclusively owned (refcount 1, not interned); otherwise the buffer is separated first, so a string returned by toBinary() is never retroactively mutated. Growth releases the pointer cache so .= keeps its in-place realloc fast path.
• Consumes only z-engine's existing public API (StringEntry, Core::cast) — no z-engine changes. AGENTS.md decision 13 is amended to sanction the Native\ namespace as the second engine touchpoint, confined to this class's private helpers.

This is a direct answer to the array<T> entry in docs/limitations.md: a vector's elements are enforced by construction.

Also in this PR

• NativeVectorException / NativeVectorBoundsException with named constructors (misaligned binary, unsupported element type, bounds, destroyed, fixed layout).
• Stub generator growth: NativeVector is the first stubbed template with private helpers, static named constructors, constants, parameter defaults and PHP interfaces — the generator now reproduces all of those (Box/AttributeBox stubs regenerate byte-identical). PHPStan sees the stub (excluded via analyseAndScan), so $v->get(0) is int for NativeVector<int>.
• docs/native-vectors.md (memory model, COW/destroy semantics, roadmap to sized scalar kinds and C-struct layouts), cross-links from docs/limitations.md, docs/static-analysis.md and README.
• examples/native-vector.php + subprocess example test.
• New documented limitation: a stub-described template does not narrow of() (stub vs GenericObject-extension exclusivity) — pre-existing for Box, now written down.

Verification

All run locally on PHP 8.5.9 (z-engine 8.5.x-dev):

• engine suite (ffi.enable=1, opcache.jit=off): 179 tests, 510 assertions, 1 pre-existing skip
• same under opcache.enable_cli=1 opcache.save_comments=0: pass (1 new deliberate skip: the stub generator's @implements test, which reads doc comments by design — tooling, not runtime)
• --group internal --process-isolation: pass
• composer test:analysis, composer phpstan (level max, no new baseline entries), composer cs:check, composer stubs:check, composer test:preload, composer bench:smoke: all pass

Roadmap (out of scope here)

Sized scalar kinds (int32, uint16, …) and C-struct layouts as follow-up phases; a zero-copy engine-side buffer was considered and deliberately not built (this class already writes in place through the existing API).

🤖 Generated with Claude Code

https://claude.ai/code/session_013qW1hct9mDKsFaHTvkLggx

---

Generated by Claude Code

[lisachenko]

Session:

• Fable 5: 175 in / 404 out / 9.8M cache read / 1.2M cache write
• Cost: $2.79 | API 0m | Wall 1m