infocyph · abmmhasan · Oct 5, 2026 · Oct 4, 2026 · Oct 4, 2026 · Oct 4, 2026
@@ -5,17 +5,75 @@ on:
     - cron: "0 0 * * 0"
   push:
     branches: [ "main", "master" ]
+    tags: [ "v*", "[0-9]*" ]
   pull_request:
     branches: [ "main", "master", "develop", "development" ]
 
 jobs:
+  release:
+    if: github.event_name == 'push' && startsWith(github.ref, 'refs/tags/')
+    uses: infocyph/phpforge/.github/workflows/release.yml@main
+    permissions:
+      contents: write
+    secrets:
+      COPILOT_GITHUB_TOKEN: ${{ secrets.COPILOT_GITHUB_TOKEN }}
+
   phpforge:
+    if: github.event_name != 'push' || !startsWith(github.ref, 'refs/tags/')
     uses: infocyph/phpforge/.github/workflows/security-standards.yml@main
     with:
       integration_services: '[]'
       service_topologies: '{}'
+      benchmark_composer_script: "benchmark:representative"
+      benchmark_result_file: "build/release-candidate.json"
+      benchmark_baseline_file: "build/release-baseline.json"
+      benchmark_max_regression_percent: 2
+      benchmark_stable_environment: false
     permissions:
       security-events: write
       actions: read
       contents: read
 
+  release-acceptance:
+    if: github.event_name != 'push' || !startsWith(github.ref, 'refs/tags/')
+    name: "Release Acceptance"
+    needs: phpforge
+    runs-on: ubuntu-latest
+    env:
+      XDEBUG_MODE: off
+    steps:
+      - uses: actions/checkout@v7
+      - name: Setup PHP 8.5
+        uses: shivammathur/setup-php@v2
+        with:
+          php-version: "8.5"
+          tools: composer:v2
+          extensions: opcache
+          ini-values: opcache.enable_cli=1
+          coverage: none
+      - name: Install acceptance dependencies
+        run: composer install --no-interaction --prefer-dist --no-progress
+      - name: Run ArrayKit release acceptance tests
+        run: >-
+          php vendor/bin/pest
+          --configuration vendor/infocyph/phpforge/resources/pest.xml
+          --bootstrap vendor/autoload.php
+          tests/Feature/Release530BatchFTest.php
+      - name: Run persistent-worker soak
+        run: |
+          mkdir -p build
+          composer ic:soak:worker \
+            --duration=300 \
+            --warmup=10 \
+            --sample-interval=1 \
+            --max-growth-mb=16 \
+            --report=build/release-worker-soak.json \
+            -- php -d opcache.enable_cli=1 tests/Support/release530-persistent-worker.php
+      - name: Upload worker-soak evidence
+        if: always() && hashFiles('build/release-worker-soak.json') != ''
+        uses: actions/upload-artifact@v7
+        with:
+          name: release-worker-soak
+          path: build/release-worker-soak.json
+          if-no-files-found: error
+          retention-days: 61
@@ -61,7 +61,7 @@ configuration or object models.
 | **Collection**          | OOP array wrapper implementing `ArrayAccess`, `IteratorAggregate`, `Countable`, `JsonSerializable`. |
 | **HookedCollection**    | Extends `Collection` with **on-get/on-set hooks** for real-time transformation of values.  |
 | **Pipeline**            | Functional-style pipeline for chaining operations on collections.                          |
-| **LazyCollection**      | Repeatable lazy operations (`mapLazy`, `filterLazy`, `chunkLazy`, `take`, `takeUntil`), including one-shot generators and renewable factories. |
+| **LazyCollection**      | Repeatable lazy operations (`mapLazy`, `filterLazy`, `chunkLazy`, `take`, `takeUntil`), including one-shot generators, renewable factories, and optional passed-instance Runwire cancellation/yield checkpoints. |
 | **BaseCollectionTrait** | Shared collection behavior.                                                                |
 
 
@@ -90,6 +90,8 @@ configuration or object models.
 
 * **PHP 8.4** or higher
 
+Runwire is optional. ArrayKit 5.3 tests its lazy-runtime integration against `infocyph/runwire` 2.1.1; ordinary ArrayKit installation has no Runwire runtime dependency.
+
 
 ## Installation
 
@@ -295,7 +297,7 @@ $row = ArrayShape::require(
 $config = new LazyFileConfig(__DIR__ . '/config', namespaceCacheDirectory: __DIR__ . '/bootstrap/cache/config');
 $config->warmNamespaceCache(['db', 'cache']);
 
-// Exact scalar leaf reads can hit bootstrap/cache/config/__flat.php first.
+// Exact scalar leaf reads can hit the active generation's .arraykit-flat.php first.
 $host = $config->get('db.host');
 ```
 
@@ -308,7 +310,7 @@ $host = $config->get('db.host');
 - `DotNotation` treats existing `null` keys/properties as present (does not fall back to defaults).
 - `DotNotation::hasWildcard()`, `paths()`, `matches()`, `rename()`, and `move()` are available for wildcard/path operations.
 - For untrusted/deep payloads, use bounded traversal variants: `DotNotation::getSafe()`, `ArrayMulti::depthGuarded()`, `flattenGuarded()`, and `sortRecursiveGuarded()`.
-- `LazyFileConfig` namespace cache writes one cache file per namespace plus a shared `__flat.php` file containing only final scalar/null leaf values for exact-key fast paths.
+- `LazyFileConfig` publishes immutable cache generations selected by `.arraykit-generation`; each generation contains namespace files plus `.arraykit-flat.php` for exact scalar/null fast paths.
 
 ## Security
 

@@ -37,20 +37,40 @@ public function benchCollectionMap(): void
         Collection::make($this->data)->map(static fn(int $value): int => $value * 2);
     }
 
+    public function benchLazyArrayReplayMaterialization(): void
+    {
+        LazyCollection::from($this->data)->all();
+    }
+
     public function benchLazyChunkMaterialization(): void
     {
         LazyCollection::fromFactory(fn(): array => $this->data)
             ->chunkLazy(100)
             ->all();
     }
 
+    public function benchLazyFactoryArrayMaterialization(): void
+    {
+        LazyCollection::fromFactory(fn(): array => $this->data)->all();
+    }
+
     public function benchLazyFilterMaterialization(): void
     {
         LazyCollection::fromFactory(fn(): array => $this->data)
             ->filterLazy(static fn(int $value): bool => ($value % 2) === 0)
             ->all();
     }
 
+    public function benchLazyGeneratorReplayMaterialization(): void
+    {
+        $data = $this->data;
+        $source = (static function () use ($data): \Generator {
+            yield from $data;
+        })();
+
+        LazyCollection::from($source)->all();
+    }
+
     public function benchLazyMapFilterTake(): void
     {
         LazyCollection::fromFactory(fn(): array => $this->data)

@@ -58,29 +58,29 @@ public function setUp(): void
 
     public function tearDown(): void
     {
-        foreach (['app.php', '__flat.php'] as $file) {
-            $cachePath = $this->cacheDirectory . DIRECTORY_SEPARATOR . $file;
-            if (is_file($cachePath)) {
-                unlink($cachePath);
+        $remove = static function (string $path) use (&$remove): void {
+            if (is_file($path)) {
+                unlink($path);
+
+                return;
             }
-        }
 
-        $sourcePath = $this->sourceDirectory . DIRECTORY_SEPARATOR . 'app.php';
-        if (is_file($sourcePath)) {
-            unlink($sourcePath);
-        }
+            if (!is_dir($path)) {
+                return;
+            }
 
-        if (is_dir($this->cacheDirectory)) {
-            rmdir($this->cacheDirectory);
-        }
-        if (is_dir($this->sourceDirectory)) {
-            rmdir($this->sourceDirectory);
-        }
+            foreach (scandir($path) ?: [] as $entry) {
+                if ($entry === '.' || $entry === '..') {
+                    continue;
+                }
 
-        $base = dirname($this->sourceDirectory);
-        if (is_dir($base)) {
-            rmdir($base);
-        }
+                $remove($path . DIRECTORY_SEPARATOR . $entry);
+            }
+
+            rmdir($path);
+        };
+
+        $remove(dirname($this->sourceDirectory));
     }
 
     public function benchAlreadyLoadedNamespace(): void

@@ -0,0 +1,74 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Infocyph\ArrayKit\Benchmarks;
+
+use Infocyph\ArrayKit\Collection\LazyCollection;
+use Infocyph\Runwire\RequestContext;
+use Infocyph\Runwire\RuntimeContext;
+use PhpBench\Attributes\BeforeMethods;
+use PhpBench\Attributes\Iterations;
+use PhpBench\Attributes\ParamProviders;
+use PhpBench\Attributes\Revs;
+
+#[Revs(1)]
+#[Iterations(3)]
+#[BeforeMethods('setUp')]
+#[ParamProviders('provideSizes')]
+final class RunwireLazyCollectionBench
+{
+    /** @var array<int, int> */
+    private array $data = [];
+
+    private RequestContext $request;
+
+    private RuntimeContext $runtime;
+
+    /** @param array{size:int} $params */
+    public function setUp(array $params): void
+    {
+        $this->data = range(1, $params['size']);
+        $this->runtime = RuntimeContext::standalone();
+        $this->request = RequestContext::create($this->runtime);
+    }
+
+    public function benchBoundRequestMapFilter(): void
+    {
+        LazyCollection::from($this->data)
+            ->withRunwire($this->runtime, $this->request, checkpointEvery: 256)
+            ->mapLazy(static fn(int $value): int => $value * 2)
+            ->filterLazy(static fn(int $value): bool => ($value % 3) === 0)
+            ->all();
+    }
+
+    public function benchBoundRequestMaterialization(): void
+    {
+        LazyCollection::from($this->data)
+            ->withRunwire($this->runtime, $this->request, checkpointEvery: 256)
+            ->all();
+    }
+
+    public function benchUnboundMapFilter(): void
+    {
+        LazyCollection::from($this->data)
+            ->mapLazy(static fn(int $value): int => $value * 2)
+            ->filterLazy(static fn(int $value): bool => ($value % 3) === 0)
+            ->all();
+    }
+
+    public function benchUnboundMaterialization(): void
+    {
+        LazyCollection::from($this->data)->all();
+    }
+
+    /** @return array<string, array{size:int}> */
+    public function provideSizes(): array
+    {
+        return [
+            '1k' => ['size' => 1000],
+            '10k' => ['size' => 10000],
+            '100k' => ['size' => 100000],
+        ];
+    }
+}