# Appendix: Satellite Packages

A reference map of what exists in each optional satellite package, by
namespace. For core (`kinetis/framework` itself), see {doc}`appendix`.

## `packages/bref-adapter` (`kinetis/bref-adapter`)

Separate Composer package, not part of `kinetis/framework` core.

- `Kinetis\BrefAdapter\BrefLambdaAdapter implements Kinetis\Runtime\RuntimeAdapterInterface` — `run()` polls the Lambda Runtime API for the next invocation in a `while (true)` loop, converts the API Gateway HTTP API (payload format 2.0) event into a PSR-7 request, and posts the response back as the invocation's result; `isPersistent(): true` (a warm container keeps reusing the same process across invocations, the same shape `FrankenPhpAdapter` has). Talks to the Runtime API with plain stream-context HTTP, not `ext-curl`; a transport failure or a non-2xx status from the Runtime API itself throws rather than being treated as an empty response. Maps the event's top-level `cookies` list into a real `Cookie` header/`getCookieParams()` and `requestContext.http.sourceIp` into the request's `REMOTE_ADDR` server parameter — neither is in `headers`, and nothing else here has a real socket to read either from. `handleEvent(array $event, callable $handler)` is one invocation from decoded event to response payload — the Lambda counterpart of `SuperglobalsBridge::handle()`, answering an `Exception\MalformedRequestBodyException` (invalid base64, a multipart body with no usable boundary) with the same `400` every adapter gives instead of an invocation error, and the entry point the runtime conformance suite drives (`tests/Conformance/LambdaDriver`). `requestFromEvent()` decodes a base64 body strictly (invalid base64 is `MalformedRequestBodyException`, never an empty body); `responseToPayload()` base64-encodes a response body that isn't valid UTF-8 (`json_encode()` would otherwise reject it) and emits every `Set-Cookie` header value as its own entry in the payload's `cookies` array rather than folding them into one comma-joined header. Parses `multipart/form-data` via `riverline/multipart-parser`'s `StreamedPart`, `application/x-www-form-urlencoded` via `parse_str()` — a Lambda event body is one in-memory string with no live `php://input`, so `request_parse_body()` (what core's own adapters use) can't apply here. See {doc}`runtime-adapters` for the full supported/unsupported feature list.
- Depends on `kinetis/framework` (via a `path` repository to this monorepo's root), `nyholm/psr7`, `psr/http-message`, `riverline/multipart-parser`. Own `composer.json`/`phpunit.xml`/`phpstan.neon`.

## `packages/persistence` (`kinetis/persistence`)

Separate Composer package, not part of `kinetis/framework` core — extracted
from it so core itself has no direct MySQL/Postgres dependency.

- `Kinetis\Persistence\TransactionGuard` — request-scoped SQL transaction safety net. `transaction()` (commit on success, rollback on throw) and `beginTransaction()`/`rollbackDangling()` for the manual case. `Kinetis\Http\Kernel` and `bin/kinetis` both register `rollbackDangling()` as a dispose hook whenever this class is available (`class_exists()`-gated), not unconditionally — an application with no database can skip this package entirely.
- `Kinetis\Persistence\SqlConnectionFactory::fromConfig(Config $config, string $connection = 'default'): Contract\MysqlLink|Contract\PostgresLink` — builds a runtime-matched driver client from `DB_*` (or `DB_{NAME}_*` for a named connection); shared by `kinetis/migrations`' `migrate*` commands, `kinetis/queue-sql`'s `SqlQueueFactory`, and this package's own `PackageBootstrap`. `$poolOptions['warmConnections']`/`DB_WARM_CONNECTIONS` opens connections at construction via each driver's `warmUp(?int $connections = null)` — load-bearing for the mysqli driver under worker mode (see {doc}`performance-tuning`).
- `Kinetis\Persistence\Testing\DatabaseTransactions` / `DatabaseTruncation` — per-test database isolation for a consumer's PHPUnit suite (see {doc}`testing`): a rolled-back transaction per test, or explicit-table deletion before each test. Both ask the test for the connection via an abstract `databaseLink()`. `DatabaseTransactions` requires a single-connection (PDO) driver and skips otherwise — a transaction on one pooled connection isolates nothing the others do; `DatabaseTruncation` works with any driver and with code that opens its own transactions. `Testing\DatabaseIsolation` (@internal) holds their shared checks.
- `Kinetis\Persistence\Contract\PrefersPreparedStatements` — a marker, no methods: this link is faster binding a value than reading it as a literal. Carried by `PdoMysqlClient`/`PdoPgsqlClient` and their transactions, which memoize prepared statements per connection (and per transaction — a transaction owns its own handle, so it keeps its own cache) and therefore keep the binary protocol; the native drivers do not carry it, since an unparameterized query saves them a round trip. `Kinetis\QueryBuilder\Query` is the caller that branches on it.
- `Kinetis\Persistence\PackageBootstrap` — declared via `extra.kinetis`; with `DB_CONNECTION` set, binds `SqlConnectionFactory::fromConfig()`'s result under its dialect contract (`Contract\MysqlLink` or `Contract\PostgresLink`) before the application's own `bootstrap.php` runs (which wins on the same binding). Inert when `DB_CONNECTION` is unset; named (non-default) connections stay explicit app-side wiring.
- Depends on `kinetis/framework` (via a `path` repository to this monorepo's root) and `revolt/event-loop`; the drivers use `ext-mysqli`/`ext-pgsql`/PDO, suggested rather than required. Own `composer.json`/`phpunit.xml`/`phpstan.neon`.

## `packages/cache-redis` (`kinetis/cache-redis`)

Separate Composer package, not part of `kinetis/framework` core — extracted
from it for the identical reason `kinetis/persistence` was: core has no
direct Redis dependency either. `NullSimpleCache` and the PSR-16 exception
types stay in core (see {doc}`appendix`'s `Kinetis\SimpleCache` section);
only the classes with a real `amphp/redis` dependency moved.

- `Kinetis\SimpleCache\RedisSimpleCache` — single-node, backed by `Amp\Redis\RedisClient`. `fromConfig(Config $config, string $connection = 'default')`/`buildRedisConfig(Config $config, string $connection = 'default')` read `REDIS_URL` or discrete `REDIS_HOST`/`REDIS_PORT`/`REDIS_PASSWORD`/`REDIS_DATABASE`/`REDIS_TIMEOUT` (or their `REDIS_{NAME}_*` named-connection equivalents), returning `null` when neither is set. `clear()` flushes the entire selected database. Also implements core's `Kinetis\SimpleCache\AtomicCounterInterface`: `increment()` runs `INCR` and `EXPIRE` as one Lua script, so concurrent callers each receive a distinct value, and `count()` reads that counter — a bare integer, not a serialized value, so `get()` cannot read it. And `Kinetis\SimpleCache\AtomicConsumeInterface`: `consume()` runs `GET` and `DEL` as one Lua script, so at most one of two concurrent callers ever receives a given value.
- `Kinetis\SimpleCache\ClusteredRedisSimpleCache` — the Redis Cluster counterpart, activated by `REDIS_CLUSTER=true`/`REDIS_CLUSTER_SEEDS`. `Cluster\Crc16::slotFor()` computes the owning slot (CRC16-XMODEM mod 16384, honoring a `{...}` hash tag when present); `Cluster\ClusterTopology` discovers the slot→node layout via `CLUSTER SHARDS` and resolves a slot to the `RedisClient` that owns it, refreshing on a `MOVED` reply. `getMultiple()`/`deleteMultiple()` dispatch one command per key rather than a batched `MGET`/`DEL` (Redis Cluster rejects any multi-key command whose keys don't share a slot), run concurrently via `Kinetis\Async\concurrently()`; `clear()` fans `FLUSHDB` out to every master. Only database 0 is supported, matching a real cluster's own restriction. Implements `AtomicCounterInterface`/`AtomicConsumeInterface` too — each script carries one key, so it runs on whichever node owns that key's slot.
- `Kinetis\SimpleCache\Connection\TlsRedisConnector` — a `RedisConnector` using `Amp\Socket\connectTls()`, since `Amp\Redis`'s own default connector never upgrades to TLS. Shared by both classes above; returns `null` when `REDIS_TLS` isn't set.
- `Kinetis\Container\AppScope::boot()` tries `ClusteredRedisSimpleCache::fromConfig()` then `RedisSimpleCache::fromConfig()`, both `class_exists()`-gated against this package; Redis configured (`REDIS_HOST`/`REDIS_URL`/`REDIS_CLUSTER`) but this package not installed binds core's `UnavailableSimpleCache`, whose every operation throws `Kinetis\SimpleCache\Exception\SimpleCacheUnavailableException` naming this package — never a silent fallback to `NullSimpleCache`, and never a boot-time failure for an application that doesn't touch the cache.
- Depends on `kinetis/framework` (via a `path` repository to this monorepo's root), `amphp/redis`, `amphp/socket`, `amphp/serialization`. Own `composer.json`/`phpunit.xml`/`phpstan.neon`.

## `packages/mcp` (`kinetis/mcp`)

The Model Context Protocol server. Installing the package is the whole
setup: its `extra.kinetis` declares a scan root covering the namespace
and a bootstrap, so the `/mcp` route, `mcp:serve`, and the docs
resources all appear with nothing to wire. Core has no MCP surface
without it.

- `PackageBootstrap` — lazy-binds `McpServer`: discovery
  (`McpDiscovery::discover()`) runs when something first resolves the
  server — once per worker under a persistent runtime, once per `/mcp`
  request under PHP-FPM, never on a request that doesn't touch it. The
  project root comes from Composer's own runtime API
  (`InstalledVersions::getRootPackage()`), so the same code serves a
  consumer install and this package's own development.
- `Http\McpController` — `/mcp` as an ordinary route (`#[Post('/mcp')]`,
  `#[Middleware('@mcp')]`): parse-error handling, protocol-era
  detection, the mirrored-header checks (`MCP-Protocol-Version`/
  `Mcp-Method`/`Mcp-Name`, modern-era requests only, with the
  `=?base64?{...}?=` sentinel decoded and failing closed), the
  spec's error-code-to-HTTP-status mapping, `202` for notification-only
  bodies, and the SSE progress stream (a `StreamedResponse` whose
  emitter runs after the request scope is disposed, so the streamed
  call gets its own scope — with the request's `CurrentUserInterface`
  carried across — disposed after the final event). GET/DELETE declare
  no routes: the router's own `405` with `Allow: POST` is exactly what
  the 2026-07-28 spec asks for.
- `Http\McpOriginMiddleware` — the spec-required `Origin` validation,
  reading `MCP_ALLOWED_ORIGINS` (comma-separated exact list, empty
  means any request carrying an Origin is rejected `403`). A permanent
  `mcp`-group member at priority 100 — which is also what guarantees
  the group `McpController` references always exists.
- `Console\McpServeCommand` — `#[Command('mcp:serve')]`, resolving the
  bootstrap's own `McpServer` binding and handing the transport the
  real `AppScope` for per-message scopes.
- `McpServer` — handles one decoded JSON-RPC message; `handle()` takes an optional per-message scope threaded through to `McpDispatcher`. Supports the legacy (`2025-03-26`) `initialize` handshake and the modern (`2026-07-28`) stateless `server/discover` model side by side. `logger` param defaults to `NullLogger` (constructed directly, not through the container). A throwing tool reports `isError: true` with the fixed content string `Tool execution failed.`, the real exception going to the logger — a failed validation keeps its real `errors` map, since that's the argument feedback an agent retries on. `wrapModernResult()` adds `ttlMs`/`cacheScope` per `CACHEABLE_METHOD_SCOPES` (`server/discover`/`tools/list`/`resources/list` → `public`, `resources/read` → `private`, `tools/call` → neither, since it's an action not a cacheable read). The optional constructor `$instructions` is included on `server/discover` only when given, omitted entirely otherwise.
- `McpRegistry` — `#[McpTool]`/`#[McpResource]` discovery, `toArray()`/`fromArray()` for the AOT cache.
- `McpDispatcher` — the MCP analogue of `Http\Dispatcher`. `callTool()`/`readResource()` take an optional per-call scope the transports create per message; the controller and its dependencies resolve from it, falling back to the constructor's container when none is given (which is then not per-message-scoped).
- `ProgressReporter` — injected by type into a tool method; `report()` streams a `notifications/progress` event when `_meta.progressToken` is present, a no-op otherwise.
- `Transport\StdioTransport` — one JSON-RPC message per line on stdin/stdout. Given an `AppScope` (as `mcp:serve` passes), each line is a unit of work: fresh scope, the `TransactionGuard` rollback hook behind the same `class_exists()` gate `Kernel` uses, disposal once the response is written, then `gc_collect_cycles()` — a stdio server is a persistent process. Without one, messages share the dispatcher's own container, the pre-scope behavior.
- `KinetisDocsResource` — registers every `docs/*.md` page as an MCP resource (`kinetis://docs/{slug}`) — the monorepo's own files when developing Kinetis, the published documentation otherwise. Lives under this package's scan root, so discovery always finds it on both transports; registering it manually (`$registry->register(KinetisDocsResource::class)`) is only needed for a hand-wired `McpRegistry` that never goes through discovery.
- `McpDiscovery::discover(string $projectRoot, ?array $paths = null): McpRegistry` — builds a registry from every class found anywhere under a project's own PSR-4 root(s), plus `Kinetis\Mcp` itself (`NamespaceScanner`, see `Kinetis\Cache` below), rather than an explicit registration file. `$paths`, or `MCP_DISCOVERY_PATHS` when omitted, restricts the project-side scan.

## `packages/migrations` (`kinetis/migrations`)

Separate Composer package, not part of `kinetis/framework` core.

- `Kinetis\Migrations\Migration` — the interface a migration file's anonymous class implements: `up(MysqlLink|PostgresLink $db): void`/`down(...): void`, raw SQL only, issued via `$db->execute()`.
- `Kinetis\Migrations\MigrationFile` — discovers `<timestamp>_<description>.php` files under a `migrations/` project-root directory, sorted by filename; `load()` is a bare `require` of the file.
- `Kinetis\Migrations\MigrationRepositoryInterface` / `SqlMigrationRepository` — tracks applied migrations in a `kinetis_migrations` table (`migration` primary key, `applied_at`), typed against the generic `Kinetis\Persistence\Contract\SqlLink` since its own bookkeeping SQL is dialect-agnostic.
- `Kinetis\Migrations\MigrationRunner` — `pending()`/`migrate()`/`rollback()`/`status()`. Never wraps a migration in a transaction; `rollback()` targets the single most recently applied migration only, throwing `Exception\MigrationFileMissingException` if that migration's file no longer exists. `migrate()`/`rollback()` hold a cross-process advisory lock (MySQL `GET_LOCK()`, Postgres `pg_advisory_lock()`) for their whole duration, throwing `Exception\MigrationLockTimeoutException` if it can't be acquired within `$lockTimeoutSeconds` (10 by default).
- `Kinetis\Migrations\MigrationScaffolder` — writes a new timestamped migration file with the `up()`/`down()` stubs filled in, via an exclusive (`x`) file create rather than an unconditional overwrite; a same-second name collision retries with a random suffix. Throws `Exception\MigrationScaffoldException` on a real I/O failure creating the directory or writing the file.
- `Kinetis\Migrations\Console\{MigrateCommand, RollbackCommand, StatusCommand, MakeCommand}` — the `migrate`/`migrate:rollback`/`migrate:status`/`migrate:make <description>` commands on `vendor/bin/kinetis`, registered through this package's `extra.kinetis` scan root and all `#[Command(bootstrap: false)]`. `Console\MigrationContext` (@internal) is their shared connection/paths holder: connects via `Kinetis\Persistence\SqlConnectionFactory`, reading `DB_CONNECTION` (`mysql`|`pgsql`, required) plus `DB_HOST`/`DB_NAME`/`DB_USER`/`DB_PASSWORD`/`DB_PORT`; `--connection=<name>` wins over `MIGRATE_CONNECTION_NAME` (default `'default'`) for a named connection.
- Depends on `kinetis/framework` and `kinetis/persistence` (both via a `path` repository to this monorepo's root); `SqlMigrationRepository` types against the generic `Kinetis\Persistence\Contract\SqlLink`. Own `composer.json`/`phpunit.xml`/`phpstan.neon`.

## `packages/query-builder` (`kinetis/query-builder`)

Separate Composer package, not part of `kinetis/framework` core.

- `Kinetis\QueryBuilder\Query` — a thin, parameterized SQL query builder, not an ORM (no relationships/migrations/change-tracking). One class works with either MySQL or Postgres via the shared `Kinetis\Persistence\Contract\SqlLink` family (auto-detected instanceof `Contract\MysqlLink`/`Contract\PostgresLink`). `select()`/`selectRaw()`/`where()`/`orWhere()`/`whereIn()`/`whereRaw()`/`join()`/`leftJoin()`/`orderBy()`/`orderByRaw()`/`limit()`/`offset()`, terminal `get()`/`first()`/`count()` (optional `Hydrator`-based DTO mapping) and `insert()`/`insertGetId()`/`update()`/`delete()`. Accepts a plain pool or an in-flight `SqlTransaction`, so it composes inside `TransactionGuard::transaction()`. Every terminal method routes through one private `run()`, which chooses between `$link->query()` and `$link->execute()` per driver: a query with nothing bound always takes `query()`, and a query whose every value is an `int` or `bool` writes them as literals and takes it too — unless the link carries `Contract\PrefersPreparedStatements`, which the PDO drivers do, where binding is the cheaper of the two. Strings, `null` and floats always bind, and any use of `whereRaw()`/`selectRaw()`/`orderByRaw()` disables inlining for the whole query.
- `Kinetis\QueryBuilder\Dialect` (+ `Dialect\MySqlDialect`/`Dialect\PostgresDialect`) — isolates identifier quoting, retrieving a generated primary key after an insert (MySQL: `getLastInsertId()`; Postgres: `INSERT ... RETURNING`), and `literalFor()`, the per-dialect logic behind the literal-inlining above.
- `Kinetis\QueryBuilder\CompiledQuery` — the `{sql, params}` output of every `to*Sql()` compile method, built together in one pass so bound parameters always land in the same position as their `?` in the generated SQL, even once `whereRaw()`/`whereIn()` mix with structured `where()` calls.
- `Query::paginate(int $perPage, int $page = 1, ?string $dtoClass = null): Kinetis\Http\Pagination\Paginator` — a `count()` for `total`/`lastPage` plus a `limit()`/`offset()`-based `get()` for the page, against the same `where()`/`join()` filters already on the query. A page past the last one returns empty `data` with the real `total` still reported, not an error.
- `Query::cursorPaginate(int $perPage, ?string $cursor, string $cursorColumn = 'id', ?string $dtoClass = null, ?string $cursorAlias = null): Kinetis\Http\Pagination\CursorPaginator` — orders by `$cursorColumn` and filters `WHERE $cursorColumn > $cursor` once one is given (`null` fetches from the start); no `COUNT(*)`, no page number. `nextCursor` always comes out of the same result as the delivered rows — one query, never two, so a write landing between reads can't leave the cursor naming a row the caller was never handed. Always fetches raw rows first regardless of `$dtoClass`, so the cursor is read off the real column name rather than a hydrated DTO's own property name. A `select()` projection that omits an *unqualified* `$cursorColumn` still works: it's added to the query automatically and stripped back out of every returned row (and never reaches `$dtoClass` hydration) before returning. A *qualified* `$cursorColumn` (`orders.id`, for a `join()`ed query) requires `$cursorAlias`: both MySQL and Postgres report it under its bare name, which a join collides with, and no alias this class could pick is guaranteed absent from an arbitrary projection — so the caller names one, the column is additionally selected under it, and it is stripped from every returned row. Omitting it for a qualified column throws `InvalidArgumentException`, as does an alias matching a column the caller listed in `select()` (checked before any SQL runs). An alias colliding with a column only a wildcard brings in is a documented caller precondition rather than a check: it replaces that column, since detecting it would need column metadata `SqlResult` doesn't carry and the one available proxy also fires on the ordinary duplicate `id` of a `SELECT *` across a join. Everything else about the query is untouched, so an alias an `orderBy()` depends on and a caller's own `offset()` both survive.
- One `Query` instance is one query — nothing resets between fluent calls; construct a fresh instance per query.
- Depends on `kinetis/framework` and `kinetis/persistence` (via `path` repositories to this monorepo's root). Own `composer.json`/`phpunit.xml`/`phpstan.neon`.

## `packages/queue` (`kinetis/queue`)

Separate Composer package, not part of `kinetis/framework` core.

- `Kinetis\Queue\Job` — a marker interface (no declared methods) a job class implements. `handle()` is discovered and invoked by reflection, not a fixed interface method, since its parameter list varies per job.
- `Kinetis\Queue\QueueInterface` — `push(Job $job, int $delaySeconds = 0, string $queue = 'default', ?int $maxAttempts = null): void`, `pop(int $timeoutSeconds = 0, array $queues = ['default']): ?QueuedJob`, `ack(QueuedJob $job): void`, `release(QueuedJob $job): void`, `fail(QueuedJob $job): void`, `size(string $queue = 'default'): int` (jobs waiting to be popped — delayed included, reserved excluded), `clear(string $queue = 'default'): int` (discards waiting jobs, returning how many; reserved jobs are untouched). `$queues` is checked in the given order — priority by list position, not a numeric score. `$maxAttempts` null (the default) defers to the processing `QueueWorker`'s own `$defaultMaxAttempts`, which is never itself unlimited; once `QueuedJob::$attempts` reaches the effective cap, `fail()` removes the job permanently instead of `release()` retrying it.
- `Kinetis\Queue\QueuedJob` — `{class, args, handle, queue, attempts, maxAttempts, metadata}`. `$attempts` is the attempt number the current `pop()` represents (1-indexed), not a raw failure count. `$metadata` is opaque string metadata stored at push time — the instrumentation propagation channel, carried verbatim by every backend.
- `Kinetis\Queue\JobSerializer` — converts a `Job` instance to plain `{class, args}` data (reading each constructor parameter's value off a same-named property via reflection) and back via `new $class(...$args)`. Throws `Exception\UnserializableJobException` for a constructor parameter with no matching property. `redact(string $class, array $args): array` returns those arguments with every value whose constructor parameter carries `Attributes\Sensitive` replaced by `JobSerializer::REDACTED` (`[redacted]`), for logging; a class that no longer loads redacts every value rather than none.
- `Kinetis\Queue\Attributes\Sensitive` — `TARGET_PARAMETER`, no arguments. Marks a job constructor parameter whose value must never reach a log; affects logging only, never what is written to the backend. Redacts an array or object value whole, with no per-element redaction within one.
- `Kinetis\Queue\JobInvoker` — `invoke(Job $job, ContainerInterface $container): void`, reflecting and calling `handle()` with each parameter resolved through the given container. Shared by `QueueWorker` and `SyncQueue`.
- `Kinetis\Queue\SyncQueue` — runs `push()`'s job immediately, inline, via `JobInvoker`; `pop()` always returns `null`, `ack()`/`release()`/`fail()` are no-ops. For local development; not selectable via `QUEUE_CONNECTION`. A fresh `RequestScope` per `push()`, same as `QueueWorker`; unlike `QueueWorker`, a failing job's exception propagates rather than being caught and logged.
- `Kinetis\Queue\QueueWorker` — `__construct(AppScope $app, QueueInterface $queue, int $defaultMaxAttempts = 0)`, `run()`/`processNext()`/`stop()`. SIGTERM/SIGINT (via `ext-pcntl`, when loaded — `supportsGracefulShutdown()`) stop `run()`'s loop after the job in flight finishes, so a deploy never truncates a job. One fresh `RequestScope` per job via `AppScope::createRequestScope()`, `handle()`'s parameters autowired through it via `JobInvoker`. A throwing job is always logged (job class, queue, attempt number, and the exception, plus the arguments — redacted per `Attributes\Sensitive` — only when the job is being given up on, since a job about to be retried still holds its payload in the backend); the effective cap is `QueuedJob::$maxAttempts ?? $defaultMaxAttempts` — released while `$attempts` is below it, `fail()`ed once reached. `$defaultMaxAttempts` is non-nullable: there is no configuration on this class that produces unlimited retries by default.
- `Kinetis\Queue\QueuedListenerInvoker` — implements core's `Kinetis\Events\ListenerInvokerInterface`. Serializes the event (via `JobSerializer`, generalized to accept any `object`, not `Job` specifically) and pushes an `InvokeListenerJob` carrying the listener's class/method as plain strings.
- `Kinetis\Queue\InvokeListenerJob` — the job `QueuedListenerInvoker` pushes. `handle(RequestScope $scope)` resolves the listener through the given scope and reconstructs the event via `JobSerializer::deserialize()`, invoking the original method by name.
- `Kinetis\Queue\QueueFactory::fromConfig(Config): QueueInterface` — builds the backend `QUEUE_CONNECTION` selects (`redis`|`sql`|`sqs`|`rabbitmq`, required); `QUEUE_CONNECTION_NAME` (default `'default'`) selects a named connection of that backend. Every one of the four is `class_exists()`-gated against its own package's `XxxQueueFactory::fromConfig()` — `kinetis/queue` itself depends on none of them, `redis`/`sql` exactly as optional as `sqs`/`rabbitmq`; throws `Exception\QueueUnavailableException` naming the missing package when the selected one isn't installed.
- `Kinetis\Queue\PackageBootstrap` — declared via `extra.kinetis`; with `QUEUE_CONNECTION` set, binds `QueueInterface` to `QueueFactory::fromConfig()`'s result before the application's own `bootstrap.php` runs (which wins on the same binding). Inert when `QUEUE_CONNECTION` is unset.
- `Kinetis\Queue\Console\WorkCommand` — the `queue:work [--queue=high,default]` command on `vendor/bin/kinetis`, registered through this package's `extra.kinetis` scan root. Constructor-injects `QueueInterface` (the `PackageBootstrap` binding, or the application's override) plus `Config` for `QUEUE_POLL_TIMEOUT` and `QUEUE_MAX_ATTEMPTS` (passed through as `QueueWorker`'s `$defaultMaxAttempts`, both defaulting to `5`/`0` respectively). Warns on STDERR at startup when `ext-pcntl` is missing, since graceful shutdown is impossible without it.
- `Kinetis\Queue\Console\StatsCommand` / `ClearCommand` — `queue:stats [--queue=high,default]` (waiting counts per queue, with a total) and `queue:clear --queue=<name> --force` (discards waiting jobs; refuses without `--force`, exit 1). Both drive the `QueueInterface` binding, so they report on whichever backend `QUEUE_CONNECTION` selects.
- Depends on `kinetis/framework` (via a `path` repository to this monorepo's root) plus `psr/log` (`QueueWorker`'s failure logging), `psr/container` (`JobInvoker`'s container parameter). No backend dependency at all — Redis, SQL, SQS, and RabbitMQ each live in their own separate package below. Own `composer.json`/`phpunit.xml`/`phpstan.neon`.

## `packages/queue-redis` (`kinetis/queue-redis`)

Separate Composer package, not part of `kinetis/framework` core.

- `Kinetis\QueueRedis\RedisQueue implements Kinetis\Queue\QueueInterface` — backed by `Amp\Redis\RedisClient`. Uses the "reliable queue" pattern (`popTailPushHeadBlocking()`, i.e. `BRPOPLPUSH`) rather than a plain destructive pop, moving a job to a separate processing list until `ack()`/`release()`; delayed jobs live in a sorted set scored by ready-at time, promoted in bounded batches (`DELAYED_PROMOTION_BATCH_SIZE`) once per `pop()` call, so a large ready backlog can't stall other Redis clients for one script's whole duration. `release()` (processing → pending) and delayed-job promotion (delayed → pending) both run as a single Lua script (`RedisClient::eval()`) rather than a remove-then-push pair of commands, so a process crash can never land between the two halves of either move; `release()`'s script is also conditional on actually having found and removed the source entry, so a duplicate call or a retry after an ambiguous connection failure throws `Exception\StaleJobHandleException` (which `QueueWorker` treats as benign) instead of enqueueing a second replacement. Every envelope carries a random `id` (and a `pushedAt` timestamp), generated fresh only on an independent `push()` — `release()` preserves the `id`/`pushedAt` it reads back off the envelope it's replacing, keeping the job's own logical identity and original enqueue time stable across retries. `id` is what keeps two byte-identical jobs from colliding into one member when both land in the delayed sorted set — sorted-set members are unique, plain strings are not. A job written by the envelope format that predates `id`/`pushedAt` is still release()-able after an upgrade: both fields are read optionally, falling through to a freshly generated value the first time such a job is released, rather than depending on a key that older format never wrote.
- `Kinetis\QueueRedis\RedisQueueFactory::fromConfig(Config $config, string $connectionName = 'default'): QueueInterface` — builds a `RedisQueue` from the same `REDIS_*` convention `RedisSimpleCache::buildRedisConfig()` reads; throws when neither `REDIS_URL` nor `REDIS_HOST` is set.
- `kinetis/queue`'s `QueueFactory` dispatches to this package for `QUEUE_CONNECTION=redis`.
- Depends on `kinetis/framework`, `kinetis/queue`, and `kinetis/cache-redis` (all via `path` repositories), plus `amphp/redis`. Own `composer.json`/`phpunit.xml`/`phpstan.neon`.

## `packages/queue-sql` (`kinetis/queue-sql`)

Separate Composer package, not part of `kinetis/framework` core.

- `Kinetis\QueueSql\SqlQueue implements Kinetis\Queue\QueueInterface` — backed by the generic `Kinetis\Persistence\Contract\SqlLink` (dialect-agnostic SQL, including priority ordering via `CASE queue WHEN ... END`). Dequeues via `SELECT ... FOR UPDATE SKIP LOCKED` inside a transaction; `pop()`'s blocking contract is a poll loop suspended with `Kinetis\Async\Timer::delay()`, since SQL has no native blocking-wait primitive. Requires the `kinetis_queue_jobs` table (with `queue`, `attempts`, `max_attempts` columns and a composite `(queue, available_at, reserved_at)` index) — see `resources/migrations/create_kinetis_queue_jobs_table.{mysql,pgsql}.php.stub`, not auto-created. `fail()` deletes the row, the same as `ack()`. Its second constructor argument, `$visibilityTimeoutSeconds` (default `null`, meaning never), reclaims a crashed worker's reserved row after that many seconds, incrementing `attempts` at that point.
- `Kinetis\QueueSql\SqlQueueFactory::fromConfig(Config $config, string $connectionName = 'default'): QueueInterface` — builds a `SqlQueue` from `SqlConnectionFactory::fromConfig()`'s result, reading the optional `QUEUE_VISIBILITY_TIMEOUT_SECONDS` (via `Config::scopedKey()`) for the second constructor argument — absent means `null`.
- `kinetis/queue`'s `QueueFactory` dispatches to this package for `QUEUE_CONNECTION=sql`.
- Depends on `kinetis/framework`, `kinetis/queue`, and `kinetis/persistence` (`SqlQueue`'s `TransactionGuard` use, `SqlConnectionFactory`) — all via `path` repositories. Own `composer.json`/`phpunit.xml`/`phpstan.neon`.

## `packages/queue-sqs` (`kinetis/queue-sqs`)

Separate Composer package, not part of `kinetis/framework` core.

- `Kinetis\QueueSqs\SqsQueue implements Kinetis\Queue\QueueInterface` — backed by `AsyncAws\Sqs\SqsClient`. `push()`/`pop()` map onto `SendMessage`/`ReceiveMessage`; `ack()`/`fail()` onto `DeleteMessage`; `release()` onto `ChangeMessageVisibility` with `VisibilityTimeout: 0` (immediately available again, rather than waiting out the normal timeout). A queue name resolves to an SQS queue of that name (optionally prefixed) via `GetQueueUrl`, cached per instance — never auto-created. `delaySeconds` uses SQS's own native `SendMessage` delay, capped at 900 seconds — a longer value throws before any network call. `QueuedJob::$attempts` comes directly from SQS's own `ApproximateReceiveCount` message attribute; `$maxAttempts` (no native SQS equivalent) travels as a custom `maxAttempts` message attribute; instrumentation propagation metadata travels the same way, as one JSON-encoded `metadata` attribute (see the telemetry package's `OtelTelemetry` above). `pop()`'s multi-queue priority cycling uses a short, fixed per-queue `WaitTimeSeconds` (SQS's own long-polling primitive, capped at 20 seconds) — no `Kinetis\Async\Timer::delay()` or `concurrently()` wrapper, since the injected `AmpHttpClient` transport tolerates being called from plain top-level code. Standard SQS queues only; FIFO is not supported.
- `Kinetis\QueueSqs\SqsClientFactory::fromConfig(Config $config, string $connection = 'default'): SqsClient` — builds `SqsClient` with `Kinetis\RevoltHttpClient\AmpHttpClientFactory::create()` injected as its transport. `QUEUE_SQS_REGION` required; `QUEUE_SQS_ENDPOINT`/`QUEUE_SQS_QUEUE_PREFIX` optional, all via `Config::scopedKey()`. Credentials are never read from `Kinetis\Config` — left to AsyncAws's own default credential provider chain.
- `Kinetis\QueueSqs\SqsQueueFactory::fromConfig(Config $config, string $connectionName = 'default'): QueueInterface` — the `class_exists()`-gated entry point `kinetis/queue`'s own `QueueFactory` calls: builds `SqsQueue` from `SqsClientFactory::fromConfig()` plus the optional `QUEUE_SQS_QUEUE_PREFIX`.
- `kinetis/queue`'s `QueueFactory` dispatches to this package for `QUEUE_CONNECTION=sqs`.
- Depends on `kinetis/framework`, `kinetis/queue`, and `kinetis/revolt-http-client` (all via `path` repositories), plus `async-aws/sqs`. Own `composer.json`/`phpunit.xml`/`phpstan.neon`.

## `packages/queue-rabbitmq` (`kinetis/queue-rabbitmq`)

Separate Composer package, not part of `kinetis/framework` core.

- `Kinetis\QueueRabbitMq\RabbitMqQueue implements Kinetis\Queue\QueueInterface` — backed by `Thesis\Amqp\Client`/`Channel`. A queue is declared durable on first touch by any method, never auto-created ahead of that. `push()` publishes to the queue directly; a delayed `push()` instead publishes to a dedicated `{queue}.delay` queue configured with `x-dead-letter-exchange`/`x-dead-letter-routing-key` pointing back at the real queue and a per-message `expiration` equal to the delay, so RabbitMQ itself moves the message once it expires — no polling-based promotion. `attempts`/`maxAttempts` travel as plain message headers (AMQP 0-9-1 has no native attempt count, only a boolean `redelivered` flag), and instrumentation propagation metadata as a JSON-encoded `metadata` header carried forward by `release()`; `release()` republishes with an incremented `attempts` header before discarding the original delivery via `nack(requeue: false)`, since `nack`'s own `requeue` flag redelivers the message unchanged. `QueuedJob::$handle` is the `Thesis\Amqp\DeliveryMessage` itself. `pop()`'s multi-queue priority cycling uses `basic.get` (a single, immediate, non-blocking request per queue — AMQP has no native blocking-wait-with-timeout primitive), sleeping via `Amp\delay()` between full sweeps when nothing is found. One channel per instance, opened lazily and reused. `Kinetis\Async\concurrently()` composes correctly with a still-open connection, confirmed against a real broker — `ConcurrentBatch` parks on a targeted Revolt suspension resumed once its own tasks finish, unaffected by `Thesis\Amqp\Channel`'s permanent background reader.
- `Kinetis\QueueRabbitMq\RabbitMqClientFactory::fromConfig(Config $config, string $connection = 'default'): Client` — builds `Thesis\Amqp\Client` from `Thesis\Amqp\Config::fromURI()`. `QUEUE_RABBITMQ_URL` required, via `Config::scopedKey()`.
- `Kinetis\QueueRabbitMq\RabbitMqQueueFactory::fromConfig(Config $config, string $connectionName = 'default'): QueueInterface` — the `class_exists()`-gated entry point `kinetis/queue`'s own `QueueFactory` calls: builds `RabbitMqQueue` from `RabbitMqClientFactory::fromConfig()` plus the optional `QUEUE_RABBITMQ_QUEUE_PREFIX`.
- `kinetis/queue`'s `QueueFactory` dispatches to this package for `QUEUE_CONNECTION=rabbitmq`.
- Depends on `kinetis/framework` and `kinetis/queue` (both via `path` repositories) plus `thesis/amqp`. Own `composer.json`/`phpunit.xml`/`phpstan.neon`.

## `packages/storage` (`kinetis/storage`)

Separate Composer package, not part of `kinetis/framework` core.

- `Kinetis\Storage\AmpFileAdapter` — a `League\Flysystem\FilesystemAdapter` for local disk backed by `Amp\File\Filesystem` instead of Flysystem's own local adapter, so every operation suspends the calling Fiber via Revolt rather than blocking the worker. `readStream()` is the one exception: it reads the whole file via the same non-blocking primitive, then buffers it into an in-memory `php://temp` resource, since a PHP `resource` can't lazily pull from a userland object without a registered stream wrapper. `write()`/`writeStream()`/`copy()` stream genuinely, via `Amp\ByteStream\pipe()` between real `Amp\File\File` handles. Rejects a symlink observed at check time: every path is checked component by component (`Amp\File\Filesystem::isSymlink()`, lstat semantics) before the real operation runs, and a discovered symlink throws `League\Flysystem\SymbolicLinkEncountered` rather than being resolved — a check-then-use guard, not a race-free one, so `FILESYSTEM_ROOT` is a real boundary only when this adapter is the sole writer to it; see {doc}`storage`'s "Symlink checks" section for the full threat model and the operational mitigation for a shared root. `deleteDirectory()` plans the whole subtree before deleting anything, so a symlink found partway through leaves nothing deleted rather than the entries visited earlier already gone.
- `Kinetis\Storage\PackageBootstrap` — declared via `extra.kinetis`; with `FILESYSTEM_DRIVER` set, lazily binds `League\Flysystem\FilesystemOperator` to `FilesystemFactory::fromConfig()`'s result before the application's own `bootstrap.php` runs (which wins on the same binding). Inert when `FILESYSTEM_DRIVER` is unset; named connections stay explicit app-side wiring.
- `Kinetis\Storage\FilesystemFactory::fromConfig(Config $config, string $connection = 'default'): League\Flysystem\Filesystem` — `FILESYSTEM_DRIVER` (default `'local'`) and `FILESYSTEM_ROOT` (required for the local driver), both via `Config::scopedKey()` for named connections. `FILESYSTEM_DRIVER=s3` dispatches to `packages/storage-s3` (below) if installed, else throws `Exception\StorageUnavailableException`.
- Depends on `kinetis/framework` (via a `path` repository), `league/flysystem`, `league/mime-type-detection` (`FinfoMimeTypeDetector`), `amphp/file`, `amphp/byte-stream` (`AmpFileAdapter`'s streaming `write()`/`writeStream()`/`copy()`, via `Amp\ByteStream\pipe()`). Own `composer.json`/`phpunit.xml`/`phpstan.neon`.

## `packages/revolt-http-client` (`kinetis/revolt-http-client`)

Separate Composer package, not part of `kinetis/framework` core — and,
unlike every other satellite package, not dependent on it either:
`kinetis/framework` appears only in `require-dev` (for tests and the
`NoStaticPropertiesRule` dogfooding), never in `require`. Genuinely
installable and usable with no Kinetis framework present at all.

- `Kinetis\RevoltHttpClient\Http` — the client application code uses. Immutable: `withBaseUrl()`/`withToken()`/`withBasicAuth()`/`withHeaders()`/`withQuery()`/`withTimeout()`/`withRetries()`/`asForm()` each return a new instance. `get()`/`post()`/`put()`/`patch()`/`delete()` take arrays (query for `get()`, JSON body for the rest); `send()` is the general form taking Symfony HttpClient options. Constructed with no argument it defaults to `AmpHttpClientFactory::create()`, so it autowires; pass any `HttpClientInterface` (Symfony's `MockHttpClient`, for one) to substitute the transport. `withRetries()` wraps the transport in Symfony's own `RetryableHttpClient` rather than hand-rolled retry logic.
- `Kinetis\RevoltHttpClient\HttpResponse` — `status()`/`successful()`/`failed()`/`clientError()`/`serverError()`/`body()`/`json()`/`jsonPath()`/`header()`. An error status is returned rather than thrown; `throw()` opts into raising `Exception\HttpRequestException` and returns the response otherwise, so it chains. `getMessage()` deliberately excludes the response body, the request URL's userinfo/query string, and any lower-level transport exception's own message — any of those could carry a secret (a signed URL's signature, an API key, PII in an upstream error body, a credential embedded in a transport client's own error text) that routine exception logging would otherwise leak; the full, unredacted detail is still reachable via `diagnosticUrl()`/`diagnosticBody()`/`diagnosticMessage()`/`getPrevious()`, but only by an explicit call — the first two are accessor *methods* over private fields, not public properties, so a generic serializer like `json_encode($e)` never exposes them either. A transport failure — no response at all — throws the same exception type with status `0`, so one catch covers everything the client throws. The body is read once and cached, and reading is deferred until asked for, which is what lets requests started inside `concurrently()` overlap.
- `Kinetis\RevoltHttpClient\AmpHttpClientFactory::create(array $defaultOptions = [], ?callable $clientConfigurator = null, int $maxHostConnections = 6, int $maxPendingPushes = 50): Symfony\Contracts\HttpClient\HttpClientInterface` — mirrors `Symfony\Component\HttpClient\AmpHttpClient`'s own constructor exactly, no Kinetis-specific defaults layered on top.
- Depends on `symfony/http-client` (`^8.0` — the first version whose `AmpHttpClient` targets the current, Revolt-based `amphp/http-client` generation rather than the old pre-Fiber one), `symfony/http-client-contracts`, and `amphp/http-client` (`^5.3`, an optional peer dependency of `symfony/http-client` that isn't auto-installed, so declared directly). Own `composer.json`/`phpunit.xml`/`phpstan.neon`.

## `packages/aws-sigv4` (`kinetis/aws-sigv4`)

Separate Composer package, not part of `kinetis/framework` core — and,
like `kinetis/revolt-http-client`, not dependent on it either:
`kinetis/framework` appears only in `require-dev`.

- `Kinetis\AwsSigV4\SigV4SigningClient implements Psr\Http\Client\ClientInterface` — the package's main class. Wraps another PSR-18 client and signs every request with AWS Signature Version 4 before delegating to it, reusing `AsyncAws\Core\Signer\SignerV4` directly (the same signer every AsyncAws service client already uses internally) rather than reimplementing the algorithm. Converts a PSR-7 request to `AsyncAws\Core\Request`, resolves credentials via `AsyncAws\Core\Credentials\ChainProvider::createDefaultChain()` (wrapped in `CacheProvider`) unless a `CredentialProvider` is passed directly, signs, and copies the resulting headers back onto a PSR-7 request. The constructor's own `?\DateTimeImmutable $now` parameter exists solely for testability (`sendRequest()`'s signature is fixed by the PSR-18 interface, so there's nowhere else to thread a fixed clock through) — real usage always leaves it `null`. Before signing, the request's body is always replaced with a `SpooledStream` (below) — sourced by rewinding-then-reading a seekable original body, or reading a non-seekable one from wherever it already is (seeking one backward is impossible by definition) — so neither the signature computation nor the wrapped client's own read ever has to seek the caller's original stream. A seekable original body's own cursor position is saved before reading and restored afterward (success or failure), since it's the same stream object the caller's own request was built with, not a private copy.
- `Kinetis\AwsSigV4\SpooledStream implements Psr\Http\Message\StreamInterface` — `@internal`, constructed only by `SigV4SigningClient` itself. A minimal, always-seekable PSR-7 stream over an already-in-memory string, backed by `php://temp` (in memory up to 2MB, then a real temp file) so this stream's own storage doesn't hold a second long-lived full copy of the body — it does not bound the *peak* memory a signed request costs, since the body is still read into a plain PHP string more than once along the way (once to build this stream, again to compute the signature); avoids this package taking on a full PSR-7 implementation as a runtime dependency either way.
- Its own test suite includes AWS's published "get-vanilla" SigV4 test vector (a fixed date and static test credentials, `AKIDEXAMPLE`) and matches the published expected `Authorization` header exactly, plus a non-seekable request body and a body past `php://temp`'s in-memory threshold, both signed and sent correctly, and a seekable body's own cursor position confirmed restored to exactly where it started after signing.
- Depends on `kinetis/revolt-http-client`, `async-aws/core`, `psr/http-client`, `psr/http-message`. Own `composer.json`/`phpunit.xml`/`phpstan.neon`.

## `packages/storage-s3` (`kinetis/storage-s3`)

Separate Composer package, not part of `kinetis/framework` core.

- `Kinetis\StorageS3\S3FilesystemFactory::fromConfig(Config $config, string $connection = 'default'): League\Flysystem\Filesystem` — builds `AsyncAws\S3\S3Client` with `Kinetis\RevoltHttpClient\AmpHttpClientFactory::create()` injected as its transport, wraps it in `League\Flysystem\AsyncAwsS3\AsyncAwsS3Adapter`. `FILESYSTEM_S3_BUCKET`/`FILESYSTEM_S3_REGION` required; `FILESYSTEM_S3_PREFIX`/`FILESYSTEM_S3_ENDPOINT`/`FILESYSTEM_S3_PATH_STYLE` optional, all via `Config::scopedKey()`. Credentials are never read from `Kinetis\Config` — left to `AsyncAws\Core\Configuration`'s own default credential provider chain.
- `kinetis/storage`'s own `Kinetis\Storage\FilesystemFactory` dispatches to this package for `FILESYSTEM_DRIVER=s3`, `class_exists()`-gated; throws `Kinetis\Storage\Exception\StorageUnavailableException` naming this package when it isn't installed.
- Depends on `kinetis/framework` and `kinetis/revolt-http-client` (both via `path` repositories), `async-aws/s3`, `league/flysystem-async-aws-s3`. Own `composer.json`/`phpunit.xml`/`phpstan.neon`.

## `packages/mailer` (`kinetis/mailer`)

Separate Composer package, not part of `kinetis/framework` core.

- `Kinetis\Mailer\PackageBootstrap` — declared via `extra.kinetis`; with `MAILER_DSN` set, lazily binds `Symfony\Component\Mailer\MailerInterface` to `MailerFactory::fromConfig()`'s result. Inert when `MAILER_DSN` is unset. The binding resolves in whichever process injects it, so a queued job's `handle()` gets it in the worker.
- `Kinetis\Mailer\MailerFactory::fromConfig(Config $config, string $connection = 'default'): Symfony\Component\Mailer\MailerInterface` — the only class in the package. Reads a single `MAILER_DSN` (`Config::scopedKey()` for named connections) and always passes `Kinetis\RevoltHttpClient\AmpHttpClientFactory::create()` into `Symfony\Component\Mailer\Transport::fromDsn()` as its `HttpClientInterface`. Genuinely non-blocking for any API-based transport (Sendgrid, Mailgun, Postmark, SES, ...) it resolves to; `EsmtpTransport` (SMTP) ignores the injected client and opens a raw, genuinely blocking socket regardless — a disclosed exception, not a bug.
- No Kinetis-owned `MailerInterface` — `Symfony\Component\Mailer\MailerInterface` is used directly, the same "don't wrap an already-right abstraction" reasoning `kinetis/storage` already applies to `League\Flysystem\FilesystemOperator`.
- `Transport::fromDsn()` discovers whichever bridge package (`symfony/sendgrid-mailer`, `symfony/mailgun-mailer`, ...) is actually installed via its own `class_exists()`-gated factory list — `MailerFactory` has no dispatch logic of its own.
- Mail is queueable with zero code in this package: a `kinetis/queue` `Job`'s own `handle()` method constructor-injects `MailerInterface` exactly like any other service, resolved through the same container `QueueWorker`/`SyncQueue` already autowire against.
- Depends on `kinetis/framework` and `kinetis/revolt-http-client` (both via `path` repositories), `symfony/mailer`. Own `composer.json`/`phpunit.xml`/`phpstan.neon`.

## `packages/search-opensearch` (`kinetis/search-opensearch`)

Separate Composer package, not part of `kinetis/framework` core.

- `Kinetis\SearchOpenSearch\PackageBootstrap` — declared via `extra.kinetis`; with `SEARCH_OPENSEARCH_HOST` set, lazily binds `OpenSearch\Client` to `OpenSearchClientFactory::fromConfig()`'s result. Inert when the key is unset; the concrete client is the binding id because opensearch-php exposes no interface for it.
- `Kinetis\SearchOpenSearch\OpenSearchClientFactory::fromConfig(Config $config, string $connection = 'default'): OpenSearch\Client` — the only class in the package. Builds the client through `OpenSearch\TransportFactory::setHttpClient()` (a real PSR-18 injection point, part of the library's own non-deprecated construction path — the older `ClientBuilder`/`Transport`/`ConnectionPool` stack is deprecated since 2.4.0 and has no such injection point) with a `Symfony\Component\HttpClient\Psr18Client` wrapping `Kinetis\RevoltHttpClient\AmpHttpClientFactory::create()` as the client.
- No Kinetis-owned client interface — the real `OpenSearch\Client` is returned directly.
- `SEARCH_OPENSEARCH_HOST` is a single base URI; `SEARCH_OPENSEARCH_USERNAME`/`SEARCH_OPENSEARCH_PASSWORD` (Basic auth) and `SEARCH_OPENSEARCH_VERIFY_PEER` (default `true`) are optional, all via `Config::scopedKey()` for named connections.
- Depends on `kinetis/framework` and `kinetis/revolt-http-client` (both via `path` repositories), `opensearch-project/opensearch-php`, `symfony/http-client`. Own `composer.json`/`phpunit.xml`/`phpstan.neon`.

## `packages/telemetry` (`kinetis/telemetry`)

Separate Composer package, not part of `kinetis/framework` core.
Participates in `extra.kinetis`: a scan root covering
`Kinetis\Telemetry\Middleware\` (so `RequestSpanMiddleware` is
discovered as global middleware on install) and a `PackageBootstrap`.

- `Kinetis\Telemetry\PackageBootstrap` — binds
  `OpenTelemetry\API\Trace\TracerProviderInterface` on `AppScope`: the
  OTLP-exporting provider when `OTEL_EXPORTER_OTLP_ENDPOINT` is set, a
  `NoopTracerProvider` otherwise. Also replaces OTel's fiber-bound
  default context storage with the shared `ContextStorage` — Kinetis
  Fibers are scheduling units within one request, not independent
  execution contexts, and the swap is what lets a span begun by the
  middleware parent spans created inside `concurrently()` tasks.
  Registers the provider's `shutdown()` via
  `register_shutdown_function` — request end under boot-and-die,
  worker exit under a persistent runtime, so both shapes flush.
- `Kinetis\Telemetry\TracerFactory::fromConfig(Config): ?TracerProvider` —
  a `BatchSpanProcessor` over the OTLP/HTTP exporter, whose transport
  is `Symfony\Component\HttpClient\Psr18Client` wrapping
  `AmpHttpClientFactory::create()`, so span export suspends rather
  than blocks. `null` when no endpoint is configured.
- `Kinetis\Telemetry\Middleware\RequestSpanMiddleware` —
  `#[AsGlobalMiddleware(priority: 90)]`, a server span per request:
  method as the span name (route templates aren't visible to global
  middleware and raw paths would explode name cardinality), `url.path`,
  `http.response.status_code`, `php.memory.usage`, error status on 5xx
  or an exception, `traceparent` extraction for distributed traces. The
  span is active while the handler runs — the parent for everything
  below.
- `Kinetis\Telemetry\Persistence\TracingMysqlLink`/`TracingPostgresLink`
  (and the `TracingMysqlTransaction`/`TracingPostgresTransaction` their
  `beginTransaction()` hands back, plus the `TracingSqlLinkBase`/
  `TracingSqlTransactionBase` abstract bases) — a client span per
  `query()`/`execute()` named by the SQL's first keyword, `db.system.name`
  and `db.query.text` attributes, bound parameter values deliberately
  never recorded. `COMMIT`/`ROLLBACK` spanned too. Each decorator
  implements its dialect marker, so query-builder dialect detection is
  unaffected. Query spans are never activated — they read the current
  context as parent and end immediately, so concurrent queries can't
  interleave anyone's scope stack.
- `Kinetis\Telemetry\Queue\TracingQueue` — wraps any `QueueInterface`.
  `push()` gets a producer span; a consumer span opens at `pop()` and
  closes at `ack()`/`release()`/`fail()` (tracked via a
  `WeakMap<QueuedJob, ...>`), carrying `kinetis.job.class`/`attempt`/
  `outcome`, error status on `fail()`. Active while the job runs, so
  the job's own spans nest under it. Producer and consumer spans are
  separate traces — linking them needs context in the payload, which a
  decorator can't reach; a disclosed gap.
- `Kinetis\Telemetry\HttpClient\TracingHttpClient`/`TracingResponse` —
  a client span per outgoing request with `traceparent` injection
  (appended in Symfony's `"Name: value"` string form, coexisting with
  any existing header shape). The span ends when the response is
  consumed — `getContent()`/`toArray()`, an error, `cancel()`, or
  destruct as the safety net — never when `request()` returns, since
  requests through this transport complete later by design.
  `stream()` unwraps to the inner client's own responses (Symfony
  clients only stream responses they created), so stream consumers get
  destruct-time span timing.
- `Kinetis\Telemetry\Logging\TraceAwareLogger` — PSR-3 decorator adding
  `trace_id`/`span_id` to entry context when a span is recording;
  caller-supplied keys win.
- `Kinetis\Telemetry\Instrumentation\OtelTelemetry` — implements core's
  `Kinetis\Instrumentation\TelemetryInterface`, turning the framework's
  hooks into spans; `PackageBootstrap` swaps it into
  `Telemetry::global()` whenever the OTLP endpoint is configured. Which
  hooks *activate* their span (parenting whatever starts next) is the
  load-bearing choice: only strictly-nested single-fiber pairs do —
  middleware, controller, event/listener, the `concurrently()` batch,
  MCP tool calls, worker jobs. Query and per-task spans never activate:
  they can overlap across fibers on the shared context, and activating
  them would interleave the scope stack. `jobPushMetadata()` injects a
  `traceparent` carrier the backend stores with the job;
  `jobStarted()` extracts it, parenting the consumer span into the
  producer's trace — one trace across processes.
- Depends on `kinetis/framework`, `kinetis/revolt-http-client`,
  `open-telemetry/sdk`, `open-telemetry/exporter-otlp`,
  `symfony/http-client`, `nyholm/psr7`, `psr/log`;
  `kinetis/persistence`/`kinetis/queue` only in `require-dev` — the
  decorators' classes load lazily, so neither is forced on an install
  that only wants request spans. Own
  `composer.json`/`phpunit.xml`/`phpstan.neon`.

## `packages/auth` (`kinetis/auth`)

Separate Composer package, not part of `kinetis/framework` core.

- `Kinetis\Auth\BearerAuthMiddleware` — PSR-15 route middleware (never global) validating an `Authorization: Bearer <token>` header against an app-supplied `UserProviderInterface`, registering the resolved user on the current `RequestScope` as `CurrentUserInterface` on success, or returning `401` with a `WWW-Authenticate: Bearer` header on failure. Resolved fresh per request from the route's own `RequestScope`, so it constructor-injects `RequestScope` directly.
- `Kinetis\Auth\UserProviderInterface` — one method, `findByToken(string $token): ?CurrentUserInterface`. Storage-agnostic; the app implements it.
- `Kinetis\Auth\TokenGenerator` — `generate(int $bytes = 32): string`, a `random_bytes()` wrapper, hex-encoded.
- Depends on `kinetis/framework` (via a `path` repository to this monorepo's root), `nyholm/psr7` (`BearerAuthMiddleware`'s `401` response), `psr/http-message`, `psr/http-server-middleware`. Own `composer.json`/`phpunit.xml`/`phpstan.neon`.

## `packages/auth-jwt` (`kinetis/auth-jwt`)

Separate Composer package, not part of `kinetis/framework` core.

- `Kinetis\AuthJwt\JwtAuthMiddleware` — PSR-15 route middleware (never global) verifying an `Authorization: Bearer <token>` header's signature via `firebase/php-jwt`, registering the decoded claims as a `JwtUser` (`CurrentUserInterface`) on success, or returning `401` with `WWW-Authenticate: Bearer` on failure — a decode exception, a structurally valid token with no `sub` claim, and a revoked token (checked against the optional `RevocationStore`) are all treated identically. `$key` is the shared secret for `HS256`/`HS384`/`HS512`, the *public* half of a key pair (PEM string) for `RS256`/`RS384`/`RS512` — `JwtIssuer` takes the matching *private* half — or an `array<string, Firebase\JWT\Key>` map keyed by `kid`, for verifying against more than one key at once during a rotation; a plain string keeps working unchanged. Deliberately not `final`: `#[Middleware(...)]` carries only a class-string, with nowhere to pass a key, so a subclass supplying it via a constructor of only class-typed parameters is the documented pattern.
- `Kinetis\AuthJwt\JwtUser` — wraps the decoded claims (`stdClass`). `id()` reads `sub`, throwing if it's missing or non-scalar; `claim(string)`/`claims()` expose the rest.
- `Kinetis\AuthJwt\JwtIssuer` — `issue(string|int $subject, array $claims = [], ?int $ttlSeconds = 3600): string`, signing with the same key/algorithm `JwtAuthMiddleware` verifies against. `sub`/`iat`/`exp`/`jti` (a random unique token ID) always win over a same-named entry in `$claims`. An optional constructor `$kid` is written into the token's own header, for `JwtAuthMiddleware`'s multi-key `$key` map to select against.
- `Kinetis\AuthJwt\RevocationStore` — a `Psr\SimpleCache\CacheInterface`-backed denylist. Per-token: `revoke(string $jti, int $ttlSeconds)` is the primitive; `revokeToken(JwtUser $user)` derives the TTL from the token's own `exp` claim automatically. Per-user ("log out everywhere"): `revokeAllForUser(string|int $userId, int $ttlSeconds)` stores an inclusive `iat` cutoff; `isRevokedForUser()` compares a token's own `iat` against it. Requires a real cache — construction over `NullSimpleCache` throws `Exception\RevocationUnavailableException`, since a denylist that never stores anything would let every revoked token stay valid until natural expiry.
- `Kinetis\AuthJwt\RefreshTokenStore` — a `Psr\SimpleCache\CacheInterface`-backed, single-use opaque refresh token, independent of `RevocationStore`. `issue(string|int $subject, array $claims = [], int $ttlSeconds = 1_209_600): string` stores `sha256(token) => {subject, claims, issuedAt}`; `redeem(string $token): ?array` atomically reads and deletes the entry the moment it's looked up (valid or not, via `Kinetis\SimpleCache\AtomicConsumeInterface::consume()`) and returns `{subject, claims}` or `null`. `revoke(string $token): void` invalidates one token directly. `revokeAllForUser(string|int $userId, int $ttlSeconds): void` stores a per-subject cutoff timestamp (the same mechanism `RevocationStore::revokeAllForUser()` uses) rather than an enumerated list — `redeem()` checks a token's own `issuedAt` against its subject's latest cutoff, inclusive. Construction throws `Exception\RefreshTokenUnavailableException` over `NullSimpleCache` (same as `RevocationStore`) or over any cache not implementing `AtomicConsumeInterface` — a `get()` then a separate `delete()` would let two concurrent redeems of the same token both succeed.
- `Kinetis\AuthJwt\JwkSet::fromRsaPublicKeys(array $publicKeysByKid, string $algorithm = 'RS256'): array` — builds an RFC 7517 JWK Set (`{"keys": [...]}`) from one or more PEM-format RSA public keys via `openssl_pkey_get_public()`/`openssl_pkey_get_details()`, base64url-encoding the modulus/exponent. RSA only; throws `Exception\JwkSetException` for an invalid PEM or a non-RSA key.
- Depends on `kinetis/framework` (via a `path` repository to this monorepo's root), `firebase/php-jwt` (`^7.1` — `6.10`/`6.11` are excluded by an open security advisory), `psr/simple-cache` (`RevocationStore`/`RefreshTokenStore`), `ext-openssl` (`JwkSet`), `nyholm/psr7`, `psr/http-message`, `psr/http-server-middleware`. Own `composer.json`/`phpunit.xml`/`phpstan.neon`.

## `packages/session` (`kinetis/session`)

Separate Composer package, not part of `kinetis/framework` core.
Participates in `extra.kinetis` with a `PackageBootstrap` plus a scan
root covering `Kinetis\Session\Console` (the `session:gc` command);
both middlewares are explicit per-route opt-ins.

- `Kinetis\Session\SessionStoreInterface` — `read(id): ?array` / `write(id, data, lifetimeSeconds)` / `destroy(id)`. Payloads are JSON-serialized `array<string, mixed>`, never PHP `serialize()`; expiry is the store's own job; concurrency is declared last-write-wins — no locking, deliberately, since serializing a browser's parallel requests would fight the concurrent-worker model.
- `Kinetis\Session\GarbageCollectableStoreInterface` — `gc(): int`, deleting every expired session and returning the count. Implemented by the file and sql stores; the cache store leaves it out because its backend expires entries itself.
- `Kinetis\Session\Console\GcCommand` — the `session:gc` command on `vendor/bin/kinetis`. Calls `gc()` on the bound store and prints the count; for a store without `GarbageCollectableStoreInterface` it reports that the backend expires entries on its own and exits `0`; with no store bound at all it exits `1` naming `SESSION_DRIVER`. Nothing schedules it — cron or an equivalent does.
- `Kinetis\Session\Session` — what a controller constructor-injects (registered on the RequestScope by the middleware). `get`/`set`/`has`/`remove`/`all`, `flash()`/`flashed()` (survives exactly one following request, aged at commit), `csrfToken()` (generated on first use, stored in the session), `regenerate()` (fresh id, same data, old payload destroyed — the fixation defense), `destroy()`. Lazy: the store isn't read until first access, and `commit()` writes only when something changed — an untouched session costs no round trip and no cookie.
- `Kinetis\Session\Store\FileSessionStore` — one JSON file per session (`sess_{id}`), expiry embedded as a timestamp; an expired file is deleted when next read, and `gc()` sweeps the rest for `session:gc`. Validates ids against `^[a-f0-9]{32}$` before building any path — defense in depth against traversal even though the middleware validates first.
- `Kinetis\Session\Store\CacheSessionStore` — over PSR-16, the backend's TTL as expiry; rejects `NullSimpleCache` at construction (a store that never stores means logins that silently don't stick). Redis sessions are this store plus the `CacheInterface` binding `kinetis/cache-redis` already provides.
- `Kinetis\Session\Store\SqlSessionStore` — `kinetis_sessions` (id/payload/expires_at) over the generic `SqlLink` contract; dialect-agnostic SQL. The upsert is UPDATE-then-INSERT with a catch-and-re-UPDATE on a primary-key collision — surviving both MySQL's 0-affected-rows-on-identical-values report and racing first-writes. Expired rows stay until `gc()` (the `session:gc` command) deletes them. Migration stubs in `resources/migrations/`, never auto-created.
- `Kinetis\Session\Middleware\SessionMiddleware` — route middleware only (the `BearerAuthMiddleware` structural rule): reads the cookie (id validated, tampered values get a fresh session), registers a lazy `Session` on the scope, and afterwards commits + sets the cookie only when needed. Cookie: `HttpOnly` always, `Path=/`, no `Domain`, `Secure`/`SameSite`/name/lifetime from `SESSION_*` config. Validates the configured name at construction: it must be a legal cookie token, and a `__Host-`/`__Secure-` prefix (matched case-sensitively) requires `SESSION_SECURE` — a browser drops such a cookie silently, which presents as sessions that never persist. `SESSION_SAMESITE` is validated there too: `Strict`, `Lax`, or `None` matched case-insensitively and normalised to that casing in the header, with `None` requiring `SESSION_SECURE` for the same reason. Reads `cookieParams` first with the raw `Cookie` header as fallback, so `TestClient`-built requests work by setting the header.
- `Kinetis\Session\Middleware\CsrfMiddleware` — synchronizer-token check on non-GET/HEAD/OPTIONS, via `X-CSRF-Token` header or a form body's `_token`, `hash_equals()` comparison, `403` on mismatch; a missing upstream `SessionMiddleware` is a distinct `500` naming the declaration-order mistake. JSON bodies use the header — the dispatcher decodes JSON itself, so `getParsedBody()` never carries `_token` for them.
- `Kinetis\Session\PackageBootstrap` — with `SESSION_DRIVER` set, binds `SessionStoreInterface` as a lazy factory (resolved on first use, after `boot()` and every sibling bootstrap have run — which is what lets the `cache` driver consume the boot-time `CacheInterface` binding and the `sql` driver consume persistence's link binding regardless of bootstrap order). Unknown driver throws naming the valid set; `sql` without kinetis/persistence installed, or with no link bound, throws naming the fix.
- Depends on `kinetis/framework`, `psr/simple-cache`, `psr/http-message`, `psr/http-server-middleware`; `kinetis/persistence`/`kinetis/cache-redis` only in `require-dev` — store classes load lazily. Own `composer.json`/`phpunit.xml`/`phpstan.neon`.

## See also

- {doc}`appendix` — the same reference map for core (`kinetis/framework`).
- {doc}`appendix-ci` — what actually runs in CI, including the
  real-backend integration checks for several packages listed above.
- {doc}`appendix-contributing` — the monorepo layout, dev environment
  setup, and the manifest-driven tooling for changing a package's
  dependencies.
- {doc}`migrations`, {doc}`query-builder`, {doc}`queue`, {doc}`queue-redis`,
  {doc}`queue-sql`, {doc}`queue-sqs`, {doc}`queue-rabbitmq`, {doc}`storage`,
  {doc}`storage-s3`, {doc}`revolt-http-client`, {doc}`aws-sigv4`,
  {doc}`mailer`, {doc}`search-opensearch`, {doc}`auth`, {doc}`auth-jwt` —
  the task-oriented page for each package above.