chore: cleanup fragile tests, contexts, bundle configs

Author: norberttech

documentation/components/bridges/symfony-filesystem-bundle.md

@@ -32,6 +32,7 @@ This bundle integrates Flow PHP's Filesystem library with Symfony applications.
 - **Pluggable filesystem factories** — register custom backends with the `#[AsFilesystemFactory]` attribute or a DI tag
 - **Built-in factories** — `file`, `memory`, `stdout`, `aws_s3`, and `azure_blob` ship out of the box
 - **Console commands** — `flow:filesystem:*` (alias `flow:fs:*`) for `ls`, `cat`, `cp`, `mv`, `rm`, `stat`, `touch` against any configured filesystem
+- **Symfony Cache pools** — register PSR-6 cache pools backed by any mounted filesystem (local disk, S3, Azure Blob …) when [flow-php/symfony-filesystem-cache-bridge](/documentation/components/bridges/symfony-filesystem-cache-bridge.md) is installed
 - **Telemetry integration** — wrap every filesystem in `TraceableFilesystem` via OpenTelemetry
 - **Multi-fstab support** *(advanced)* — configure several independent `FilesystemTable` services when you really need them
 
@@ -393,6 +394,119 @@ Remote object stores (S3, Azure Blob, …) do not have a real concept of directo
 keyspaces with `/` as a convention. Rather than emulate `mkdir` inconsistently across backends, the bundle
 omits the command entirely. Directories appear when files appear inside them.
 
+## Symfony Cache Integration
+
+The bundle integrates with [flow-php/symfony-filesystem-cache-bridge](/documentation/components/bridges/symfony-filesystem-cache-bridge.md) to provide PSR-6 / Symfony Cache pools backed by any filesystem already mounted in a fstab — local disk, S3, Azure Blob, anything the bundle's factories can build. The adapter implements `PruneableInterface`, so `cache:pool:prune` works out of the box.
+
+Each pool resolves its filesystem **through a fstab mount**, not by referencing a service id directly. Filesystems must already be declared under `flow_filesystem.fstabs.<fstab>.filesystems.<protocol>` before a cache pool can target them. This keeps fstab the single place where filesystems live and avoids the cache and the rest of the app drifting into separate filesystem definitions.
+
+### Setup
+
+1. Install the cache bridge:
+
+```bash
+composer require flow-php/symfony-filesystem-cache-bridge:~--FLOW_PHP_VERSION--
+```
+
+2. Define one or more pools under `flow_filesystem.cache.pools`. Each pool names a fstab mount (the YAML key under `filesystems:`) and a base path inside it:
+
+```yaml
+# config/packages/flow_filesystem.yaml
+flow_filesystem:
+    fstabs:
+        default:
+            filesystems:
+                file:
+                    type: file
+
+    cache:
+        pools:
+            app:
+                filesystem: file                                       # mount protocol from the default fstab
+                path: '%kernel.project_dir%/var/cache/flow/app'
+                default_lifetime: 3600
+
+            sessions:
+                filesystem: file
+                path: '%kernel.project_dir%/var/cache/flow/sessions'
+                namespace: 'sess.'
+                default_lifetime: 86400
+```
+
+`fstab` is optional and defaults to the bundle's resolved default fstab — same rule the `flow:filesystem:*` CLI commands follow. Set it explicitly when you want a pool to use a non-default fstab:
+
+```yaml
+flow_filesystem:
+    default_fstab: primary
+    fstabs:
+        primary:
+            filesystems:
+                file:
+                    type: file
+        archive:
+            filesystems:
+                aws-s3:
+                    type: aws_s3
+                    bucket: '%env(ARCHIVE_BUCKET)%'
+
+    cache:
+        pools:
+            cold_storage:
+                fstab: archive
+                filesystem: aws-s3
+                path: '/cache/cold'
+                default_lifetime: 86400
+```
+
+Each pool registers as `flow_filesystem.cache.pool.<name>` (public).
+
+3. Wire the pools into Symfony's cache framework via `cache.adapter.psr6`:
+
+```yaml
+# config/packages/framework.yaml
+framework:
+    cache:
+        pools:
+            cache.app_fs:
+                adapter: cache.adapter.psr6
+                provider: flow_filesystem.cache.pool.app
+
+            cache.sessions_fs:
+                adapter: cache.adapter.psr6
+                provider: flow_filesystem.cache.pool.sessions
+```
+
+The `cache.adapter.psr6` wrapper is required because Symfony's `CachePoolPass` overwrites the first constructor argument of any service used directly as `adapter:`, which conflicts with this bridge's strict `Filesystem` typing on argument 0.
+
+### Configuration Options (per pool)
+
+| Option                   | Default        | Description                                                                                            |
+|--------------------------|----------------|--------------------------------------------------------------------------------------------------------|
+| `fstab`                  | default fstab  | Fstab name. Defaults to the bundle's resolved default fstab when omitted.                              |
+| `filesystem`             | *required*     | Mount protocol within the chosen fstab (the YAML key under `filesystems:`).                            |
+| `path`                   | *required*     | Base directory inside the chosen filesystem where cache files are stored.                              |
+| `namespace`              | `''`           | Cache pool namespace; chars in `[-+.A-Za-z0-9]` only.                                                  |
+| `default_lifetime`       | `0`            | Default TTL in seconds; `0` means no expiry.                                                           |
+| `marshaller_service_id`  | `null`         | Service ID of a custom `MarshallerInterface`.                                                          |
+
+Validation runs at container compile time:
+
+- A pool referencing a missing fstab fails with `flow_filesystem.cache.pools.<name>: fstab "<x>" is not declared. Available fstabs: [...]`.
+- A pool referencing a mount protocol that is not registered in the chosen fstab fails with `flow_filesystem.cache.pools.<name>: filesystem "<x>" is not mounted in fstab "<y>". Available mounts: [...]`.
+- `flow_filesystem.cache.pools` is configured but `flow-php/symfony-filesystem-cache-bridge` is not installed → fails fast with a message pointing at the missing package.
+
+### Pruning
+
+Schedule the standard Symfony command on a cron to remove expired files:
+
+```bash
+php bin/console cache:pool:prune
+```
+
+Without pruning, expired files accumulate under each pool's directory. They are filtered out on read but only deleted when either the same key is fetched again or `cache:pool:prune` runs.
+
+For full documentation, see the [Symfony Filesystem Cache Bridge](/documentation/components/bridges/symfony-filesystem-cache-bridge.md).
+
 ## Multi-Fstab Support
 
 > **Advanced.** Most applications should stick to a single fstab with multiple filesystems mounted under

documentation/components/bridges/symfony-filesystem-cache-bridge.md

@@ -1,9 +1,10 @@
 # Symfony Filesystem Cache Bridge
 
-A Symfony Cache adapter backed by Flow PHP's native filesystem library. Cache items are stored as files using Flow's `Filesystem` abstraction, so the same adapter works with local filesystems, Azure Blob Storage, S3, and any other Flow filesystem implementation.
+A Symfony Cache adapter backed by Flow PHP's native `Filesystem` library. Cache items are stored as files on top of any filesystem the library can mount — local disk, in-memory, AWS S3, Azure Blob — without depending on Symfony's `FilesystemAdapter` and the local-only assumptions baked into it.
 
 - [Back](/documentation/introduction.md)
 - [Packagist](https://packagist.org/packages/flow-php/symfony-filesystem-cache-bridge)
+- [Installation](/documentation/installation/packages/symfony-filesystem-cache-bridge.md)
 - [GitHub](https://github.com/flow-php/symfony-filesystem-cache-bridge)
 - [API Reference](/documentation/api/bridge/symfony-filesystem-cache)
 
@@ -15,6 +16,93 @@ A Symfony Cache adapter backed by Flow PHP's native filesystem library. Cache it
 composer require flow-php/symfony-filesystem-cache-bridge:~--FLOW_PHP_VERSION--
 ```
 
+For Symfony framework integration (config-driven pool registration) use this bridge through the [Symfony Filesystem Bundle](/documentation/components/bridges/symfony-filesystem-bundle.md). The page below covers standalone usage.
+
+## How It Works
+
+`FlowFilesystemCacheAdapter` extends Symfony's `AbstractAdapter` and implements `PruneableInterface`. Items are stored one-per-file under a base directory you provide:
+
+```
+<base>/
+  ab/
+    qZ5K-…   ← single cache item
+  c4/
+    Mn7p-…
+```
+
+- The 2-character shard directory is `substr(str_replace('/', '-', base64_encode(hash('xxh128', $id, true))), 0, 2)` — the same recipe as Symfony's built-in `FilesystemAdapter`, so the on-disk layout is familiar.
+- Each file body has three newline-separated parts: a 10-digit zero-padded expiry timestamp (`0000000000` for "no expiry"), the cache id, and the marshalled value.
+- **Saves** write to a randomised temp path (`Path::randomize()`), then `mv()` to the final path. If `mv()` returns `false` the temp file is removed and the failure is reported to the configured logger as a `FilesystemCacheException`.
+- **Reads** stream the file once, split on `"\n"`, drop the row when the expiry has passed and call `doDelete()` for the expired ids in the same call.
+- **`prune()`** walks the base directory recursively, reads only the first line of every file, and deletes any file whose expiry is in the past.
+- **Marshalling** uses Symfony's `DefaultMarshaller` by default; pass a custom `MarshallerInterface` to the constructor to override.
+
+## Filesystem Ownership
+
+The adapter does NOT create or own a `Filesystem`. You hand it any `Flow\Filesystem\Filesystem` instance and a `Path` for the base directory:
+
+- **Local disk** — pass `new NativeLocalFilesystem()` and a `Path::from('/var/cache/app')`.
+- **Remote object store** — pass an S3 or Azure-backed filesystem; the adapter writes through it transparently.
+- **Same instance, multiple pools** — give two adapters the same `Filesystem` but different `Path` directories (or different `namespace` strings) to keep their files isolated.
+
+The `Path` value is the only state the adapter holds about location — every `getItem`/`save`/`clear` call composes the per-item path from it, so changing the directory means re-instantiating the adapter.
+
 ## Usage
 
-TODO: Add usage documentation
+```php
+use Flow\Bridge\Symfony\FilesystemCache\FlowFilesystemCacheAdapter;
+use Flow\Filesystem\Local\NativeLocalFilesystem;
+use Flow\Filesystem\Path;
+
+$cache = new FlowFilesystemCacheAdapter(
+    filesystem: new NativeLocalFilesystem(),
+    directory: Path::from('/var/cache/app'),
+    namespace: 'app',
+    defaultLifetime: 3600,
+);
+
+$item = $cache->getItem('greeting');
+
+if (!$item->isHit()) {
+    $item->set('hello world');
+    $item->expiresAfter(600);
+    $cache->save($item);
+}
+
+echo $cache->getItem('greeting')->get();
+```
+
+The same code works against `flow-php/filesystem-async-aws-bridge` or `flow-php/filesystem-azure-bridge` — swap the `Filesystem` argument and the cache lives in S3 or Azure Blob.
+
+## Constructor
+
+```php
+new FlowFilesystemCacheAdapter(
+    Flow\Filesystem\Filesystem $filesystem,
+    Flow\Filesystem\Path $directory,
+    string $namespace = '',
+    int $defaultLifetime = 0,
+    ?Symfony\Component\Cache\Marshaller\MarshallerInterface $marshaller = null,
+);
+```
+
+`$namespace` is validated against `[-+.A-Za-z0-9]` — same rule Symfony enforces. `$directory` must be a non-pattern path; the adapter creates the shard directories on demand via the underlying filesystem's `writeTo()`.
+
+## File Layout
+
+| Section | Format | Notes |
+|---------|--------|-------|
+| Line 1  | `printf('%010d', $expiry)` | Zero-padded UNIX timestamp; `0000000000` means "never expires" |
+| Line 2  | raw cache id | Used by `clear($prefix)` to match items by namespace prefix |
+| Line 3+ | marshaller output | Whatever `MarshallerInterface::marshall()` produced (binary safe) |
+
+The shard prefix keeps any single directory bounded — even with millions of keys, no shard dir holds more than `~items / 256 / 256` entries on average, and the tree never grows wider than 256 sub-directories.
+
+## Pruning
+
+The filesystem has no built-in TTL, so expired files are removed by either of two paths:
+
+- **Lazy** — a read of the same key triggers a delete of that one file.
+- **Explicit** — calling `$cache->prune()` (or `bin/console cache:pool:prune` when the adapter is wired into a Symfony app) walks the base directory and deletes everything past its expiry.
+
+Without periodic pruning, dead files accumulate even though they are invisible to readers.

documentation/installation/packages/symfony-filesystem-bundle.md

@@ -36,4 +36,5 @@ Mount remote object stores by installing the matching bridge alongside the bundl
 
 ## Suggested Dependencies
 
+- [flow-php/symfony-filesystem-cache-bridge](/documentation/installation/packages/symfony-filesystem-cache-bridge.md) — for PSR-6 / Symfony Cache pools backed by any mounted filesystem (local disk, S3, Azure Blob)
 - [flow-php/symfony-telemetry-bundle](/documentation/installation/packages/symfony-telemetry-bundle.md) — for telemetry integration (distributed tracing, metrics, logging)

documentation/installation/packages/symfony-filesystem-cache-bridge.md

@@ -0,0 +1,30 @@
+---
+seo_title: "Installing Symfony Filesystem Cache Bridge"
+seo_description: >
+  How to install flow-php/symfony-filesystem-cache-bridge in your PHP project using Composer.
+---
+
+# Symfony Filesystem Cache Bridge
+
+- [Back](/documentation/installation.md)
+- [Documentation](/documentation/components/bridges/symfony-filesystem-cache-bridge.md)
+- [Packagist](https://packagist.org/packages/flow-php/symfony-filesystem-cache-bridge)
+
+[TOC]
+
+## Composer
+
+```bash
+composer require flow-php/symfony-filesystem-cache-bridge:~--FLOW_PHP_VERSION--
+```
+
+## Core Dependencies
+
+- [flow-php/filesystem](/documentation/installation/packages/filesystem.md)
+- [symfony/cache](https://packagist.org/packages/symfony/cache)
+
+## Recommended Packages
+
+- [flow-php/symfony-filesystem-bundle](/documentation/installation/packages/symfony-filesystem-bundle.md) — registers the cache adapter from `flow_filesystem.cache.pools` config
+- [flow-php/filesystem-async-aws-bridge](/documentation/installation/packages/filesystem-async-aws-bridge.md) — to back cache pools with AWS S3
+- [flow-php/filesystem-azure-bridge](/documentation/installation/packages/filesystem-azure-bridge.md) — to back cache pools with Azure Blob Storage

src/bridge/psr18/telemetry/tests/Flow/Bridge/Psr18/Telemetry/Tests/Integration/LocalHttpServer.php

@@ -0,0 +1,123 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Flow\Bridge\Psr18\Telemetry\Tests\Integration;
+
+/**
+ * Forks a child process that serves a fixed 200 OK on a free loopback port
+ * for one test. Avoids depending on public URLs or PHP's built-in web server
+ * (the latter writes a lock file that's not always writable under sandboxes).
+ */
+final class LocalHttpServer
+{
+    private int $childPid = 0;
+
+    private int $port = 0;
+
+    public function port() : int
+    {
+        return $this->port;
+    }
+
+    public function start() : void
+    {
+        if (!\function_exists('pcntl_fork')) {
+            throw new \RuntimeException('pcntl_fork() is required to run the local test HTTP server.');
+        }
+
+        $server = \stream_socket_server('tcp://127.0.0.1:0', $errno, $errstr);
+
+        if (!\is_resource($server)) {
+            throw new \RuntimeException(\sprintf('Failed to bind local test HTTP server: %s (%d)', $errstr, $errno));
+        }
+
+        $name = \stream_socket_get_name($server, false);
+
+        if (!\is_string($name)) {
+            \fclose($server);
+
+            throw new \RuntimeException('Failed to read bound socket name.');
+        }
+
+        $colon = \strrpos($name, ':');
+
+        if ($colon === false) {
+            \fclose($server);
+
+            throw new \RuntimeException(\sprintf('Unexpected socket name "%s".', $name));
+        }
+
+        $this->port = (int) \substr($name, $colon + 1);
+
+        $pid = \pcntl_fork();
+
+        if ($pid === -1) {
+            \fclose($server);
+
+            throw new \RuntimeException('pcntl_fork() failed.');
+        }
+
+        if ($pid === 0) {
+            $this->serveLoop($server);
+        }
+
+        \fclose($server);
+        $this->childPid = $pid;
+    }
+
+    public function stop() : void
+    {
+        if ($this->childPid > 0) {
+            @\posix_kill($this->childPid, \SIGTERM);
+            \pcntl_waitpid($this->childPid, $status);
+            $this->childPid = 0;
+        }
+    }
+
+    public function url() : string
+    {
+        return \sprintf('http://127.0.0.1:%d', $this->port);
+    }
+
+    /**
+     * @param resource $server
+     */
+    private function serveLoop($server) : never
+    {
+        \pcntl_signal(\SIGTERM, static function () : void {
+            exit(0);
+        });
+
+        while (true) {
+            \pcntl_signal_dispatch();
+            $client = @\stream_socket_accept($server, 1.0);
+
+            if (!\is_resource($client)) {
+                continue;
+            }
+
+            \stream_set_timeout($client, 1);
+
+            // Read request line + headers; we don't actually need the body.
+            while (!\feof($client)) {
+                $line = \fgets($client, 8192);
+
+                if ($line === false || $line === "\r\n" || $line === "\n") {
+                    break;
+                }
+            }
+
+            $body = 'ok';
+            $response = "HTTP/1.1 200 OK\r\n"
+                . "Content-Type: text/plain\r\n"
+                . 'Content-Length: ' . \strlen($body) . "\r\n"
+                . "Connection: close\r\n"
+                . "\r\n"
+                . $body;
+
+            \fwrite($client, $response);
+            \fclose($client);
+        }
+    }
+}