feat(driver): pluggable weaving drivers: stream filter, stream wrapper and ffi (z-engine)

[lisachenko]

What and why

Weaving becomes a pluggable driver of the kernel: the driver option names the class that decides how advised classes get their advices woven in, everything else (aspects, pointcuts, advisor cache, join-point runtime) is shared. Three drivers, two of them packages of their own under packages/:

Driver	Where	Weaves by
Go\Driver\StreamFilter\StreamFilterDriver (default)	core	source transformation at load time through the php://filter stream filter behind composer's loader (the existing engine, untouched)
Go\Driver\StreamWrapper\StreamWrapperDriver	packages/stream-wrapper-driver (goaop/stream-wrapper-driver)	stream_wrapper_unregister('file') + stream_wrapper_register('file', AopStreamWrapper::class): every include within the weaving scope is served transformed, includes are intercepted by nature, opcache caches the woven sources under their original path
Go\Driver\Ffi\FfiDriver (experimental)	packages/ffi-driver (goaop/ffi-driver)	runtime method-table weaving through lisachenko/z-engine (PHP FFI): classes load natively, advised method bodies are swapped in place with the dispatchers of a cached donor trait, the original body stays callable under <method>OriginalAlias

Core (diff against master: src/Driver/, 13 files)

• Go\Driver\WeavingDriver::boot(AspectKernel, AspectContainer): AspectKernel::init() instantiates the configured class, registers it in the container and boots it once (after the framework services, before configureAop()). An unknown class or a class that is no driver is refused by normalizeOptions().
• Go\Driver\SourceTransformingDriver (marker): only for such a driver the kernel registers the transformer chain (registerTransformerServices()) and the cache warmer builds a cache ahead of time; any other driver is refused by cache:warmup:aop / debug:weaving.
• SourceTransformingLoader::transformSource($uri, $source, $stream): the cache-or-transform logic extracted from filter(), shared by the stream filter and the stream wrapper.
• CachePathManager::isFreshRecord() / writeIndexFile() (the one freshness rule and the portable index format, used by the ffi index), ComposerLoaderDecorator (every driver wrapping composer's loader), generic code-gen helpers (TypeGenerator::resolveScopeKeywords(), ParameterGenerator::withType(), MethodGenerator::get/setParameters()), exception constructors following master's convention.

ffi driver package

FfiDriver::boot() refuses Features::INTERCEPT_INCLUDES, requires z-engine, runs the JIT guard (an active JIT is switched off at runtime and reported), boots the engine and wraps composer's loader with FfiComposerLoader; ClassWeaver matches advices on the parsed source and generates the donor trait Ns\FooOriginalTrait (DonorTraitGenerator, the suffix and structure of the trait codegen: in a trait self::class and parent:: bind at run time to the woven class, only the self/parent keywords of signatures are spelled out because the engine compares signatures against the declaring type); MethodTableRewriter swaps the bodies (redefine(..., preserveAs:), addMethod()) and marks the class with Go\Aop\Proxy; DonorCacheIndex keeps {cacheDir}/_ffi.cache. Function pointcuts are served by the stream driver's namespaced function proxies, enabled from the registered pointcuts (AdvisorIndex), no flag. Everything but method execution and functions is refused with UnsupportedJoinpointException. Exceptions: EngineConfigurationException (configuration), FfiWeavingException / UnsupportedJoinpointException (weave time).

Tests and CI

• Root testsuites framework, stream-wrapper-driver (part of composer test) and ffi-driver (composer test:ffi, excluded from composer test, self-skips without the engine; composer analyze:ffi analyses the package with the real engine). The ffi package has unit tests, in-process tests weaving its stubs through z-engine inside the runner, and functional tests comparing the fixture probe tests/Fixtures/project/bin/driver-weaving.php with the stream filter driver; the wrapper package runs the core class weaving and magic constant suites through the wrapper and compares the same probe.
• .github/workflows/ffi-driver.yml is triggered by packages/ffi-driver/**, src/Driver/**, the workflow and composer.json only, on PHP 8.4 and 8.5, with a plain composer require lisachenko/z-engine; the coverage job no longer installs z-engine (package coverage comes from the ffi workflow under the ffi-driver codecov flag).
• Needs z-engine releases: the packagist releases 8.4.2 / 8.5.0 predate the redefine(preserveAs:) / addMethod() API; the 8.4 and 8.5 heads must be tagged 8.4.3 / 8.5.1 for the ffi workflow (and the package constraint ~8.4.3 || ~8.5.1) to resolve.

Docs: docs/driver/README.md (the concept, the interface, how to write a driver), stream-filter.md, stream-wrapper.md, ffi.md; AGENTS.md per package.

Verified locally on PHP 8.5.11 and 8.4.19: composer check (3284 tests, PHPStan level 10, PER-CS) and composer test:ffi (52 tests) green on both.

Checklist

• The title follows Conventional Commits (type(scope): summary)
• Tests cover the change
• composer check passes
• User-facing or breaking changes are in CHANGELOG.md (and the upgrade guide for breaking changes)

🤖 Generated with Claude Code

https://claude.ai/code/session_01VLQcsvgdQUzwBFsoKUAcG2

[codecov]

Codecov Report

❌ Patch coverage is 99.29825% with 2 lines in your changes missing coverage. Please review.
✅ Project coverage is 98.19%. Comparing base (a4ead81) to head (41ef03a).

Files with missing lines	Patch %	Lines
...ges/stream-wrapper-driver/src/AopStreamWrapper.php	98.75%	2 Missing ⚠️

Additional details and impacted files

@@             Coverage Diff              @@
##             master     #765      +/-   ##
============================================
+ Coverage     98.13%   98.19%   +0.05%     
- Complexity     1891     2021     +130     
============================================
  Files           113      118       +5     
  Lines          5037     5203     +166     
============================================
+ Hits           4943     5109     +166     
  Misses           94       94              

Flag	Coverage Δ
framework	98.19% <99.29%> (?)

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[lisachenko]

Too much changes in the framework + scattered implementation. I propose to refactor the implementation via low coupling - to define the driver as a plugin, which is stored in isolated package + namespace. And has minimum tangling.

You can restruct existing code to organize drivers first and to define interfaces and way how to use different weaving drivers.

[lisachenko]

Status after the review round (head 12013dd, master #771 merged in): every check is green or running except the two ffi driver (PHP 8.4 / 8.5) jobs, which fail in composer analyze:ffi with

Parameter #1 $newCode of method ZEngine\Reflection\ReflectionMethod::redefine() expects Closure, ZEngine\Reflection\ReflectionMethod given.
Unknown parameter $preserveAs in call to method ZEngine\Reflection\ReflectionMethod::redefine().

That is not this PR's code: the plain composer require --dev lisachenko/z-engine asked for in the review resolves to the packagist releases 8.4.2 / 8.5.0, which predate the method-table API (redefine(..., preserveAs:), addMethod() with a method donor, fromClassTable()) merged into the z-engine 8.4 and 8.5 branches (lisachenko/z-engine#284, #282 and the follow-ups). The fix is on the z-engine side: tag the branch heads as releases, 8.4.3 on origin/8.4 and 8.5.1 on origin/8.5 (the package constraint is ~8.4.3 || ~8.5.1, and FfiDriver::boot() refuses an older engine with a message naming it). I could not push release tags from this session; once they exist, re-running the ffi weaving driver workflow is enough, nothing in this PR has to change.

---

Generated by Claude Code