From 9bbc4e21421137805399482afb10b973997cfd3b Mon Sep 17 00:00:00 2001
From: Gustavo Freze <gustavo.freze@outlook.com>
Date: Fri, 26 Jun 2026 18:09:32 -0300
Subject: [PATCH] feat: Add PSR-15 error-handling middleware.

---
 .claude/hooks/php-ordering-conformance.py     | 607 +++++++++++
 .../php-prose-punctuation-conformance.py      | 176 ++++
 .claude/rules/php-library-architecture.md     | 147 +++
 .claude/rules/php-library-code-style.md       | 960 ++++++++++++++++++
 .claude/rules/php-library-documentation.md    | 203 ++++
 .claude/rules/php-library-github-workflows.md | 104 ++
 .claude/rules/php-library-modeling.md         | 314 ++++++
 .claude/rules/php-library-testing.md          | 372 +++++++
 .claude/rules/php-library-tooling.md          | 138 +++
 .claude/settings.json                         | 249 +++++
 .claude/skills/commit-message/SKILL.md        | 119 +++
 .claude/skills/tiny-blocks-consume/SKILL.md   |  68 ++
 .../tiny-blocks-consume/references/catalog.md |  32 +
 .../scripts/refresh-catalog.py                | 102 ++
 .claude/skills/tiny-blocks-create/SKILL.md    | 158 +++
 .../assets/config/.editorconfig               |  19 +
 .../assets/config/.gitattributes              |  19 +
 .../assets/config/.gitignore                  |  28 +
 .../tiny-blocks-create/assets/config/Makefile |  74 ++
 .../assets/config/composer.json               |  70 ++
 .../assets/config/infection.json.dist         |  23 +
 .../assets/config/phpcs.xml                   |   7 +
 .../assets/config/phpstan.neon.dist           |   6 +
 .../assets/config/phpunit.xml                 |  39 +
 .../assets/docs/SECURITY.md                   |  12 +
 .../github/ISSUE_TEMPLATE/bug_report.md       |  29 +
 .../github/ISSUE_TEMPLATE/feature_request.md  |  17 +
 .../assets/github/PULL_REQUEST_TEMPLATE.md    |  16 +
 .../assets/github/workflows/ci.yml            | 105 ++
 .editorconfig                                 |  19 +
 .gitattributes                                |  19 +
 .github/ISSUE_TEMPLATE/bug_report.md          |  29 +
 .github/ISSUE_TEMPLATE/feature_request.md     |  17 +
 .github/PULL_REQUEST_TEMPLATE.md              |  16 +
 .github/copilot-instructions.md               |  12 +
 .github/dependabot.yml                        |  31 +
 .github/workflows/auto-assign.yml             |  32 +
 .github/workflows/ci.yml                      | 105 ++
 .github/workflows/codeql.yml                  |  39 +
 .gitignore                                    |  28 +
 CLAUDE.md                                     |  61 ++
 Makefile                                      |  74 ++
 README.md                                     | 205 ++++
 SECURITY.md                                   |  12 +
 composer.json                                 |  81 ++
 infection.json.dist                           |  23 +
 phpcs.xml                                     |   7 +
 phpstan.neon.dist                             |  34 +
 phpunit.xml                                   |  39 +
 src/ErrorHandlingSettings.php                 |  53 +
 src/ErrorMiddleware.php                       |  71 ++
 src/ExceptionMapping.php                      |  22 +
 src/ExceptionMappingRule.php                  |  69 ++
 src/ExceptionMappingTable.php                 | 121 +++
 src/Exceptions/HttpStatusOutOfRange.php       |  14 +
 src/Internal/AnyExactClassMatcher.php         |  19 +
 src/Internal/DynamicMappedErrorResolver.php   |  21 +
 src/Internal/ErrorLogger.php                  |  43 +
 src/Internal/ErrorMiddlewareBuilder.php       |  79 ++
 src/Internal/ErrorOutcome.php                 |  37 +
 src/Internal/ExactClassMatcher.php            |  19 +
 src/Internal/ExceptionMatcher.php             |  21 +
 .../Exceptions/MappingNotConfigured.php       |  11 +
 src/Internal/FallbackResponse.php             |  45 +
 src/Internal/FixedMappedErrorResolver.php     |  20 +
 src/Internal/MappedErrorResolver.php          |  22 +
 src/Internal/MappedResponse.php               |  36 +
 src/Internal/MappingEntry.php                 |  24 +
 src/Internal/SubclassMatcher.php              |  19 +
 src/MappedError.php                           |  31 +
 tests/Unit/CapturingHandler.php               |  30 +
 tests/Unit/ErrorMiddlewareTest.php            | 640 ++++++++++++
 tests/Unit/ExceptionMappingRuleTest.php       | 103 ++
 tests/Unit/ExceptionMappingTableTest.php      | 255 +++++
 .../Internal/AnyExactClassMatcherTest.php     |  62 ++
 .../DynamicMappedErrorResolverTest.php        |  58 ++
 tests/Unit/Internal/ExactClassMatcherTest.php |  63 ++
 .../Internal/FixedMappedErrorResolverTest.php |  44 +
 tests/Unit/Internal/MappingEntryTest.php      |  77 ++
 tests/Unit/Internal/SubclassMatcherTest.php   |  50 +
 tests/Unit/MappedErrorTest.php                |  94 ++
 tests/Unit/UnmappedExceptions.php             |  16 +
 82 files changed, 7385 insertions(+)
 create mode 100644 .claude/hooks/php-ordering-conformance.py
 create mode 100644 .claude/hooks/php-prose-punctuation-conformance.py
 create mode 100644 .claude/rules/php-library-architecture.md
 create mode 100644 .claude/rules/php-library-code-style.md
 create mode 100644 .claude/rules/php-library-documentation.md
 create mode 100644 .claude/rules/php-library-github-workflows.md
 create mode 100644 .claude/rules/php-library-modeling.md
 create mode 100644 .claude/rules/php-library-testing.md
 create mode 100644 .claude/rules/php-library-tooling.md
 create mode 100644 .claude/settings.json
 create mode 100644 .claude/skills/commit-message/SKILL.md
 create mode 100644 .claude/skills/tiny-blocks-consume/SKILL.md
 create mode 100644 .claude/skills/tiny-blocks-consume/references/catalog.md
 create mode 100644 .claude/skills/tiny-blocks-consume/scripts/refresh-catalog.py
 create mode 100644 .claude/skills/tiny-blocks-create/SKILL.md
 create mode 100644 .claude/skills/tiny-blocks-create/assets/config/.editorconfig
 create mode 100644 .claude/skills/tiny-blocks-create/assets/config/.gitattributes
 create mode 100644 .claude/skills/tiny-blocks-create/assets/config/.gitignore
 create mode 100644 .claude/skills/tiny-blocks-create/assets/config/Makefile
 create mode 100644 .claude/skills/tiny-blocks-create/assets/config/composer.json
 create mode 100644 .claude/skills/tiny-blocks-create/assets/config/infection.json.dist
 create mode 100644 .claude/skills/tiny-blocks-create/assets/config/phpcs.xml
 create mode 100644 .claude/skills/tiny-blocks-create/assets/config/phpstan.neon.dist
 create mode 100644 .claude/skills/tiny-blocks-create/assets/config/phpunit.xml
 create mode 100644 .claude/skills/tiny-blocks-create/assets/docs/SECURITY.md
 create mode 100644 .claude/skills/tiny-blocks-create/assets/github/ISSUE_TEMPLATE/bug_report.md
 create mode 100644 .claude/skills/tiny-blocks-create/assets/github/ISSUE_TEMPLATE/feature_request.md
 create mode 100644 .claude/skills/tiny-blocks-create/assets/github/PULL_REQUEST_TEMPLATE.md
 create mode 100644 .claude/skills/tiny-blocks-create/assets/github/workflows/ci.yml
 create mode 100644 .editorconfig
 create mode 100644 .gitattributes
 create mode 100644 .github/ISSUE_TEMPLATE/bug_report.md
 create mode 100644 .github/ISSUE_TEMPLATE/feature_request.md
 create mode 100644 .github/PULL_REQUEST_TEMPLATE.md
 create mode 100644 .github/copilot-instructions.md
 create mode 100644 .github/dependabot.yml
 create mode 100644 .github/workflows/auto-assign.yml
 create mode 100644 .github/workflows/ci.yml
 create mode 100644 .github/workflows/codeql.yml
 create mode 100644 .gitignore
 create mode 100644 CLAUDE.md
 create mode 100644 Makefile
 create mode 100644 README.md
 create mode 100644 SECURITY.md
 create mode 100644 composer.json
 create mode 100644 infection.json.dist
 create mode 100644 phpcs.xml
 create mode 100644 phpstan.neon.dist
 create mode 100644 phpunit.xml
 create mode 100644 src/ErrorHandlingSettings.php
 create mode 100644 src/ErrorMiddleware.php
 create mode 100644 src/ExceptionMapping.php
 create mode 100644 src/ExceptionMappingRule.php
 create mode 100644 src/ExceptionMappingTable.php
 create mode 100644 src/Exceptions/HttpStatusOutOfRange.php
 create mode 100644 src/Internal/AnyExactClassMatcher.php
 create mode 100644 src/Internal/DynamicMappedErrorResolver.php
 create mode 100644 src/Internal/ErrorLogger.php
 create mode 100644 src/Internal/ErrorMiddlewareBuilder.php
 create mode 100644 src/Internal/ErrorOutcome.php
 create mode 100644 src/Internal/ExactClassMatcher.php
 create mode 100644 src/Internal/ExceptionMatcher.php
 create mode 100644 src/Internal/Exceptions/MappingNotConfigured.php
 create mode 100644 src/Internal/FallbackResponse.php
 create mode 100644 src/Internal/FixedMappedErrorResolver.php
 create mode 100644 src/Internal/MappedErrorResolver.php
 create mode 100644 src/Internal/MappedResponse.php
 create mode 100644 src/Internal/MappingEntry.php
 create mode 100644 src/Internal/SubclassMatcher.php
 create mode 100644 src/MappedError.php
 create mode 100644 tests/Unit/CapturingHandler.php
 create mode 100644 tests/Unit/ErrorMiddlewareTest.php
 create mode 100644 tests/Unit/ExceptionMappingRuleTest.php
 create mode 100644 tests/Unit/ExceptionMappingTableTest.php
 create mode 100644 tests/Unit/Internal/AnyExactClassMatcherTest.php
 create mode 100644 tests/Unit/Internal/DynamicMappedErrorResolverTest.php
 create mode 100644 tests/Unit/Internal/ExactClassMatcherTest.php
 create mode 100644 tests/Unit/Internal/FixedMappedErrorResolverTest.php
 create mode 100644 tests/Unit/Internal/MappingEntryTest.php
 create mode 100644 tests/Unit/Internal/SubclassMatcherTest.php
 create mode 100644 tests/Unit/MappedErrorTest.php
 create mode 100644 tests/Unit/UnmappedExceptions.php

diff --git a/.claude/hooks/php-ordering-conformance.py b/.claude/hooks/php-ordering-conformance.py
new file mode 100644
index 0000000..21a3ec0
--- /dev/null
+++ b/.claude/hooks/php-ordering-conformance.py
@@ -0,0 +1,607 @@
+#!/usr/bin/env python3
+"""PHP ordering conformance hook for tiny-blocks PHP libraries.
+
+Self-contained PostToolUse hook on Edit|Write|MultiEdit. Verifies the deterministic
+ordering conventions for PHP declarations:
+
+- Parameter ordering: declaration parameters (constructors, factories, methods,
+  property promotion) in three tiers, required parameters first, then defaulted
+  parameters, then a variadic, each tier by identifier length ascending,
+  alphabetical tie-breaker, semantic pairs preserved. A PHPUnit test method fed by
+  a data provider is exempt, its parameters are the columns of its data set.
+- Member ordering: constants, enum cases, constructor, static methods, instance
+  methods, in that group order, each group length-ascending with alphabetical
+  tie-breaker. PHPUnit test classes instead order methods as lifecycle hooks (in
+  execution order), then other methods, then data providers.
+
+The analysis is pure (FileUnit in, Violation out) and runs in three passes over
+well-formed PHP: a lexical pass blanks every comment, string, and heredoc/nowdoc
+body (LITERALS), a structural pass maps every bracket to its pair (bracket_spans);
+extraction assigns tokens of interest to their containers by flat walks. Control
+flow uses guard clauses only and nesting never exceeds two levels. Reports
+violations to stderr and exits 2 to prompt Claude, exits 0 silently if no violations
+or the file is out of scope.
+"""
+
+import json
+import re
+import sys
+from dataclasses import dataclass
+from enum import Enum
+from functools import cached_property
+from pathlib import Path
+from typing import Final
+
+# --- Configuration ----------------------------------------------------------
+
+# In-scope files: PHP sources under src/ or tests/.
+SCOPE_PATTERN: Final = re.compile(r"(^|/)(src|tests)/.+\.php$")
+
+# Semantic pairs (exhaustive). Natural order wins between
+# the two members when both appear in the same parameter list.
+SEMANTIC_PAIRS: Final = (
+    ("start", "end"),
+    ("from", "to"),
+    ("startAt", "endAt"),
+    ("createdAt", "updatedAt"),
+    ("before", "after"),
+    ("min", "max"),
+)
+
+# Each member maps to (first, second, position). Both members keep their natural
+# order only when both are present, sorting as a unit at the lead member's key.
+PAIR_MEMBER: Final = {
+    member: (first, second, position)
+    for first, second in SEMANTIC_PAIRS
+    for position, member in enumerate((first, second))
+}
+
+MODIFIERS: Final = ("abstract", "final", "private", "protected", "public", "static")
+
+# The lexical grammar: every PHP construct that must not be scanned as code.
+# Alternatives are ordered, the heredoc label closes via backreference.
+LITERALS: Final = re.compile(
+    r"""
+      /\*.*?\*/                                  # block comment
+    | //[^\n]*                                   # line comment
+    | \#(?!\[)[^\n]*                             # hash comment, never a #[ attribute
+    | <<<[ \t]*(?P<quote>['"]?)(?P<label>\w+)(?P=quote)[^\n]*\n
+      .*?\n[ \t]*(?P=label)\b                    # heredoc and nowdoc body
+    | '(?:\\.|[^'\\])*'                          # single-quoted string
+    | "(?:\\.|[^"\\])*"                          # double-quoted string
+    """,
+    re.DOTALL | re.MULTILINE | re.VERBOSE,
+)
+
+TYPE_DECLARATION: Final = re.compile(
+    r"^[ \t]*(?:(?:abstract|final|readonly)\s+)*(class|interface|trait|enum)\s+(\w+)",
+    re.MULTILINE,
+)
+FUNCTION_DECLARATION: Final = re.compile(r"\bfunction\s+&?(\w+)\s*\(")
+METHOD_LINE: Final = re.compile(
+    rf"^\s*((?:(?:{'|'.join(MODIFIERS)})\s+)+)function\s+&?(\w+)\s*\("
+)
+CONST_LINE: Final = re.compile(
+    r"^\s*(?:(?:final|private|protected|public)\s+)*const\s+(?:[?\w|&()\s]+\s)?(\w+)\s*="
+)
+CASE_LINE: Final = re.compile(r"^\s*case\s+(\w+)\s*[=;]")
+
+PARAMETER: Final = re.compile(r"\$(\w+)")
+VARIADIC: Final = re.compile(r"\.\.\.\s*\$")
+# A default assignment is a lone `=`, never `=>` in an array or arrow function,
+# never a comparison (`==`, `!=`, `<=`, `>=`).
+DEFAULT_ASSIGNMENT: Final = re.compile(r"(?<![=!<>])=(?![=>])")
+
+# PHPUnit lifecycle hooks in fixed execution order, with detection patterns for a
+# test class and for the data providers its methods reference.
+LIFECYCLE_ORDER: Final = ("setUpBeforeClass", "setUp", "tearDown", "tearDownAfterClass")
+LIFECYCLE_HOOKS: Final = frozenset(LIFECYCLE_ORDER)
+EXTENDS_TESTCASE: Final = re.compile(r"\bextends\s+\\?(?:\w+\\)*TestCase\b")
+DATA_PROVIDER_REFERENCE: Final = re.compile(
+    r"#\[\s*(?:\\?\w+\\)*DataProvider\s*\(\s*['\"](\w+)['\"]"
+    r"|@dataProvider\s+(\w+)"
+)
+
+MAX_ERRORS_REPORTED = 30
+
+
+# --- Types --------------------------------------------------------------------
+
+
+@dataclass(frozen=True)
+class Violation:
+    """One style violation at a source position."""
+
+    line: int
+    path: str
+    message: str
+
+    def __str__(self) -> str:
+        return f"{self.path}:{self.line}: {self.message}"
+
+
+@dataclass(frozen=True)
+class Source:
+    """PHP source with literals blanked out at their original positions."""
+
+    clean: str
+
+    @staticmethod
+    def blanked(literal: re.Match[str]) -> str:
+        """The matched literal as spaces, newlines preserved."""
+        return re.sub(r"[^\n]", " ", literal.group(0))
+
+    @classmethod
+    def from_php(cls, text: str) -> "Source":
+        """A source with every comment, string, and heredoc blanked out."""
+        return cls(clean=LITERALS.sub(cls.blanked, text))
+
+    def line_of(self, index: int) -> int:
+        """The 1-based line number of a character index."""
+        return self.clean.count("\n", 0, index) + 1
+
+
+@dataclass(frozen=True)
+class FileUnit:
+    """One file under analysis: its raw text and the blanked Source on demand."""
+
+    path: str
+    text: str
+
+    @cached_property
+    def source(self) -> Source:
+        """The PHP source with literals blanked, computed once per file."""
+        return Source.from_php(self.text)
+
+
+@dataclass(frozen=True)
+class Ordering:
+    """Sole owner of the parameter-ordering logic for one variant."""
+
+    pair_member: dict[str, tuple[str, str, int]]
+
+    def sorted(self, names: list[str]) -> list[str]:
+        """The names in the required order."""
+        present = set(names)
+        return sorted(names, key=lambda name: self.key(name, present))
+
+    def key(self, name: str, present: set[str]) -> tuple[int, str, int]:
+        """Length, then alphabet, with both members of a present pair at the lead key."""
+        entry = self.pair_member.get(name)
+        if entry is not None:
+            first, second, position = entry
+            partner = second if position == 0 else first
+            if partner in present:
+                return (len(first), first, position)
+        return (len(name), name, 0)
+
+
+PARAMETER_ORDERING: Final = Ordering(pair_member=PAIR_MEMBER)
+MEMBER_ORDERING: Final = Ordering(pair_member={})
+
+
+class MemberKind(Enum):
+    """Closed set of class-member groups in required declaration order.
+
+    Ranks 0 to 4 are the production families. A PHPUnit test class keeps the
+    const, case, constructor ranks then draws its methods from the test families
+    (5 to 7): lifecycle hooks, other methods, data providers. A class draws its
+    methods from one family set or the other, never both, so ranks stay monotonic.
+    """
+
+    CONSTANT = (0, "const")
+    CASE = (1, "case")
+    CONSTRUCTOR = (2, "constructor")
+    STATIC_METHOD = (3, "static method")
+    INSTANCE_METHOD = (4, "instance method")
+    LIFECYCLE = (5, "lifecycle hook")
+    METHOD = (6, "method")
+    DATA_PROVIDER = (7, "data provider")
+
+    @property
+    def rank(self) -> int:
+        return self.value[0]
+
+    @property
+    def label(self) -> str:
+        return self.value[1]
+
+    def precedes(self, other: "MemberKind") -> bool:
+        """Whether this group must appear before the other group."""
+        return self.rank < other.rank
+
+
+@dataclass(frozen=True)
+class Member:
+    """One classified class member at its declaration line."""
+
+    kind: MemberKind
+    line: int
+    name: str
+
+
+@dataclass(frozen=True)
+class TypeMembers:
+    """The members of one class-like declaration in source order."""
+
+    name: str
+    is_test: bool
+    members: list[Member]
+
+
+# Parameter ordering tiers: required first, then defaulted, then a variadic.
+REQUIRED_TIER: Final = 0
+DEFAULT_TIER: Final = 1
+VARIADIC_TIER: Final = 2
+
+
+@dataclass(frozen=True)
+class Parameter:
+    """One declared parameter: its identifier and its ordering tier."""
+
+    name: str
+    tier: int
+
+
+@dataclass(frozen=True)
+class ParameterList:
+    """One declaration's parameters in source order."""
+
+    line: int
+    owner: str
+    params: list[Parameter]
+
+    @property
+    def names(self) -> list[str]:
+        return [parameter.name for parameter in self.params]
+
+    def in_tier(self, tier: int) -> list[str]:
+        return [parameter.name for parameter in self.params if parameter.tier == tier]
+
+    def required(self) -> list[str]:
+        ordered = PARAMETER_ORDERING.sorted(self.in_tier(REQUIRED_TIER))
+        ordered += PARAMETER_ORDERING.sorted(self.in_tier(DEFAULT_TIER))
+        return ordered + self.in_tier(VARIADIC_TIER)
+
+    def out_of_order(self) -> bool:
+        return len(self.params) >= 2 and self.names != self.required()
+
+
+# --- Structure ----------------------------------------------------------------
+
+
+def bracket_spans(text: str) -> dict[int, int]:
+    """Every opening bracket position mapped to its closing position."""
+    spans: dict[int, int] = {}
+    stack: list[int] = []
+
+    for position, character in enumerate(text):
+        if character in "([{":
+            stack.append(position)
+
+        if character in ")]}" and stack:
+            spans[stack.pop()] = position
+
+    return spans
+
+
+def top_level_pieces(text: str) -> list[str]:
+    """The comma-separated pieces of a list, ignoring nested separators."""
+    pieces, depth, current = [], 0, []
+    for character in text:
+        if character in "([{":
+            depth += 1
+
+        if character in ")]}":
+            depth -= 1
+
+        if character == "," and depth == 0:
+            pieces.append("".join(current))
+            current = []
+            continue
+        current.append(character)
+
+    tail = "".join(current).strip()
+
+    if tail:
+        pieces.append(tail)
+
+    return pieces
+
+
+# --- Extraction ---------------------------------------------------------------
+
+
+def declared_signatures(source: Source) -> list[ParameterList]:
+    """Every function or method declaration with its parameters."""
+    signatures = []
+    spans = bracket_spans(source.clean)
+
+    for match in FUNCTION_DECLARATION.finditer(source.clean):
+        open_paren = source.clean.index("(", match.end() - 1)
+        inner = source.clean[open_paren + 1: spans.get(open_paren, len(source.clean))]
+        params = [
+            parameter_of(piece)
+            for piece in top_level_pieces(inner)
+            if PARAMETER.search(piece)
+        ]
+
+        signatures.append(ParameterList(
+            line=source.line_of(match.start()),
+            owner=match.group(1),
+            params=params,
+        ))
+    return signatures
+
+
+def parameter_of(piece: str) -> Parameter:
+    """One parameter's identifier and ordering tier from its declaration piece."""
+    name = PARAMETER.findall(piece)[-1]
+
+    if VARIADIC.search(piece):
+        return Parameter(name=name, tier=VARIADIC_TIER)
+
+    if DEFAULT_ASSIGNMENT.search(piece):
+        return Parameter(name=name, tier=DEFAULT_TIER)
+    return Parameter(name=name, tier=REQUIRED_TIER)
+
+
+def class_members(unit: FileUnit) -> list[TypeMembers]:
+    """Every class-like declaration with its members in source order."""
+    declarations = []
+    clean = unit.source.clean
+    spans = bracket_spans(clean)
+
+    for type_match in TYPE_DECLARATION.finditer(clean):
+        body_open = clean.find("{", type_match.end())
+
+        if body_open == -1:
+            continue
+
+        body_close = spans.get(body_open, len(clean))
+        is_test = bool(EXTENDS_TESTCASE.search(clean[type_match.end(): body_open]))
+        providers = test_providers(unit.text[body_open + 1: body_close]) if is_test else set()
+        declarations.append(TypeMembers(
+            name=type_match.group(2),
+            is_test=is_test,
+            members=declared_members(
+                at_line=unit.source.line_of(body_open),
+                body=clean[body_open + 1: body_close],
+                is_test=is_test,
+                providers=providers,
+            ),
+        ))
+    return declarations
+
+
+def test_providers(raw_body: str) -> set[str]:
+    """Every method name a data-provider attribute or annotation references."""
+    names = set()
+    for match in DATA_PROVIDER_REFERENCE.finditer(raw_body):
+        names.add(match.group(1) or match.group(2))
+    return names
+
+
+def provider_consumer_lines(unit: FileUnit) -> set[int]:
+    """Declaration lines of the test methods a data provider feeds.
+
+    The consumer side of the data-provider relation: the method a
+    `#[DataProvider('name')]` attribute or `@dataProvider name` tag immediately
+    precedes. Its parameters are the columns of the data set, ordered by the data
+    rather than by name length, so the parameter check skips these lines. Detection
+    runs on the raw text, since the docblock form is blanked in the Source, then the
+    next declaration in the position-aligned Source fixes the line.
+    """
+    clean = unit.source.clean
+    lines = set()
+    for reference in DATA_PROVIDER_REFERENCE.finditer(unit.text):
+        method = FUNCTION_DECLARATION.search(clean, reference.end())
+        if not method:
+            continue
+        lines.add(unit.source.line_of(method.start()))
+    return lines
+
+
+def declared_members(at_line: int, body: str, is_test: bool, providers: set[str]) -> list[Member]:
+    """The members declared at the top level of one type body."""
+    members, depth = [], 0
+    for offset, line in enumerate(body.split("\n")):
+        member = classified(at=at_line + offset, line=line, is_test=is_test, providers=providers)
+        if depth == 0 and member:
+            members.append(member)
+        depth += line.count("{") - line.count("}")
+    return members
+
+
+def classified(at: int, line: str, is_test: bool, providers: set[str]) -> Member | None:
+    """The member a line declares, when it declares one."""
+    method = METHOD_LINE.match(line)
+    if method:
+        name = method.group(2)
+        if name == "__construct":
+            return Member(kind=MemberKind.CONSTRUCTOR, line=at, name=name)
+
+        if is_test:
+            return Member(kind=test_method_kind(name=name, providers=providers), line=at, name=name)
+
+        if "static" in method.group(1).split():
+            return Member(kind=MemberKind.STATIC_METHOD, line=at, name=name)
+        return Member(kind=MemberKind.INSTANCE_METHOD, line=at, name=name)
+
+    constant = CONST_LINE.match(line)
+
+    if constant:
+        return Member(kind=MemberKind.CONSTANT, line=at, name=constant.group(1))
+    case = CASE_LINE.match(line)
+
+    if case:
+        return Member(kind=MemberKind.CASE, line=at, name=case.group(1))
+    return None
+
+
+def test_method_kind(name: str, providers: set[str]) -> MemberKind:
+    """The method family a name takes inside a PHPUnit test class."""
+    if name in LIFECYCLE_HOOKS:
+        return MemberKind.LIFECYCLE
+
+    if name in providers:
+        return MemberKind.DATA_PROVIDER
+    return MemberKind.METHOD
+
+
+# --- Checks -------------------------------------------------------------------
+
+
+def parameter_violations(unit: FileUnit) -> tuple[Violation, ...]:
+    """Parameter ordering on every declaration a data provider does not feed."""
+    exempt = provider_consumer_lines(unit)
+    return tuple(
+        Violation(
+            line=signature.line,
+            path=unit.path,
+            message=(
+                f"parameter order in `{signature.owner}()` is "
+                f"({', '.join(signature.names)}), "
+                f"required ({', '.join(signature.required())})"
+            ),
+        )
+
+        for signature in declared_signatures(unit.source)
+        if signature.line not in exempt and signature.out_of_order()
+    )
+
+
+def member_violations(unit: FileUnit) -> tuple[Violation, ...]:
+    """Member ordering on group sequence and order within each group."""
+    violations: list[Violation] = []
+    for declared in class_members(unit):
+        violations.extend(group_sequence_violations(path=unit.path, declared=declared))
+        violations.extend(within_group_violations(path=unit.path, declared=declared))
+    return tuple(violations)
+
+
+def group_sequence_violations(path: str, declared: TypeMembers) -> tuple[Violation, ...]:
+    """Members declared after a group that must come later."""
+    violations = []
+    order = group_order_text(declared.is_test)
+    latest = MemberKind.CONSTANT
+    for member in declared.members:
+        if member.kind.precedes(latest):
+            violations.append(Violation(
+                line=member.line,
+                path=path,
+                message=(
+                    f"`{member.name}` ({member.kind.label}) declared after a later "
+                    f"group in `{declared.name}`, required group order {order}"
+                ),
+            ))
+
+        if latest.precedes(member.kind):
+            latest = member.kind
+    return tuple(violations)
+
+
+def group_order_text(is_test: bool) -> str:
+    """The required group-order clause for the production or the test layout."""
+    if is_test:
+        return "const, case, constructor, lifecycle hooks, methods, data providers"
+    return "const, case, constructor, static methods, instance methods"
+
+
+def within_group_violations(path: str, declared: TypeMembers) -> tuple[Violation, ...]:
+    """Groups whose members break their required intra-group order."""
+    violations = []
+    for kind in MemberKind:
+        if kind is MemberKind.CONSTRUCTOR:
+            continue
+        grouped = [member for member in declared.members if member.kind is kind]
+        names = [member.name for member in grouped]
+
+        if not names:
+            continue
+        required = required_within(kind=kind, names=names)
+
+        if names == required:
+            continue
+
+        violations.append(Violation(
+            line=grouped[0].line,
+            path=path,
+            message=(
+                f"{kind.label} order in `{declared.name}` is ({', '.join(names)}), "
+                f"required ({', '.join(required)})"
+            ),
+        ))
+    return tuple(violations)
+
+
+def required_within(kind: MemberKind, names: list[str]) -> list[str]:
+    """One group's required order, lifecycle hooks by execution order, else length then alphabet."""
+    if kind is MemberKind.LIFECYCLE:
+        return [hook for hook in LIFECYCLE_ORDER if hook in names]
+    return MEMBER_ORDERING.sorted(names)
+
+
+def ordering_violations(unit: FileUnit) -> tuple[Violation, ...]:
+    """Every ordering violation in one PHP file: members, parameters."""
+    return (
+        *member_violations(unit),
+        *parameter_violations(unit),
+    )
+
+
+# --- Shell --------------------------------------------------------------------
+
+
+def requested_paths() -> list[Path]:
+    """The paths to verify, from argv or from the hook's stdin payload."""
+    if len(sys.argv) > 1:
+        return [Path(argument) for argument in sys.argv[1:]]
+    try:
+        payload = json.load(sys.stdin)
+    except ValueError:
+        return []
+
+    file_path = (payload.get("tool_input") or {}).get("file_path")
+
+    if isinstance(file_path, str):
+        return [Path(file_path)]
+    return []
+
+
+def in_scope(path: Path) -> bool:
+    """Whether the path is a PHP source under src/ or tests/."""
+    return bool(SCOPE_PATTERN.search(path.as_posix())) and path.is_file()
+
+
+def file_violations(path: Path) -> tuple[Violation, ...]:
+    """The ordering violations for one file."""
+    unit = FileUnit(
+        path=path.as_posix(),
+        text=path.read_text(errors="replace", encoding="utf-8"),
+    )
+    return ordering_violations(unit)
+
+
+def main() -> int:
+    violations = [
+        violation
+        for path in requested_paths()
+        if in_scope(path)
+        for violation in file_violations(path)
+    ]
+
+    if not violations:
+        return 0
+
+    for violation in violations[:MAX_ERRORS_REPORTED]:
+        print(violation, file=sys.stderr)
+    overflow = len(violations) - MAX_ERRORS_REPORTED
+
+    if overflow > 0:
+        print(f"... and {overflow} more violations", file=sys.stderr)
+    return 2
+
+
+if __name__ == "__main__":
+    sys.exit(main())
diff --git a/.claude/hooks/php-prose-punctuation-conformance.py b/.claude/hooks/php-prose-punctuation-conformance.py
new file mode 100644
index 0000000..18cd3ef
--- /dev/null
+++ b/.claude/hooks/php-prose-punctuation-conformance.py
@@ -0,0 +1,176 @@
+#!/usr/bin/env python3
+"""Prose punctuation conformance hook for tiny-blocks PHP libraries.
+
+Self-contained PostToolUse hook on Edit|Write|MultiEdit. Verifies prose punctuation:
+no em-dash, en-dash, or ` -- ` as a clause separator in Markdown prose or
+PHP comments, plus no `;` separator in Markdown. The checks read raw text only, so
+this script carries no PHP lexer. Markdown files route to the prose check, PHP
+sources to the comment check.
+
+Control flow uses guard clauses only and nesting never exceeds two levels. Reports
+violations to stderr and exits 2 to prompt Claude with feedback; exits 0 silently if
+no violations or the file is out of scope.
+"""
+
+import json
+import re
+import sys
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Final
+
+# --- Configuration ----------------------------------------------------------
+
+# In-scope files: PHP sources under src/ or tests/, plus any Markdown file.
+SCOPE_PATTERN: Final = re.compile(r"(^|/)(src|tests)/.+\.php$")
+MARKDOWN_PATTERN: Final = re.compile(r"\.md$")
+
+# Prohibited prose punctuation as clause separators. Em-dash U+2014, en-dash U+2013,
+# spaced double hyphen, and (Markdown only) the semicolon.
+PROSE_PUNCTUATION: Final = re.compile(r"[\u2014\u2013]| -- |;")
+PROSE_DASHES: Final = re.compile(r"[\u2014\u2013]| -- ")
+FENCE: Final = re.compile(r"^\s*```")
+PHP_COMMENT: Final = re.compile(r"/\*.*?\*/|//[^\n]*|#(?!\[)[^\n]*", re.DOTALL)
+INLINE_CODE: Final = re.compile(r"`[^`]*`")
+
+MAX_ERRORS_REPORTED = 30
+
+
+# --- Types --------------------------------------------------------------------
+
+
+@dataclass(frozen=True)
+class Violation:
+    """One style violation at a source position."""
+
+    line: int
+    path: str
+    message: str
+
+    def __str__(self) -> str:
+        return f"{self.path}:{self.line}: {self.message}"
+
+
+@dataclass(frozen=True)
+class FileUnit:
+    """One file under analysis: its path and raw text. No lexing needed here."""
+
+    path: str
+    text: str
+
+
+# --- Checks -------------------------------------------------------------------
+
+
+def is_markdown(path: str) -> bool:
+    """Whether the path is a Markdown file, routed to the Markdown prose check."""
+    return bool(MARKDOWN_PATTERN.search(path))
+
+
+def markdown_violations(unit: FileUnit) -> tuple[Violation, ...]:
+    """No `;`, em-dash, en-dash, or ` -- ` as a clause
+    separator in Markdown prose. Fenced code and table rows are exempt."""
+    violations = []
+    in_fence = False
+    for number, line in enumerate(unit.text.split("\n"), start=1):
+        if FENCE.match(line):
+            in_fence = not in_fence
+            continue
+
+        if in_fence or "|" in line:
+            continue
+
+        if PROSE_PUNCTUATION.search(INLINE_CODE.sub("", line)):
+            violations.append(Violation(
+                line=number,
+                path=unit.path,
+                message=(
+                    "prohibited prose punctuation (`;`, em-dash, en-dash, or ` -- `), "
+                    "split the sentence or use a comma, colon, or parentheses"
+                ),
+            ))
+    return tuple(violations)
+
+
+def comment_violations(unit: FileUnit) -> tuple[Violation, ...]:
+    """In PHPDoc and comments: no em-dash, en-dash,
+    or ` -- ` as a separator. The `;` is not checked in PHP comments (it terminates
+    statements in commented code)."""
+    violations = []
+    for match in PHP_COMMENT.finditer(unit.text):
+        if PROSE_DASHES.search(INLINE_CODE.sub("", match.group(0))):
+            violations.append(Violation(
+                line=unit.text.count("\n", 0, match.start()) + 1,
+                path=unit.path,
+                message=(
+                    "prohibited prose punctuation (em-dash, en-dash, or ` -- `) in a "
+                    "comment"
+                ),
+            ))
+    return tuple(violations)
+
+
+def punctuation_violations(unit: FileUnit) -> tuple[Violation, ...]:
+    """Punctuation violations for one file: Markdown prose for `.md`, comments otherwise."""
+    if is_markdown(unit.path):
+        return markdown_violations(unit)
+    return comment_violations(unit)
+
+
+# --- Shell --------------------------------------------------------------------
+
+
+def requested_paths() -> list[Path]:
+    """The paths to verify, from argv or from the hook's stdin payload."""
+    if len(sys.argv) > 1:
+        return [Path(argument) for argument in sys.argv[1:]]
+    try:
+        payload = json.load(sys.stdin)
+    except ValueError:
+        return []
+
+    file_path = (payload.get("tool_input") or {}).get("file_path")
+
+    if isinstance(file_path, str):
+        return [Path(file_path)]
+    return []
+
+
+def in_scope(path: Path) -> bool:
+    """Whether the path is a PHP source or any Markdown this hook covers."""
+    posix = path.as_posix()
+    matched = SCOPE_PATTERN.search(posix) or MARKDOWN_PATTERN.search(posix)
+    return bool(matched) and path.is_file()
+
+
+def file_violations(path: Path) -> tuple[Violation, ...]:
+    """The punctuation violations for one file."""
+    unit = FileUnit(
+        path=path.as_posix(),
+        text=path.read_text(errors="replace", encoding="utf-8"),
+    )
+    return punctuation_violations(unit)
+
+
+def main() -> int:
+    violations = [
+        violation
+        for path in requested_paths()
+        if in_scope(path)
+        for violation in file_violations(path)
+    ]
+
+    if not violations:
+        return 0
+
+    for violation in violations[:MAX_ERRORS_REPORTED]:
+        print(violation, file=sys.stderr)
+    overflow = len(violations) - MAX_ERRORS_REPORTED
+
+    if overflow > 0:
+        print(f"... and {overflow} more violations", file=sys.stderr)
+    return 2
+
+
+if __name__ == "__main__":
+    sys.exit(main())
diff --git a/.claude/rules/php-library-architecture.md b/.claude/rules/php-library-architecture.md
new file mode 100644
index 0000000..4be7fc3
--- /dev/null
+++ b/.claude/rules/php-library-architecture.md
@@ -0,0 +1,147 @@
+---
+description: Folder structure, public API boundary, and Internal/ semantics for PHP libraries.
+paths:
+    - "src/**/*.php"
+---
+
+# Architecture
+
+Covers the physical layout of the library. Folder structure, the boundary between public API and
+implementation detail, and where each type of class lives. Semantic rules (value objects,
+exceptions, enums, complexity, nomenclature) live in `php-library-modeling.md`. Code style lives
+in `php-library-code-style.md`.
+
+## Pre-output checklist
+
+Verify every item before producing or relocating any file. If any item fails, revise before
+outputting.
+
+1. None of the following folder names exist in `src/`: `Models/`, `Entities/`, `ValueObjects/`,
+   `Enums/`, `Domain/`. They carry no semantic content and conflate technical role with domain
+   meaning.
+2. The `src/` root contains only interfaces, extension points, public enums, thin orchestration
+   classes, and primary implementations or façades. Substantial logic (algorithms, state machines,
+   I/O) lives in `src/Internal/`, never at the root.
+3. `src/Internal/` is implementation detail and not part of the public API. Breaking changes
+   inside `src/Internal/` are not semver-breaking.
+4. Consumers must not reference, extend, or depend on any type inside `src/Internal/`. The
+   namespace itself is the boundary.
+5. Public exception classes live in `src/Exceptions/`.
+6. Internal exception classes live in `src/Internal/Exceptions/`.
+7. Public enums live at the `src/` root or inside a public `<ConceptGroup>/` folder. Enums used
+   only by internals live in `src/Internal/`.
+8. Public interfaces live at the `src/` root or inside a public `<ConceptGroup>/` folder.
+9. A `<ConceptGroup>/` folder at the `src/` root groups related public types under a shared
+   concept. Each group has its own namespace and is part of the public API.
+10. `<ConceptGroup>/` is optional. Use it only when the library exposes several coherent groups of
+    types (for example, aggregates and events) rather than a flat set of types around a single
+    concept.
+11. Test fixtures representing domain concepts live in `tests/Models/`. Test doubles for system
+    boundaries live at the root of `tests/Unit/` or `tests/Integration/`. No dedicated `Mocks/`
+    or `Doubles/` subdirectory exists. Vendor compatibility (driver) tests, verifying the
+    library against specific external libraries/frameworks, are optional and have no `src/`
+    counterpart. They exist only as tests, under `tests/Integration/Drivers/<Vendor>/`,
+    grouped by vendor. Never a top-level `Drivers/` under `tests/`.
+12. The `tests/Integration/` folder exists only when the library interacts with external
+    infrastructure (filesystem, database, network). Otherwise, the folder is absent.
+
+## Folder structure
+
+Canonical layout for a PHP library in the tiny-blocks ecosystem.
+
+```
+src/
+├── <PublicInterface>.php     # public contract at root
+├── <Implementation>.php      # main implementation or extension point at root
+├── <PublicEnum>.php          # public enum at root
+├── <ConceptGroup>/           # public folder grouping related public types under a shared concept
+│   ├── <PublicType>.php
+│   └── ...
+├── Internal/                 # implementation details, not part of the public API
+│   ├── <Collaborator>.php
+│   └── Exceptions/           # internal exception classes
+└── Exceptions/               # public exception classes
+
+tests/
+├── Models/                   # domain fixtures reused across tests
+├── Unit/                     # unit tests targeting the public API
+│   ├── <SomeMock>.php        # test doubles at root of Unit/
+│   └── <SomeSpy>.php
+└── Integration/              # only present when the library interacts with infrastructure
+    ├── Drivers/              # only present when the library exposes vendor-specific drivers
+    │   └── <Vendor>/         # tests against one specific third-party implementation
+    └── <SomeMock>.php        # test doubles at root of Integration/ when needed
+```
+
+Never use `Models/`, `Entities/`, `ValueObjects/`, `Enums/`, or `Domain/` as folder names. They
+carry no semantic content and describe technical role instead of domain meaning.
+
+## Public API boundary
+
+The `src/` root is the contract. Everything at the root, plus everything inside public
+`<ConceptGroup>/` folders and the public `Exceptions/` folder, is what consumers depend on. Changes
+to these types follow semver rules.
+
+`src/Internal/` is implementation detail. The namespace itself signals the boundary. Consumers
+must not depend on any type inside `src/Internal/`. Breaking changes inside `src/Internal/` are
+not semver-breaking for the library.
+
+### What lives at the public boundary
+
+- Interfaces that define contracts for consumers.
+- Extension points designed to be subclassed or composed by consumers.
+- Public enums and value objects consumers manipulate directly.
+- Thin orchestration classes that wire collaborators together without containing substantial logic.
+- Public exception classes consumers may catch.
+
+### What lives in `src/Internal/`
+
+- Algorithms, state machines, and complex transformations.
+- Adapters for I/O (filesystem, network, database).
+- Collaborators that exist purely to break a public class into testable units.
+- Implementation details that may change between minor or patch releases.
+- Internal exception classes raised by collaborators.
+
+## Reference examples
+
+### Small library with flat root
+
+```
+src/
+├── Timezone.php              # public value object
+├── Timezones.php             # public collection
+├── Clock.php                 # public interface
+└── Internal/
+    ├── SystemClock.php       # default Clock implementation
+    └── Exceptions/
+        └── InvalidTimezone.php
+```
+
+Everything lives at the root or inside `Internal/`. No `<ConceptGroup>/` folders. Suitable when
+the library exposes a small, cohesive set of types around a single concept.
+
+### Library with public concept groups
+
+```
+src/
+├── ValueObject.php                 # public extension point at root
+├── Aggregate/                      # public namespace grouping aggregate types
+│   ├── AggregateRoot.php
+│   ├── EventualAggregateRoot.php
+│   └── ModelVersion.php
+├── Event/                          # public namespace grouping event types
+│   ├── EventRecord.php
+│   ├── EventRecords.php
+│   └── SequenceNumber.php
+├── Internal/
+│   ├── DefaultModelVersionResolver.php
+│   └── Exceptions/
+│       └── InvalidSequenceNumber.php
+└── Exceptions/
+    └── EventRecordingFailure.php
+```
+
+`Aggregate/` and `Event/` are public folders at the root, each grouping a coherent set of public
+types under one shared concept. Consumers import directly, for example
+`TinyBlocks\<LibName>\Aggregate\AggregateRoot`. Suitable when the library exposes several distinct
+concept areas, each with its own set of related types.
diff --git a/.claude/rules/php-library-code-style.md b/.claude/rules/php-library-code-style.md
new file mode 100644
index 0000000..c44dbc1
--- /dev/null
+++ b/.claude/rules/php-library-code-style.md
@@ -0,0 +1,960 @@
+---
+description: Semantic code rules for all PHP files in libraries.
+paths:
+    - "src/**/*.php"
+    - "tests/**/*.php"
+---
+
+# Code style
+
+Semantic rules for all PHP files in libraries. Formatting rules covered by `PSR-12` are enforced
+by `phpcs.xml`. Four formatting rules outside `PSR-12` (single-line signatures within 120
+characters, no vertical alignment in parameter lists, vertical alignment of `=>` in multi-line
+match arms and array literals, no trailing comma in multi-line lists) are documented at the end
+of this file under "Formatting overrides". Complexity rules live in `php-library-modeling.md`.
+Folder structure, public API boundary, and the semantics of `Internal/` live in
+`php-library-architecture.md`.
+
+## Pre-output checklist
+
+Verify every item before producing any PHP code. If any item fails, revise before outputting.
+
+1. `declare(strict_types=1)` is present.
+2. All parameters, return types, and properties have explicit types.
+3. Constructor property promotion is used.
+4. Named arguments are used at call sites for own code, tests, and third-party library methods
+   (for example, tiny-blocks). Never use named arguments on:
+    - Native PHP functions (`array_map`, `in_array`, `preg_match`, `is_null`,
+      `iterator_to_array`, `sprintf`, `implode`, and similar).
+    - Native PHP enum methods (`from`, `tryFrom`, `cases`).
+    - PHPUnit assertions and expectations (`assertEquals`, `assertSame`, `assertTrue`,
+      `expectException`, and similar).
+    - Interfaces from PHP-FIG PSR standards (PSR-7 `withHeader`, PSR-18 `sendRequest`, etc.).
+      The PSR contract does not include parameter names. Implementations may rename parameters.
+    - Calls that include variadic spread (`...$args`). PHP rejects positional argument unpacking
+      after named arguments. When the caller passes through a `...$variadic`, all arguments are
+      positional. New own-code APIs should prefer a typed collection parameter over a variadic
+      so named-argument call sites remain possible.
+    - Native PHP class static and instance methods (`DateTimeImmutable::createFromFormat`,
+      `DateTimeImmutable::createFromInterface`, `->setTimezone`, `->format`, and similar). Their
+      parameter names are an internal implementation detail, not a stable contract, exactly as
+      with native functions.
+
+   Native PHP **class constructors** (`parent::__construct` calls to `\Exception`,
+   `\RuntimeException`, `\InvalidArgumentException`, `\LogicException`, and similar) are not
+   in the list above. They accept named arguments, and rule 8 requires using them whenever
+   the positional call would pass an argument whose value equals the parameter's default.
+   Example: `parent::__construct(message: sprintf(...), previous: $previous)` instead of
+   `parent::__construct(sprintf(...), 0, $previous)`. The exclusion above covers native
+   functions, enum methods, and native class static and instance methods, but not native class
+   constructors (instantiation): those accept named arguments per rule 8.
+5. Classes follow the rules in "Inheritance and constructors". `final readonly` is the default,
+   with documented exceptions for extension points and for parents that are not `readonly`.
+6. Members are ordered constants first, then constructor, then static methods, then instance
+   methods. Within each group, order by **member name length ascending** (count the name only,
+   without parentheses, arguments, or return type). Constants, enum cases, and methods share
+   the same name-length-ascending rule, applied within their respective groups. This mirrors
+   the rule that governs constructor parameters and named arguments (rule 7). When two names
+   have equal length, order them alphabetically. This ordering may be overridden only when the
+   alternative carries explicit documentation value: grouping by domain class with section
+   markers (HTTP status codes by 1xx/2xx/3xx/etc), mirroring the order of an implemented
+   interface, or similar evident structure. The override must be obvious at first reading.
+
+   **At call sites** (chained method calls in production code, tests, or documentation
+   examples), consecutive method invocations on the same receiver are ordered by **method name
+   length ascending**, the same rule that governs member declarations. Boolean toggles such as
+   `->secure()` and `->httpOnly()` come before parameterized `with*` builders because their
+   names are shorter, not because the expression is narrower. When two method names have equal
+   length, order them alphabetically.
+
+   **Terminal methods that change the receiver type** stay at the end of the chain regardless
+   of name length. A `build()` that returns the built value, a `commit()` that finalizes a unit
+   of work, a `send()` that flushes a request, are terminal: the chain ends with them. The
+   ordering rule applies only to consecutive calls on the same receiver type. Calls that
+   transition to a different type are not reorderable. The same applies in reverse to the
+   factory or accessor that starts the chain (`Cookie::create(...)`, `$repository`) stays
+   at its position.
+
+   **PHPUnit test classes** follow a dedicated sub-grouping inside the instance-methods group
+   that overrides the name-length-ascending rule:
+
+    1. **Lifecycle hooks** first, in PHPUnit execution order:
+       `setUpBeforeClass` → `setUp` → `tearDown` → `tearDownAfterClass`. Only those actually
+       defined appear. Never introduce an empty hook to satisfy the rule.
+    2. **Test methods** (prefix `test`) next, ordered by name length ascending (alphabetical
+       tiebreak).
+    3. **Data providers** last, ordered by name length ascending (alphabetical tiebreak).
+
+   A method is a data provider if and only if its name appears as the string argument of a
+   `#[DataProvider('<name>')]` attribute or a `@dataProvider <name>` docblock annotation on a
+   test method in the same class. The naming convention (`*DataProvider`) is informational
+   only. The reference is the authoritative signal. A method named `*DataProvider` that no
+   test references is dead code under rule 17, not a data provider.
+7. Constructor parameters are ordered by parameter name length ascending (count the name only,
+   without `$` or type), except when parameters have an implicit semantic order (for example,
+   `$start/$end`, `$from/$to`, `$startAt/$endAt`), which takes precedence. Parameters with default
+   values go last, regardless of name length. The same rule applies to named arguments at call
+   sites. Example order: `$id` (2), `$value` (5), `$status` (6), `$precision` (9).
+8. Never pass an argument whose value equals the parameter's default. Omit the argument entirely.
+   Example with `toArray(KeyPreservation $keyPreservation = KeyPreservation::PRESERVE)`. The call
+   `$collection->toArray(keyPreservation: KeyPreservation::PRESERVE)` becomes
+   `$collection->toArray()`. Only pass the argument when the value differs from the default.
+9. No `else` or `else if` exists anywhere. Use early returns, polymorphism, or map dispatch
+   instead. See "Polymorphism and tell-don't-ask".
+10. No abbreviations appear in identifiers. Use `$index` instead of `$i`, `$account` instead of
+    `$acc`.
+11. No generic identifiers exist. Use domain-specific names instead. Examples are `$data` to
+    `$payload`, `$value` to `$totalAmount`, `$item` to `$element`, `$info` to `$currencyDetails`,
+    `$result` to `$conversionOutcome`. **Exception:** a factory or constructor parameter that
+    wraps a single opaque scalar the value object exists to represent may keep `$value` when no
+    more specific meaning applies (for example, `Seconds::from(int $value)`). Where a more
+    specific meaning exists, prefer it (`$iso`, `$identifier`, `$isoDay`).
+12. No raw arrays exist where a typed collection or value object is available. When data is
+    `Collectible`, use the `tiny-blocks/collection` fluent API (`Collection`, `Collectible`). Use
+    `createLazyFrom` when elements are consumed once. Raw arrays are acceptable only for primitive
+    configuration data, variadic pass-through, and interop at system boundaries. See "Collection
+    usage" for the full rule and example.
+13. No private methods exist except for private constructors in factory patterns, methods inside
+    `src/Internal/` (implementation detail by definition, where the namespace is the abstraction
+    boundary), and `setUp` or `tearDown` overrides in PHPUnit test classes. Outside these cases,
+    inline trivial logic at the call site or extract it to a collaborator or value object.
+14. No logic is duplicated across two or more places (DRY). See "Duplication" for the resolution
+    under the inheritance and private-method constraints.
+15. No abstraction exists without real duplication or isolation need (KISS).
+16. No inline comments exist in `src/` or `tests/`, except `# TODO: <reason>` when implementation
+    is unknown, uncertain, or intentionally deferred. Code is the documentation. Block comments
+    (`/* */`) never appear outside docblocks (`/** */`). The `#` style for inline PHP comments
+    applies only to code examples inside Markdown files (see `php-library-documentation.md`).
+17. No dead or unused code exists. Remove unreferenced classes, methods, constants, and imports.
+18. Never create public methods, constants, or classes in `src/` solely to serve tests. If
+    production code does not need it, it does not exist.
+19. Format strings with placeholders (`%s`, `%d`, `%f`, etc.) are assigned to a `$template`
+    variable before being passed to `sprintf`. The variable assignment and the `sprintf` call live
+    on separate statements. See "Format strings" for examples.
+20. All class references use `use` imports at the top of the file. Fully qualified names inline are
+    prohibited.
+21. Return types and `new` calls use the explicit class name. `self` is prohibited as a type,
+    as a return type, in `new self()` instantiation, and in static method calls
+    (`self::from(...)` → `ClassName::from(...)`). Constant access via `self::CONST_NAME` is the
+    only permitted `self::` form. `static` is permitted only inside extension-point classes
+    (declared `class` without `final readonly`) and inside traits, where late static binding lets
+    subclasses or consuming classes instantiate the correct concrete type. In every other
+    context, use the class name.
+22. Always use the most current and clean syntax available in the target PHP version. Prefer
+    `match` over `switch`, first-class callables over `Closure::fromCallable()`, readonly promotion
+    over manual assignment, enum methods over external switch or if chains, named arguments over
+    positional ambiguity (except where excluded by rule 4), `Collection::map` over foreach
+    accumulation, concise standard regex character classes (`\w`, `\d`, `\s`, and their negations)
+    over their explicit equivalents (`[A-Za-z0-9_]`, `[0-9]`), and **unparenthesized constructor
+    chaining** (PHP 8.4+): `new Foo()->bar()` instead of `(new Foo())->bar()`. The parentheses
+    around the `new` expression are no longer required and add visual noise.
+23. All identifiers, comments, and documentation use American English. See "American English" for
+    the spelling list.
+24. No method has more than three `return` statements. This bounds branching complexity and
+    coexists with rule 9 (no `else`): early-return guard clauses are fine, but a method that needs
+    more than three exit points is doing too much. Invariant violations `throw` a dedicated
+    exception rather than returning, so guards rarely add return points. When branching still
+    produces more than three returns, replace it with a `match` or map dispatch that resolves to a
+    single return, or extract a collaborator. When the branches turn on the runtime type of
+    polymorphic collaborator, the behavior belongs on that type instead. See "Return statements"
+    and "Polymorphism and tell-don't-ask".
+25. The string concatenation operator (`.`) is never used, in any position. A string that
+    would be assembled by concatenation, whether it embeds a value or joins two or more
+    strings, is built with `sprintf` and a `$template` variable (rule 19) instead. This
+    covers value prefixes, value suffixes, inline fragments, and plain joins. See "Format
+    strings".
+
+    **Exception:** a `const` string literal that contains no `sprintf` placeholder may
+    use `.` to split a message across lines when a single-line literal would exceed the
+    120-character limit. In that case `sprintf` offers no benefit, since the `$template`
+    line would itself exceed the limit, and heredoc and nowdoc are not permitted in
+    constant expressions, so concatenation is the only way to honor the line length.
+    This exception is limited to placeholder-free constant literals. Runtime string
+    assembly, and any constant that interpolates a value, still uses `sprintf` with a
+    `$template`.
+26. Behavior that varies by the concrete type of type the library owns is a polymorphic method
+    on that type, never an `instanceof`, `get_class`, or enum-case branch. A value or behavior an
+    enum case owns (a token, a flag about the case's nature, a derived value) lives on the enum as
+    a predicate or vocabulary method, called at the site instead of comparing the case. Behavior
+    that depends on a collaborator's state lives on that collaborator. See "Polymorphism and
+    tell-don't-ask".
+
+## Naming
+
+- Internal code (variables, methods, classes) uses `camelCase`.
+- Constants and enum-backed values when representing codes use `SCREAMING_SNAKE_CASE`.
+- Names describe what in domain terms, not how technically. `$monthlyRevenue` instead of
+  `$calculatedValue`. Generic technical verbs are avoided. See `php-library-modeling.md` for the
+  full banlist of generic and anemic names.
+- Booleans use predicate form. Examples are `isActive`, `hasPermission`, `wasProcessed`.
+- Collections are always plural. Examples are `$orders`, `$lines`.
+- A boolean method reads as a predicate, using an `is`/`has`/`can`/`was`/`should` prefix or a
+  third-person verb that reads as a yes/no question, such as `contains`, `matches`, `supports`,
+  `equals`, or `omits`.
+
+## Class self-references
+
+Type declarations, return types, and `new` calls inside a class use the explicit class name.
+The class name is unambiguous, survives refactors that move the method to a different class,
+and reads identically inside the class body and at the call site.
+
+- `self` is prohibited everywhere as a type, as a return type, in `new self()` instantiation,
+  and in static method calls (`self::from(...)`). Constant access via `self::CONST_NAME` is
+  **permitted** and is the only allowed `self::` form. The prohibition covers the forms that
+  carry refactoring ambiguity when a method moves to a different class (type, instantiation, and
+  static-call forms): a `self::from()` call rebinds to the wrong class if the method moves,
+  exactly like `new self()`. Constant access does not have that ambiguity because the constant is
+  declared in the same class body.
+- `static` is permitted only inside extension-point classes (declared `class` without
+  `final readonly`) and inside traits, where late static binding is required for subclasses or
+  consuming classes to instantiate the correct concrete type.
+- In every other context (the default `final readonly class`, factory methods, return types),
+  use the class name.
+
+**Prohibited.** `self` as return type and `new self()` inside a final class:
+
+```php
+final readonly class UserAgent
+{
+    public static function from(string $product): self
+    {
+        return new self(product: $product);
+    }
+}
+```
+
+**Correct.** Explicit class name in a final class:
+
+```php
+final readonly class UserAgent
+{
+    public static function from(string $product): UserAgent
+    {
+        return new UserAgent(product: $product);
+    }
+}
+```
+
+**Correct.** `static` permitted in an extension-point class:
+
+```php
+class Collection
+{
+    public static function createFrom(iterable $elements): static
+    {
+        return new static(elements: $elements);
+    }
+}
+```
+
+## Inheritance and constructors
+
+- All classes are `final readonly` by default.
+- Use `class` (without `final` or `readonly`) only when the class is designed as an extension point
+  for consumers, for example `Collection` or `ValueObject`.
+- Use `final class` without `readonly` only when the parent class is not readonly, for example
+  when extending a third-party abstract class.
+- Use `final class` without `readonly` is also permitted for `src/Internal/` collaborators that
+  carry intrinsically mutable state (resource handles, counters, cursors) where the mutation is
+  central to the class's responsibility (`Stream` closing a resource, `Cursor` advancing a
+  position). The class must remain confined to `src/Internal/`.
+- Use `final class` without `readonly` for classes that consist exclusively of `static` methods
+  (no instance properties, no instance methods, only static factories or utilities). Pair it
+  with `private function __construct() {}` to prevent instantiation. `readonly` is meaningless
+  without instance state, and the private constructor signals that the class is a static
+  surface, not a value type.
+- Inheritance between concrete classes is prohibited. Every concrete class is `final`.
+- Polymorphism uses interfaces plus composition, never extension of concrete types.
+- The only allowed `extends` is against framework or SPL base classes that the language requires.
+  Examples are `RuntimeException`, `LogicException`, `PHPUnit\Framework\TestCase`.
+- Constructors of `final` classes are `private` when paired with named factory methods, `public`
+  otherwise. `protected` constructors are prohibited because no subclasses exist to call them.
+
+## Comparisons
+
+1. Null checks use `is_null($variable)`, never `$variable === null`.
+2. Empty string checks on typed `string` parameters use `$variable === ''`. Avoid `empty()` on
+   typed strings because `empty('0')` returns `true`.
+3. Mixed or untyped checks (value may be `null`, empty string, `0`, or `false`) use
+   `empty($variable)`.
+
+## American English
+
+All identifiers, enum values, comments, and error codes use American English spelling. Examples
+are `canceled` (not `cancelled`), `organization` (not `organisation`), `initialize` (not
+`initialise`), `behavior` (not `behaviour`), `modeling` (not `modelling`), `labeled` (not
+`labelled`), `fulfill` (not `fulfil`), `color` (not `colour`).
+
+## PHPDoc
+
+### When required
+
+Everything exposed on the public API for consumption carries PHPDoc per these rules.
+
+- Every method of an interface, regardless of location. Interfaces are contracts, so they carry
+  PHPDoc per these rules even when declared inside `src/Internal/`.
+- Every public method of a concrete class outside `src/Internal/`. Public classes are at the
+  public API boundary by definition. Consumers call every public method directly, and the
+  PHPDoc is the contract for each call. Trivial getters and `with*` methods are not exempt.
+  The only exception is a public method whose contract is already documented on an implemented
+  interface (the interface carries the docblock).
+- Every abstract method on a public class or extension point outside `src/Internal/`. Abstract
+  methods are part of the public contract consumers implement or override, so each carries PHPDoc
+  exactly as an interface method does.
+- A class-level summary docblock on every interface (including interfaces inside `src/Internal/`)
+  and on every public class or enum outside `src/Internal/`. The summary is a single line placed
+  directly above the declaration stating what the type is or does, following the same summary-line
+  rule as method docblocks. It is the class-level counterpart of the per-method PHPDoc.
+
+### When prohibited
+
+- Constructors. The constructor signature with property promotion is self-documenting. Parameter
+  types are already explicit in the signature.
+- Private and protected methods.
+- Public methods of concrete classes whose contract is already documented on an implemented
+  interface. The interface carries the docblock.
+- Concrete classes and collaborators inside `src/Internal/`. Internal implementation types are
+  detail, not contract, and carry no PHPDoc, class-level summary included. **Interfaces are the
+  exception**: an interface declared inside `src/Internal/` is still a contract and follows the
+  interface PHPDoc rules under "When required", including the class-level summary. See
+  `php-library-architecture.md` for the architectural meaning of `Internal/`.
+- Anywhere inside `tests/`. Test methods name the scenario via the `testXxxWhenYyyThenZzz`
+  naming convention, and the `@Given`/`@When`/`@Then`/`@And` annotation blocks defined in
+  `php-library-testing.md` describe the steps. PHPDoc documentation (summary plus
+  `@param`/`@return` descriptions) is prohibited on test methods, data providers, fixtures,
+  setUp/tearDown overrides, and anonymous classes inside tests. The BDD annotations are not
+  PHPDoc documentation in the sense of this section and remain required per the testing rule.
+- Single-line PHPDocs with only a tag (`/** @param ... */`, `/** @return ... */`,
+  `/** @throws ... */`). PHPDoc always opens with a summary line. Bare-tag docblocks are
+  prohibited regardless of how few tags they carry.
+
+The prohibitions above apply to **every form of PHPDoc** in the prohibited scope:
+method-level docblocks, property-level docblocks, inline `@var` annotations on local variables,
+and PHPDoc blocks placed above anonymous functions or closures inside method bodies. Inside
+`tests/`, zero PHPDoc is the rule, save for the generics carve-out below. Inside `src/Internal/`,
+zero PHPDoc applies to concrete classes and collaborators, but interfaces carry PHPDoc per "When
+required", and the generics carve-out below still applies to those concrete classes. PHPStan
+errors that result from the missing annotations on the non-interface code route through
+`ignoreErrors` (see below).
+
+**Generics carve-out.** The prohibitions above are waived for PHPDoc that exists *purely to
+express generics* the native type system cannot: `@template`, `@extends`, `@implements`, and the
+`@param`/`@return`/`@var` tags whose sole purpose is to carry a type parameter (for example
+`Collection<TValue>`, `iterable<TValue>`, `Closure(TValue): bool`, `static<TValue>`). These tags
+are permitted wherever they are necessary for generic typing, including on **constructors**, on
+**concrete classes and collaborators inside `src/Internal/`**, and as a **bare-tag block with no
+summary line** (a summary would be the prohibited descriptive form). The waiver is strict: it
+covers only the type-parameter information. Descriptive or redundant PHPDoc (summaries, prose
+`@param`/`@return` descriptions, anything restating what the signature already says) stays
+prohibited everywhere. When the only missing annotation is non-generic (a plain iterable value
+type, a mixed-origin argument), the typed-array case below still applies and routes through
+`ignoreErrors`, not PHPDoc.
+
+The PHPDoc prohibitions above take priority over the typed-array case. When PHPStan at
+`level: max` flags a missing iterable value type (`missingType.iterableValue`,
+`argument.type`, `return.type`):
+
+- On a **constructor parameter** → suppress via `ignoreErrors` in `phpstan.neon.dist`. Do not
+  add PHPDoc.
+- On a concrete class or collaborator inside **`src/Internal/`** → suppress via `ignoreErrors`.
+  Do not add PHPDoc. An interface inside `src/Internal/` is the exception: it carries PHPDoc per
+  "When required", so the typed-array information goes in the docblock, not `ignoreErrors`.
+- On anything inside **`tests/`** → suppress via `ignoreErrors`. Do not add PHPDoc.
+- On a **public method of a public (non-Internal) class** → add full PHPDoc with summary,
+  `@param` descriptions, and the typed-array information. The bare-tag form remains
+  prohibited. This is the normal case where PHPDoc is permitted by "When required" above.
+
+The summary requirement and the bare-tag prohibition are never waived. Use `ignoreErrors` only
+when the context (constructor, `src/Internal/`, `tests/`) makes PHPDoc impossible. Every public
+method of a public concrete class carries PHPDoc per "When required", whether the method
+has typed-array parameters.
+
+### Style
+
+- Summary on the first line, in domain terms. **Mandatory.** PHPDoc without a summary line is
+  prohibited, even when it carries a single `@param` or `@return`.
+- Optional detailed body in `<p>` paragraphs below the summary.
+- Tags use the form `@param Type $name Description.`, `@return Type Description.`,
+  `@throws ExceptionClass If <condition>.`.
+- Document `@throws` for every exception the method may raise.
+- HTML tags allowed inside descriptions are `<p>` for paragraphs, `<ul><li>` for lists,
+  `<code>` for inline code, `<em>` and `<strong>` for emphasis.
+
+### Summary patterns
+
+The summary line is not a creative intent statement. It is a template selected by the method's
+name prefix. Apply the matching template. Only methods with no matching prefix require a
+free-form one-line summary in domain terms.
+
+| Method shape                                                            | Template                                                                       |
+|-------------------------------------------------------------------------|--------------------------------------------------------------------------------|
+| Static factory (`create`, `from`, `fromX`, `with*` when static)         | `Creates a {ClassName} from {input}.` or `Builds a {ClassName} with {fields}.` |
+| `with*` instance method                                                 | `Returns a copy of the {ClassName} with the {field} replaced.`                 |
+| Getter (no prefix, returns a property: `code()`, `body()`, `headers()`) | `Returns the {field}.`                                                         |
+| Predicate (`is*`, `has*`, `can*`, `was*`, `should*`)                    | `Tells whether {condition}.`                                                   |
+| Converter (`toArray`, `toString`, `asX`)                                | `Returns the {ClassName} as {target shape}.`                                   |
+| `apply*`, `merge*`, `add*`, and other side-effect-free operations       | One-line summary in domain terms describing the operation.                     |
+
+The patterns are mandatory when applicable. They make summary lines mechanical: substitute
+`{ClassName}` and `{field}` and the summary is complete. No per-method intent decision is
+required. Volume is never a reason to skip the summary. Many methods just mean applying the
+template many times.
+
+### Cross-references
+
+- `{@see ClassName}` for links to other types in the codebase.
+- `@see Author, <em>Title</em> (Publisher, Year), Chapter X.` for bibliographical references.
+
+### Examples
+
+**Prohibited.** Single-line bare-tag PHPDoc, no summary:
+
+```php
+/** @param array<string, mixed>|null $body */
+public static function with(Code $code, ?array $body = null): Response
+```
+
+**Prohibited.** PHPDoc on a constructor:
+
+```php
+/** @param array<string, mixed> $entries */
+public function __construct(public array $entries)
+{
+}
+```
+
+**Prohibited.** PHPDoc on anything inside `src/Internal/`:
+
+```php
+namespace TinyBlocks\Http\Internal\Client;
+
+final readonly class Url
+{
+    /** @param array<string, scalar>|null $query */
+    public static function compose(string $path, ?array $query, string $baseUrl): string
+    {
+    }
+}
+```
+
+**Correct.** Generic array type with summary and `@param` description:
+
+```php
+/**
+ * Builds a synthesized response from a status code and an optional body.
+ *
+ * @param array<string, mixed>|null $body The response body as an associative array.
+ * @return Response The synthesized response instance.
+ */
+public static function with(Code $code, ?array $body = null): Response
+```
+
+**Correct.** Interface with rich description, paragraphs, cross-references, and bibliography:
+
+```php
+/**
+ * Money tied to a specific currency.
+ *
+ * <p>Operations between different currencies raise <code>CurrencyMismatch</code>. Arithmetic
+ * preserves the currency.</p>
+ *
+ * <p>Sibling of {@see Quantity}, not a parent. <code>Money</code> carries currency semantics.</p>
+ *
+ * @see Eric Evans, <em>Domain-Driven Design</em> (Addison-Wesley, 2003), Chapter 5.
+ */
+interface Money
+{
+    /**
+     * Adds the given amount.
+     *
+     * @param Money $other The amount to add.
+     * @return Money A new instance with the summed amount.
+     * @throws CurrencyMismatch If <code>$other</code> has a different currency.
+     */
+    public function add(Money $other): Money;
+}
+```
+
+**Correct.** Concrete class with a short summary and direct tags:
+
+```php
+/**
+ * IANA timezone identifier (e.g. America/Sao_Paulo).
+ */
+final readonly class Timezone
+{
+    /**
+     * Creates a Timezone from a valid IANA identifier.
+     *
+     * @param string $identifier The IANA timezone identifier.
+     * @return Timezone The created instance.
+     * @throws InvalidTimezone If the identifier is not a valid IANA timezone.
+     */
+    public static function from(string $identifier): Timezone
+    {
+        # ...
+    }
+}
+```
+
+## Dependencies
+
+When the library needs an external dependency, prefer packages from the `tiny-blocks` ecosystem
+(https://github.com/tiny-blocks) whenever a suitable option exists. Reach for outside packages
+only when the ecosystem has no equivalent that fits the use case.
+
+## Collection usage
+
+When a property or parameter is `Collectible`, use its fluent API. Never break out to raw array
+functions such as `array_map`, `array_filter`, `iterator_to_array`, or `foreach` plus accumulation.
+The same applies to `filter()`, `reduce()`, `each()`, and every other `Collectible` operation.
+Chain them fluently. Never materialize with `iterator_to_array` to then pass into a raw `array_*`
+function.
+
+**Prohibited.** `array_map` plus `iterator_to_array` on a `Collectible`:
+
+```php
+$names = array_map(
+    static fn(Element $element): string => $element->name(),
+    iterator_to_array($collection)
+);
+```
+
+**Correct.** Fluent chain with `map()` plus `toArray()`:
+
+```php
+$names = $collection
+    ->map(transformations: static fn(Element $element): string => $element->name())
+    ->toArray(keyPreservation: KeyPreservation::DISCARD);
+```
+
+## Format strings
+
+When building a message with placeholders, assign the format string to a `$template` variable
+first. Pass it to `sprintf` on a separate statement. The format and the data are visually
+separated, and the template line stays scannable.
+
+**Prohibited.** Format string inline with the call:
+
+```php
+if ($value < 0 || $value > 16) {
+    throw new PrecisionOutOfRange(
+        message: sprintf('Precision must be between 0 and 16, got %d.', $value)
+    );
+}
+```
+
+**Correct.** Format string in a `$template` variable:
+
+```php
+if ($value < 0 || $value > 16) {
+    $template = 'Precision must be between 0 and 16, got %d.';
+
+    throw new PrecisionOutOfRange(message: sprintf($template, $value));
+}
+```
+
+The `.` operator is never used to assemble a string. Value prefixes, value suffixes, inline
+fragments, and plain joins all go through `sprintf` with a `$template`. This holds even when
+no value is interpolated, for example when joining a directory and a file name.
+
+The sole exception is a placeholder-free `const` string literal that would exceed 120
+characters on a single line: it may use `.` to split across lines, since `sprintf` would
+not shorten the line and heredoc is unavailable in constant expressions.
+
+**Prohibited.** Concatenation to inject a value:
+
+```php
+$candidate = is_int($value) ? '@' . $value : $value;
+```
+
+**Correct.** `$template` plus `sprintf`:
+
+```php
+$template = '@%d';
+$candidate = is_int($value) ? sprintf($template, $value) : $value;
+```
+
+**Prohibited.** Concatenation to join strings:
+
+```php
+$location = $directory . '/' . $file;
+```
+
+**Correct.** A single `$template` for the join:
+
+```php
+$template = '%s/%s';
+$location = sprintf($template, $directory, $file);
+```
+
+## Constructor chaining
+
+PHP 8.4 allows chained method calls directly on a `new` expression without wrapping it in
+parentheses. The parentheses are no longer required and only add visual noise. Apply this
+everywhere a `new` is followed by a method call.
+
+**Prohibited.** Parentheses around the `new` expression:
+
+```php
+$body = (new ServerRequest(uri: 'https://api.example.com', method: 'GET'))
+    ->withHeader('Accept', 'application/json')
+    ->getBody();
+```
+
+**Correct.** No parentheses:
+
+```php
+$body = new ServerRequest(uri: 'https://api.example.com', method: 'GET')
+    ->withHeader('Accept', 'application/json')
+    ->getBody();
+```
+
+## Duplication
+
+When two or more places share logic, extract it into a collaborator (a value object, or a class
+in `src/Internal/`), or move it onto a collaborator both call sites already depend on. The type
+that owns the data owns the derived behavior.
+
+A shared base class is not available: inheritance between concrete classes is prohibited (see
+"Inheritance and constructors"). A shared private helper is not available either: private methods
+on public classes are prohibited (rule 13). Composition is therefore the only mechanism, and
+leaving the duplication in place is never the resolution.
+
+**Prohibited.** The same derivation copied byte for byte into two types:
+
+```php
+final readonly class Exam
+{
+    public function __construct(public int $score) {}
+
+    public function grade(): Grade
+    {
+        return match (true) {
+            $this->score >= 90 => Grade::A,
+            $this->score >= 80 => Grade::B,
+            $this->score >= 70 => Grade::C,
+            default            => Grade::F
+        };
+    }
+}
+
+final readonly class Assignment
+{
+    public function __construct(public int $score) {}
+
+    public function grade(): Grade
+    {
+        return match (true) {
+            $this->score >= 90 => Grade::A,
+            $this->score >= 80 => Grade::B,
+            $this->score >= 70 => Grade::C,
+            default            => Grade::F
+        };
+    }
+}
+```
+
+**Correct.** The derivation lives once on the collaborator both types hold, and each delegates:
+
+```php
+final readonly class Score
+{
+    public function __construct(public int $value) {}
+
+    public function toGrade(): Grade
+    {
+        return match (true) {
+            $this->value >= 90 => Grade::A,
+            $this->value >= 80 => Grade::B,
+            $this->value >= 70 => Grade::C,
+            default            => Grade::F
+        };
+    }
+}
+
+final readonly class Exam
+{
+    public function __construct(public Score $score) {}
+
+    public function grade(): Grade
+    {
+        return $this->score->toGrade();
+    }
+}
+
+final readonly class Assignment
+{
+    public function __construct(public Score $score) {}
+
+    public function grade(): Grade
+    {
+        return $this->score->toGrade();
+    }
+}
+```
+
+## Polymorphism and tell-don't-ask
+
+This refines rules 9 and 24. A `match` on an enum, on a scalar, or on a value condition stays
+correct. What is prohibited is branching on the runtime type of polymorphic collaborator the
+library defines: when behavior differs across the concrete implementations of an interface the
+library owns, that behavior is a method on the interface, resolved by the object itself, never an
+`instanceof` or `get_class` chain at the call site.
+
+The opening sentence holds only for control flow. When a branch on an enum case yields a value or
+behavior that belongs to the case itself, a token, a flag about the case's nature, or a derived
+value, that value or behavior is a method on the enum: a predicate `isXxx()`, or a vocabulary
+method that returns the value, called at the site instead of comparing the case. Comparing a case
+(`$direction === Order::ASCENDING`, `match ($direction)`) stays correct for control flow whose
+outcome is not a property of the case. This is the enum form of tell-don't-ask, and the companion
+of the modeling rule that enums carry methods only when those methods hold vocabulary meaning (see
+`php-library-modeling.md`, "Enums"): a case that drives a derived value is exactly that vocabulary.
+
+A consumer is outside this rule. A consumer matching on a sealed type the library exposes (for
+example, translating a parsed tree into its own store) cannot add methods to the library's types,
+so its `instanceof` is legitimate. The rule binds the library's own code.
+
+A type the library owns may `instanceof` its own internal types at construction or registration
+time, to invoke behavior that exists only on the concrete type and that cannot be lifted onto a
+public extension interface without breaking external implementers. The minimal public interface
+outweighs the local, build-time type check.
+
+Tell-don't-ask. Behavior that depends on a collaborator's state belongs to the collaborator. Do
+not read a collaborator's fields to recompute a result the collaborator should produce. Ask it for
+the result, not for its parts. A getter exposes a value the caller needs as data, it is not a
+license to reimplement the collaborator's logic at the call site. Tell-don't-ask binds the types
+the library owns. Reading a value off a type the library does not own (a dependency's value object,
+a PSR type) and computing with it is interop, not a violation: the library cannot add a method to a
+type it does not control. The rule still binds the library's own types.
+
+**Prohibited.** Dispatching on the concrete type of interface the library owns:
+
+```php
+return match (true) {
+    $discount instanceof Percentage => $amount->multiplyBy(factor: $discount->rate()),
+    $discount instanceof Fixed      => $amount->subtract(other: $discount->amount())
+};
+```
+
+**Correct.** The behavior is a method on the interface, resolved by the object:
+
+```php
+return $discount->applyTo(amount: $amount);
+```
+
+**Prohibited.** Comparing an enum case to produce a value the case owns:
+
+```php
+$token = match ($direction) {
+    Order::ASCENDING  => '',
+    Order::DESCENDING => '-'
+};
+```
+
+**Correct.** A vocabulary method on the enum returns the value, called at the site:
+
+```php
+enum Order: string
+{
+    case ASCENDING = 'asc';
+    case DESCENDING = 'desc';
+
+    public function token(): string
+    {
+        return match ($this) {
+            self::ASCENDING  => '',
+            self::DESCENDING => '-'
+        };
+    }
+}
+
+$token = $direction->token();
+```
+
+**Prohibited.** Reading a collaborator's parts to recompute what it already owns:
+
+```php
+$doubled = Money::of(amount: $price->amount() * 2, currency: $price->currency());
+```
+
+**Correct.** Telling the collaborator to produce the result:
+
+```php
+$doubled = $price->multiplyBy(factor: 2);
+```
+
+## Return statements
+
+A method has at most three `return` statements. The cap keeps methods small and their control
+flow scannable, and it complements rule 9: early returns are the preferred alternative to `else`,
+but they stop being a simplification once a method accumulates more than three exit points.
+Invariant violations are signaled with a `throw`, not a `return`, so guard clauses usually do not
+add to the count.
+
+**Prohibited.** Four return points:
+
+```php
+public function classify(int $score): Grade
+{
+    if ($score >= 90) {
+        return Grade::A;
+    }
+
+    if ($score >= 80) {
+        return Grade::B;
+    }
+
+    if ($score >= 70) {
+        return Grade::C;
+    }
+
+    return Grade::F;
+}
+```
+
+**Correct.** Single return through `match`:
+
+```php
+public function classify(int $score): Grade
+{
+    return match (true) {
+        $score >= 90 => Grade::A,
+        $score >= 80 => Grade::B,
+        $score >= 70 => Grade::C,
+        default      => Grade::F
+    };
+}
+```
+
+## Formatting overrides
+
+Four formatting rules are not covered by the canonical `phpcs.xml` (which references `PSR-12`
+only). Apply them manually.
+
+### Single-line signatures within 120 characters
+
+A function or constructor signature stays on one line when the whole signature fits within the
+120-character limit. Do not break the parameter list onto multiple lines unless the single-line
+form would exceed 120 characters. The opening brace still goes on its own line (PSR-12). Break to
+one parameter per line only when the signature genuinely overflows.
+
+**Prohibited.** Multiline signature that fits on one line:
+
+```php
+private function __construct(
+    public ExternalReference $id,
+    public Money $amount,
+    public OrderContext $context
+) {
+}
+```
+
+**Correct.** Single line within 120 characters:
+
+```php
+private function __construct(public ExternalReference $id, public Money $amount, public OrderContext $context)
+{
+}
+```
+
+When the one-line form would exceed 120 characters, break to one parameter per line and apply the
+no-vertical-alignment and no-trailing-comma rules below.
+
+### No vertical alignment in parameter lists
+
+Use a single space between the type and the variable name in parameter lists (constructors,
+function signatures, closures). Never pad with extra spaces to align columns. This rule applies
+only to parameter lists, not to other contexts that use `=>` alignment (see "Vertical alignment
+of `=>`" below).
+
+**Prohibited.** Vertical alignment of types:
+
+```php
+public function __construct(
+    public OrderId     $id,
+    public Money       $total,
+    public Customer    $customer,
+    public Precision   $precision
+) {}
+```
+
+**Correct.** Single space between type and variable:
+
+```php
+public function __construct(
+    public OrderId $id,
+    public Money $total,
+    public Customer $customer,
+    public Precision $precision
+) {}
+```
+
+### Vertical alignment of `=>` in match arms and array literals
+
+Multi-line `match` expressions and multi-line array literals with `=>` align the `=>` column
+across all arms or entries by padding shorter left-hand sides with spaces. Single-line cases
+(one-arm match, single-line array) keep the standard PSR-12 single-space form.
+
+**Prohibited.** Unaligned `=>` in match:
+
+```php
+return match ($this) {
+    self::MAX_AGE => sprintf($template, $this->value, $value),
+    default => $this->value
+};
+```
+
+**Correct.** Aligned `=>` in match:
+
+```php
+return match ($this) {
+    self::MAX_AGE => sprintf($template, $this->value, $value),
+    default       => $this->value
+};
+```
+
+**Prohibited.** Unaligned `=>` in array literal:
+
+```php
+return [
+    'name' => 'Gustavo',
+    'role' => 'developer',
+    'company' => 'Anthropic'
+];
+```
+
+**Correct.** Aligned `=>` in array literal:
+
+```php
+return [
+    'name'    => 'Gustavo',
+    'role'    => 'developer',
+    'company' => 'Anthropic'
+];
+```
+
+### No trailing comma in multi-line lists
+
+Never place a trailing comma after the last element of any multi-line list. Applies to parameter
+lists, argument lists, array literals, match arms, and every other comma-separated multi-line
+structure. PHP accepts trailing commas in these positions, but this ecosystem prohibits them for
+visual consistency.
+
+**Prohibited.** Trailing comma after the last argument:
+
+```php
+new Precision(
+    value: 2,
+    rounding: RoundingMode::HALF_UP,
+);
+```
+
+**Correct.** No trailing comma:
+
+```php
+new Precision(
+    value: 2,
+    rounding: RoundingMode::HALF_UP
+);
+```
diff --git a/.claude/rules/php-library-documentation.md b/.claude/rules/php-library-documentation.md
new file mode 100644
index 0000000..a29de61
--- /dev/null
+++ b/.claude/rules/php-library-documentation.md
@@ -0,0 +1,203 @@
+---
+description: Conventions for README and public-facing Markdown docs in PHP libraries.
+paths:
+    - "README.md"
+    - "docs/**/*.md"
+---
+
+# Documentation
+
+Conventions for `README.md` and the public-facing Markdown a library ships. PHPDoc rules for
+`.php` files live in `php-library-code-style.md`. American English applies everywhere (see the
+American English section in `php-library-code-style.md`).
+
+The **canonical bodies** of the non-README repository files (`SECURITY.md`, the issue templates,
+the pull request template) are not duplicated here. They live as drop-in assets in the
+`tiny-blocks-create` skill, the single source of truth for those files. This rule governs how
+the README and any `docs/` Markdown are written. "Required repository files" below lists which
+files must exist and points to the skill for their content.
+
+`CONTRIBUTING.md` is centralized at
+`https://github.com/tiny-blocks/tiny-blocks/blob/main/CONTRIBUTING.md`. Each library's README and
+pull request template link to that location. No local `CONTRIBUTING.md` is created per library.
+
+## Pre-output checklist
+
+Verify every item before producing any Markdown documentation. If any item fails, revise before
+outputting.
+
+1. README title is `# <LibName>` with spaces between words (`# Building Blocks`, not
+   `# BuildingBlocks`).
+2. License badge is the only badge. No build, coverage, Packagist, or version badges.
+3. Header is followed by an anchor-linked table of contents.
+4. Table of contents uses `*` for top-level (H2) entries, `+` indented by 4 spaces for
+   second-level (H3) entries, and `-` indented by 8 spaces for third-level (H4) entries. Every
+   heading from the document appears in the TOC, except FAQ entries: the FAQ is represented by a
+   single `* [FAQ](#faq)` line regardless of how many questions it contains.
+5. Sections appear in the canonical order: Overview, Installation, How to use, FAQ (optional),
+   License, Contributing.
+6. FAQ exists only when there are genuine points of confusion or unusual design decisions. Skip
+   it entirely when not needed.
+7. **Self-contained code examples** are blocks that include any of: a `use` statement, a
+   `class`/`enum`/`interface`/`trait`/`function` declaration, or more than 3 lines of executable
+   code. Self-contained blocks open with `<?php`, a blank line, `declare(strict_types=1);`, and
+   every `use` statement required to compile.
+8. **Inline fragment examples** are blocks with at most 3 lines of executable code, no `use`
+   statements, and no type declarations. Fragments may omit the prologue.
+9. Inline comments in PHP code examples (inside Markdown files) use `#` for single-line.
+   Multi-line comments use consecutive `#` lines, all aligned at the same indentation level.
+   `//` and `/* */` are not used in examples.
+10. Tables are used for structured data such as constructor parameter lists, builder method
+    catalogs, configuration options, or complexity tables. Column layout is chosen per case.
+11. FAQ entries use the heading format `### NN. <Question>?` with zero-padded numbering
+    (`### 01.`, `### 02.`).
+12. FAQ bibliographic citations use the format
+    `> Author, *Title* (Publisher, Year), Chapter X, "Section Name".`
+13. License and Contributing sections each follow the canonical one-line template.
+14. The repository contains the required non-README files listed in "Required repository files",
+    each matching its canonical asset in the `tiny-blocks-create` skill.
+
+## README
+
+### Structure
+
+The README follows a fixed section order:
+
+1. **Overview**. One or more paragraphs explaining the problem the library solves and its design
+   philosophy. Cross-references to related `tiny-blocks` libraries belong here.
+2. **Installation**. Composer command in a code block, with no surrounding prose unless strictly
+   necessary.
+3. **How to use**. Runnable examples covering the primary use cases. Each subsection demonstrates
+   one capability with a heading and a self-contained code block.
+4. **FAQ** (optional). Numbered questions that address real points of confusion or unusual design
+   decisions.
+5. **License**. One-line link to the `LICENSE` file.
+6. **Contributing**. One-line link to the centralized `CONTRIBUTING.md` in
+   `tiny-blocks/tiny-blocks`.
+
+### Header and license badge
+
+The first line is `# <LibName>` followed by a blank line and the license badge:
+
+```markdown
+# Outbox
+
+[![License](https://img.shields.io/badge/license-MIT-green)](https://github.com/tiny-blocks/<lib-name>/blob/main/LICENSE)
+```
+
+Replace `<lib-name>` with the library's repository name. The badge is the only badge in the
+document.
+
+### Table of contents
+
+The table of contents is anchor-linked. Top-level (H2) entries use `*`. Second-level (H3) entries
+use `+` indented by 4 spaces. Third-level (H4) entries use `-` indented by 8 spaces. Every heading
+from the document appears, with one exception: the FAQ is represented by a single
+`* [FAQ](#faq)` line. Its questions never appear as TOC sub-entries, regardless of how many exist.
+
+```markdown
+* [Overview](#overview)
+* [Installation](#installation)
+* [How to use](#how-to-use)
+    + [Subtopic A](#subtopic-a)
+    + [Subtopic B](#subtopic-b)
+* [FAQ](#faq)
+* [License](#license)
+* [Contributing](#contributing)
+```
+
+Use the third level whenever the document has H4 headings. The TOC mirrors the document structure
+exactly.
+
+### Code examples
+
+Code examples fall into two categories.
+
+**Self-contained examples** include at least one of these: a `use` statement, a
+`class`/`enum`/`interface`/`trait`/`function` declaration, or more than 3 lines of executable code.
+They open with `<?php`, a blank line, and `declare(strict_types=1);`, and carry every `use`
+statement required to compile. A reader can copy the block into a file and run it.
+
+```php
+<?php
+
+declare(strict_types=1);
+
+use TinyBlocks\Outbox\DoctrineOutboxRepository;
+use TinyBlocks\Outbox\Serialization\PayloadSerializerReflection;
+use TinyBlocks\Outbox\Serialization\PayloadSerializers;
+
+# Single-line comments use #.
+$repository = new DoctrineOutboxRepository(
+    connection: $connection,
+    payloadSerializers: PayloadSerializers::createFrom(elements: [
+        new PayloadSerializerReflection()
+    ])
+);
+```
+
+**Inline fragment examples** have at most 3 lines of executable code, no `use` statements, and no
+type declarations. Fragments may omit the prologue.
+
+```php
+Code::OK->value;
+```
+
+The criteria are mechanical: a block meeting any self-contained condition gets the prologue. A
+block meeting every fragment condition may omit it. There is no middle ground.
+
+The `#` convention for inline comments applies only to code examples inside Markdown files. PHP
+files under `src/` and `tests/` have no inline comments at all, except `# TODO: <reason>` (see
+rule 16 in `php-library-code-style.md`).
+
+### FAQ
+
+FAQ entries are numbered with zero-padded prefixes and end with a question mark:
+
+```markdown
+### 01. Why is DomainEvent close to a marker interface?
+
+A domain event is a fact about something that happened in the domain. The contract carries only
+`revision()` so the library can route schema migrations through upcasters.
+
+> Vaughn Vernon, *Implementing Domain-Driven Design* (Addison-Wesley, 2013), Chapter 8,
+> "Domain Events".
+```
+
+Bibliographic citations follow `> Author, *Title* (Publisher, Year), Chapter X, "Section Name".`
+The chapter and section fragments are optional when the title is precise enough. Multiple
+citations stack as separate blockquote lines.
+
+### License and Contributing
+
+```markdown
+## License
+
+<LibName> is licensed under [MIT](LICENSE).
+```
+
+```markdown
+## Contributing
+
+Please follow the [contributing guidelines](https://github.com/tiny-blocks/tiny-blocks/blob/main/CONTRIBUTING.md) to
+contribute to the project.
+```
+
+## Structured data
+
+Tables are preferred to prose for any structured information: constructor parameter lists,
+builder method catalogs, default value tables, complexity tables, and configuration matrices.
+Column layout is chosen per case. No fixed column set is mandated.
+
+## Required repository files
+
+In addition to the README, every library repository contains the files below. Their canonical
+bodies are the drop-in assets in the `tiny-blocks-create` skill. This rule only asserts they
+must exist and match those assets.
+
+- `SECURITY.md`: security policy (supported versions, private reporting via GitHub Security
+  Advisories). `<lib-name>` is substituted.
+- `.github/ISSUE_TEMPLATE/bug_report.md`: bug report template (`labels: bug`).
+- `.github/ISSUE_TEMPLATE/feature_request.md`: feature request template (`labels: enhancement`).
+- `.github/PULL_REQUEST_TEMPLATE.md`: pull request template linking the centralized contributing
+  guidelines, with the standard checklist (`composer review` passes, `composer tests` passes).
diff --git a/.claude/rules/php-library-github-workflows.md b/.claude/rules/php-library-github-workflows.md
new file mode 100644
index 0000000..c30d364
--- /dev/null
+++ b/.claude/rules/php-library-github-workflows.md
@@ -0,0 +1,104 @@
+---
+description: Structure, ordering, and pinning conventions for GitHub Actions workflows in PHP libraries.
+paths:
+    - ".github/workflows/**/*.yml"
+    - ".github/workflows/**/*.yaml"
+---
+
+# Workflows
+
+Conventions for GitHub Actions workflows in PHP libraries. CD does not apply: libraries publish to
+Packagist via tags and never deploy.
+
+The **canonical `ci.yml` body** is not duplicated here. It lives as a drop-in asset in the
+`tiny-blocks-create` skill (`assets/github/workflows/ci.yml`), the single source of truth. This
+rule defines the conventions that asset satisfies and that any edit to a workflow must preserve.
+
+`ci.yml` is mandatory. Additional workflow files (security scanning, automated triage, scheduled
+tasks, dependency updates) may exist and follow the general rules below. Their trigger, job
+structure, and steps are chosen by their purpose. The Composer scripts invoked by `ci.yml`
+(`composer review`, `composer tests`) are defined in `php-library-tooling.md`.
+
+## Pre-output checklist
+
+Verify every item before producing or editing any workflow YAML. If any item fails, revise before
+outputting.
+
+### Rules for every workflow
+
+Apply to `ci.yml` and to every additional workflow in `.github/workflows/`.
+
+1. Keys at the workflow root follow the canonical order `name`, `on`, `concurrency`,
+   `permissions`, `jobs`. Absent keys are omitted. The relative order of the rest is preserved.
+2. Properties inside a job follow the canonical order `name`, `needs`, `runs-on`,
+   `timeout-minutes`, `outputs`, `env`, `steps`. Same omission rule.
+3. Inside any block (`env`, `outputs`, `with`, `permissions`), entries are ordered by key length
+   ascending.
+4. The workflow `name`, every job `name`, and every step `name` are mandatory and use sentence
+   case (`Resolve PHP version`, not `RESOLVE_PHP_VERSION`). Step names start with a verb. Job keys
+   describe the job's purpose. Generic keys (`run`, `job`, `do`) are discouraged in favor of
+   descriptive identifiers (`auto-assign`, `analyze`, `notify`).
+5. `concurrency` is set at the workflow root with `cancel-in-progress: true` and a `group`
+   expression scoped by the workflow's trigger, prefixed by the workflow's short purpose name
+   (`ci`, `codeql`, `auto-assign`):
+    - `pull_request`: `<purpose>-${{ github.event.pull_request.number }}`.
+    - `issues`, or `issues` combined with `pull_request`:
+      `<purpose>-${{ github.event.issue.number || github.event.pull_request.number }}`.
+    - `push`, `schedule`, or both: `<purpose>-${{ github.ref }}`.
+6. `permissions` is declared at the workflow root with the minimum scope every job needs.
+   Job-level `permissions` are allowed only when a specific job needs a narrower scope than the
+   root, never broader.
+7. Every job sets `timeout-minutes`. Defaults: 5 for trivial steps (single API call, lightweight
+   script), 15 for jobs with PHP setup or test runs, 30 for analysis-heavy jobs (CodeQL, security
+   scanning). Adjust based on observed runtime when prior runs exist.
+8. Every action is pinned to a fixed, immutable ref: a version tag at any granularity (major, minor, or patch) or a
+   commit SHA. Moving refs (branch names such as @main/@master, or @v with no version) are prohibited. Do not normalize
+   an explicit minor or patch pin down to its major, preserve the granularity the maintainer chose.
+9. Inline shell logic longer than 3 lines is extracted to a script in `scripts/ci/`.
+10. All text (workflow name, job names, step names, comments) uses American English with correct
+    spelling and punctuation. Sentences and descriptions end with a period.
+
+### Rules specific to ci.yml
+
+Apply only to `.github/workflows/ci.yml`. Additional workflows are not bound by them.
+
+1. File path is `.github/workflows/ci.yml`. The workflow `name` field is exactly `CI`. Per rule 5
+   for every workflow, with purpose `ci` and a `pull_request` trigger, `concurrency.group` is
+   `ci-${{ github.event.pull_request.number }}`.
+2. Trigger is `pull_request` only. No `push`, no branch filter, no `workflow_dispatch`.
+3. Jobs run in the fixed sequence `resolve-php-version`, `build`, `auto-review`, `tests`. Each
+   downstream job lists its upstream jobs in `needs`.
+4. PHP version is never hardcoded. The `resolve-php-version` job reads `.require.php` from
+   `composer.json` at runtime and exposes the minor version (for example, `8.5`) as the job
+   output `php-version`. Downstream jobs reference
+   `${{ needs.resolve-php-version.outputs.php-version }}` when setting up PHP.
+5. The `auto-review` job runs `composer review`. The `tests` job runs `composer tests`. No other
+   command is invoked in either job.
+6. The `build` job uploads `vendor/` and `composer.lock` as a single artifact named
+   `vendor-artifact`. The `auto-review` and `tests` jobs download that artifact instead of
+   running `composer install` again.
+7. The `tests` job is the only job that may extend with extra setup the library needs (service
+   containers, fixture preparation, environment variables used during testing). The other three
+   jobs are identical across every library in the ecosystem.
+8. `timeout-minutes` is 5 for `resolve-php-version` and 15 for `build`, `auto-review`, and
+   `tests`. `permissions` is `contents: read`.
+
+## ci.yml job sequence
+
+`ci.yml` gates every pull request with four jobs in this exact order. The first three are
+identical across every library. Only `tests` may extend.
+
+- **Resolve PHP version.** Reads `.require.php` from `composer.json` and exposes the minor version
+  as the output `php-version`. A single step uses `jq` and a short regex to extract the value.
+- **Build.** Sets up PHP using the resolved version, validates `composer.json`, installs with
+  `--no-progress --optimize-autoloader --prefer-dist --no-interaction`, and uploads `vendor/` and
+  `composer.lock` as `vendor-artifact`.
+- **Auto review.** Needs `resolve-php-version` and `build`. Downloads `vendor-artifact`, sets up
+  PHP, runs `composer review` (phpcs + phpstan).
+- **Tests.** Needs `resolve-php-version` and `auto-review`. Downloads `vendor-artifact`, sets up
+  PHP, runs `composer tests` (phpunit + infection). Library-specific test setup lives in this job
+  only.
+
+To extend the `tests` job (external services, env vars, fixtures), the additions go inside the
+`tests` job exclusively. The skill asset includes an extended example with a MySQL service
+container.
diff --git a/.claude/rules/php-library-modeling.md b/.claude/rules/php-library-modeling.md
new file mode 100644
index 0000000..a587b54
--- /dev/null
+++ b/.claude/rules/php-library-modeling.md
@@ -0,0 +1,314 @@
+---
+description: Semantic modeling rules for PHP libraries (nomenclature, value objects, exceptions, enums, extension points, complexity).
+paths:
+    - "src/**/*.php"
+---
+
+# Modeling
+
+Library modeling rules. How to model the concepts the library exposes. Folder structure and
+public API boundary live in `php-library-architecture.md`. Code style lives in
+`php-library-code-style.md`. Tooling lives in `php-library-tooling.md`.
+
+## Pre-output checklist
+
+Verify every item before producing any PHP code that defines a model, an exception, or an
+algorithm. If any item fails, revise before outputting.
+
+1. Each model has a single, clear responsibility. Apply DDD, SOLID, DRY, and KISS where they
+   sharpen the design, not as dogma.
+2. Concept names. Every class, property, method, and exception name reflects the concept the
+   library represents, not a technical role.
+3. No always-banned names. Never use `Data`, `Info`, `Utils`, `Item`, `Record`, `Entity` as
+   class suffix, prefix, or method name. Never use `Exception` as a class suffix. Exception:
+   names that correspond to externally standardized identifiers (HTTP status text from RFC
+   documents, PSR interface names being mirrored, etc.) are permitted. The standard reference
+   is the meaning carrier.
+4. No anemic verbs as the primary operation name (`ensure`, `validate`, `check`, `verify`,
+   `assert`, `mark`, `enforce`, `sanitize`, `normalize`, `compute`, `transform`, `parse`) unless
+   the verb is the library's reason to exist.
+5. Architectural role names (`Manager`, `Handler`, `Processor`, `Service`, and their verb forms
+   `process`, `handle`, `execute`) are allowed only when the class IS that role for consumers
+   integrating with the library.
+6. Value objects are immutable. No setters. Operations return new instances.
+7. Value objects compare by value, never by reference. No identity field.
+8. Value objects validate invariants in the constructor and throw a dedicated exception on
+   invalid input.
+9. Value objects with multiple creation paths use static factory methods (`from`, `of`, `zero`)
+   with a private constructor.
+10. Every failure throws a dedicated exception class named after the invariant it guards. Never
+    `throw new DomainException(...)`, `throw new InvalidArgumentException(...)`, or any other
+    generic native exception directly.
+11. Dedicated exception classes extend the appropriate native PHP exception (`DomainException`,
+    `InvalidArgumentException`, `OverflowException`, etc.).
+12. Exceptions are pure. No transport-specific fields (HTTP status in `code`, formatted message
+    for end-user display). They signal invariant violations only, never control flow.
+13. Enums are PHP backed enums. They include methods only when those methods carry vocabulary
+    meaning. A value or behavior a case owns lives on the enum as that method, called instead of a
+    `match` on the case at the site. See "Polymorphism and tell-don't-ask" in
+    `php-library-code-style.md`.
+14. Extension points use `class` instead of `final readonly class`. They expose a private
+    constructor with static factory methods as the only creation path. Internal state is
+    injected via the constructor.
+15. Algorithms run in O(N) or O(N log N) unless the problem inherently requires worse. O(N²)
+    or worse needs explicit justification.
+16. Prefer lazy or streaming evaluation over materializing intermediate results. Memory usage
+    is bounded and proportional to the output, not to the sum of intermediate stages.
+17. A configuration-like value object whose fields are mostly optional exposes a no-argument
+    baseline factory (`default()`) plus fluent immutable `with*` copies, not a single factory
+    whose signature lists every field. See "Value objects".
+
+## Modeling principles
+
+Apply the following principles where they sharpen the design. Treat them as guides, not as dogma.
+
+- Single responsibility. Each model represents one concept, has one reason to change, and
+  exposes operations that belong to that concept.
+- DDD ubiquitous language. Names, types, and operations match the vocabulary the library's
+  domain uses. Code and conversation share the same terms.
+- SOLID. Interfaces define narrow contracts. Composition is preferred to inheritance.
+  Substitutability holds at every interface boundary.
+- DRY. No duplicated logic across two or more places. See "Duplication" in
+  `php-library-code-style.md` for how to resolve it without inheritance or private helpers.
+- KISS. No abstraction without real duplication or isolation need.
+
+## Nomenclature
+
+- Every class, property, method, and exception name reflects the concept the library represents.
+  A math library uses `Precision` and `RoundingMode`. A money library uses `Currency` and
+  `Amount`. A collection library uses `Collectible` and `Order`.
+- Name classes after what they represent, not after what they do technically. Use `Money`,
+  `Color`, `Pipeline`, not `MoneyCalculator`, `ColorHelper`, `PipelineProcessor`.
+- Name methods after the operation in the library's vocabulary. Use `add()`, `convertTo()`,
+  `splitAt()`, not `compute()`, `process()`, `handle()`.
+
+### Always banned
+
+These names carry zero semantic content. Never use them anywhere as class suffix, prefix, or
+method name.
+
+- `Data`, `Info`, `Utils`, `Item`, `Record`, `Entity`.
+- `Exception` as a class suffix (e.g., `FooException`). Use the invariant name when extending a
+  native exception (e.g., `PrecisionOutOfRange`, not `InvalidPrecisionException`).
+
+### Externally standardized names (exception to the banlist)
+
+Names that correspond to externally standardized identifiers are exempt from the banlist. The
+standard reference is the meaning carrier. Renaming weakens it. Examples:
+
+- HTTP status text from RFC documents (`unprocessableEntity` from RFC 4918, `noContent`).
+- PSR interface names being mirrored as test doubles (`ClientException` mirroring
+  `Psr\Http\Client\ClientExceptionInterface`).
+- Unicode category names, locale identifiers, MIME type tokens, and similar registered names.
+
+This exception applies only when the external standard is the actual source of the name. It
+does not authorize using `Data` or `Entity` as generic suffixes when no external reference is
+involved.
+
+### Anemic verbs
+
+These verbs hide what is actually happening behind a generic action. Banned unless the verb IS
+the operation that constitutes the library's reason to exist (e.g., a JSON parser may have
+`parse()`, a hashing library may have `compute()`).
+
+- `ensure`, `validate`, `check`, `verify`, `assert`, `mark`, `enforce`, `sanitize`, `normalize`,
+  `compute`, `transform`, `parse`.
+
+When in doubt, prefer the domain operation name. `Password::hash()` beats `Password::compute()`.
+`Email::parse()` is fine in a parser library but suspicious elsewhere. Use `Email::from()`
+instead.
+
+### Architectural roles
+
+These names describe a role the library offers as a building block. Acceptable when the class IS
+that role (e.g., `EventHandler` in an events library, `CacheManager` in a cache library,
+`Upcaster` in an event-sourcing library). Not acceptable on domain objects inside the library
+(value objects, enums, contract interfaces).
+
+- `Manager`, `Handler`, `Processor`, `Service`.
+- Verb forms: `process`, `handle`, `execute`.
+
+The test. If the consumer instantiates or extends this class to integrate with the library, the
+role name is legitimate. If the class models a concept the consumer manipulates (a money amount,
+a country code, a color), the role name is wrong.
+
+**Scope.** The architectural-role banlist and the anemic-verb banlist apply to the **public
+surface**: types at the `src/` root, types in public `<ConceptGroup>/` folders, and public
+exception and contract names. Inside `src/Internal/` (implementation detail by definition, where
+the namespace is the boundary), a collaborator may carry a mechanical role or operation name that
+describes its job (`Decoder`, `Encoder`, `Parser`, `Resolver`), since consumers never see or
+manipulate it. The always-banned names (`Data`, `Info`, `Utils`, `Item`, `Record`, `Entity`)
+remain banned everywhere, `Internal/` included.
+
+## Value objects
+
+- Are immutable. No setters. No mutation after construction. Operations return new instances.
+- Compare by value, not by reference.
+- Validate invariants in the constructor and throw a dedicated exception on invalid input.
+- Have no identity field.
+- Use static factory methods (`from`, `of`, `zero`) with a private constructor when multiple
+  creation paths exist. The factory name communicates the semantic intent.
+
+**Prohibited.** Public constructor with multiple creation paths. Semantics are unclear at the
+call site:
+
+```php
+final readonly class Money
+{
+    public function __construct(public int $amount, public Currency $currency) {}
+}
+
+new Money(amount: 1000, currency: Currency::BRL);
+new Money(amount: 0, currency: Currency::USD);
+```
+
+**Correct.** Private constructor with named factory methods. Each factory name communicates
+intent:
+
+```php
+final readonly class Money
+{
+    private function __construct(public int $amount, public Currency $currency) {}
+
+    public static function of(int $amount, Currency $currency): Money
+    {
+        return new Money(amount: $amount, currency: $currency);
+    }
+
+    public static function zero(Currency $currency): Money
+    {
+        return new Money(amount: 0, currency: $currency);
+    }
+}
+
+Money::of(amount: 1000, currency: Currency::BRL);
+Money::zero(currency: Currency::USD);
+```
+
+When a value object is configuration-like and most of its fields are optional with defaults, prefer
+a baseline factory that takes no required arguments (`default()`, or `from()` with every parameter
+defaulted) together with fluent immutable `with*` copies, over a single factory whose signature
+carries every field. Each `with*` returns a new instance. Prefer the `with*` methods on the value
+object itself over a separate mutable builder class: the value object is already immutable, so it
+is its own builder. The smell is a factory signature that lists every field while most are
+optional.
+
+**Prohibited.** A single factory whose signature carries every field, most of them optional:
+
+```php
+MoneyFormat::from(scale: 4, symbol: '€', grouping: ',');
+```
+
+**Correct.** A baseline `default()` plus fluent `with*` copies that override only what differs:
+
+```php
+MoneyFormat::default()->withScale(scale: 4)->withGrouping(grouping: ',');
+```
+
+## Exceptions
+
+- Every failure throws a dedicated exception class named after the invariant it guards. Never
+  `throw new DomainException(...)`, `throw new InvalidArgumentException(...)`,
+  `throw new RuntimeException(...)`, or any other generic native exception directly. If the
+  invariant is worth throwing for, it is worth a named class.
+- Dedicated exception classes extend the appropriate native PHP exception (`DomainException`,
+  `InvalidArgumentException`, `OverflowException`, etc.). The native class is the parent, never
+  the thing that is thrown. Consumers that catch the broad standard types continue to work.
+  Consumers that need precise handling can catch the specific classes.
+- Exceptions are pure. No transport-specific fields (`code` populated with HTTP status,
+  formatted `message` meant for end-user display). Formatting to any transport happens at the
+  consumer's boundary, not inside the library.
+- Exceptions signal invariant violations only, not control flow.
+- Name the class after the invariant violated, never after the technical type. Use
+  `PrecisionOutOfRange`, not `InvalidPrecisionException`. Use `CurrencyMismatch`, not
+  `BadCurrencyException`. Use `ContainerWaitTimeout`, not `TimeoutException`.
+- A descriptive `message` argument is allowed and encouraged when it carries debugging context
+  (the violating value, the boundary crossed, the state the library was in). The class name
+  identifies the invariant. The message describes the specific violation for stack traces and
+  test assertions. Keep messages short, factual, and in American English.
+
+**Prohibited.** Throwing a native exception directly:
+
+```php
+if ($value < 0) {
+    throw new InvalidArgumentException('Precision cannot be negative.');
+}
+```
+
+**Correct.** Dedicated class, no message (class name is sufficient):
+
+```php
+final class PrecisionOutOfRange extends InvalidArgumentException
+{
+}
+
+if ($value < 0) {
+    throw new PrecisionOutOfRange();
+}
+```
+
+**Correct.** Dedicated class with debugging context in the message:
+
+```php
+if ($value < 0 || $value > 16) {
+    $template = 'Precision must be between 0 and 16, got %d.';
+
+    throw new PrecisionOutOfRange(message: sprintf($template, $value));
+}
+```
+
+## Enums
+
+- Are PHP backed enums.
+- Include methods only when those methods carry vocabulary meaning. Examples are
+  `OrderStatus::isFinal()` and `RoundingMode::apply()`.
+- A value or behavior a case owns (a token, a flag, a derived value) is one of those vocabulary
+  methods, a predicate `isXxx()` or a method returning the value, called at the site instead of a
+  `match` comparing the case. This is the enum form of tell-don't-ask. See "Polymorphism and
+  tell-don't-ask" in `php-library-code-style.md`.
+
+## Extension points
+
+- A class designed to be extended by consumers (e.g., `Collection`, `ValueObject`) uses `class`
+  instead of `final readonly class`. All other classes use `final readonly class`. See
+  "Inheritance and constructors" in `php-library-code-style.md`.
+- Extension point classes use a private constructor with static factory methods (`createFrom`,
+  `createFromEmpty`) as the only creation path.
+- Internal state is injected via the constructor and stored in a `private readonly` property.
+
+## Time and space complexity
+
+- Algorithms run in O(N) or O(N log N) unless the problem inherently requires worse. O(N²) or
+  worse needs explicit justification at the point of definition.
+- Prefer lazy or streaming evaluation over materializing intermediate results. In pipeline-style
+  libraries, fuse stages so a single pass suffices over the input.
+- Memory usage is bounded and proportional to the output, not to the sum of intermediate stages.
+- Never re-iterate the same source. When a sequence is consumed once, use lazy creation
+  primitives (`createLazyFrom`) instead of materializing.
+
+**Prohibited.** Eager pipeline that materializes between stages:
+
+```php
+$paidTotals = array_map(
+    static fn(Order $order): float => $order->total(),
+    array_filter(
+        $orders->toArray(),
+        static fn(Order $order): bool => $order->isPaid()
+    )
+);
+```
+
+Each stage allocates a full intermediate array. Memory grows with the input size, even when only
+the final scalar matters.
+
+**Correct.** Fused pipeline that runs in a single pass:
+
+```php
+$paidTotals = $orders
+    ->filter(predicates: static fn(Order $order): bool => $order->isPaid())
+    ->map(transformations: static fn(Order $order): float => $order->total())
+    ->toArray(keyPreservation: KeyPreservation::DISCARD);
+```
+
+Operations stack on the same iterator. No intermediate array is built. Memory stays bounded by
+the final output.
diff --git a/.claude/rules/php-library-testing.md b/.claude/rules/php-library-testing.md
new file mode 100644
index 0000000..30a329f
--- /dev/null
+++ b/.claude/rules/php-library-testing.md
@@ -0,0 +1,372 @@
+---
+description: BDD Given/When/Then structure, PHPUnit conventions, fixture rules, and coverage discipline.
+paths:
+    - "tests/**/*.php"
+---
+
+# Testing
+
+PHPUnit conventions for tests in PHP libraries. Covers BDD structure, fixture rules, and coverage
+discipline. Code style applies to test files as well. See `php-library-code-style.md`. Folder
+structure for `tests/` lives in `php-library-architecture.md`. Canonical thresholds (MSI 100,
+covered MSI 100) live in `php-library-tooling.md`.
+
+## Pre-output checklist
+
+Verify every item before producing any test code. If any item fails, revise before outputting.
+
+1. Each test contains exactly one `@When` block. Two actions require two tests.
+2. Use `@And` for complementary preconditions or actions within the same scenario, avoiding
+   consecutive `@Given` or `@When` tags.
+3. Each `@Given` or `@And` block contains exactly one annotation line followed by one expression
+   or assignment. Never place multiple variable declarations or object constructions under a
+   single annotation. **Exception for data-provider tests.** When the test method binds its
+   inputs through a `#[DataProvider]` attribute (or the equivalent `@dataProvider` annotation),
+   the `@Given` block may declare the input shape in prose form, without an expression below
+   it. The values are bound by PHPUnit before the test body runs, so the prose annotation
+   replaces the assignment that would otherwise sit under the `@Given`.
+
+   `@When` blocks follow the same one-expression rule by default: the block represents the
+   single action under test. **Exception for repeated-invocation tests** (idempotence, caching,
+   memoization). When the purpose of the test is asserting that the same operation produces the
+   same outcome across N invocations, the `@When` block may contain N consecutive identical
+   invocations, each captured in a numbered variable (`$first`, `$second`, ...), and the
+   annotation reads `@When invoked twice` (or thrice, etc.) to make the composite-action
+   semantic explicit. Two unrelated actions still require two tests.
+4. No intermediate variables used only once. Chain method calls when the intermediate state is
+   not referenced elsewhere (e.g., `Money::of(...)->add(...)` instead of
+   `$money = Money::of(...)` followed by `$money->add(...)`).
+5. No private or helper methods in test classes. The only non-test methods allowed are PHPUnit
+   lifecycle hooks (`setUp`, `setUpBeforeClass`, `tearDown`, `tearDownAfterClass`) and data
+   providers. Setup logic complex enough to extract belongs in a dedicated fixture class.
+6. Test only the public API. Never assert on private state or `Internal/` classes directly.
+   One narrow, last-resort exception covers irreducible internal elements. See "White-box
+   coverage of irreducible internals".
+7. Test the behavior that **raises** an exception, never the exception itself. Exception classes
+   represent invariant violations and are value objects, not the subject of behavior tests. A
+   test constructs the conditions, invokes the public method that is supposed to fail, and
+   asserts the expected exception class is raised (plus its accessor values when they carry
+   information relevant to the failure). Constructing an exception directly
+   (`new HttpRequestInvalid(...)`) and asserting on its accessors is **prohibited**: the
+   exception's structure is exercised through the call path that produces it. If a method does
+   not exist whose call path produces the exception, the exception is dead code and should be
+   removed.
+8. Never mock internal collaborators. Use real objects. Test doubles are used only at system
+   boundaries (filesystem, clock, network) when the library interacts with external resources.
+9. Name tests after behavior using the `testXxxWhenYyyThenZzz` shape, never after the method
+   under test. `Xxx` names the subject or operation, `Yyy` the condition, `Zzz` the expected
+   outcome (for example, `testAddMoneyWhenSameCurrencyThenAmountsAreSummed`). The `When`/`Then`
+   structure is mandatory. The `@Given`/`@When`/`@Then`/`@And` annotation blocks describe the
+   steps within. A condition-free operation may collapse to `testXxxThenZzz` when there is no
+   meaningful precondition to name.
+10. Use domain-specific names in variables and properties. Never `$spy`, `$mock`, `$stub`,
+    `$fake`, `$dummy` as variable or property names. Use the domain concept the object
+    represents (`$collection`, `$amount`, `$currency`, `$sortedElements`). Class names like
+    `ClientMock` or `GatewaySpy` are acceptable. The variable holding the instance is what matters.
+11. Annotations use domain language. Write `/** @Given a collection of amounts */`, not
+    `/** @Given a mocked collection in test state */`.
+12. Never use the `/** @test */` annotation. Test methods are discovered by the `test` prefix in
+    the method name.
+13. Named arguments are never used on PHPUnit assertions and expectations. Arguments are passed
+    positionally. The canonical rule and its full exclusion list live in
+    `php-library-code-style.md` rule 4.
+14. Never include conditional logic inside tests. Each `@Then` block expresses one logical
+    concept. The only allowed `try`/`catch` is when the assertion target is a property of the
+    caught exception that cannot be expressed via `expectException*` methods (notably
+    `getPrevious()` for chain inspection). The catch block contains only assertions against the
+    caught exception, no branching.
+15. Never use `@codeCoverageIgnore`, attributes, or configuration that exclude code from
+    coverage. Never suppress mutants via `infection.json.dist` or any other mechanism. See
+    "Coverage and mutation discipline".
+16. Member ordering in test classes follows `php-library-code-style.md` rule 6 (PHPUnit
+    test-class sub-grouping).
+
+## Generics in test PHPDoc
+
+The "zero PHPDoc anywhere inside `tests/`" rule (defined in `php-library-code-style.md`) has one
+narrow exception: PHPDoc that exists *purely to express generics* the native type system cannot.
+A test fixture that extends a generic public type carries the type argument with `@extends` (for
+example `@extends Collection<Invoice>` on an `Invoices` fixture), and a generics-only `@var` may
+pin a type parameter at an inference point where an imprecise result feeds a typed sink (for
+example `/** @var Collection<Shipment> $shipments */` before passing a mapped collection to
+`Shipments::createFrom(...)`). These tags carry only the type-parameter information, never a
+summary or prose description. Every other form of PHPDoc (summaries, `@param`/`@return`
+descriptions on test methods, fixtures, data providers, or anonymous classes) stays prohibited.
+This is the same carve-out stated in `php-library-code-style.md` under "When prohibited",
+restated here because it most often surfaces on collection fixtures and inference points in
+`tests/`.
+
+## Structure: Given/When/Then (BDD)
+
+Every test uses `/** @Given */`, `/** @And */`, `/** @When */`, `/** @Then */` doc comments
+without exception.
+
+### Happy path example
+
+```php
+public function testAddMoneyWhenSameCurrencyThenAmountsAreSummed(): void
+{
+    /** @Given two money instances in the same currency */
+    $ten = Money::of(amount: 1000, currency: Currency::BRL);
+
+    /** @And another money instance with the same currency */
+    $five = Money::of(amount: 500, currency: Currency::BRL);
+
+    /** @When adding them together */
+    $total = $ten->add(other: $five);
+
+    /** @Then the result contains the sum of both amounts */
+    self::assertEquals(1500, $total->amount());
+}
+```
+
+### Exception example
+
+When testing that an exception is thrown, place `@Then` (`expectException`) before `@When`.
+PHPUnit requires this ordering.
+
+```php
+public function testAddMoneyWhenDifferentCurrenciesThenCurrencyMismatch(): void
+{
+    /** @Given two money instances in different currencies */
+    $brl = Money::of(amount: 1000, currency: Currency::BRL);
+
+    /** @And another money instance with a different currency */
+    $usd = Money::of(amount: 500, currency: Currency::USD);
+
+    /** @Then an exception indicating currency mismatch should be thrown */
+    $this->expectException(CurrencyMismatch::class);
+
+    /** @When trying to add money with different currencies */
+    $brl->add(other: $usd);
+}
+```
+
+## Testing exceptions
+
+Exception classes are value objects describing an invariant violation. They are not the subject
+of behavior tests. A test verifies that a public method, under specific conditions, raises a
+specific exception. Constructing the exception directly and asserting on its accessors is
+prohibited. The exception's structure is exercised through the call path that produces it.
+
+**Prohibited.** Testing the exception as a value object:
+
+```php
+public function testFromWhenAllFieldsGivenThenExposesEveryAccessor(): void
+{
+    /** @Given a URL */
+    $url = 'https://api.example.com';
+
+    /** @And an HTTP method */
+    $method = Method::GET;
+
+    /** @And a reason */
+    $reason = 'Connection refused.';
+
+    /** @When the exception is constructed */
+    $exception = HttpNetworkFailed::from(url: $url, method: $method, reason: $reason);
+
+    /** @Then it exposes the URL */
+    self::assertSame($url, $exception->url());
+}
+```
+
+The test constructs the exception in isolation and asserts on its accessors. No production code
+is exercised. The same coverage is achieved (and made meaningful) by the test below, which
+drives the path that raises the exception.
+
+**Correct.** Testing the behavior that raises the exception:
+
+```php
+public function testSendRequestWhenTransportCannotReachServerThenThrowsHttpNetworkFailed(): void
+{
+    /** @Given an HTTP client backed by a transport that always raises a network error */
+    $http = Http::usingTransport(transport: new ThrowingClient());
+
+    /** @And a target request to that transport */
+    $request = Request::create(url: 'https://api.example.com', method: Method::GET);
+
+    /** @Then a network failure exception describing the unreachable target is raised */
+    $this->expectException(HttpNetworkFailed::class);
+
+    /** @When the request is sent */
+    $http->send(request: $request);
+}
+```
+
+When the accessor values on the raised exception are part of the assertion, `expectException`
+alone is not enough (it asserts only the class). Use a `try`/`catch` block as permitted by
+rule 14. The catch block contains only assertions against the caught exception, no branching.
+
+```php
+public function testSendRequestWhenTargetUnreachableThenExceptionCarriesUrlAndMethod(): void
+{
+    /** @Given an HTTP client backed by a transport that always raises a network error */
+    $http = Http::usingTransport(transport: new ThrowingClient());
+
+    /** @And a target request to that transport */
+    $request = Request::create(url: 'https://api.example.com', method: Method::GET);
+
+    try {
+        /** @When the request is sent */
+        $http->send(request: $request);
+    } catch (HttpNetworkFailed $failure) {
+        /** @Then the exception exposes the target URL and method */
+        self::assertSame('https://api.example.com', $failure->url());
+        self::assertSame(Method::GET, $failure->method());
+    }
+}
+```
+
+If a method does not exist whose call path produces the exception, the exception itself is dead
+code. Remove it instead of writing a behavior test against a constructor.
+
+**The `try`/`catch` form is reserved for assertions that PHPUnit's `expectException*` family
+does not cover.** Message, code, and class are covered by PHPUnit (`expectException`,
+`expectExceptionMessage`, `expectExceptionMessageMatches`, `expectExceptionCode`): use those
+methods, not `try`/`catch`. The only case that warrants `try`/`catch` is inspecting accessors
+that PHPUnit cannot reach, notably `getPrevious()` for chain inspection, or domain-specific
+accessors on a `HttpNetworkFailed` (`url()`, `method()`, `reason()`).
+
+**Prohibited.** `try`/`catch` to assert message:
+
+```php
+try {
+    $http->send(request: $request);
+    self::fail('NoMoreResponses was expected.');
+} catch (NoMoreResponses $exception) {
+    self::assertStringContainsString('queue exhausted', $exception->getMessage());
+}
+```
+
+**Correct.** PHPUnit's `expectExceptionMessage`:
+
+```php
+$this->expectException(NoMoreResponses::class);
+$this->expectExceptionMessage('queue exhausted');
+
+$http->send(request: $request);
+```
+
+## Test setup and fixtures
+
+Checklist items 3, 4, 5, 10, and 11 govern setup blocks: one declaration per annotation, no
+single-use intermediate variables, no private or helper methods, domain-named variables, and
+domain-language annotations. The examples below illustrate the rules most often violated in
+practice. Double naming (the `$spy`/`$mock` banlist and the class-name suffix nuance) is detailed
+in "Test doubles" below.
+
+**Prohibited.** Multiple declarations under a single annotation:
+
+```php
+/** @And two money instances in different currencies */
+$usd = Money::of(amount: 500, currency: Currency::USD);
+$eur = Money::of(amount: 300, currency: Currency::EUR);
+```
+
+**Correct.** One annotation per declaration:
+
+```php
+/** @And a money instance in USD */
+$usd = Money::of(amount: 500, currency: Currency::USD);
+
+/** @And a money instance in EUR */
+$eur = Money::of(amount: 300, currency: Currency::EUR);
+```
+
+**Also prohibited.** Setup multi-statement grouped under a single annotation because "the
+statements build one coherent concept":
+
+```php
+/** @Given transport seeded with two responses */
+$first = Response::with(code: Code::OK);
+$second = Response::with(code: Code::CREATED);
+$transport = InMemoryTransport::with(responses: [$first, $second]);
+```
+
+Three statements, one annotation. The fact that the three lines together build a single
+setup concept is **not** a license to share one annotation. Each declaration takes its own
+`@And` block. The same applies under `@When` when the test prepares the input alongside the
+action: the input preparation goes back to `@And` under `@Given`, and `@When` contains only
+the action under test.
+
+**Correct.** Each statement keeps its own annotation:
+
+```php
+/** @Given a first queued response */
+$first = Response::with(code: Code::OK);
+
+/** @And a second queued response */
+$second = Response::with(code: Code::CREATED);
+
+/** @And transport with both responses */
+$transport = InMemoryTransport::with(responses: [$first, $second]);
+```
+
+## Test doubles
+
+Conventions for naming and locating test doubles (mocks, spies, stubs, fakes, dummies).
+
+### Naming
+
+- Variables and properties never carry the technical role in their name. Never `$spy`, `$mock`,
+  `$stub`, `$fake`, `$dummy`. Use the domain concept the object represents (`$gateway`,
+  `$clock`, `$repository`, `$client`).
+- Class names may carry the technical role as suffix when the class IS a test double
+  (`ClientMock`, `GatewaySpy`, `ClockFake`). The suffix signals that the file is a collaborator
+  built for tests, not a production type.
+
+### Location
+
+- Test doubles live at the root of `tests/Unit/`. When integration tests exist, doubles used
+  there live at the root of `tests/Integration/`.
+- No dedicated `Mocks/` or `Doubles/` subdirectory exists.
+- Domain fixtures that represent real domain concepts live in `tests/Models/`. See
+  `php-library-architecture.md` for the canonical `tests/` folder layout.
+
+## Coverage and mutation discipline
+
+- Never use `@codeCoverageIgnore`, attributes, or configuration that exclude code from coverage.
+- Never suppress mutants via `infection.json.dist` or any other mechanism.
+- If a line or mutation cannot be covered or killed, the design is wrong. Refactor the
+  production code to make it testable. Never work around the tool.
+- The sole exception is an irreducible internal element (a non-functional memoization
+  cache, or the private constructor of a static-only surface) that cannot be reached
+  publicly without harming the design. It is covered or killed through a reflection-based
+  white-box test, never through suppression. See "White-box coverage of irreducible
+  internals".
+
+Canonical thresholds (MSI 100, covered MSI 100) live in `php-library-tooling.md`. They are
+enforced by `infection.json.dist`. Achieving MSI 100 implies effective full coverage of `src/`
+because every mutation must be killed by an assertion. This file covers only the behavioral
+rules that complement those thresholds.
+
+## White-box coverage of irreducible internals
+
+Rules 6 and 15 are near-absolute: tests exercise the public API, refactoring is the response
+when a line or mutation resists coverage, and code is never hidden from coverage or mutation.
+They yield in one narrow case: an *irreducible* internal element that cannot be reached
+through the public API without either removing a legitimate non-functional optimization or
+defeating a deliberate design. Two such elements recur:
+
+- **Memoization caches.** A purely non-functional cache (a resolved-mapping cache, a
+  shared-instance cache, a reflection-descriptor cache) whose removal leaves behavior
+  identical. The mutant that drops the cache is an equivalent mutant: no public observation
+  distinguishes the cached path from the recomputed one, so no public-API test can kill it.
+- **Intentionally-uncallable members.** The private constructor of a static-only surface (a
+  class that exists solely to expose static factories and must never be instantiated). It is
+  never executed through any public path, so its line stays uncovered by construction.
+
+For these, and only these, a white-box test is permitted as a last resort: reflecting into
+`Internal/` private state to assert that memoization holds, or reflection-invoking an
+uncallable constructor so its line is covered. Such a test still follows the BDD structure
+and `testXxxWhenYyyThenZzz` naming, and the repeated-invocation `@When` exception (checklist
+item 3) already covers the memoization case.
+
+This exception covers code. It never hides it. `@codeCoverageIgnore`, coverage-excluding
+configuration, and mutant suppression remain prohibited without exception. The irreducible
+element is killed or covered honestly through reflection, not excluded from the metric. The
+burden is on demonstrating irreducibility: if the line or mutation can be reached through the
+public API, or if a proportionate refactor would expose it without harming the design, this
+exception does not apply and the public-API test is required. White-box access is never a
+convenience and never the first resort.
diff --git a/.claude/rules/php-library-tooling.md b/.claude/rules/php-library-tooling.md
new file mode 100644
index 0000000..8cf50d2
--- /dev/null
+++ b/.claude/rules/php-library-tooling.md
@@ -0,0 +1,138 @@
+---
+description: Invariants for the canonical config files of PHP libraries in the tiny-blocks ecosystem.
+paths:
+    - "composer.json"
+    - "phpcs.xml"
+    - "phpstan.neon"
+    - "phpstan.neon.dist"
+    - "phpunit.xml"
+    - "infection.json"
+    - "infection.json.dist"
+    - ".editorconfig"
+    - ".gitattributes"
+    - ".gitignore"
+    - "Makefile"
+---
+
+# Tooling
+
+Invariants that every config file in a tiny-blocks library must satisfy. The **canonical file
+bodies** (full `composer.json`, `Makefile`, `phpunit.xml`, etc.) are not duplicated here. They
+live as drop-in assets in the `tiny-blocks-create` skill, which is the single source of truth
+for scaffolding a new library or restoring a file to its canonical shape. This rule defines the
+invariants those files are checked against when editing an existing library.
+
+Folder structure lives in `php-library-architecture.md`. Code style lives in
+`php-library-code-style.md`.
+
+## Pre-output checklist
+
+Verify every item before creating, editing, or relocating any config file. If any item fails,
+revise before outputting.
+
+1. The repository root contains all of: `composer.json`, `phpcs.xml`, `phpstan.neon.dist`,
+   `phpunit.xml`, `infection.json.dist`, `.editorconfig`, `.gitattributes`, `.gitignore`,
+   `Makefile`. (See "Config file naming" for which carry a `.dist` suffix and why.)
+2. `composer.json` exposes exactly five scripts: `configure`, `configure-and-update`, `review`,
+   `test-file`, `tests`. No other public scripts.
+3. `composer.json` fixed fields use the canonical values from the skill asset (`license`, `type`,
+   `minimum-stability`, `prefer-stable`, `authors`, `config`, `require.php`). The five universal
+   dev dependencies (`ergebnis/composer-normalize`, `infection/infection`, `phpstan/phpstan`,
+   `phpunit/phpunit`, `squizlabs/php_codesniffer`) are present. `require-dev` may add libraries
+   the tests need on top of those five. The asset's caret ranges are the canonical floor, and
+   the repo `composer.json` matches the asset. To bump, update the asset first, then the repo.
+4. `composer.json` `description` is a single short sentence. Multi-sentence prose belongs in the
+   README Overview, not in Composer metadata.
+5. `composer.json` includes a `keywords` array that contains `"tiny-blocks"`. Its position in
+   the array is not constrained. The remaining entries are topic tokens derived from the
+   library's purpose (`psr-7`, `http-client`, `event-sourcing`, etc.).
+6. `phpcs.xml` references only the `PSR12` ruleset. No additional sniffs. Formatting rules outside
+   PSR-12 live in `php-library-code-style.md` under "Formatting overrides".
+7. `phpunit.xml` sets all five `failOn*` flags to `true` (`failOnDeprecation`, `failOnNotice`,
+   `failOnPhpunitDeprecation`, `failOnRisky`, `failOnWarning`).
+8. `phpunit.xml` sets `executionOrder="random"` and `beStrictAboutOutputDuringTests="true"`.
+   Non-namespace root attributes are sorted alphabetically. The `xmlns:xsi` and
+   `xsi:noNamespaceSchemaLocation` declarations lead the attribute list and are not part of
+   the alphabetical run.
+9. `infection.json.dist` sets `minMsi: 100` and `minCoveredMsi: 100`. Lowering either is
+   prohibited.
+10. `.editorconfig` sets `max_line_length = 120`, `indent_size = 4`, `indent_style = space`,
+    `end_of_line = lf` as the global default under `[*]`. YAML uses `indent_size = 2` and
+    Makefile uses `indent_style = tab` as per-extension overrides.
+11. `.gitattributes` sets `* text=auto eol=lf` and lists every committed dev-only file under
+    `export-ignore`. The Packagist tarball contains only `src/`, `composer.json`, `README.md`,
+    `LICENSE`, and `SECURITY.md`. `.claude/` is listed under `export-ignore` (versioned on
+    GitHub for contributor parity, excluded from the published package), and `CLAUDE.md` (where
+    committed) is `export-ignore`d alongside it for the same reason. `.gitattributes` lists
+    only files that are actually committed: it never names a file the repository does not
+    contain (no `CONTRIBUTING.md`, which is centralized, and no phantom `.dist`/non-`.dist`
+    twin of a file that is committed under only one of those names).
+12. `.gitignore` ignores the dependency and artifact paths, the local config overrides
+    (`/phpstan.neon`, `/infection.json`), and nothing tool caches the project does not produce.
+    The `.claude/` directory itself is **not** ignored (it is versioned on GitHub). Only
+    `/.claude/settings.local.json`, the per-clone settings override, is ignored.
+13. `Makefile` wraps every PHP and Composer command in Docker using the canonical image
+    `gustavofreze/php:8.5-alpine`. No PHP command runs on the host directly. Targets that share
+    a name with a Composer script delegate to it. Additional non-Composer convenience targets
+    (`help`, `clean`, `show-*`) are permitted.
+14. All test artifact paths use `reports/` (plural), consistent across `composer tests`,
+    `infection.json.dist`, `phpunit.xml`, and `Makefile`. `reports/` is listed under
+    `export-ignore` in `.gitattributes`.
+
+## Config file naming
+
+The committed config files split into two naming conventions on purpose. The split is documented
+here so it reads as intentional, not accidental.
+
+- **Committed live, no `.dist`:** `phpcs.xml` and `phpunit.xml`. The ruleset (`PSR12` only) and
+  the test configuration are stable across the whole ecosystem and identical in every library.
+  There is no per-clone local-override story, so the live file is committed directly.
+- **Committed as `.dist`:** `phpstan.neon.dist` and `infection.json.dist`. These are the two
+  tools a contributor may legitimately want to tune locally (a temporary `ignoreErrors` entry, a
+  narrower mutator set while iterating). The `.dist` baseline is committed. A contributor drops a
+  gitignored `phpstan.neon` or `infection.json` to override it, and the tool auto-resolves the
+  override over the `.dist` fallback. Those override names appear in `.gitignore`.
+
+Do not introduce a `.dist` twin for `phpcs.xml`/`phpunit.xml`, and do not commit a live
+`phpstan.neon`/`infection.json` in place of the `.dist` baseline.
+
+## phpstan ignoreErrors
+
+`phpstan.neon.dist` runs at `level: max` on `src` and `tests`. `ignoreErrors` is permitted to
+suppress legitimate false positives produced by `level: max` (third-party signatures carrying
+`mixed`, PHP-FIG interfaces returning untyped arrays, trait unused-method warnings on shared
+behavior, and the typed-array cases routed here by `php-library-code-style.md` instead of adding
+PHPDoc). Each entry follows these rules:
+
+- A short comment above the entry justifies its existence.
+- Prefer scoping via `identifier:` plus `path:` over raw `#...#` message patterns.
+- `reportUnmatchedIgnoredErrors: true` is mandatory. Obsolete entries fail the build, forcing
+  cleanup.
+
+```neon
+ignoreErrors:
+    # Trait method intentionally unused by the consuming aggregate. Reflection wires it.
+    - identifier: trait.unused
+      path: src/Internal/EventualAggregateRootBehavior.php
+```
+
+## Infection mutator config
+
+`infection.json.dist` is configured with `"mutators": {"@default": true}`. That is the only
+permitted form. No `ignore` lists, no `ignoreSourceCodeByRegex`, and no per-mutator overrides
+are allowed. Every mutant the default profile produces must be killed by a test. When a mutant
+escapes, the production code is refactored to make it testable rather than the configuration
+relaxed. This aligns with `php-library-testing.md` rule 15 (no mutant suppression by any
+mechanism) and with the MSI 100 thresholds in checklist item 9.
+
+## Composer scripts
+
+The five scripts and their purpose. Bodies live in the skill asset.
+
+- `composer configure` installs with `--optimize-autoloader` then normalizes. Run after cloning
+  or pulling.
+- `composer configure-and-update` updates dependencies then normalizes. Run when intentionally
+  bumping dependencies.
+- `composer review` runs `phpcs` then `phpstan`. Used by CI (`auto-review` job) and locally.
+- `composer tests` runs `phpunit` then `infection`. Used by CI (`tests` job).
+- `composer test-file <FilterPattern>` runs a filtered subset without coverage. Local only.
diff --git a/.claude/settings.json b/.claude/settings.json
new file mode 100644
index 0000000..f01749f
--- /dev/null
+++ b/.claude/settings.json
@@ -0,0 +1,249 @@
+{
+  "$schema": "https://json.schemastore.org/claude-code-settings.json",
+  "permissions": {
+    "defaultMode": "default",
+    "allow": [
+      "Read",
+      "Glob",
+      "Grep",
+
+      "Edit(./**)",
+      "Write(./**)",
+
+      "Bash(make:*)",
+      "Bash(docker:*)",
+
+      "Bash(rtk gain:*)",
+      "Bash(rtk discover:*)",
+      "Bash(rtk --version)",
+
+      "Bash(rtk git status:*)",
+      "Bash(rtk git diff:*)",
+      "Bash(rtk git log:*)",
+      "Bash(rtk git show:*)",
+      "Bash(rtk ls:*)",
+      "Bash(rtk cat:*)",
+      "Bash(rtk grep:*)",
+      "Bash(rtk rg:*)",
+      "Bash(rtk head:*)",
+      "Bash(rtk tail:*)",
+
+      "Bash(rtk docker:*)",
+
+      "Bash(rg:*)",
+      "Bash(grep:*)",
+      "Bash(jq:*)",
+      "Bash(cat:*)",
+      "Bash(ls:*)",
+      "Bash(head:*)",
+      "Bash(tail:*)",
+      "Bash(wc:*)",
+      "Bash(sort:*)",
+      "Bash(uniq:*)",
+      "Bash(diff:*)",
+      "Bash(echo:*)",
+      "Bash(mkdir:*)",
+      "Bash(rmdir:*)",
+      "Bash(rm:*)",
+
+      "Bash(composer install:*)",
+      "Bash(composer validate:*)",
+      "Bash(composer outdated:*)",
+      "Bash(composer show:*)",
+
+      "Bash(git status:*)",
+      "Bash(git diff:*)",
+      "Bash(git log:*)",
+      "Bash(git show:*)",
+      "Bash(git blame:*)",
+      "Bash(git ls-files:*)",
+      "Bash(git grep:*)",
+      "Bash(git merge-base:*)",
+      "Bash(git rev-parse:*)",
+      "Bash(git describe:*)",
+      "Bash(git shortlog:*)",
+      "Bash(git reflog show:*)",
+      "Bash(git remote -v)",
+      "Bash(git remote get-url:*)",
+      "Bash(git stash list)",
+      "Bash(git stash show:*)",
+      "Bash(git worktree list)",
+      "Bash(git config --get:*)",
+      "Bash(git config --get-all:*)",
+      "Bash(git config --list)",
+      "Bash(git config --list:*)",
+
+      "Bash(git branch)",
+      "Bash(git branch -a)",
+      "Bash(git branch -r)",
+      "Bash(git branch -v)",
+      "Bash(git branch -vv)",
+      "Bash(git branch --show-current)",
+      "Bash(git branch --list:*)",
+      "Bash(git branch --contains:*)",
+      "Bash(git branch --merged:*)",
+      "Bash(git branch --no-merged:*)",
+
+      "Bash(git tag)",
+      "Bash(git tag -l)",
+      "Bash(git tag -l:*)",
+      "Bash(git tag -n)",
+      "Bash(git tag -n:*)",
+      "Bash(git tag --list)",
+      "Bash(git tag --list:*)",
+      "Bash(git tag --contains:*)",
+      "Bash(git tag --points-at:*)",
+
+      "Bash(git rm:*)"
+    ],
+    "ask": [
+      "Edit(./.claude/**)",
+      "Write(./.claude/**)",
+
+      "Bash(git add:*)",
+      "Bash(git commit:*)",
+      "Bash(git mv:*)",
+
+      "Bash(composer require:*)",
+      "Bash(composer update:*)",
+      "Bash(composer remove:*)",
+      "Bash(composer normalize:*)",
+
+      "Bash(curl:*)",
+      "Bash(wget:*)"
+    ],
+    "deny": [
+      "Read(./.env)",
+      "Read(./.env.*)",
+      "Read(./**/.env)",
+      "Read(./**/.env.*)",
+      "Read(./secrets/**)",
+      "Read(./**/credentials*)",
+      "Read(./**/*.pem)",
+      "Read(./**/*.key)",
+      "Read(./**/id_rsa)",
+      "Read(./**/id_ed25519)",
+      "Read(~/.ssh/**)",
+
+      "Edit(./.env)",
+      "Edit(./.env.*)",
+      "Edit(./**/.env)",
+      "Edit(./**/.env.*)",
+      "Edit(./secrets/**)",
+      "Edit(./.git/**)",
+      "Edit(~/.bashrc)",
+      "Edit(~/.zshrc)",
+      "Edit(~/.profile)",
+      "Edit(~/.ssh/**)",
+
+      "Write(./.env)",
+      "Write(./.env.*)",
+      "Write(./**/.env)",
+      "Write(./**/.env.*)",
+      "Write(./secrets/**)",
+      "Write(./.git/**)",
+      "Write(~/.bashrc)",
+      "Write(~/.zshrc)",
+      "Write(~/.profile)",
+      "Write(~/.ssh/**)",
+
+      "Bash(php:*)",
+
+      "Bash(rm --no-preserve-root:*)",
+      "Bash(rm -rf /)",
+      "Bash(rm * /)",
+      "Bash(rm * ~)",
+      "Bash(rm * ~/)",
+      "Bash(rm * $HOME)",
+      "Bash(rm * $HOME/)",
+
+      "Bash(git push:*)",
+      "Bash(git pull:*)",
+      "Bash(git fetch:*)",
+      "Bash(git checkout:*)",
+      "Bash(git switch:*)",
+      "Bash(git restore:*)",
+      "Bash(git reset:*)",
+      "Bash(git merge:*)",
+      "Bash(git rebase:*)",
+      "Bash(git revert:*)",
+      "Bash(git cherry-pick:*)",
+      "Bash(git apply:*)",
+      "Bash(git am:*)",
+      "Bash(git stash push:*)",
+      "Bash(git stash pop:*)",
+      "Bash(git stash apply:*)",
+      "Bash(git stash drop:*)",
+      "Bash(git stash clear)",
+      "Bash(git stash save:*)",
+      "Bash(git branch -d:*)",
+      "Bash(git branch -D:*)",
+      "Bash(git branch -m:*)",
+      "Bash(git branch -M:*)",
+      "Bash(git branch -c:*)",
+      "Bash(git branch -C:*)",
+      "Bash(git tag -a:*)",
+      "Bash(git tag -s:*)",
+      "Bash(git tag -d:*)",
+      "Bash(git tag -f:*)",
+      "Bash(git tag --delete:*)",
+      "Bash(git tag --force:*)",
+      "Bash(git remote add:*)",
+      "Bash(git remote remove:*)",
+      "Bash(git remote rm:*)",
+      "Bash(git remote rename:*)",
+      "Bash(git remote set-url:*)",
+      "Bash(git submodule:*)",
+      "Bash(git worktree add:*)",
+      "Bash(git worktree remove:*)",
+      "Bash(git worktree prune:*)",
+      "Bash(git filter-branch:*)",
+      "Bash(git filter-repo:*)",
+      "Bash(git replace:*)",
+      "Bash(git notes:*)",
+      "Bash(git clean:*)",
+      "Bash(git gc:*)",
+      "Bash(git prune:*)",
+      "Bash(git reflog delete:*)",
+      "Bash(git reflog expire:*)",
+      "Bash(git config --add:*)",
+      "Bash(git config --unset:*)",
+      "Bash(git config --unset-all:*)",
+      "Bash(git config --replace-all:*)",
+      "Bash(git config --global:*)",
+
+      "Bash(eval:*)",
+
+      "Bash(sudo:*)",
+      "Bash(mysql:*)",
+      "Bash(dropdb:*)",
+      "Bash(dd:*)",
+      "Bash(chmod:*)",
+      "Bash(chown:*)",
+
+      "Bash(curl * | sh)",
+      "Bash(curl * | bash)",
+      "Bash(curl * | sudo:*)",
+      "Bash(wget * | sh)",
+      "Bash(wget * | bash)",
+      "Bash(wget * | sudo:*)"
+    ]
+  },
+  "hooks": {
+    "PostToolUse": [
+      {
+        "matcher": "Edit|Write|MultiEdit",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "python3 ${CLAUDE_PROJECT_DIR}/.claude/hooks/php-ordering-conformance.py"
+          },
+          {
+            "type": "command",
+            "command": "python3 ${CLAUDE_PROJECT_DIR}/.claude/hooks/php-prose-punctuation-conformance.py"
+          }
+        ]
+      }
+    ]
+  }
+}
diff --git a/.claude/skills/commit-message/SKILL.md b/.claude/skills/commit-message/SKILL.md
new file mode 100644
index 0000000..de37fcd
--- /dev/null
+++ b/.claude/skills/commit-message/SKILL.md
@@ -0,0 +1,119 @@
+---
+name: commit-message
+description: Generate a git commit message in the tiny-blocks Conventional Commits format (type-prefixed, imperative, capitalized, period-terminated, no scopes). Use this skill whenever the user asks you to write, draft, suggest, or fix a commit message, or whenever you are about to propose commit text for staged changes, even if they do not say the words "conventional commits". Commit messages are produced on request only and are never generated automatically as part of another task.
+---
+
+# Commit message
+
+Produce a single commit message in the tiny-blocks format. This skill formats the message only.
+It never stages, commits, or runs any Git command. That happens only when the user explicitly
+asks for it.
+
+All commit messages are written in English.
+
+## Format
+
+```
+<type>: <Description>
+```
+
+The description starts with a capital letter, uses imperative present tense (`Add`, `Fix`,
+`Change`, not `Added`, `Adds`, or `Adding`), and ends with a period. Keep the subject under 300
+characters. If it does not fit, split the change into multiple commits or move detail into the
+body.
+
+**Scopes are prohibited.** `feat(orders): ...` is wrong. The type stands alone.
+
+## Trailers
+
+Commit messages carry no trailers, regardless of any default to the contrary. Never append a
+`Co-Authored-By` line or any other trailer. The message is the type-prefixed subject and, when
+justified, a body. Nothing follows the body.
+
+## Allowed types
+
+- `ci` for CI configuration changes.
+- `fix` for a bug fix.
+- `feat` for a user-facing feature.
+- `docs` for documentation only.
+- `test` for adding or correcting tests.
+- `chore` for maintenance with no production code change.
+- `build` for build or dependency changes.
+- `revert` for reverting a previous commit.
+- `refactor` for a code change that neither fixes a bug nor adds a feature.
+
+`style` is not used. Formatting is enforced by the linter and never appears as a standalone
+commit.
+
+## Subject examples
+
+**Example 1:**
+Input: handled the case where a transaction has a zero amount
+Output: `fix: Handle zero-amount transactions.`
+
+**Example 2:**
+Input: added an endpoint to cancel an order
+Output: `feat: Add order cancellation endpoint.`
+
+**Example 3:**
+Input: pulled OrderStatus out into its own enum, no behavior change
+Output: `refactor: Extract OrderStatus into its own enum.`
+
+Reject these shapes:
+
+- `Added order cancellation`: past tense, missing type, missing period.
+- `feat: Adds order cancellation.`: third-person singular instead of imperative.
+- `feat: added order cancellation.`: starts lowercase and is past tense.
+- `feat: Add cancellation, and fix billing rounding.`: bundles two changes, so split them.
+- `feat(orders): Add cancellation.`: uses a scope, which is prohibited.
+
+## Body
+
+The body is **optional and rarely needed**. Single-purpose commits never have a body. Add a body
+only when the reason cannot be inferred from the diff: a non-obvious trade-off, a workaround for
+an external bug, a decision worth recording.
+
+Separate the body from the subject with a blank line. Wrap at 72 characters per line. Explain
+**why**, not what. The diff already shows what.
+
+### Prose vs. bullets in the body
+
+Default to prose. One or two paragraphs fits almost every commit that has a body at all.
+
+Use bullets only when **all** of these are true:
+
+1. The commit covers 3 or more independent changes that genuinely belong in the same commit.
+2. The list cannot be expressed as continuous prose without becoming disconnected sentences.
+3. Each item is independently meaningful (no sub-bullets, no continuation across bullets).
+
+A two-item bullet list is the wrong shape. Use prose.
+
+When bullets are used, every bullet starts with a capital letter and ends with a period, with an
+imperative present-tense verb, same as the subject line.
+
+### Body example with prose (preferred)
+
+```
+fix: Handle zero-amount transactions.
+
+The payment gateway rejects zero-amount charges with a generic 400 instead
+of a documented error code, so the adapter short-circuits before the HTTP
+call and raises ZeroAmountNotAllowed directly.
+```
+
+### Body example with bullets
+
+```
+feat: Add order cancellation flow.
+
+- Add the OrderCancelling inbound port and OrderCancellingHandler.
+- Add the CancelOrder command and its validator.
+- Cover the cancellation path in the integration test suite.
+```
+
+## Commit splitting
+
+Prefer one logical change per commit. Refactor commits never modify behavior. When a task needs
+multiple types of change, produce multiple commits in order: `refactor` first, then `feat` or
+`fix` on top. When the staged diff mixes types, say so and propose the split rather than forcing
+one message over an incoherent change set.
diff --git a/.claude/skills/tiny-blocks-consume/SKILL.md b/.claude/skills/tiny-blocks-consume/SKILL.md
new file mode 100644
index 0000000..c318df8
--- /dev/null
+++ b/.claude/skills/tiny-blocks-consume/SKILL.md
@@ -0,0 +1,68 @@
+---
+name: tiny-blocks-consume
+description:
+    Discover and reuse an existing tiny-blocks library as a dependency instead of writing or keeping hand-written code. Use this skill in two moments: before implementing a capability from scratch or adding a dependency from outside the ecosystem, and when reviewing or refactoring existing code, to catch where a tiny-blocks package now covers something already written by hand. It checks the catalog of published tiny-blocks packages for a candidate, adds the match with composer, and reads the installed library's own README and public API to use it correctly. Trigger on any request to implement, add, build, review, simplify, or refactor where an existing building block (collections, value objects, money, time, http, mapping, logging, identifiers, and similar) might apply.
+---
+
+# tiny-blocks consume
+
+Reuse the ecosystem before building anew. Inside any library, when a capability is needed, the
+first move is to check whether a tiny-blocks package already provides it, adopt that package, and
+use its documented API. This is the consuming counterpart of `tiny-blocks-create`.
+
+The source of truth for how to use a package is the package itself. After adding a dependency, its
+README and public PHPDoc under `vendor/tiny-blocks/<name>/` are authoritative. This skill does not
+copy any package API. It only points to the catalog for discovery and to the installed package for
+usage.
+
+## When to use
+
+Use this before writing new code for a capability that is plausibly generic: collections, value
+objects, money or currency, time, country codes, http primitives, object mapping, logging,
+identifiers, encoding, environment variables, and similar. Also use it before reaching for any
+dependency from outside the ecosystem.
+
+Use it also when reviewing or refactoring existing code. A package may have been published after
+that code was written, so check whether hand-rolled logic can now be replaced by a tiny-blocks
+package. The catalog is what surfaces newly published packages, so refresh it (see below) before
+concluding that nothing applies.
+
+Do not use it for logic that is specific to the library being built and has no general building
+block. In that case, write the code following the rules.
+
+## Consume steps
+
+1. Name the capability in one phrase, whether it is something you are about to write or something
+   the existing code already does by hand (for example, "type-safe ordered collection" or "ISO
+   currency with fraction digits").
+2. Check `references/catalog.md` for a tiny-blocks candidate. If nothing matches and the need is
+   generic, refresh the catalog (see below) and look again, since a newer package may exist.
+3. If a candidate fits, add it with `composer require tiny-blocks/<name>`. Packages from the
+   ecosystem are exempt from the freshness cooldown, and `composer require` prompts once before
+   adding.
+4. Learn the API from the installed package, not from memory. Read
+   `vendor/tiny-blocks/<name>/README.md` and the public classes, interfaces, and enums under
+   `vendor/tiny-blocks/<name>/src/`. Their PHPDoc and the README examples are the contract.
+5. Use the package following its documented API. Transitive dependencies are resolved by composer,
+   so depend on and use only the package that solves the capability directly.
+6. If no candidate fits, only then write the code from scratch, or consider a dependency from
+   outside the ecosystem, subject to the freshness cooldown and the `composer require` prompt.
+
+## Catalog
+
+`references/catalog.md` is the committed index of published tiny-blocks packages, with a one-line
+purpose for each. It exists for fast, offline discovery. It is generated from Packagist, not hand
+maintained. Each entry points to a package whose full API lives in its own README and PHPDoc once
+installed.
+
+## Refresh the catalog
+
+Run `python3 scripts/refresh-catalog.py` to rebuild `references/catalog.md` from the `tiny-blocks`
+vendor on Packagist. The script uses only the Python standard library, with no curl or jq, pulls
+the package list plus each description, skips abandoned packages, and rewrites the list. Refresh
+when a new package shipped, or when the catalog looks stale and a needed capability is not listed.
+
+## Validate
+
+After adding a dependency and wiring it in, run `make review` and `make tests`. Both must be green
+before the work is complete. A new dependency that breaks either gate is not done.
diff --git a/.claude/skills/tiny-blocks-consume/references/catalog.md b/.claude/skills/tiny-blocks-consume/references/catalog.md
new file mode 100644
index 0000000..778be52
--- /dev/null
+++ b/.claude/skills/tiny-blocks-consume/references/catalog.md
@@ -0,0 +1,32 @@
+# tiny-blocks catalog
+
+Index of published tiny-blocks packages and their one-line purpose. Generated from Packagist by
+scripts/refresh-catalog.py, not hand-maintained. For the full API of a package, read its README
+and public PHPDoc under vendor/tiny-blocks/<name>/.
+
+- `tiny-blocks/building-blocks`: Implements tactical DDD building blocks for PHP: entities, aggregate roots, domain
+  events, snapshots, and upcasters.
+- `tiny-blocks/collection`: Models a type-safe, fluent collection API for PHP with eager and lazy pipelines over arrays,
+  iterators, and generators.
+- `tiny-blocks/country`: Provides an ISO 3166-1 country value object for PHP, with Alpha-2, Alpha-3, numeric, and IANA
+  timezone resolution.
+- `tiny-blocks/currency`: Models ISO-4217 currencies as a PHP enum, with per-currency fraction digit resolution.
+- `tiny-blocks/docker-container`: Manages Docker containers programmatically for PHP, aimed at integration tests and
+  disposable infrastructure.
+- `tiny-blocks/encoder`: Encoder and decoder for arbitrary data.
+- `tiny-blocks/environment-variable`: Provides a type-safe environment variable reader for PHP, with strict integer and
+  boolean conversion.
+- `tiny-blocks/http`: Implements PSR-7, PSR-15, PSR-17 and PSR-18 HTTP primitives for PHP, with a fluent response
+  builder, cookies, cache control, and a PSR-18 client facade.
+- `tiny-blocks/immutable-object`: Provides immutable behavior for objects.
+- `tiny-blocks/ksuid`: K-Sortable Unique Identifier.
+- `tiny-blocks/logger`: Emits PSR-3 structured logs for PHP, with correlation tracking and configurable sensitive data
+  redaction.
+- `tiny-blocks/mapper`: Maps PHP objects to and from arrays, JSON, and iterables through reflection and pluggable
+  strategies.
+- `tiny-blocks/math`: Value Objects for handling arbitrary precision numbers.
+- `tiny-blocks/outbox`: Write-side adapter for the Transactional Outbox pattern that persists domain events atomically
+  with aggregate state through Doctrine DBAL.
+- `tiny-blocks/time`: Models time as immutable value objects for PHP: instants, durations, periods, timezones, and
+  time-of-day, all UTC-normalized.
+- `tiny-blocks/value-object`: Defines the default behavior contract for PHP value objects with structural equality.
diff --git a/.claude/skills/tiny-blocks-consume/scripts/refresh-catalog.py b/.claude/skills/tiny-blocks-consume/scripts/refresh-catalog.py
new file mode 100644
index 0000000..b6fa359
--- /dev/null
+++ b/.claude/skills/tiny-blocks-consume/scripts/refresh-catalog.py
@@ -0,0 +1,102 @@
+#!/usr/bin/env python3
+"""Rebuild references/catalog.md from the tiny-blocks vendor on Packagist.
+
+Usage:
+    python3 scripts/refresh-catalog.py
+
+Depends only on the Python standard library. No curl, no jq, no shell.
+"""
+
+from __future__ import annotations
+
+import json
+import sys
+import textwrap
+import urllib.error
+import urllib.request
+from pathlib import Path
+from typing import List, Optional
+
+VENDOR = "tiny-blocks"
+LIST_URL = f"https://packagist.org/packages/list.json?vendor={VENDOR}"
+CATALOG_PATH = Path(__file__).resolve().parent.parent / "references" / "catalog.md"
+LINE_WIDTH = 120
+REQUEST_TIMEOUT_SECONDS = 30
+
+CATALOG_HEADER = """\
+# tiny-blocks catalog
+
+Index of published tiny-blocks packages and their one-line purpose. Generated from Packagist by
+scripts/refresh-catalog.py, not hand-maintained. For the full API of a package, read its README
+and public PHPDoc under vendor/tiny-blocks/<name>/.
+
+"""
+
+
+def report(message: str) -> None:
+    print(message, file=sys.stderr)
+
+
+def fetch_json(url: str) -> dict:
+    request = urllib.request.Request(url=url, headers={"User-Agent": "tiny-blocks-catalog"})
+
+    with urllib.request.urlopen(url=request, timeout=REQUEST_TIMEOUT_SECONDS) as response:
+        payload = json.load(fp=response)
+    return payload
+
+
+def sanitize(description: str) -> str:
+    collapsed = " ".join(description.split())
+
+    for character in (";", "—", "–"):
+        collapsed = collapsed.replace(character, ",")
+    return collapsed
+
+
+def catalog_line(name: str) -> Optional[str]:
+    try:
+        metadata = fetch_json(url=f"https://packagist.org/packages/{name}.json").get("package", {})
+    except (urllib.error.URLError, json.JSONDecodeError):
+        report(message=f"Skipping {name}, metadata fetch failed.")
+        return None
+
+    if metadata.get("abandoned"):
+        return None
+
+    description = sanitize(description=metadata.get("description") or "")
+
+    return textwrap.fill(
+        text=f"- `{name}`: {description}",
+        width=LINE_WIDTH,
+        subsequent_indent="  ",
+        break_long_words=False,
+        break_on_hyphens=False,
+    )
+
+
+def build_catalog() -> str:
+    names = sorted(fetch_json(url=LIST_URL).get("packageNames", []))
+    lines: List[str] = []
+
+    for name in names:
+        line = catalog_line(name=name)
+
+        if line is not None:
+            lines.append(line)
+    return CATALOG_HEADER + "\n".join(lines) + "\n"
+
+
+def main() -> int:
+    try:
+        catalog = build_catalog()
+    except (urllib.error.URLError, json.JSONDecodeError) as error:
+        report(message=f"Failed to build the catalog: {error}")
+        return 1
+
+    CATALOG_PATH.write_text(data=catalog, encoding="utf-8")
+    print(f"Wrote {CATALOG_PATH}")
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())
diff --git a/.claude/skills/tiny-blocks-create/SKILL.md b/.claude/skills/tiny-blocks-create/SKILL.md
new file mode 100644
index 0000000..efcc62b
--- /dev/null
+++ b/.claude/skills/tiny-blocks-create/SKILL.md
@@ -0,0 +1,158 @@
+---
+name: tiny-blocks-create
+description: Scaffold a new PHP library for the tiny-blocks ecosystem, or restore a single canonical config/repository file (composer.json, phpcs.xml, phpunit.xml, phpstan.neon.dist, infection.json.dist, .editorconfig, .gitattributes, .gitignore, Makefile, the CI workflow, SECURITY.md, the issue templates, the PR template) to its standard shape. Use this skill whenever the user asks to create, bootstrap, set up, or initialize a new tiny-blocks library, to add the standard config/tooling files to a repository, or to fix/regenerate any of those files to match the ecosystem standard, even if they only mention one file by name. This skill owns the canonical bodies of those files. Do not hand-write them from memory.
+---
+
+# tiny-blocks library scaffolding
+
+This skill is the single source of truth for the boilerplate every tiny-blocks PHP library
+shares: the config files, the CI workflow, and the repository templates. The canonical bodies
+live in `assets/` as drop-in files. Copy them and substitute the placeholders rather than
+regenerating them from memory. The assets already encode the ecosystem's decisions (PSR-12 only,
+`level: max`, MSI 100, Docker-wrapped Makefile, the `.dist` naming split, the export-ignore set).
+
+The semantic conventions (how to name classes, how to structure `src/`, how to write tests) are
+**not** in this skill. They live in `.claude/rules/`. This skill produces the skeleton. The rules
+govern the code you then write into it.
+
+## When to use which mode
+
+- **Full scaffold**: the user is starting a new library. Create the directory skeleton and copy
+  every asset, substituting placeholders.
+- **Single-file restore**: the user wants one file brought back to standard (for example, "fix
+  my Makefile" or "regenerate the CI workflow"). Copy only that asset. Do not touch the rest.
+
+## Asset map
+
+Copy each asset to the path on the right, relative to the repository root.
+
+| Asset (`assets/…`)                         | Destination                                 | Placeholders |
+|--------------------------------------------|---------------------------------------------|--------------|
+| `config/composer.json`                     | `composer.json`                             | yes          |
+| `config/phpcs.xml`                         | `phpcs.xml`                                 | no           |
+| `config/phpstan.neon.dist`                 | `phpstan.neon.dist`                         | no           |
+| `config/phpunit.xml`                       | `phpunit.xml`                               | no           |
+| `config/infection.json.dist`               | `infection.json.dist`                       | no           |
+| `config/.editorconfig`                     | `.editorconfig`                             | no           |
+| `config/.gitattributes`                    | `.gitattributes`                            | no           |
+| `config/.gitignore`                        | `.gitignore`                                | no           |
+| `config/Makefile`                          | `Makefile`                                  | no           |
+| `github/workflows/ci.yml`                  | `.github/workflows/ci.yml`                  | no           |
+| `github/ISSUE_TEMPLATE/bug_report.md`      | `.github/ISSUE_TEMPLATE/bug_report.md`      | no           |
+| `github/ISSUE_TEMPLATE/feature_request.md` | `.github/ISSUE_TEMPLATE/feature_request.md` | no           |
+| `github/PULL_REQUEST_TEMPLATE.md`          | `.github/PULL_REQUEST_TEMPLATE.md`          | no           |
+| `docs/SECURITY.md`                         | `SECURITY.md`                               | yes          |
+
+## Placeholders
+
+Two assets carry placeholders. Substitute every occurrence.
+
+| Placeholder                                             | Meaning                                      | Example                   |
+|---------------------------------------------------------|----------------------------------------------|---------------------------|
+| `<lib-name>`                                            | Repository name, kebab-case                  | `event-sourcing`          |
+| `<LibName>`                                             | PSR-4 namespace segment, PascalCase          | `EventSourcing`           |
+| `<one short sentence describing what the library does>` | `composer.json` `description` (one sentence) | n/a                       |
+| `<topic-1>`, `<topic-2>`                                | `composer.json` `keywords` topic tokens      | `psr-7`, `event-sourcing` |
+
+`<lib-name>` appears in `composer.json` (`name`, `homepage`, `support`) and in `SECURITY.md`
+(advisory URL). `<LibName>` appears only in `composer.json` (`autoload` / `autoload-dev` PSR-4
+prefixes). The first `keywords` entry is always `tiny-blocks`. The topic tokens follow.
+
+## Full scaffold steps
+
+1. Confirm `<lib-name>`, `<LibName>`, the one-sentence description, and the keyword topics with
+   the user if not already known.
+2. Create the directory skeleton:
+   ```
+   src/
+   tests/
+   .github/workflows/
+   .github/ISSUE_TEMPLATE/
+   ```
+3. Copy every asset to its destination (table above), substituting placeholders.
+4. Author the files this skill does **not** carry, following the rules:
+   - `README.md`: follow `php-library-documentation.md` (title, license badge, TOC, the fixed
+     section order, code-example rules).
+   - `LICENSE`: MIT, attributed to the author in `composer.json`.
+   - Initial `src/` and `tests/`: follow `php-library-architecture.md`,
+     `php-library-code-style.md`, `php-library-modeling.md`, and `php-library-testing.md`.
+5. Validate (see below) before reporting the scaffold complete.
+
+## The .dist naming split
+
+The assets deliberately commit `phpcs.xml` and `phpunit.xml` as live files, but
+`phpstan.neon.dist` and `infection.json.dist` with the `.dist` suffix. This is intentional and
+documented in `php-library-tooling.md`: the ruleset and the test config are stable and committed
+live. PHPStan and Infection are the two tools a contributor may tune locally, so a gitignored
+`phpstan.neon` / `infection.json` overrides the committed `.dist` baseline. Do not add a `.dist`
+twin for `phpcs.xml`/`phpunit.xml`, and do not commit a live `phpstan.neon`/`infection.json`.
+
+## Extending the CI tests job
+
+`ci.yml` is the minimal canonical workflow. Only the `tests` job may be extended, and only when
+the library's tests need external services, environment variables, or fixture preparation. Add
+them inside the `tests` job. Leave `resolve-php-version`, `build`, and `auto-review` untouched.
+Example with a MySQL service container:
+
+```yaml
+tests:
+  name: Tests
+  needs: [resolve-php-version, auto-review]
+  runs-on: ubuntu-latest
+  timeout-minutes: 15
+  env:
+    DB_HOST: 127.0.0.1
+    DB_NAME: library_test
+    DB_PORT: '3306'
+    DB_USER: library
+    DB_PASSWORD: library
+  services:
+    mysql:
+      image: mysql:8
+      ports:
+        - 3306:3306
+      env:
+        MYSQL_DATABASE: library_test
+        MYSQL_ROOT_PASSWORD: library
+      options: >-
+        --health-cmd="mysqladmin ping"
+        --health-interval=10s
+        --health-timeout=5s
+        --health-retries=5
+  steps:
+    - name: Checkout
+      uses: actions/checkout@v6
+
+    - name: Setup PHP
+      uses: shivammathur/setup-php@v2
+      with:
+        tools: composer:2
+        php-version: ${{ needs.resolve-php-version.outputs.php-version }}
+
+    - name: Download vendor artifact from build
+      uses: actions/download-artifact@v8
+      with:
+        name: vendor-artifact
+        path: .
+
+    - name: Run tests
+      run: composer tests
+```
+
+## Pinned action versions
+
+The action versions pinned in `ci.yml` (`actions/checkout@v6`, `shivammathur/setup-php@v2`,
+`actions/upload-artifact@v7`, `actions/download-artifact@v8`) may be outdated. Before adopting the
+workflow, verify the current major version of each action and update the pin while preserving the
+`@vN` prefix style, as required by `php-library-github-workflows.md` rule 8.
+
+## Validate
+
+After scaffolding (or restoring `composer.json`/the test config), run the toolchain through the
+Makefile and confirm both pass before reporting done:
+
+- `make review`: phpcs (PSR-12) and phpstan (`level: max`) must pass clean.
+- `make tests`: phpunit and infection must pass with MSI 100 / covered MSI 100.
+
+If `make` targets are missing, `make help` lists them. Do not claim the scaffold is complete on
+the strength of file creation alone. The definition of done is a clean `review` and `tests`.
diff --git a/.claude/skills/tiny-blocks-create/assets/config/.editorconfig b/.claude/skills/tiny-blocks-create/assets/config/.editorconfig
new file mode 100644
index 0000000..be5640e
--- /dev/null
+++ b/.claude/skills/tiny-blocks-create/assets/config/.editorconfig
@@ -0,0 +1,19 @@
+root = true
+
+[*]
+charset = utf-8
+end_of_line = lf
+indent_size = 4
+indent_style = space
+max_line_length = 120
+insert_final_newline = true
+trim_trailing_whitespace = true
+
+[*.{yml,yaml}]
+indent_size = 2
+
+[Makefile]
+indent_style = tab
+
+[*.md]
+trim_trailing_whitespace = false
diff --git a/.claude/skills/tiny-blocks-create/assets/config/.gitattributes b/.claude/skills/tiny-blocks-create/assets/config/.gitattributes
new file mode 100644
index 0000000..2bd9baa
--- /dev/null
+++ b/.claude/skills/tiny-blocks-create/assets/config/.gitattributes
@@ -0,0 +1,19 @@
+* text=auto eol=lf
+
+*.php text diff=php
+
+# Dev-only, excluded from the Packagist tarball
+/.github             export-ignore
+/tests               export-ignore
+/.claude             export-ignore
+/CLAUDE.md           export-ignore
+/.editorconfig       export-ignore
+/.gitattributes      export-ignore
+/.gitignore          export-ignore
+/phpcs.xml           export-ignore
+/phpunit.xml         export-ignore
+/phpstan.neon.dist   export-ignore
+/infection.json.dist export-ignore
+/Makefile            export-ignore
+/reports             export-ignore
+/.phpunit.cache      export-ignore
diff --git a/.claude/skills/tiny-blocks-create/assets/config/.gitignore b/.claude/skills/tiny-blocks-create/assets/config/.gitignore
new file mode 100644
index 0000000..c8f4364
--- /dev/null
+++ b/.claude/skills/tiny-blocks-create/assets/config/.gitignore
@@ -0,0 +1,28 @@
+# PHP dependencies
+/vendor/
+composer.lock
+
+# Local config overrides (committed baselines are the .dist files)
+/phpstan.neon
+/infection.json
+
+# Tooling cache
+.phpunit.cache/
+.phpunit.result.cache
+
+# Coverage and reports
+build/
+reports/
+coverage/
+infection.log
+
+# Editors and agents
+.idea/
+.cursor/
+.vscode/
+/.claude/settings.local.json
+
+# OS
+Thumbs.db
+.DS_Store
+Desktop.ini
diff --git a/.claude/skills/tiny-blocks-create/assets/config/Makefile b/.claude/skills/tiny-blocks-create/assets/config/Makefile
new file mode 100644
index 0000000..90ab50d
--- /dev/null
+++ b/.claude/skills/tiny-blocks-create/assets/config/Makefile
@@ -0,0 +1,74 @@
+PWD := $(CURDIR)
+ARCH := $(shell uname -m)
+PLATFORM :=
+
+ifeq ($(ARCH),arm64)
+    PLATFORM := --platform=linux/amd64
+endif
+
+TTY := $(shell [ -t 0 ] && echo -it)
+
+DOCKER_RUN = docker run ${PLATFORM} --rm ${TTY} --net=host -v ${PWD}:/app -w /app gustavofreze/php:8.5-alpine
+
+RESET := \033[0m
+GREEN := \033[0;32m
+YELLOW := \033[0;33m
+
+.DEFAULT_GOAL := help
+
+.PHONY: configure
+configure: ## Configure development environment
+	@${DOCKER_RUN} composer configure
+
+.PHONY: configure-and-update
+configure-and-update: ## Configure development environment and update dependencies
+	@${DOCKER_RUN} composer configure-and-update
+
+.PHONY: tests
+tests: ## Run unit and mutation tests with coverage
+	@${DOCKER_RUN} composer tests
+
+.PHONY: test-file
+test-file: ## Run tests for a specific file (usage: make test-file FILE=ClassNameTest)
+	@${DOCKER_RUN} composer test-file ${FILE}
+
+.PHONY: review
+review: ## Run lint and static analysis
+	@${DOCKER_RUN} composer review
+
+.PHONY: show-reports
+show-reports: ## Open coverage and mutation reports in the browser
+	@sensible-browser reports/coverage/coverage-html/index.html reports/coverage/mutation-report.html
+
+.PHONY: show-outdated
+show-outdated: ## Show outdated direct dependencies
+	@${DOCKER_RUN} composer outdated --direct
+
+.PHONY: clean
+clean: ## Remove dependencies and generated artifacts
+	@sudo chown -R ${USER}:${USER} ${PWD}
+	@rm -rf reports vendor .phpunit.cache *.lock
+
+.PHONY: help
+help: ## Display this help message
+	@echo "Usage: make [target]"
+	@echo ""
+	@echo "$$(printf '$(GREEN)')Setup$$(printf '$(RESET)')"
+	@grep -E '^(configure|configure-and-update):.*?## .*$$' $(MAKEFILE_LIST) \
+		| awk 'BEGIN {FS = ":.*? ## "}; {printf "$(YELLOW)%-25s$(RESET) %s\n", $$1, $$2}'
+	@echo ""
+	@echo "$$(printf '$(GREEN)')Testing$$(printf '$(RESET)')"
+	@grep -E '^(tests|test-file):.*?## .*$$' $(MAKEFILE_LIST) \
+		| awk 'BEGIN {FS = ":.*?## "}; {printf "$(YELLOW)%-25s$(RESET) %s\n", $$1, $$2}'
+	@echo ""
+	@echo "$$(printf '$(GREEN)')Quality$$(printf '$(RESET)')"
+	@grep -E '^(review):.*?## .*$$' $(MAKEFILE_LIST) \
+		| awk 'BEGIN {FS = ":.*?## "}; {printf "$(YELLOW)%-25s$(RESET) %s\n", $$1, $$2}'
+	@echo ""
+	@echo "$$(printf '$(GREEN)')Reports$$(printf '$(RESET)')"
+	@grep -E '^(show-reports|show-outdated):.*?## .*$$' $(MAKEFILE_LIST) \
+		| awk 'BEGIN {FS = ":.*?## "}; {printf "$(YELLOW)%-25s$(RESET) %s\n", $$1, $$2}'
+	@echo ""
+	@echo "$$(printf '$(GREEN)')Cleanup$$(printf '$(RESET)')"
+	@grep -E '^(clean):.*?## .*$$' $(MAKEFILE_LIST) \
+		| awk 'BEGIN {FS = ":.*?## "}; {printf "$(YELLOW)%-25s$(RESET) %s\n", $$1, $$2}'
diff --git a/.claude/skills/tiny-blocks-create/assets/config/composer.json b/.claude/skills/tiny-blocks-create/assets/config/composer.json
new file mode 100644
index 0000000..e10a520
--- /dev/null
+++ b/.claude/skills/tiny-blocks-create/assets/config/composer.json
@@ -0,0 +1,70 @@
+{
+    "name": "tiny-blocks/<lib-name>",
+    "description": "<one short sentence describing what the library does>",
+    "license": "MIT",
+    "type": "library",
+    "keywords": [
+        "tiny-blocks",
+        "<topic-1>",
+        "<topic-2>"
+    ],
+    "authors": [
+        {
+            "name": "Gustavo Freze de Araujo Santos",
+            "homepage": "https://github.com/gustavofreze"
+        }
+    ],
+    "homepage": "https://github.com/tiny-blocks/<lib-name>",
+    "support": {
+        "issues": "https://github.com/tiny-blocks/<lib-name>/issues",
+        "source": "https://github.com/tiny-blocks/<lib-name>"
+    },
+    "require": {
+        "php": "^8.5"
+    },
+    "require-dev": {
+        "ergebnis/composer-normalize": "^2.52",
+        "infection/infection": "^0.33",
+        "phpstan/phpstan": "^2.2",
+        "phpunit/phpunit": "^13.1",
+        "squizlabs/php_codesniffer": "^4.0"
+    },
+    "minimum-stability": "stable",
+    "prefer-stable": true,
+    "autoload": {
+        "psr-4": {
+            "TinyBlocks\\<LibName>\\": "src/"
+        }
+    },
+    "autoload-dev": {
+        "psr-4": {
+            "Test\\TinyBlocks\\<LibName>\\": "tests/"
+        }
+    },
+    "config": {
+        "allow-plugins": {
+            "ergebnis/composer-normalize": true,
+            "infection/extension-installer": true
+        },
+        "sort-packages": true
+    },
+    "scripts": {
+        "configure": [
+            "@composer install --optimize-autoloader",
+            "@composer normalize"
+        ],
+        "configure-and-update": [
+            "@composer update --optimize-autoloader",
+            "@composer normalize"
+        ],
+        "review": [
+            "@php ./vendor/bin/phpcs --standard=phpcs.xml --extensions=php ./src ./tests",
+            "@php ./vendor/bin/phpstan analyse -c phpstan.neon.dist --quiet --no-progress"
+        ],
+        "test-file": "@php ./vendor/bin/phpunit --configuration phpunit.xml --no-coverage --filter",
+        "tests": [
+            "@php -d memory_limit=2G ./vendor/bin/phpunit --configuration phpunit.xml tests",
+            "@php ./vendor/bin/infection --threads=max --logger-html=reports/coverage/mutation-report.html --coverage=reports/coverage"
+        ]
+    }
+}
diff --git a/.claude/skills/tiny-blocks-create/assets/config/infection.json.dist b/.claude/skills/tiny-blocks-create/assets/config/infection.json.dist
new file mode 100644
index 0000000..aab8c7e
--- /dev/null
+++ b/.claude/skills/tiny-blocks-create/assets/config/infection.json.dist
@@ -0,0 +1,23 @@
+{
+    "logs": {
+        "text": "reports/infection/logs/infection-text.log",
+        "summary": "reports/infection/logs/infection-summary.log"
+    },
+    "tmpDir": "reports/infection/",
+    "minMsi": 100,
+    "timeout": 30,
+    "source": {
+        "directories": [
+            "src"
+        ]
+    },
+    "phpUnit": {
+        "configDir": "",
+        "customPath": "./vendor/bin/phpunit"
+    },
+    "mutators": {
+        "@default": true
+    },
+    "minCoveredMsi": 100,
+    "testFramework": "phpunit"
+}
diff --git a/.claude/skills/tiny-blocks-create/assets/config/phpcs.xml b/.claude/skills/tiny-blocks-create/assets/config/phpcs.xml
new file mode 100644
index 0000000..a52372c
--- /dev/null
+++ b/.claude/skills/tiny-blocks-create/assets/config/phpcs.xml
@@ -0,0 +1,7 @@
+<?xml version="1.0"?>
+<ruleset name="tiny-blocks">
+    <description>Code style for the tiny-blocks library.</description>
+    <rule ref="PSR12"/>
+    <file>src</file>
+    <file>tests</file>
+</ruleset>
diff --git a/.claude/skills/tiny-blocks-create/assets/config/phpstan.neon.dist b/.claude/skills/tiny-blocks-create/assets/config/phpstan.neon.dist
new file mode 100644
index 0000000..0df69df
--- /dev/null
+++ b/.claude/skills/tiny-blocks-create/assets/config/phpstan.neon.dist
@@ -0,0 +1,6 @@
+parameters:
+    level: max
+    paths:
+        - src
+        - tests
+    reportUnmatchedIgnoredErrors: true
diff --git a/.claude/skills/tiny-blocks-create/assets/config/phpunit.xml b/.claude/skills/tiny-blocks-create/assets/config/phpunit.xml
new file mode 100644
index 0000000..9cc6d13
--- /dev/null
+++ b/.claude/skills/tiny-blocks-create/assets/config/phpunit.xml
@@ -0,0 +1,39 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<phpunit xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+         xsi:noNamespaceSchemaLocation="./vendor/phpunit/phpunit/phpunit.xsd"
+         beStrictAboutOutputDuringTests="true"
+         cacheDirectory=".phpunit.cache"
+         colors="true"
+         executionOrder="random"
+         failOnDeprecation="true"
+         failOnNotice="true"
+         failOnPhpunitDeprecation="true"
+         failOnRisky="true"
+         failOnWarning="true">
+
+    <source>
+        <include>
+            <directory>src</directory>
+        </include>
+    </source>
+
+    <testsuites>
+        <testsuite name="default">
+            <directory>tests</directory>
+        </testsuite>
+    </testsuites>
+
+    <coverage>
+        <report>
+            <xml outputDirectory="reports/coverage/coverage-xml"/>
+            <html outputDirectory="reports/coverage/coverage-html"/>
+            <text outputFile="reports/coverage.txt"/>
+            <clover outputFile="reports/coverage-clover.xml"/>
+        </report>
+    </coverage>
+
+    <logging>
+        <junit outputFile="reports/coverage/junit.xml"/>
+    </logging>
+
+</phpunit>
diff --git a/.claude/skills/tiny-blocks-create/assets/docs/SECURITY.md b/.claude/skills/tiny-blocks-create/assets/docs/SECURITY.md
new file mode 100644
index 0000000..a892afe
--- /dev/null
+++ b/.claude/skills/tiny-blocks-create/assets/docs/SECURITY.md
@@ -0,0 +1,12 @@
+# Security Policy
+
+## Supported versions
+
+Only the latest release receives security updates.
+
+## Reporting a vulnerability
+
+Report security vulnerabilities privately via
+[GitHub Security Advisories](https://github.com/tiny-blocks/<lib-name>/security/advisories/new).
+
+Please do not disclose the vulnerability publicly until it has been addressed.
diff --git a/.claude/skills/tiny-blocks-create/assets/github/ISSUE_TEMPLATE/bug_report.md b/.claude/skills/tiny-blocks-create/assets/github/ISSUE_TEMPLATE/bug_report.md
new file mode 100644
index 0000000..8ddd1db
--- /dev/null
+++ b/.claude/skills/tiny-blocks-create/assets/github/ISSUE_TEMPLATE/bug_report.md
@@ -0,0 +1,29 @@
+---
+name: Bug report
+about: Report a bug to help improve the library
+labels: bug
+---
+
+## Description
+
+A clear and concise description of the bug.
+
+## Steps to reproduce
+
+1.
+2.
+3.
+
+## Expected behavior
+
+What should happen.
+
+## Actual behavior
+
+What actually happens.
+
+## Environment
+
+- PHP version:
+- Library version:
+- OS:
diff --git a/.claude/skills/tiny-blocks-create/assets/github/ISSUE_TEMPLATE/feature_request.md b/.claude/skills/tiny-blocks-create/assets/github/ISSUE_TEMPLATE/feature_request.md
new file mode 100644
index 0000000..b344d9e
--- /dev/null
+++ b/.claude/skills/tiny-blocks-create/assets/github/ISSUE_TEMPLATE/feature_request.md
@@ -0,0 +1,17 @@
+---
+name: Feature request
+about: Suggest a feature for the library
+labels: enhancement
+---
+
+## Problem
+
+What problem does this feature solve?
+
+## Proposed solution
+
+How should the feature work?
+
+## Alternatives considered
+
+Other approaches considered.
diff --git a/.claude/skills/tiny-blocks-create/assets/github/PULL_REQUEST_TEMPLATE.md b/.claude/skills/tiny-blocks-create/assets/github/PULL_REQUEST_TEMPLATE.md
new file mode 100644
index 0000000..7a2c836
--- /dev/null
+++ b/.claude/skills/tiny-blocks-create/assets/github/PULL_REQUEST_TEMPLATE.md
@@ -0,0 +1,16 @@
+> Please follow the [contributing guidelines](https://github.com/tiny-blocks/tiny-blocks/blob/main/CONTRIBUTING.md).
+
+## Summary
+
+What this pull request does.
+
+## Related issue
+
+Closes #...
+
+## Checklist
+
+- [ ] Tests added or updated.
+- [ ] Documentation updated when applicable.
+- [ ] `composer review` passes.
+- [ ] `composer tests` passes.
diff --git a/.claude/skills/tiny-blocks-create/assets/github/workflows/ci.yml b/.claude/skills/tiny-blocks-create/assets/github/workflows/ci.yml
new file mode 100644
index 0000000..728bb3b
--- /dev/null
+++ b/.claude/skills/tiny-blocks-create/assets/github/workflows/ci.yml
@@ -0,0 +1,105 @@
+name: CI
+
+on:
+  pull_request:
+
+concurrency:
+  group: ci-${{ github.event.pull_request.number }}
+  cancel-in-progress: true
+
+permissions:
+  contents: read
+
+jobs:
+  resolve-php-version:
+    name: Resolve PHP version
+    runs-on: ubuntu-latest
+    timeout-minutes: 5
+    outputs:
+      php-version: ${{ steps.config.outputs.php-version }}
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v6
+
+      - name: Resolve PHP version from composer.json
+        id: config
+        run: |
+          version=$(jq -r '.require.php' composer.json | grep -oP '\d+\.\d+' | head -1)
+          echo "php-version=$version" >> "$GITHUB_OUTPUT"
+
+  build:
+    name: Build
+    needs: resolve-php-version
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v6
+
+      - name: Setup PHP
+        uses: shivammathur/setup-php@v2
+        with:
+          tools: composer:2
+          php-version: ${{ needs.resolve-php-version.outputs.php-version }}
+
+      - name: Validate composer.json
+        run: composer validate --no-interaction
+
+      - name: Install dependencies
+        run: composer install --no-progress --optimize-autoloader --prefer-dist --no-interaction
+
+      - name: Upload vendor and composer.lock as artifact
+        uses: actions/upload-artifact@v7
+        with:
+          name: vendor-artifact
+          path: |
+            vendor
+            composer.lock
+
+  auto-review:
+    name: Auto review
+    needs: [resolve-php-version, build]
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v6
+
+      - name: Setup PHP
+        uses: shivammathur/setup-php@v2
+        with:
+          tools: composer:2
+          php-version: ${{ needs.resolve-php-version.outputs.php-version }}
+
+      - name: Download vendor artifact from build
+        uses: actions/download-artifact@v8
+        with:
+          name: vendor-artifact
+          path: .
+
+      - name: Run review
+        run: composer review
+
+  tests:
+    name: Tests
+    needs: [resolve-php-version, auto-review]
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v6
+
+      - name: Setup PHP
+        uses: shivammathur/setup-php@v2
+        with:
+          tools: composer:2
+          php-version: ${{ needs.resolve-php-version.outputs.php-version }}
+
+      - name: Download vendor artifact from build
+        uses: actions/download-artifact@v8
+        with:
+          name: vendor-artifact
+          path: .
+
+      - name: Run tests
+        run: composer tests
diff --git a/.editorconfig b/.editorconfig
new file mode 100644
index 0000000..be5640e
--- /dev/null
+++ b/.editorconfig
@@ -0,0 +1,19 @@
+root = true
+
+[*]
+charset = utf-8
+end_of_line = lf
+indent_size = 4
+indent_style = space
+max_line_length = 120
+insert_final_newline = true
+trim_trailing_whitespace = true
+
+[*.{yml,yaml}]
+indent_size = 2
+
+[Makefile]
+indent_style = tab
+
+[*.md]
+trim_trailing_whitespace = false
diff --git a/.gitattributes b/.gitattributes
new file mode 100644
index 0000000..2bd9baa
--- /dev/null
+++ b/.gitattributes
@@ -0,0 +1,19 @@
+* text=auto eol=lf
+
+*.php text diff=php
+
+# Dev-only, excluded from the Packagist tarball
+/.github             export-ignore
+/tests               export-ignore
+/.claude             export-ignore
+/CLAUDE.md           export-ignore
+/.editorconfig       export-ignore
+/.gitattributes      export-ignore
+/.gitignore          export-ignore
+/phpcs.xml           export-ignore
+/phpunit.xml         export-ignore
+/phpstan.neon.dist   export-ignore
+/infection.json.dist export-ignore
+/Makefile            export-ignore
+/reports             export-ignore
+/.phpunit.cache      export-ignore
diff --git a/.github/ISSUE_TEMPLATE/bug_report.md b/.github/ISSUE_TEMPLATE/bug_report.md
new file mode 100644
index 0000000..8ddd1db
--- /dev/null
+++ b/.github/ISSUE_TEMPLATE/bug_report.md
@@ -0,0 +1,29 @@
+---
+name: Bug report
+about: Report a bug to help improve the library
+labels: bug
+---
+
+## Description
+
+A clear and concise description of the bug.
+
+## Steps to reproduce
+
+1.
+2.
+3.
+
+## Expected behavior
+
+What should happen.
+
+## Actual behavior
+
+What actually happens.
+
+## Environment
+
+- PHP version:
+- Library version:
+- OS:
diff --git a/.github/ISSUE_TEMPLATE/feature_request.md b/.github/ISSUE_TEMPLATE/feature_request.md
new file mode 100644
index 0000000..b344d9e
--- /dev/null
+++ b/.github/ISSUE_TEMPLATE/feature_request.md
@@ -0,0 +1,17 @@
+---
+name: Feature request
+about: Suggest a feature for the library
+labels: enhancement
+---
+
+## Problem
+
+What problem does this feature solve?
+
+## Proposed solution
+
+How should the feature work?
+
+## Alternatives considered
+
+Other approaches considered.
diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md
new file mode 100644
index 0000000..7a2c836
--- /dev/null
+++ b/.github/PULL_REQUEST_TEMPLATE.md
@@ -0,0 +1,16 @@
+> Please follow the [contributing guidelines](https://github.com/tiny-blocks/tiny-blocks/blob/main/CONTRIBUTING.md).
+
+## Summary
+
+What this pull request does.
+
+## Related issue
+
+Closes #...
+
+## Checklist
+
+- [ ] Tests added or updated.
+- [ ] Documentation updated when applicable.
+- [ ] `composer review` passes.
+- [ ] `composer tests` passes.
diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md
new file mode 100644
index 0000000..de1576d
--- /dev/null
+++ b/.github/copilot-instructions.md
@@ -0,0 +1,12 @@
+# Copilot instructions
+
+## Context
+
+PHP library in the tiny-blocks ecosystem.
+
+## Mandatory pre-task step
+
+Before starting any task, read and strictly follow `CLAUDE.md` and every rule file in
+`.claude/rules/`. These files are the absolute source of truth for code generation. Apply every
+rule strictly. Do not deviate from the patterns, folder structure, or naming conventions defined
+in them.
diff --git a/.github/dependabot.yml b/.github/dependabot.yml
new file mode 100644
index 0000000..f0ce8fc
--- /dev/null
+++ b/.github/dependabot.yml
@@ -0,0 +1,31 @@
+version: 2
+
+updates:
+  - package-ecosystem: "composer"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+    open-pull-requests-limit: 0
+    labels:
+      - "php"
+      - "security"
+      - "dependencies"
+    groups:
+      php-security:
+        applies-to: security-updates
+        patterns:
+          - "*"
+
+  - package-ecosystem: "github-actions"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+    commit-message:
+      prefix: "build"
+    labels:
+      - "dependencies"
+      - "github-actions"
+    groups:
+      github-actions:
+        patterns:
+          - "*"
diff --git a/.github/workflows/auto-assign.yml b/.github/workflows/auto-assign.yml
new file mode 100644
index 0000000..e87e331
--- /dev/null
+++ b/.github/workflows/auto-assign.yml
@@ -0,0 +1,32 @@
+name: Auto assign issues and pull requests
+
+on:
+  issues:
+    types:
+      - opened
+  pull_request:
+    types:
+      - opened
+
+concurrency:
+  group: auto-assign-${{ github.event.issue.number || github.event.pull_request.number }}
+  cancel-in-progress: true
+
+permissions:
+  issues: write
+  pull-requests: write
+
+jobs:
+  auto-assign:
+    name: Auto assign
+    runs-on: ubuntu-latest
+    timeout-minutes: 5
+    steps:
+      - name: Assign issues and pull requests
+        uses: gustavofreze/auto-assign@2.1.0
+        with:
+          assignees: '${{ vars.ASSIGNEES }}'
+          github_token: '${{ secrets.GITHUB_TOKEN }}'
+          allow_self_assign: 'true'
+          allow_no_assignees: 'true'
+          assignment_options: 'ISSUE,PULL_REQUEST'
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
new file mode 100644
index 0000000..728bb3b
--- /dev/null
+++ b/.github/workflows/ci.yml
@@ -0,0 +1,105 @@
+name: CI
+
+on:
+  pull_request:
+
+concurrency:
+  group: ci-${{ github.event.pull_request.number }}
+  cancel-in-progress: true
+
+permissions:
+  contents: read
+
+jobs:
+  resolve-php-version:
+    name: Resolve PHP version
+    runs-on: ubuntu-latest
+    timeout-minutes: 5
+    outputs:
+      php-version: ${{ steps.config.outputs.php-version }}
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v6
+
+      - name: Resolve PHP version from composer.json
+        id: config
+        run: |
+          version=$(jq -r '.require.php' composer.json | grep -oP '\d+\.\d+' | head -1)
+          echo "php-version=$version" >> "$GITHUB_OUTPUT"
+
+  build:
+    name: Build
+    needs: resolve-php-version
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v6
+
+      - name: Setup PHP
+        uses: shivammathur/setup-php@v2
+        with:
+          tools: composer:2
+          php-version: ${{ needs.resolve-php-version.outputs.php-version }}
+
+      - name: Validate composer.json
+        run: composer validate --no-interaction
+
+      - name: Install dependencies
+        run: composer install --no-progress --optimize-autoloader --prefer-dist --no-interaction
+
+      - name: Upload vendor and composer.lock as artifact
+        uses: actions/upload-artifact@v7
+        with:
+          name: vendor-artifact
+          path: |
+            vendor
+            composer.lock
+
+  auto-review:
+    name: Auto review
+    needs: [resolve-php-version, build]
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v6
+
+      - name: Setup PHP
+        uses: shivammathur/setup-php@v2
+        with:
+          tools: composer:2
+          php-version: ${{ needs.resolve-php-version.outputs.php-version }}
+
+      - name: Download vendor artifact from build
+        uses: actions/download-artifact@v8
+        with:
+          name: vendor-artifact
+          path: .
+
+      - name: Run review
+        run: composer review
+
+  tests:
+    name: Tests
+    needs: [resolve-php-version, auto-review]
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v6
+
+      - name: Setup PHP
+        uses: shivammathur/setup-php@v2
+        with:
+          tools: composer:2
+          php-version: ${{ needs.resolve-php-version.outputs.php-version }}
+
+      - name: Download vendor artifact from build
+        uses: actions/download-artifact@v8
+        with:
+          name: vendor-artifact
+          path: .
+
+      - name: Run tests
+        run: composer tests
diff --git a/.github/workflows/codeql.yml b/.github/workflows/codeql.yml
new file mode 100644
index 0000000..0634bbf
--- /dev/null
+++ b/.github/workflows/codeql.yml
@@ -0,0 +1,39 @@
+name: Security checks
+
+on:
+  push:
+    branches: [ "main" ]
+  pull_request:
+    branches: [ "main" ]
+  schedule:
+    - cron: "0 0 * * *"
+
+concurrency:
+  group: codeql-${{ github.ref }}
+  cancel-in-progress: true
+
+permissions:
+  actions: read
+  contents: read
+  security-events: write
+
+jobs:
+  analyze:
+    name: Analyze
+    runs-on: ubuntu-latest
+    timeout-minutes: 30
+    strategy:
+      fail-fast: false
+      matrix:
+        language: [ "actions" ]
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v6
+
+      - name: Initialize CodeQL
+        uses: github/codeql-action/init@v4
+        with:
+          languages: ${{ matrix.language }}
+
+      - name: Perform CodeQL analysis
+        uses: github/codeql-action/analyze@v4
diff --git a/.gitignore b/.gitignore
new file mode 100644
index 0000000..c8f4364
--- /dev/null
+++ b/.gitignore
@@ -0,0 +1,28 @@
+# PHP dependencies
+/vendor/
+composer.lock
+
+# Local config overrides (committed baselines are the .dist files)
+/phpstan.neon
+/infection.json
+
+# Tooling cache
+.phpunit.cache/
+.phpunit.result.cache
+
+# Coverage and reports
+build/
+reports/
+coverage/
+infection.log
+
+# Editors and agents
+.idea/
+.cursor/
+.vscode/
+/.claude/settings.local.json
+
+# OS
+Thumbs.db
+.DS_Store
+Desktop.ini
diff --git a/CLAUDE.md b/CLAUDE.md
new file mode 100644
index 0000000..d7efbcf
--- /dev/null
+++ b/CLAUDE.md
@@ -0,0 +1,61 @@
+# tiny-blocks PHP library
+
+A library in the [tiny-blocks](https://github.com/tiny-blocks) ecosystem: small, focused,
+framework-agnostic PHP building blocks published to Packagist. Target runtime is **PHP 8.5**.
+
+This file is the index. The detailed conventions live in `.claude/rules/` (loaded automatically
+when you touch matching files) and in three skills under `.claude/skills/`. Keep this file short:
+when a convention needs explaining, it belongs in a rule or a skill, not here.
+
+## Validate
+
+Every PHP and Composer command runs inside Docker via the `Makefile` (image
+`gustavofreze/php:8.5-alpine`). Never run PHP on the host directly.
+
+- `make review`: phpcs (PSR-12) + phpstan (`level: max`). Run before claiming code is clean.
+- `make tests`: phpunit + infection. Mutation thresholds are `minMsi: 100` / `minCoveredMsi: 100`.
+- `make test-file FILE=<ClassNameTest>`: one filtered test file, no coverage.
+- `make help`: discover all targets if any of the above is missing or has changed.
+
+Treat `make review` and `make tests` as the definition of done. Both gate every pull request in
+CI. Passing them locally is the bar before any "complete" / "fixed" / "passing" claim.
+
+## Conventions (`.claude/rules/`)
+
+Path-scoped. Each loads only when you edit matching files.
+
+- `php-library-architecture.md`: folder layout, public API boundary, `Internal/` semantics (`src/`).
+- `php-library-code-style.md`: semantic code rules, naming, PHPDoc, `self`/`static` (`src/`, `tests/`).
+- `php-library-modeling.md`: value objects, exceptions, enums, complexity (`src/`).
+- `php-library-testing.md`: BDD Given/When/Then, PHPUnit, fixtures, coverage discipline (`tests/`).
+- `php-library-tooling.md`: invariants for `composer.json`, `phpcs.xml`, `phpunit.xml`, etc.
+- `php-library-documentation.md`: README and `docs/` conventions.
+- `php-library-github-workflows.md`: GitHub Actions conventions.
+
+## Skills (`.claude/skills/`)
+
+- `tiny-blocks-create`: scaffold a new library or restore a canonical config/repo file. Holds
+  the drop-in bodies of every config file, the CI workflow, and the issue/PR/security templates.
+- `tiny-blocks-consume`: discover and reuse a published tiny-blocks package as a dependency
+  instead of writing the capability by hand. Checks the catalog, adds the match with Composer,
+  and uses the installed package's own README and public API. The consuming counterpart of
+  `tiny-blocks-create`.
+- `commit-message`: generate a Conventional Commits message in the ecosystem's format. Invoke
+  when writing a commit. Commit messages are never generated automatically.
+
+## Global defaults
+
+- All identifiers, comments, documentation, and commit messages use American English.
+- In prose and headings, do not use semicolons or em-dashes. This applies to PHPDoc descriptions
+  and to every Markdown file (README, docs). Use a period or a comma in place of a semicolon, and
+  a colon, a comma, or parentheses in place of an em-dash. Hyphens in compound words and
+  identifiers (`tiny-blocks`, `name-length`) are not affected, and semicolons that terminate PHP
+  statements in code are not affected.
+- Prefer dependencies from the tiny-blocks ecosystem before reaching outside it.
+- Do not install or update any dependency to a version published less than 7 days ago. Freshly
+  released versions can be yanked or compromised. Let them age past the cooldown first. Packages
+  from the tiny-blocks ecosystem (`tiny-blocks/*`) are exempt, they are first-party. When a
+  dependency bump is needed but the target version is too recent, report it and wait rather than
+  pinning the new version.
+- Do not run any history-altering Git operation (branch, commit, push, merge, rebase, tag) unless
+  explicitly asked.
diff --git a/Makefile b/Makefile
new file mode 100644
index 0000000..90ab50d
--- /dev/null
+++ b/Makefile
@@ -0,0 +1,74 @@
+PWD := $(CURDIR)
+ARCH := $(shell uname -m)
+PLATFORM :=
+
+ifeq ($(ARCH),arm64)
+    PLATFORM := --platform=linux/amd64
+endif
+
+TTY := $(shell [ -t 0 ] && echo -it)
+
+DOCKER_RUN = docker run ${PLATFORM} --rm ${TTY} --net=host -v ${PWD}:/app -w /app gustavofreze/php:8.5-alpine
+
+RESET := \033[0m
+GREEN := \033[0;32m
+YELLOW := \033[0;33m
+
+.DEFAULT_GOAL := help
+
+.PHONY: configure
+configure: ## Configure development environment
+	@${DOCKER_RUN} composer configure
+
+.PHONY: configure-and-update
+configure-and-update: ## Configure development environment and update dependencies
+	@${DOCKER_RUN} composer configure-and-update
+
+.PHONY: tests
+tests: ## Run unit and mutation tests with coverage
+	@${DOCKER_RUN} composer tests
+
+.PHONY: test-file
+test-file: ## Run tests for a specific file (usage: make test-file FILE=ClassNameTest)
+	@${DOCKER_RUN} composer test-file ${FILE}
+
+.PHONY: review
+review: ## Run lint and static analysis
+	@${DOCKER_RUN} composer review
+
+.PHONY: show-reports
+show-reports: ## Open coverage and mutation reports in the browser
+	@sensible-browser reports/coverage/coverage-html/index.html reports/coverage/mutation-report.html
+
+.PHONY: show-outdated
+show-outdated: ## Show outdated direct dependencies
+	@${DOCKER_RUN} composer outdated --direct
+
+.PHONY: clean
+clean: ## Remove dependencies and generated artifacts
+	@sudo chown -R ${USER}:${USER} ${PWD}
+	@rm -rf reports vendor .phpunit.cache *.lock
+
+.PHONY: help
+help: ## Display this help message
+	@echo "Usage: make [target]"
+	@echo ""
+	@echo "$$(printf '$(GREEN)')Setup$$(printf '$(RESET)')"
+	@grep -E '^(configure|configure-and-update):.*?## .*$$' $(MAKEFILE_LIST) \
+		| awk 'BEGIN {FS = ":.*? ## "}; {printf "$(YELLOW)%-25s$(RESET) %s\n", $$1, $$2}'
+	@echo ""
+	@echo "$$(printf '$(GREEN)')Testing$$(printf '$(RESET)')"
+	@grep -E '^(tests|test-file):.*?## .*$$' $(MAKEFILE_LIST) \
+		| awk 'BEGIN {FS = ":.*?## "}; {printf "$(YELLOW)%-25s$(RESET) %s\n", $$1, $$2}'
+	@echo ""
+	@echo "$$(printf '$(GREEN)')Quality$$(printf '$(RESET)')"
+	@grep -E '^(review):.*?## .*$$' $(MAKEFILE_LIST) \
+		| awk 'BEGIN {FS = ":.*?## "}; {printf "$(YELLOW)%-25s$(RESET) %s\n", $$1, $$2}'
+	@echo ""
+	@echo "$$(printf '$(GREEN)')Reports$$(printf '$(RESET)')"
+	@grep -E '^(show-reports|show-outdated):.*?## .*$$' $(MAKEFILE_LIST) \
+		| awk 'BEGIN {FS = ":.*?## "}; {printf "$(YELLOW)%-25s$(RESET) %s\n", $$1, $$2}'
+	@echo ""
+	@echo "$$(printf '$(GREEN)')Cleanup$$(printf '$(RESET)')"
+	@grep -E '^(clean):.*?## .*$$' $(MAKEFILE_LIST) \
+		| awk 'BEGIN {FS = ":.*?## "}; {printf "$(YELLOW)%-25s$(RESET) %s\n", $$1, $$2}'
diff --git a/README.md b/README.md
new file mode 100644
index 0000000..0dac272
--- /dev/null
+++ b/README.md
@@ -0,0 +1,205 @@
+# Http Middleware Error
+
+[![License](https://img.shields.io/badge/license-MIT-green)](https://github.com/tiny-blocks/http-middleware-error/blob/main/LICENSE)
+
+* [Overview](#overview)
+* [Installation](#installation)
+* [How to use](#how-to-use)
+    + [Declaring a mapping](#declaring-a-mapping)
+    + [Composing multiple mappings](#composing-multiple-mappings)
+    + [Resolving the response from the exception](#resolving-the-response-from-the-exception)
+    + [Logging and displaying error details](#logging-and-displaying-error-details)
+    + [Disabling the fallback for unmapped exceptions](#disabling-the-fallback-for-unmapped-exceptions)
+* [License](#license)
+* [Contributing](#contributing)
+
+## Overview
+
+Provides a PSR-15 middleware that captures exceptions thrown by downstream handlers and translates them into
+structured JSON error responses. Each consumer declares an `ExceptionMapping`, a class whose `mappings()` method
+returns an `ExceptionMappingTable` that turns each known exception into a `MappedError` (machine-readable code, HTTP
+status between 400 and 599, human-readable message, optional headers). The consumer declares only the rules it owns,
+and the middleware composes the tables of every configured mapping into a single first-match-wins lookup, so neither
+the consumer nor the middleware repeats the composition. Unmapped exceptions either short-circuit to a generic 500
+fallback or rethrow, depending on the builder configuration.
+
+The library integrates with [tiny-blocks/http-middleware-correlation-id](https://github.com/tiny-blocks/http-middleware-correlation-id)
+to enrich every log entry with the request's correlation identifier when one is present on the request
+attributes, so error logs can be grouped across services without any extra plumbing in the consumer's log
+calls.
+
+## Installation
+
+```bash
+composer require tiny-blocks/http-middleware-error
+```
+
+## How to use
+
+### Declaring a mapping
+
+A consumer declares the rules it owns by implementing `ExceptionMapping`. The `mappings()` method returns an
+`ExceptionMappingTable` built once, so the same table is reused on every request rather than rebuilt per exception.
+Rules are evaluated in registration order, and the first match wins. Exact-class, listed-class, and subclass matches
+cover the common cases.
+
+```php
+<?php
+
+declare(strict_types=1);
+
+use DomainException;
+use InvalidArgumentException;
+use RuntimeException;
+use TinyBlocks\HttpMiddlewareError\ExceptionMapping;
+use TinyBlocks\HttpMiddlewareError\ExceptionMappingTable;
+
+final readonly class ApplicationExceptionMapping implements ExceptionMapping
+{
+    public function mappings(): ExceptionMappingTable
+    {
+        return ExceptionMappingTable::create()
+            ->when(exceptionClass: InvalidArgumentException::class)
+            ->mapsTo(code: 'INVALID_INPUT', status: 400, message: 'The request payload is invalid.')
+            ->whenAny(exceptionClasses: [DomainException::class, RuntimeException::class])
+            ->mapsTo(code: 'BUSINESS_FAILURE', status: 422, message: 'The operation could not be completed.')
+            ->whenSubclassOf(baseException: RuntimeException::class)
+            ->mapsTo(code: 'RUNTIME_FAMILY', status: 500, message: 'A runtime error occurred.');
+    }
+}
+```
+
+Register the mapping on the middleware and add it to the PSR-15 pipeline.
+
+```php
+<?php
+
+declare(strict_types=1);
+
+use TinyBlocks\HttpMiddlewareError\ErrorMiddleware;
+
+# Build the middleware with the declared mapping.
+$middleware = ErrorMiddleware::create()
+    ->withMapping(mapping: new ApplicationExceptionMapping())
+    ->build();
+```
+
+### Composing multiple mappings
+
+When several verticals each own a mapping (for example, a write side and a read side), pass them all to
+`withMappings`. The middleware composes them into a single first-match-wins lookup, evaluating the mappings in the
+order given, so the consumer never writes the composition by hand.
+
+```php
+<?php
+
+declare(strict_types=1);
+
+use TinyBlocks\HttpMiddlewareError\ErrorMiddleware;
+
+# The mappings are supplied by the consumer.
+$write = new WriteExceptionMapping();
+$read = new ReadExceptionMapping();
+
+# Compose both mappings under one middleware.
+$middleware = ErrorMiddleware::create()
+    ->withMappings($write, $read)
+    ->build();
+```
+
+### Resolving the response from the exception
+
+Builds the `MappedError` from the matched exception when the response depends on runtime state (for example,
+when the exception carries fields that should be exposed to the client). The closure receives the matched throwable
+and returns a `MappedError` built from it.
+
+```php
+<?php
+
+declare(strict_types=1);
+
+use RuntimeException;
+use Throwable;
+use TinyBlocks\HttpMiddlewareError\ExceptionMapping;
+use TinyBlocks\HttpMiddlewareError\ExceptionMappingTable;
+use TinyBlocks\HttpMiddlewareError\MappedError;
+
+final readonly class GatewayExceptionMapping implements ExceptionMapping
+{
+    public function mappings(): ExceptionMappingTable
+    {
+        return ExceptionMappingTable::create()
+            ->when(exceptionClass: RuntimeException::class)
+            ->resolvesWith(
+                resolver: fn(Throwable $exception): MappedError => new MappedError(
+                    code: 'GATEWAY_UNAVAILABLE',
+                    status: 502,
+                    message: $exception->getMessage()
+                )
+            );
+    }
+}
+```
+
+### Logging and displaying error details
+
+Enables structured error logging and the optional inclusion of exception details in the response body. The
+defaults are silent and secure: nothing is logged and no stack traces are returned to the client.
+
+```php
+<?php
+
+declare(strict_types=1);
+
+use Psr\Log\LoggerInterface;
+use TinyBlocks\HttpMiddlewareError\ErrorHandlingSettings;
+use TinyBlocks\HttpMiddlewareError\ErrorMiddleware;
+use TinyBlocks\HttpMiddlewareError\ExceptionMapping;
+
+# The logger and the mapping are supplied by the consumer.
+$logger = /** @var LoggerInterface */ null;
+$mapping = /** @var ExceptionMapping */ null;
+
+# Enable error logging with full details, but keep stack traces out of the response.
+$middleware = ErrorMiddleware::create()
+    ->withLogger(logger: $logger)
+    ->withMapping(mapping: $mapping)
+    ->withSettings(settings: ErrorHandlingSettings::from(
+        logErrors: true,
+        logErrorDetails: true,
+        displayErrorDetails: false
+    ))
+    ->build();
+```
+
+### Disabling the fallback for unmapped exceptions
+
+Forces unmapped exceptions to propagate to the outer handler instead of returning the generic 500 fallback.
+Useful when a higher-level error boundary should observe the original throwable.
+
+```php
+<?php
+
+declare(strict_types=1);
+
+use TinyBlocks\HttpMiddlewareError\ErrorMiddleware;
+use TinyBlocks\HttpMiddlewareError\ExceptionMapping;
+
+# The mapping is supplied by the consumer.
+$mapping = /** @var ExceptionMapping */ null;
+
+# Disable the fallback so that unmapped exceptions rethrow.
+$middleware = ErrorMiddleware::create()
+    ->withMapping(mapping: $mapping)
+    ->withFallbackOnUnmapped(false)
+    ->build();
+```
+
+## License
+
+Http Middleware Error is licensed under [MIT](LICENSE).
+
+## Contributing
+
+Please follow the [contributing guidelines](https://github.com/tiny-blocks/tiny-blocks/blob/main/CONTRIBUTING.md) to
+contribute to the project.
diff --git a/SECURITY.md b/SECURITY.md
new file mode 100644
index 0000000..a86eff3
--- /dev/null
+++ b/SECURITY.md
@@ -0,0 +1,12 @@
+# Security Policy
+
+## Supported versions
+
+Only the latest release receives security updates.
+
+## Reporting a vulnerability
+
+Report security vulnerabilities privately via
+[GitHub Security Advisories](https://github.com/tiny-blocks/http-middleware-error/security/advisories/new).
+
+Please do not disclose the vulnerability publicly until it has been addressed.
diff --git a/composer.json b/composer.json
new file mode 100644
index 0000000..495711a
--- /dev/null
+++ b/composer.json
@@ -0,0 +1,81 @@
+{
+    "name": "tiny-blocks/http-middleware-error",
+    "description": "PSR-15 middleware that maps thrown exceptions to structured JSON error responses with optional logging.",
+    "license": "MIT",
+    "type": "library",
+    "keywords": [
+        "http",
+        "psr-15",
+        "middleware",
+        "tiny-blocks",
+        "observability",
+        "error-handling",
+        "exception-mapping"
+    ],
+    "authors": [
+        {
+            "name": "Gustavo Freze de Araujo Santos",
+            "homepage": "https://github.com/gustavofreze"
+        }
+    ],
+    "homepage": "https://github.com/tiny-blocks/http-middleware-error",
+    "support": {
+        "issues": "https://github.com/tiny-blocks/http-middleware-error/issues",
+        "source": "https://github.com/tiny-blocks/http-middleware-error"
+    },
+    "require": {
+        "php": "^8.5",
+        "psr/http-message": "^2.0",
+        "psr/http-server-handler": "^1.0",
+        "psr/http-server-middleware": "^1.0",
+        "psr/log": "^3.0",
+        "tiny-blocks/http": "^6.3",
+        "tiny-blocks/http-middleware-correlation-id": "^1.0"
+    },
+    "require-dev": {
+        "ergebnis/composer-normalize": "^2.52",
+        "guzzlehttp/psr7": "^2.9",
+        "infection/infection": "^0.33",
+        "phpstan/phpstan": "^2.2",
+        "phpunit/phpunit": "^13.1",
+        "squizlabs/php_codesniffer": "^4.0"
+    },
+    "minimum-stability": "stable",
+    "prefer-stable": true,
+    "autoload": {
+        "psr-4": {
+            "TinyBlocks\\HttpMiddlewareError\\": "src/"
+        }
+    },
+    "autoload-dev": {
+        "psr-4": {
+            "Test\\TinyBlocks\\HttpMiddlewareError\\Unit\\": "tests/Unit/"
+        }
+    },
+    "config": {
+        "allow-plugins": {
+            "ergebnis/composer-normalize": true,
+            "infection/extension-installer": true
+        },
+        "sort-packages": true
+    },
+    "scripts": {
+        "configure": [
+            "@composer install --optimize-autoloader",
+            "@composer normalize"
+        ],
+        "configure-and-update": [
+            "@composer update --optimize-autoloader",
+            "@composer normalize"
+        ],
+        "review": [
+            "@php ./vendor/bin/phpcs --standard=phpcs.xml --extensions=php ./src ./tests",
+            "@php ./vendor/bin/phpstan analyse -c phpstan.neon.dist --quiet --no-progress"
+        ],
+        "test-file": "@php ./vendor/bin/phpunit --configuration phpunit.xml --no-coverage --filter",
+        "tests": [
+            "@php -d memory_limit=2G ./vendor/bin/phpunit --configuration phpunit.xml tests",
+            "@php ./vendor/bin/infection --threads=max --logger-html=reports/coverage/mutation-report.html --coverage=reports/coverage"
+        ]
+    }
+}
diff --git a/infection.json.dist b/infection.json.dist
new file mode 100644
index 0000000..aab8c7e
--- /dev/null
+++ b/infection.json.dist
@@ -0,0 +1,23 @@
+{
+    "logs": {
+        "text": "reports/infection/logs/infection-text.log",
+        "summary": "reports/infection/logs/infection-summary.log"
+    },
+    "tmpDir": "reports/infection/",
+    "minMsi": 100,
+    "timeout": 30,
+    "source": {
+        "directories": [
+            "src"
+        ]
+    },
+    "phpUnit": {
+        "configDir": "",
+        "customPath": "./vendor/bin/phpunit"
+    },
+    "mutators": {
+        "@default": true
+    },
+    "minCoveredMsi": 100,
+    "testFramework": "phpunit"
+}
diff --git a/phpcs.xml b/phpcs.xml
new file mode 100644
index 0000000..a52372c
--- /dev/null
+++ b/phpcs.xml
@@ -0,0 +1,7 @@
+<?xml version="1.0"?>
+<ruleset name="tiny-blocks">
+    <description>Code style for the tiny-blocks library.</description>
+    <rule ref="PSR12"/>
+    <file>src</file>
+    <file>tests</file>
+</ruleset>
diff --git a/phpstan.neon.dist b/phpstan.neon.dist
new file mode 100644
index 0000000..9147e2f
--- /dev/null
+++ b/phpstan.neon.dist
@@ -0,0 +1,34 @@
+parameters:
+    level: max
+    paths:
+        - src
+        - tests
+    ignoreErrors:
+        # Constructor parameter holds the registered entries; PHPDoc is prohibited on constructors.
+        - identifier: missingType.iterableValue
+          path: src/ExceptionMappingTable.php
+
+        # Iteration over the constructor-typed array of entries; root cause is the same as above.
+        - identifier: method.nonObject
+          path: src/ExceptionMappingTable.php
+
+        # The mapTo return type cannot be inferred without the constructor-level array shape.
+        - identifier: return.type
+          path: src/ExceptionMappingTable.php
+
+        # Internal matcher accepts a list of class-strings; PHPDoc is prohibited inside src/Internal/.
+        - identifier: missingType.iterableValue
+          path: src/Internal/AnyExactClassMatcher.php
+
+        # Closure invocation is opaque to PHPStan; PHPDoc is prohibited inside src/Internal/.
+        - identifier: return.type
+          path: src/Internal/DynamicMappedErrorResolver.php
+
+        # json_decode in test assertions yields mixed; PHPDoc is prohibited inside tests/.
+        - identifier: offsetAccess.nonOffsetAccessible
+          path: tests/Unit/ErrorMiddlewareTest.php
+
+        # Same root cause as the offset access entry: assertArrayHasKey/NotHasKey receive mixed from json_decode.
+        - identifier: argument.type
+          path: tests/Unit/ErrorMiddlewareTest.php
+    reportUnmatchedIgnoredErrors: true
diff --git a/phpunit.xml b/phpunit.xml
new file mode 100644
index 0000000..9cc6d13
--- /dev/null
+++ b/phpunit.xml
@@ -0,0 +1,39 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<phpunit xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+         xsi:noNamespaceSchemaLocation="./vendor/phpunit/phpunit/phpunit.xsd"
+         beStrictAboutOutputDuringTests="true"
+         cacheDirectory=".phpunit.cache"
+         colors="true"
+         executionOrder="random"
+         failOnDeprecation="true"
+         failOnNotice="true"
+         failOnPhpunitDeprecation="true"
+         failOnRisky="true"
+         failOnWarning="true">
+
+    <source>
+        <include>
+            <directory>src</directory>
+        </include>
+    </source>
+
+    <testsuites>
+        <testsuite name="default">
+            <directory>tests</directory>
+        </testsuite>
+    </testsuites>
+
+    <coverage>
+        <report>
+            <xml outputDirectory="reports/coverage/coverage-xml"/>
+            <html outputDirectory="reports/coverage/coverage-html"/>
+            <text outputFile="reports/coverage.txt"/>
+            <clover outputFile="reports/coverage-clover.xml"/>
+        </report>
+    </coverage>
+
+    <logging>
+        <junit outputFile="reports/coverage/junit.xml"/>
+    </logging>
+
+</phpunit>
diff --git a/src/ErrorHandlingSettings.php b/src/ErrorHandlingSettings.php
new file mode 100644
index 0000000..70c0c88
--- /dev/null
+++ b/src/ErrorHandlingSettings.php
@@ -0,0 +1,53 @@
+<?php
+
+declare(strict_types=1);
+
+namespace TinyBlocks\HttpMiddlewareError;
+
+/**
+ * Flags controlling logging behavior and the verbosity of error responses produced by
+ * {@see ErrorMiddleware}.
+ */
+final readonly class ErrorHandlingSettings
+{
+    private function __construct(
+        public bool $logErrors,
+        public bool $logErrorDetails,
+        public bool $displayErrorDetails
+    ) {
+    }
+
+    /**
+     * Creates an ErrorHandlingSettings with all flags disabled.
+     *
+     * @return ErrorHandlingSettings The default settings instance.
+     */
+    public static function default(): ErrorHandlingSettings
+    {
+        return ErrorHandlingSettings::from(
+            logErrors: false,
+            logErrorDetails: false,
+            displayErrorDetails: false
+        );
+    }
+
+    /**
+     * Creates an ErrorHandlingSettings from the given flags.
+     *
+     * @param bool $logErrors Whether to enable error logging when a logger is provided.
+     * @param bool $logErrorDetails Whether to include exception class, file, line, and trace in the log context.
+     * @param bool $displayErrorDetails Whether to include exception class, file, line, and trace in the response body.
+     * @return ErrorHandlingSettings The configured settings instance.
+     */
+    public static function from(
+        bool $logErrors,
+        bool $logErrorDetails,
+        bool $displayErrorDetails
+    ): ErrorHandlingSettings {
+        return new ErrorHandlingSettings(
+            logErrors: $logErrors,
+            logErrorDetails: $logErrorDetails,
+            displayErrorDetails: $displayErrorDetails
+        );
+    }
+}
diff --git a/src/ErrorMiddleware.php b/src/ErrorMiddleware.php
new file mode 100644
index 0000000..b1bdf90
--- /dev/null
+++ b/src/ErrorMiddleware.php
@@ -0,0 +1,71 @@
+<?php
+
+declare(strict_types=1);
+
+namespace TinyBlocks\HttpMiddlewareError;
+
+use Psr\Http\Message\ResponseInterface;
+use Psr\Http\Message\ServerRequestInterface;
+use Psr\Http\Server\MiddlewareInterface;
+use Psr\Http\Server\RequestHandlerInterface;
+use Psr\Log\LoggerInterface;
+use Throwable;
+use TinyBlocks\HttpMiddlewareError\Internal\ErrorLogger;
+use TinyBlocks\HttpMiddlewareError\Internal\ErrorMiddlewareBuilder;
+use TinyBlocks\HttpMiddlewareError\Internal\ErrorOutcome;
+
+/**
+ * PSR-15 middleware that captures exceptions thrown downstream, delegates to a consumer-provided
+ * {@see ExceptionMapping}, and produces a structured JSON error response. Unmapped exceptions either
+ * fall back to a 500 response or rethrow, depending on the builder configuration.
+ */
+final readonly class ErrorMiddleware implements MiddlewareInterface
+{
+    private function __construct(private ErrorOutcome $errorOutcome)
+    {
+    }
+
+    /**
+     * Builds an ErrorMiddleware from its configuration components.
+     *
+     * @param LoggerInterface|null $logger The logger to use for error logging, or <code>null</code> to disable logging.
+     * @param ExceptionMappingTable $mappings The composed table that maps exceptions to error responses.
+     * @param ErrorHandlingSettings $settings The settings controlling error display and logging behavior.
+     * @param bool $fallbackOnUnmapped Whether to return a fallback response when no mapping matches.
+     * @return ErrorMiddleware The configured middleware instance.
+     */
+    public static function build(
+        ?LoggerInterface $logger,
+        ExceptionMappingTable $mappings,
+        ErrorHandlingSettings $settings,
+        bool $fallbackOnUnmapped
+    ): ErrorMiddleware {
+        $errorOutcome = new ErrorOutcome(
+            mappings: $mappings,
+            settings: $settings,
+            errorLogger: ErrorLogger::from(logger: $logger, settings: $settings),
+            fallbackOnUnmapped: $fallbackOnUnmapped
+        );
+
+        return new ErrorMiddleware(errorOutcome: $errorOutcome);
+    }
+
+    /**
+     * Creates an ErrorMiddlewareBuilder for fluent configuration.
+     *
+     * @return ErrorMiddlewareBuilder The builder instance.
+     */
+    public static function create(): ErrorMiddlewareBuilder
+    {
+        return new ErrorMiddlewareBuilder();
+    }
+
+    public function process(ServerRequestInterface $request, RequestHandlerInterface $handler): ResponseInterface
+    {
+        try {
+            return $handler->handle($request);
+        } catch (Throwable $exception) {
+            return $this->errorOutcome->resolve(request: $request, exception: $exception);
+        }
+    }
+}
diff --git a/src/ExceptionMapping.php b/src/ExceptionMapping.php
new file mode 100644
index 0000000..c6426da
--- /dev/null
+++ b/src/ExceptionMapping.php
@@ -0,0 +1,22 @@
+<?php
+
+declare(strict_types=1);
+
+namespace TinyBlocks\HttpMiddlewareError;
+
+/**
+ * Consumer-declared set of rules that translate the consumer's own exceptions into mapped errors.
+ *
+ * <p>A consumer implements this once per vertical and declares only the rules it owns. The
+ * middleware composes the {@see ExceptionMappingTable} of every configured mapping into a single
+ * first-match-wins lookup, so neither the consumer nor the middleware repeats the composition.</p>
+ */
+interface ExceptionMapping
+{
+    /**
+     * Returns the table of rules that translate this mapping's exceptions into mapped errors.
+     *
+     * @return ExceptionMappingTable The rules this mapping contributes to the composed lookup.
+     */
+    public function mappings(): ExceptionMappingTable;
+}
diff --git a/src/ExceptionMappingRule.php b/src/ExceptionMappingRule.php
new file mode 100644
index 0000000..f1e0695
--- /dev/null
+++ b/src/ExceptionMappingRule.php
@@ -0,0 +1,69 @@
+<?php
+
+declare(strict_types=1);
+
+namespace TinyBlocks\HttpMiddlewareError;
+
+use Closure;
+use Throwable;
+use TinyBlocks\HttpMiddlewareError\Internal\DynamicMappedErrorResolver;
+use TinyBlocks\HttpMiddlewareError\Internal\ExceptionMatcher;
+use TinyBlocks\HttpMiddlewareError\Internal\FixedMappedErrorResolver;
+use TinyBlocks\HttpMiddlewareError\Internal\MappingEntry;
+
+/**
+ * Intermediate builder closing a rule registered on an {@see ExceptionMappingTable}. A rule
+ * resolves either to a fixed {@see MappedError} (<code>mapsTo</code>) or to one produced by a
+ * closure that receives the matched throwable (<code>resolvesWith</code>).
+ */
+final readonly class ExceptionMappingRule
+{
+    public function __construct(private ExceptionMappingTable $table, private ExceptionMatcher $matcher)
+    {
+    }
+
+    /**
+     * Closes the rule with a closure that produces a MappedError from the matched exception.
+     *
+     * <p>The closure parameter may be typed more specifically than {@see Throwable} when the
+     * matcher guarantees the runtime type before the closure is invoked.</p>
+     *
+     * @param Closure(Throwable): MappedError $resolver The closure to invoke with the matched exception.
+     * @return ExceptionMappingTable The table with the new rule appended.
+     */
+    public function resolvesWith(Closure $resolver): ExceptionMappingTable
+    {
+        return $this->table->withEntry(
+            entry: new MappingEntry(
+                matcher: $this->matcher,
+                resolver: new DynamicMappedErrorResolver(factory: $resolver)
+            )
+        );
+    }
+
+    /**
+     * Closes the rule with a fixed MappedError produced from the given fields.
+     *
+     * @param string $code Machine-readable error code.
+     * @param int $status HTTP response status code (400-599).
+     * @param string $message Human-readable error description.
+     * @param array<string, string|string[]> $headers Optional HTTP response headers.
+     * @return ExceptionMappingTable The table with the new rule appended.
+     */
+    public function mapsTo(string $code, int $status, string $message, array $headers = []): ExceptionMappingTable
+    {
+        return $this->table->withEntry(
+            entry: new MappingEntry(
+                matcher: $this->matcher,
+                resolver: new FixedMappedErrorResolver(
+                    error: new MappedError(
+                        code: $code,
+                        status: $status,
+                        message: $message,
+                        headers: $headers
+                    )
+                )
+            )
+        );
+    }
+}
diff --git a/src/ExceptionMappingTable.php b/src/ExceptionMappingTable.php
new file mode 100644
index 0000000..d1ab212
--- /dev/null
+++ b/src/ExceptionMappingTable.php
@@ -0,0 +1,121 @@
+<?php
+
+declare(strict_types=1);
+
+namespace TinyBlocks\HttpMiddlewareError;
+
+use Throwable;
+use TinyBlocks\HttpMiddlewareError\Internal\AnyExactClassMatcher;
+use TinyBlocks\HttpMiddlewareError\Internal\ExactClassMatcher;
+use TinyBlocks\HttpMiddlewareError\Internal\MappingEntry;
+use TinyBlocks\HttpMiddlewareError\Internal\SubclassMatcher;
+
+/**
+ * Fluent table of exception-to-MappedError rules, evaluated in registration order. The first
+ * matching rule wins, and unmatched exceptions return <code>null</code> to let the middleware
+ * decide between fallback and rethrow.
+ */
+final readonly class ExceptionMappingTable
+{
+    private function __construct(private array $entries)
+    {
+    }
+
+    /**
+     * Creates an empty ExceptionMappingTable.
+     *
+     * @return ExceptionMappingTable The empty table.
+     */
+    public static function create(): ExceptionMappingTable
+    {
+        return new ExceptionMappingTable(entries: []);
+    }
+
+    /**
+     * Registers a rule for an exact exception class match.
+     *
+     * @param class-string<Throwable> $exceptionClass The exception class to match exactly.
+     * @return ExceptionMappingRule The intermediate rule builder.
+     */
+    public function when(string $exceptionClass): ExceptionMappingRule
+    {
+        return new ExceptionMappingRule(
+            table: $this,
+            matcher: new ExactClassMatcher(exceptionClass: $exceptionClass)
+        );
+    }
+
+    /**
+     * Returns the mapped error of the first rule that matches the exception, or null when none matches.
+     *
+     * @param Throwable $exception The exception to translate.
+     * @return MappedError|null The mapped error, or <code>null</code> when no registered rule matches.
+     */
+    public function mapTo(Throwable $exception): ?MappedError
+    {
+        foreach ($this->entries as $entry) {
+            $mappedError = $entry->resolve(exception: $exception);
+
+            if (!is_null($mappedError)) {
+                return $mappedError;
+            }
+        }
+
+        return null;
+    }
+
+    /**
+     * Registers a rule matching any of the given exception classes exactly.
+     *
+     * @param non-empty-list<class-string<Throwable>> $exceptionClasses The exception classes to match against.
+     * @return ExceptionMappingRule The intermediate rule builder.
+     */
+    public function whenAny(array $exceptionClasses): ExceptionMappingRule
+    {
+        return new ExceptionMappingRule(
+            table: $this,
+            matcher: new AnyExactClassMatcher(exceptionClasses: $exceptionClasses)
+        );
+    }
+
+    /**
+     * Appends an entry and returns the resulting table.
+     *
+     * <p>Not part of the consumer-facing API. Used only by {@see ExceptionMappingRule} to append entries.</p>
+     *
+     * @param MappingEntry $entry The mapping entry to append.
+     * @return ExceptionMappingTable The resulting table with the entry added.
+     */
+    public function withEntry(MappingEntry $entry): ExceptionMappingTable
+    {
+        return new ExceptionMappingTable(entries: [...$this->entries, $entry]);
+    }
+
+    /**
+     * Returns a new table with this table's rules followed by the other table's rules.
+     *
+     * <p>The combined table keeps first-match-wins across both, so the rules of this table take
+     * precedence over the rules of <code>$other</code> for an exception both would match.</p>
+     *
+     * @param ExceptionMappingTable $other The table whose rules are appended after this table's.
+     * @return ExceptionMappingTable The combined table.
+     */
+    public function mergedWith(ExceptionMappingTable $other): ExceptionMappingTable
+    {
+        return new ExceptionMappingTable(entries: [...$this->entries, ...$other->entries]);
+    }
+
+    /**
+     * Registers a rule matching any subclass of the given base exception class.
+     *
+     * @param class-string<Throwable> $baseException The base exception class to match against.
+     * @return ExceptionMappingRule The intermediate rule builder.
+     */
+    public function whenSubclassOf(string $baseException): ExceptionMappingRule
+    {
+        return new ExceptionMappingRule(
+            table: $this,
+            matcher: new SubclassMatcher(baseException: $baseException)
+        );
+    }
+}
diff --git a/src/Exceptions/HttpStatusOutOfRange.php b/src/Exceptions/HttpStatusOutOfRange.php
new file mode 100644
index 0000000..38f35fc
--- /dev/null
+++ b/src/Exceptions/HttpStatusOutOfRange.php
@@ -0,0 +1,14 @@
+<?php
+
+declare(strict_types=1);
+
+namespace TinyBlocks\HttpMiddlewareError\Exceptions;
+
+use InvalidArgumentException;
+
+/**
+ * Thrown when the HTTP status configured on a mapped error falls outside the 400-599 range.
+ */
+final class HttpStatusOutOfRange extends InvalidArgumentException
+{
+}
diff --git a/src/Internal/AnyExactClassMatcher.php b/src/Internal/AnyExactClassMatcher.php
new file mode 100644
index 0000000..1419ffe
--- /dev/null
+++ b/src/Internal/AnyExactClassMatcher.php
@@ -0,0 +1,19 @@
+<?php
+
+declare(strict_types=1);
+
+namespace TinyBlocks\HttpMiddlewareError\Internal;
+
+use Throwable;
+
+final readonly class AnyExactClassMatcher implements ExceptionMatcher
+{
+    public function __construct(private array $exceptionClasses)
+    {
+    }
+
+    public function matches(Throwable $exception): bool
+    {
+        return in_array($exception::class, $this->exceptionClasses, true);
+    }
+}
diff --git a/src/Internal/DynamicMappedErrorResolver.php b/src/Internal/DynamicMappedErrorResolver.php
new file mode 100644
index 0000000..e76adb9
--- /dev/null
+++ b/src/Internal/DynamicMappedErrorResolver.php
@@ -0,0 +1,21 @@
+<?php
+
+declare(strict_types=1);
+
+namespace TinyBlocks\HttpMiddlewareError\Internal;
+
+use Closure;
+use Throwable;
+use TinyBlocks\HttpMiddlewareError\MappedError;
+
+final readonly class DynamicMappedErrorResolver implements MappedErrorResolver
+{
+    public function __construct(private Closure $factory)
+    {
+    }
+
+    public function resolve(Throwable $exception): MappedError
+    {
+        return ($this->factory)($exception);
+    }
+}
diff --git a/src/Internal/ErrorLogger.php b/src/Internal/ErrorLogger.php
new file mode 100644
index 0000000..a2c5428
--- /dev/null
+++ b/src/Internal/ErrorLogger.php
@@ -0,0 +1,43 @@
+<?php
+
+declare(strict_types=1);
+
+namespace TinyBlocks\HttpMiddlewareError\Internal;
+
+use Psr\Http\Message\ServerRequestInterface;
+use Psr\Log\LoggerInterface;
+use Throwable;
+use TinyBlocks\HttpMiddlewareCorrelationId\CorrelatedLogger;
+use TinyBlocks\HttpMiddlewareError\ErrorHandlingSettings;
+
+final readonly class ErrorLogger
+{
+    private function __construct(private ?LoggerInterface $logger, private ErrorHandlingSettings $settings)
+    {
+    }
+
+    public static function from(?LoggerInterface $logger, ErrorHandlingSettings $settings): ErrorLogger
+    {
+        return new ErrorLogger(logger: $logger, settings: $settings);
+    }
+
+    public function log(ServerRequestInterface $request, Throwable $exception): void
+    {
+        if (is_null($this->logger) || !$this->settings->logErrors) {
+            return;
+        }
+
+        $logger = CorrelatedLogger::from(logger: $this->logger)->resolve(request: $request);
+
+        $context = ['message' => $exception->getMessage()];
+
+        if ($this->settings->logErrorDetails) {
+            $context['exception'] = $exception::class;
+            $context['file'] = $exception->getFile();
+            $context['line'] = $exception->getLine();
+            $context['trace'] = $exception->getTraceAsString();
+        }
+
+        $logger->error('error', $context);
+    }
+}
diff --git a/src/Internal/ErrorMiddlewareBuilder.php b/src/Internal/ErrorMiddlewareBuilder.php
new file mode 100644
index 0000000..033cc7b
--- /dev/null
+++ b/src/Internal/ErrorMiddlewareBuilder.php
@@ -0,0 +1,79 @@
+<?php
+
+declare(strict_types=1);
+
+namespace TinyBlocks\HttpMiddlewareError\Internal;
+
+use Psr\Log\LoggerInterface;
+use TinyBlocks\HttpMiddlewareError\ErrorHandlingSettings;
+use TinyBlocks\HttpMiddlewareError\ErrorMiddleware;
+use TinyBlocks\HttpMiddlewareError\ExceptionMapping;
+use TinyBlocks\HttpMiddlewareError\ExceptionMappingTable;
+use TinyBlocks\HttpMiddlewareError\Internal\Exceptions\MappingNotConfigured;
+
+final class ErrorMiddlewareBuilder
+{
+    private bool $hasMapping = false;
+    private ?LoggerInterface $logger = null;
+    private ExceptionMappingTable $mappings;
+    private ErrorHandlingSettings $settings;
+    private bool $fallbackOnUnmapped = true;
+
+    public function __construct()
+    {
+        $this->mappings = ExceptionMappingTable::create();
+        $this->settings = ErrorHandlingSettings::default();
+    }
+
+    public function build(): ErrorMiddleware
+    {
+        if (!$this->hasMapping) {
+            throw new MappingNotConfigured();
+        }
+
+        return ErrorMiddleware::build(
+            logger: $this->logger,
+            mappings: $this->mappings,
+            settings: $this->settings,
+            fallbackOnUnmapped: $this->fallbackOnUnmapped
+        );
+    }
+
+    public function withLogger(?LoggerInterface $logger): ErrorMiddlewareBuilder
+    {
+        $this->logger = $logger;
+
+        return $this;
+    }
+
+    public function withMapping(ExceptionMapping $mapping): ErrorMiddlewareBuilder
+    {
+        $this->mappings = $this->mappings->mergedWith(other: $mapping->mappings());
+        $this->hasMapping = true;
+
+        return $this;
+    }
+
+    public function withMappings(ExceptionMapping ...$mappings): ErrorMiddlewareBuilder
+    {
+        foreach ($mappings as $mapping) {
+            $this->withMapping(mapping: $mapping);
+        }
+
+        return $this;
+    }
+
+    public function withSettings(ErrorHandlingSettings $settings): ErrorMiddlewareBuilder
+    {
+        $this->settings = $settings;
+
+        return $this;
+    }
+
+    public function withFallbackOnUnmapped(bool $fallbackOnUnmapped): ErrorMiddlewareBuilder
+    {
+        $this->fallbackOnUnmapped = $fallbackOnUnmapped;
+
+        return $this;
+    }
+}
diff --git a/src/Internal/ErrorOutcome.php b/src/Internal/ErrorOutcome.php
new file mode 100644
index 0000000..49eb7f8
--- /dev/null
+++ b/src/Internal/ErrorOutcome.php
@@ -0,0 +1,37 @@
+<?php
+
+declare(strict_types=1);
+
+namespace TinyBlocks\HttpMiddlewareError\Internal;
+
+use Psr\Http\Message\ResponseInterface;
+use Psr\Http\Message\ServerRequestInterface;
+use Throwable;
+use TinyBlocks\HttpMiddlewareError\ErrorHandlingSettings;
+use TinyBlocks\HttpMiddlewareError\ExceptionMappingTable;
+
+final readonly class ErrorOutcome
+{
+    public function __construct(
+        private ExceptionMappingTable $mappings,
+        private ErrorHandlingSettings $settings,
+        private ErrorLogger $errorLogger,
+        private bool $fallbackOnUnmapped
+    ) {
+    }
+
+    public function resolve(ServerRequestInterface $request, Throwable $exception): ResponseInterface
+    {
+        $mapped = $this->mappings->mapTo(exception: $exception);
+
+        if (is_null($mapped) && !$this->fallbackOnUnmapped) {
+            throw $exception;
+        }
+
+        $this->errorLogger->log(request: $request, exception: $exception);
+
+        return is_null($mapped)
+            ? FallbackResponse::from(settings: $this->settings, exception: $exception)->toResponse()
+            : MappedResponse::from(mapped: $mapped)->toResponse();
+    }
+}
diff --git a/src/Internal/ExactClassMatcher.php b/src/Internal/ExactClassMatcher.php
new file mode 100644
index 0000000..ec002d6
--- /dev/null
+++ b/src/Internal/ExactClassMatcher.php
@@ -0,0 +1,19 @@
+<?php
+
+declare(strict_types=1);
+
+namespace TinyBlocks\HttpMiddlewareError\Internal;
+
+use Throwable;
+
+final readonly class ExactClassMatcher implements ExceptionMatcher
+{
+    public function __construct(private string $exceptionClass)
+    {
+    }
+
+    public function matches(Throwable $exception): bool
+    {
+        return $exception::class === $this->exceptionClass;
+    }
+}
diff --git a/src/Internal/ExceptionMatcher.php b/src/Internal/ExceptionMatcher.php
new file mode 100644
index 0000000..c28b712
--- /dev/null
+++ b/src/Internal/ExceptionMatcher.php
@@ -0,0 +1,21 @@
+<?php
+
+declare(strict_types=1);
+
+namespace TinyBlocks\HttpMiddlewareError\Internal;
+
+use Throwable;
+
+/**
+ * Predicate that decides whether a given throwable is the target of a mapping rule.
+ */
+interface ExceptionMatcher
+{
+    /**
+     * Tells whether the exception matches this rule's criteria.
+     *
+     * @param Throwable $exception The thrown exception to evaluate.
+     * @return bool <code>true</code> when the exception matches, <code>false</code> otherwise.
+     */
+    public function matches(Throwable $exception): bool;
+}
diff --git a/src/Internal/Exceptions/MappingNotConfigured.php b/src/Internal/Exceptions/MappingNotConfigured.php
new file mode 100644
index 0000000..e56455e
--- /dev/null
+++ b/src/Internal/Exceptions/MappingNotConfigured.php
@@ -0,0 +1,11 @@
+<?php
+
+declare(strict_types=1);
+
+namespace TinyBlocks\HttpMiddlewareError\Internal\Exceptions;
+
+use LogicException;
+
+final class MappingNotConfigured extends LogicException
+{
+}
diff --git a/src/Internal/FallbackResponse.php b/src/Internal/FallbackResponse.php
new file mode 100644
index 0000000..943d341
--- /dev/null
+++ b/src/Internal/FallbackResponse.php
@@ -0,0 +1,45 @@
+<?php
+
+declare(strict_types=1);
+
+namespace TinyBlocks\HttpMiddlewareError\Internal;
+
+use Psr\Http\Message\ResponseInterface;
+use Throwable;
+use TinyBlocks\Http\Code;
+use TinyBlocks\Http\Server\Response;
+use TinyBlocks\HttpMiddlewareError\ErrorHandlingSettings;
+
+final readonly class FallbackResponse
+{
+    private function __construct(private ErrorHandlingSettings $settings, private Throwable $exception)
+    {
+    }
+
+    public static function from(ErrorHandlingSettings $settings, Throwable $exception): FallbackResponse
+    {
+        return new FallbackResponse(settings: $settings, exception: $exception);
+    }
+
+    public function toResponse(): ResponseInterface
+    {
+        if ($this->settings->displayErrorDetails) {
+            return Response::from(
+                body: [
+                    'code'      => 'INTERNAL_ERROR',
+                    'message'   => 'An unexpected error occurred.',
+                    'exception' => $this->exception::class,
+                    'file'      => $this->exception->getFile(),
+                    'line'      => $this->exception->getLine(),
+                    'trace'     => explode("\n", $this->exception->getTraceAsString())
+                ],
+                code: Code::INTERNAL_SERVER_ERROR
+            );
+        }
+
+        return Response::from(
+            body: ['code' => 'INTERNAL_ERROR', 'message' => 'An unexpected error occurred.'],
+            code: Code::INTERNAL_SERVER_ERROR
+        );
+    }
+}
diff --git a/src/Internal/FixedMappedErrorResolver.php b/src/Internal/FixedMappedErrorResolver.php
new file mode 100644
index 0000000..63364ae
--- /dev/null
+++ b/src/Internal/FixedMappedErrorResolver.php
@@ -0,0 +1,20 @@
+<?php
+
+declare(strict_types=1);
+
+namespace TinyBlocks\HttpMiddlewareError\Internal;
+
+use Throwable;
+use TinyBlocks\HttpMiddlewareError\MappedError;
+
+final readonly class FixedMappedErrorResolver implements MappedErrorResolver
+{
+    public function __construct(private MappedError $error)
+    {
+    }
+
+    public function resolve(Throwable $exception): MappedError
+    {
+        return $this->error;
+    }
+}
diff --git a/src/Internal/MappedErrorResolver.php b/src/Internal/MappedErrorResolver.php
new file mode 100644
index 0000000..2415a74
--- /dev/null
+++ b/src/Internal/MappedErrorResolver.php
@@ -0,0 +1,22 @@
+<?php
+
+declare(strict_types=1);
+
+namespace TinyBlocks\HttpMiddlewareError\Internal;
+
+use Throwable;
+use TinyBlocks\HttpMiddlewareError\MappedError;
+
+/**
+ * Factory that produces the MappedError payload for a matched throwable.
+ */
+interface MappedErrorResolver
+{
+    /**
+     * Produces a MappedError for the given matched exception.
+     *
+     * @param Throwable $exception The matched exception.
+     * @return MappedError The structured error response for the exception.
+     */
+    public function resolve(Throwable $exception): MappedError;
+}
diff --git a/src/Internal/MappedResponse.php b/src/Internal/MappedResponse.php
new file mode 100644
index 0000000..772784b
--- /dev/null
+++ b/src/Internal/MappedResponse.php
@@ -0,0 +1,36 @@
+<?php
+
+declare(strict_types=1);
+
+namespace TinyBlocks\HttpMiddlewareError\Internal;
+
+use Psr\Http\Message\ResponseInterface;
+use TinyBlocks\Http\Code;
+use TinyBlocks\Http\Server\Response;
+use TinyBlocks\HttpMiddlewareError\MappedError;
+
+final readonly class MappedResponse
+{
+    private function __construct(private MappedError $mapped)
+    {
+    }
+
+    public static function from(MappedError $mapped): MappedResponse
+    {
+        return new MappedResponse(mapped: $mapped);
+    }
+
+    public function toResponse(): ResponseInterface
+    {
+        $response = Response::from(
+            body: ['code' => $this->mapped->code, 'message' => $this->mapped->message],
+            code: Code::from($this->mapped->status)
+        );
+
+        foreach ($this->mapped->headers as $name => $value) {
+            $response = $response->withHeader($name, $value);
+        }
+
+        return $response;
+    }
+}
diff --git a/src/Internal/MappingEntry.php b/src/Internal/MappingEntry.php
new file mode 100644
index 0000000..c4b8714
--- /dev/null
+++ b/src/Internal/MappingEntry.php
@@ -0,0 +1,24 @@
+<?php
+
+declare(strict_types=1);
+
+namespace TinyBlocks\HttpMiddlewareError\Internal;
+
+use Throwable;
+use TinyBlocks\HttpMiddlewareError\MappedError;
+
+final readonly class MappingEntry
+{
+    public function __construct(private ExceptionMatcher $matcher, private MappedErrorResolver $resolver)
+    {
+    }
+
+    public function resolve(Throwable $exception): ?MappedError
+    {
+        if (!$this->matcher->matches(exception: $exception)) {
+            return null;
+        }
+
+        return $this->resolver->resolve(exception: $exception);
+    }
+}
diff --git a/src/Internal/SubclassMatcher.php b/src/Internal/SubclassMatcher.php
new file mode 100644
index 0000000..1170c3e
--- /dev/null
+++ b/src/Internal/SubclassMatcher.php
@@ -0,0 +1,19 @@
+<?php
+
+declare(strict_types=1);
+
+namespace TinyBlocks\HttpMiddlewareError\Internal;
+
+use Throwable;
+
+final readonly class SubclassMatcher implements ExceptionMatcher
+{
+    public function __construct(private string $baseException)
+    {
+    }
+
+    public function matches(Throwable $exception): bool
+    {
+        return $exception instanceof $this->baseException;
+    }
+}
diff --git a/src/MappedError.php b/src/MappedError.php
new file mode 100644
index 0000000..244db43
--- /dev/null
+++ b/src/MappedError.php
@@ -0,0 +1,31 @@
+<?php
+
+declare(strict_types=1);
+
+namespace TinyBlocks\HttpMiddlewareError;
+
+use TinyBlocks\Http\Code;
+use TinyBlocks\HttpMiddlewareError\Exceptions\HttpStatusOutOfRange;
+
+/**
+ * Describes an exception that has been mapped to a structured HTTP error response, with a
+ * machine-readable code, an HTTP status, and a human-readable message.
+ */
+final readonly class MappedError
+{
+    /**
+     * @param array<string, string|string[]> $headers HTTP response headers to include when this error is returned.
+     */
+    public function __construct(
+        public string $code,
+        public int $status,
+        public string $message,
+        public array $headers = []
+    ) {
+        if (!Code::isErrorCode(code: $status)) {
+            $template = 'HTTP status <%d> must be between 400 and 599.';
+
+            throw new HttpStatusOutOfRange(message: sprintf($template, $status));
+        }
+    }
+}
diff --git a/tests/Unit/CapturingHandler.php b/tests/Unit/CapturingHandler.php
new file mode 100644
index 0000000..9be0c98
--- /dev/null
+++ b/tests/Unit/CapturingHandler.php
@@ -0,0 +1,30 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Test\TinyBlocks\HttpMiddlewareError\Unit;
+
+use GuzzleHttp\Psr7\Response;
+use Psr\Http\Message\ResponseInterface;
+use Psr\Http\Message\ServerRequestInterface;
+use Psr\Http\Server\RequestHandlerInterface;
+
+final class CapturingHandler implements RequestHandlerInterface
+{
+    private ?ServerRequestInterface $capturedRequest = null;
+
+    public function __construct(private readonly ResponseInterface $response = new Response())
+    {
+    }
+
+    public function handle(ServerRequestInterface $request): ResponseInterface
+    {
+        $this->capturedRequest = $request;
+        return $this->response;
+    }
+
+    public function wasInvoked(): bool
+    {
+        return !is_null($this->capturedRequest);
+    }
+}
diff --git a/tests/Unit/ErrorMiddlewareTest.php b/tests/Unit/ErrorMiddlewareTest.php
new file mode 100644
index 0000000..5339e8c
--- /dev/null
+++ b/tests/Unit/ErrorMiddlewareTest.php
@@ -0,0 +1,640 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Test\TinyBlocks\HttpMiddlewareError\Unit;
+
+use Exception;
+use GuzzleHttp\Psr7\Response;
+use GuzzleHttp\Psr7\ServerRequest;
+use LogicException;
+use PHPUnit\Framework\TestCase;
+use Psr\Http\Server\RequestHandlerInterface;
+use Psr\Log\LoggerInterface;
+use RuntimeException;
+use TinyBlocks\Http\Code;
+use TinyBlocks\HttpMiddlewareCorrelationId\CorrelationId;
+use TinyBlocks\HttpMiddlewareError\ErrorHandlingSettings;
+use TinyBlocks\HttpMiddlewareError\ErrorMiddleware;
+use TinyBlocks\HttpMiddlewareError\ExceptionMapping;
+use TinyBlocks\HttpMiddlewareError\ExceptionMappingTable;
+use TinyBlocks\HttpMiddlewareError\Internal\Exceptions\MappingNotConfigured;
+
+final class ErrorMiddlewareTest extends TestCase
+{
+    public function testDefaultSettingsAreSecureAndSilent(): void
+    {
+        /** @Given the default error handling settings */
+        $settings = ErrorHandlingSettings::default();
+
+        /** @Then logging should be disabled by default */
+        self::assertFalse($settings->logErrors);
+
+        /** @And logging details should be disabled by default */
+        self::assertFalse($settings->logErrorDetails);
+
+        /** @And display error details should be disabled by default */
+        self::assertFalse($settings->displayErrorDetails);
+    }
+
+    public function testProcessWhenHandlerSucceedsThenResponsePassesThrough(): void
+    {
+        /** @Given a request */
+        $request = new ServerRequest('GET', '/users');
+
+        /** @And a middleware with a mapping that declares no rules */
+        $middleware = ErrorMiddleware::create()
+            ->withMapping(mapping: new UnmappedExceptions())
+            ->build();
+
+        /** @And a handler that returns a successful response */
+        $expected = new Response(Code::OK->value, [], '{"status":"ok"}');
+        $handler = new CapturingHandler(response: $expected);
+
+        /** @When the middleware processes the request */
+        $actual = $middleware->process($request, $handler);
+
+        /** @Then the original response is returned unchanged */
+        self::assertSame($expected, $actual);
+    }
+
+    public function testProcessWhenLogErrorsDisabledAndHandlerThrowsThenNoLogging(): void
+    {
+        /** @Given a request */
+        $request = new ServerRequest('POST', '/users');
+
+        /** @And a handler that throws an exception */
+        $handler = $this->createStub(RequestHandlerInterface::class);
+        $handler->method('handle')->willThrowException(new Exception('Should not be logged'));
+
+        /** @And a logger that should never be called */
+        $logger = $this->createMock(LoggerInterface::class);
+        $logger->expects(self::never())->method('error');
+
+        /** @And a middleware with logErrors disabled */
+        $middleware = ErrorMiddleware::create()
+            ->withLogger(logger: $logger)
+            ->withMapping(mapping: new UnmappedExceptions())
+            ->withSettings(settings: ErrorHandlingSettings::from(
+                logErrors: false,
+                logErrorDetails: false,
+                displayErrorDetails: false
+            ))
+            ->build();
+
+        /** @When the middleware processes the request */
+        $actual = $middleware->process($request, $handler);
+
+        /** @Then the response should be 500 */
+        self::assertSame(Code::INTERNAL_SERVER_ERROR->value, $actual->getStatusCode());
+    }
+
+    public function testProcessWhenLoggerNotProvidedAndHandlerThrowsThenNoLogging(): void
+    {
+        /** @Given a request */
+        $request = new ServerRequest('GET', '/');
+
+        /** @And a handler that throws an exception */
+        $handler = $this->createStub(RequestHandlerInterface::class);
+        $handler->method('handle')->willThrowException(new Exception('Silent error'));
+
+        /** @And a middleware built without a logger */
+        $middleware = ErrorMiddleware::create()
+            ->withMapping(mapping: new UnmappedExceptions())
+            ->build();
+
+        /** @When the middleware processes the request */
+        $actual = $middleware->process($request, $handler);
+
+        /** @Then the process should complete returning a 500 response */
+        self::assertSame(Code::INTERNAL_SERVER_ERROR->value, $actual->getStatusCode());
+    }
+
+    public function testBuildWhenMappingNotConfiguredThenMappingNotConfiguredIsThrown(): void
+    {
+        /** @Then MappingNotConfigured should be thrown when building without a mapping */
+        $this->expectException(MappingNotConfigured::class);
+
+        /** @When building a middleware without configuring a mapping */
+        ErrorMiddleware::create()->build();
+    }
+
+    public function testProcessWhenFallbackDisabledAndMappingReturnsNullThenNoLogging(): void
+    {
+        /** @Given a request */
+        $request = new ServerRequest('POST', '/checkout');
+
+        /** @And a handler that throws an exception */
+        $handler = $this->createStub(RequestHandlerInterface::class);
+        $handler->method('handle')->willThrowException(new RuntimeException('Unhandled error'));
+
+        /** @And a logger that should never be called */
+        $logger = $this->createMock(LoggerInterface::class);
+        $logger->expects(self::never())->method('error');
+
+        /** @And a middleware with fallback disabled and logErrors enabled */
+        $middleware = ErrorMiddleware::create()
+            ->withLogger(logger: $logger)
+            ->withMapping(mapping: new UnmappedExceptions())
+            ->withSettings(settings: ErrorHandlingSettings::from(
+                logErrors: true,
+                logErrorDetails: false,
+                displayErrorDetails: false
+            ))
+            ->withFallbackOnUnmapped(false)
+            ->build();
+
+        /** @Then the original exception should propagate without logging */
+        $this->expectException(RuntimeException::class);
+
+        /** @When the middleware processes the request */
+        $middleware->process($request, $handler);
+    }
+
+    public function testProcessWhenMappedErrorHasHeadersThenHeadersAreIncludedInResponse(): void
+    {
+        /** @Given a request */
+        $request = new ServerRequest('POST', '/sessions');
+
+        /** @And a handler that throws an exception */
+        $handler = $this->createStub(RequestHandlerInterface::class);
+        $handler->method('handle')->willThrowException(new RuntimeException('Too many attempts'));
+
+        /** @And a mapping that returns a MappedError with a Retry-After header */
+        $mapping = new class implements ExceptionMapping {
+            public function mappings(): ExceptionMappingTable
+            {
+                return ExceptionMappingTable::create()
+                    ->when(exceptionClass: RuntimeException::class)
+                    ->mapsTo(
+                        code: 'LOGIN_THROTTLED',
+                        status: 429,
+                        message: 'Too many failed login attempts. Please try again later.',
+                        headers: ['Retry-After' => '60']
+                    );
+            }
+        };
+
+        /** @And a middleware configured with the mapping */
+        $middleware = ErrorMiddleware::create()->withMapping(mapping: $mapping)->build();
+
+        /** @When the middleware processes the request */
+        $actual = $middleware->process($request, $handler);
+
+        /** @Then the response should have status 429 */
+        self::assertSame(Code::TOO_MANY_REQUESTS->value, $actual->getStatusCode());
+
+        /** @And the Retry-After header should be included in the response */
+        self::assertSame('60', $actual->getHeaderLine('Retry-After'));
+    }
+
+    public function testProcessWhenHandlerThrowsAndCorrelationIdPresentThenLoggerIsCorrelated(): void
+    {
+        /** @Given a request with a correlation ID attribute */
+        $correlationId = new readonly class implements CorrelationId {
+            public function toString(): string
+            {
+                return '550e8400-e29b-41d4-a716-446655440000';
+            }
+        };
+        $request = new ServerRequest('GET', '/not-found')
+            ->withAttribute('correlationId', $correlationId);
+
+        /** @And a handler that throws an exception */
+        $exceptionMessage = 'Resource not found';
+        $handler = $this->createStub(RequestHandlerInterface::class);
+        $handler->method('handle')->willThrowException(new Exception($exceptionMessage));
+
+        /** @And a logger that expects the correlated error call */
+        $logger = $this->createMock(LoggerInterface::class);
+        $logger->expects(self::once())
+            ->method('log')
+            ->with(
+                'error',
+                'error',
+                self::callback(function (array $context) use ($exceptionMessage): bool {
+                    return $context['message'] === $exceptionMessage
+                        && isset($context['correlation_id'])
+                        && !isset($context['exception']);
+                })
+            );
+
+        /** @And a middleware with logErrors enabled */
+        $middleware = ErrorMiddleware::create()
+            ->withLogger(logger: $logger)
+            ->withMapping(mapping: new UnmappedExceptions())
+            ->withSettings(settings: ErrorHandlingSettings::from(
+                logErrors: true,
+                logErrorDetails: false,
+                displayErrorDetails: false
+            ))
+            ->build();
+
+        /** @When the middleware processes the request */
+        $actual = $middleware->process($request, $handler);
+
+        /** @Then the response should be 500 */
+        self::assertSame(Code::INTERNAL_SERVER_ERROR->value, $actual->getStatusCode());
+    }
+
+    public function testProcessWhenLogErrorDetailsEnabledThenLogContextContainsExceptionDetails(): void
+    {
+        /** @Given a request */
+        $request = new ServerRequest('POST', '/payments');
+
+        /** @And a handler that throws an exception */
+        $exceptionMessage = 'Payment gateway timeout';
+        $handler = $this->createStub(RequestHandlerInterface::class);
+        $handler->method('handle')->willThrowException(new Exception($exceptionMessage));
+
+        /** @And a logger that expects the error key with full details in context */
+        $logger = $this->createMock(LoggerInterface::class);
+        $logger->expects(self::once())
+            ->method('error')
+            ->with(
+                'error',
+                self::callback(function (array $context) use ($exceptionMessage): bool {
+                    return $context['message'] === $exceptionMessage
+                        && isset($context['exception'], $context['file'], $context['line'], $context['trace'])
+                        && $context['exception'] === Exception::class
+                        && is_string($context['file'])
+                        && is_int($context['line'])
+                        && is_string($context['trace']);
+                })
+            );
+
+        /** @And a middleware with logErrors and logErrorDetails enabled */
+        $middleware = ErrorMiddleware::create()
+            ->withLogger(logger: $logger)
+            ->withMapping(mapping: new UnmappedExceptions())
+            ->withSettings(settings: ErrorHandlingSettings::from(
+                logErrors: true,
+                logErrorDetails: true,
+                displayErrorDetails: false
+            ))
+            ->build();
+
+        /** @When the middleware processes the request */
+        $actual = $middleware->process($request, $handler);
+
+        /** @Then the response should be 500 */
+        self::assertSame(Code::INTERNAL_SERVER_ERROR->value, $actual->getStatusCode());
+    }
+
+    public function testProcessWhenDisplayErrorDetailsTrueThenFallbackBodyContainsExceptionDetails(): void
+    {
+        /** @Given a request */
+        $request = new ServerRequest('POST', '/orders');
+
+        /** @And a handler that throws an exception */
+        $handler = $this->createStub(RequestHandlerInterface::class);
+        $handler->method('handle')->willThrowException(new Exception('Order processing failed'));
+
+        /** @And a middleware with displayErrorDetails enabled */
+        $middleware = ErrorMiddleware::create()
+            ->withMapping(mapping: new UnmappedExceptions())
+            ->withSettings(settings: ErrorHandlingSettings::from(
+                logErrors: false,
+                logErrorDetails: false,
+                displayErrorDetails: true
+            ))
+            ->build();
+
+        /** @When the middleware processes the request */
+        $actual = $middleware->process($request, $handler);
+
+        /** @Then the response should be 500 */
+        self::assertSame(Code::INTERNAL_SERVER_ERROR->value, $actual->getStatusCode());
+
+        /** @And the body should contain the fallback code and message */
+        $body = json_decode((string)$actual->getBody(), true);
+
+        self::assertSame('INTERNAL_ERROR', $body['code']);
+        self::assertSame('An unexpected error occurred.', $body['message']);
+
+        /** @And the body should contain exception detail fields */
+        self::assertSame(Exception::class, $body['exception']);
+        self::assertArrayHasKey('file', $body);
+        self::assertArrayHasKey('line', $body);
+        self::assertIsArray($body['trace']);
+        self::assertNotEmpty($body['trace']);
+    }
+
+    public function testProcessWhenMappedErrorHasMultiValueHeaderThenAllValuesAreIncludedInResponse(): void
+    {
+        /** @Given a request */
+        $request = new ServerRequest('POST', '/sessions');
+
+        /** @And a handler that throws an exception */
+        $handler = $this->createStub(RequestHandlerInterface::class);
+        $handler->method('handle')->willThrowException(new RuntimeException('Too many attempts'));
+
+        /** @And a mapping that returns a MappedError with a multi-value header */
+        $mapping = new class implements ExceptionMapping {
+            public function mappings(): ExceptionMappingTable
+            {
+                return ExceptionMappingTable::create()
+                    ->when(exceptionClass: RuntimeException::class)
+                    ->mapsTo(
+                        code: 'ERR',
+                        status: 429,
+                        message: 'An error occurred.',
+                        headers: ['X-Custom' => ['a', 'b']]
+                    );
+            }
+        };
+
+        /** @And a middleware configured with the mapping */
+        $middleware = ErrorMiddleware::create()->withMapping(mapping: $mapping)->build();
+
+        /** @When the middleware processes the request */
+        $actual = $middleware->process($request, $handler);
+
+        /** @Then the response should have status 429 */
+        self::assertSame(Code::TOO_MANY_REQUESTS->value, $actual->getStatusCode());
+
+        /** @And the multi-value header should be present in the response */
+        self::assertSame(['a', 'b'], $actual->getHeader('X-Custom'));
+    }
+
+    public function testProcessWhenMappingsComposeAndALaterMappingMatchesThenItResolvesTheException(): void
+    {
+        /** @Given a request */
+        $request = new ServerRequest('POST', '/orders');
+
+        /** @And a handler that throws a logic exception */
+        $handler = $this->createStub(RequestHandlerInterface::class);
+        $handler->method('handle')->willThrowException(new LogicException('Order context invalid'));
+
+        /** @And a write-side mapping that only translates runtime failures */
+        $writeMapping = new class implements ExceptionMapping {
+            public function mappings(): ExceptionMappingTable
+            {
+                return ExceptionMappingTable::create()
+                    ->when(exceptionClass: RuntimeException::class)
+                    ->mapsTo(code: 'RUNTIME_FAILURE', status: 409, message: 'A runtime failure occurred.');
+            }
+        };
+
+        /** @And a read-side mapping that translates logic failures */
+        $readMapping = new class implements ExceptionMapping {
+            public function mappings(): ExceptionMappingTable
+            {
+                return ExceptionMappingTable::create()
+                    ->when(exceptionClass: LogicException::class)
+                    ->mapsTo(code: 'INVALID_CONTEXT', status: 422, message: 'The order context is invalid.');
+            }
+        };
+
+        /** @And a middleware composing both mappings */
+        $middleware = ErrorMiddleware::create()->withMappings($writeMapping, $readMapping)->build();
+
+        /** @When the middleware processes the request */
+        $actual = $middleware->process($request, $handler);
+
+        /** @Then the later mapping resolves the exception */
+        self::assertSame(Code::UNPROCESSABLE_ENTITY->value, $actual->getStatusCode());
+
+        /** @And the body carries the later mapping's code */
+        self::assertSame('INVALID_CONTEXT', json_decode((string)$actual->getBody(), true)['code']);
+    }
+
+    public function testProcessWhenLoggerProvidedAndLogErrorsEnabledAndHandlerThrowsThenErrorIsLogged(): void
+    {
+        /** @Given a request */
+        $request = new ServerRequest('DELETE', '/account');
+
+        /** @And a handler that throws an exception */
+        $exceptionMessage = 'Critical system failure';
+        $handler = $this->createStub(RequestHandlerInterface::class);
+        $handler->method('handle')->willThrowException(new Exception($exceptionMessage));
+
+        /** @And a logger that expects an error call with the exception message in context */
+        $logger = $this->createMock(LoggerInterface::class);
+        $logger->expects(self::once())
+            ->method('error')
+            ->with(
+                'error',
+                self::callback(function (array $context) use ($exceptionMessage): bool {
+                    return $context['message'] === $exceptionMessage
+                        && !isset($context['exception']);
+                })
+            );
+
+        /** @And a middleware with logErrors enabled */
+        $middleware = ErrorMiddleware::create()
+            ->withLogger(logger: $logger)
+            ->withMapping(mapping: new UnmappedExceptions())
+            ->withSettings(settings: ErrorHandlingSettings::from(
+                logErrors: true,
+                logErrorDetails: false,
+                displayErrorDetails: false
+            ))
+            ->build();
+
+        /** @When the middleware processes the request */
+        $actual = $middleware->process($request, $handler);
+
+        /** @Then the response should be 500 */
+        self::assertSame(Code::INTERNAL_SERVER_ERROR->value, $actual->getStatusCode());
+    }
+
+    public function testProcessWhenMappingReturnsNullAndFallbackEnabledThenFallbackResponseIsReturned(): void
+    {
+        /** @Given a request */
+        $request = new ServerRequest('POST', '/checkout');
+
+        /** @And a handler that throws an exception */
+        $handler = $this->createStub(RequestHandlerInterface::class);
+        $handler->method('handle')->willThrowException(new Exception('Unexpected database error'));
+
+        /** @And a middleware with default settings (fallback enabled) */
+        $middleware = ErrorMiddleware::create()
+            ->withMapping(mapping: new UnmappedExceptions())
+            ->build();
+
+        /** @When the middleware processes the request */
+        $actual = $middleware->process($request, $handler);
+
+        /** @Then the response should be 500 */
+        self::assertSame(Code::INTERNAL_SERVER_ERROR->value, $actual->getStatusCode());
+
+        /** @And the body should contain the INTERNAL_ERROR code and message */
+        $body = json_decode((string)$actual->getBody(), true);
+
+        self::assertSame('INTERNAL_ERROR', $body['code']);
+        self::assertSame('An unexpected error occurred.', $body['message']);
+
+        /** @And the body should not contain exception details */
+        self::assertArrayNotHasKey('exception', $body);
+        self::assertArrayNotHasKey('file', $body);
+        self::assertArrayNotHasKey('line', $body);
+        self::assertArrayNotHasKey('trace', $body);
+    }
+
+    public function testProcessWhenHandlerThrowsAndMappingResolvesAndLogErrorsEnabledThenErrorIsLogged(): void
+    {
+        /** @Given a request */
+        $request = new ServerRequest('POST', '/transactions');
+
+        /** @And a handler that throws an exception */
+        $exceptionMessage = 'Transaction failed';
+        $handler = $this->createStub(RequestHandlerInterface::class);
+        $handler->method('handle')->willThrowException(new RuntimeException($exceptionMessage));
+
+        /** @And a mapping that maps the exception to a 422 response */
+        $mapping = new class implements ExceptionMapping {
+            public function mappings(): ExceptionMappingTable
+            {
+                return ExceptionMappingTable::create()
+                    ->when(exceptionClass: RuntimeException::class)
+                    ->mapsTo(
+                        code: 'TRANSACTION_FAILED',
+                        status: 422,
+                        message: 'The transaction could not be processed.'
+                    );
+            }
+        };
+
+        /** @And a logger that expects exactly one error call */
+        $logger = $this->createMock(LoggerInterface::class);
+        $logger->expects(self::once())
+            ->method('error')
+            ->with(
+                'error',
+                self::callback(function (array $context) use ($exceptionMessage): bool {
+                    return $context['message'] === $exceptionMessage;
+                })
+            );
+
+        /** @And a middleware with logErrors enabled */
+        $middleware = ErrorMiddleware::create()
+            ->withLogger(logger: $logger)
+            ->withMapping(mapping: $mapping)
+            ->withSettings(settings: ErrorHandlingSettings::from(
+                logErrors: true,
+                logErrorDetails: false,
+                displayErrorDetails: false
+            ))
+            ->build();
+
+        /** @When the middleware processes the request */
+        $actual = $middleware->process($request, $handler);
+
+        /** @Then the response should have the mapped status code */
+        self::assertSame(Code::UNPROCESSABLE_ENTITY->value, $actual->getStatusCode());
+    }
+
+    public function testProcessWhenFallbackDisabledAndMappingResolvesAndLogErrorsEnabledThenErrorIsLogged(): void
+    {
+        /** @Given a request */
+        $request = new ServerRequest('PUT', '/config');
+
+        /** @And a handler that throws an exception */
+        $exceptionMessage = 'Config update failed';
+        $handler = $this->createStub(RequestHandlerInterface::class);
+        $handler->method('handle')->willThrowException(new RuntimeException($exceptionMessage));
+
+        /** @And a mapping that maps the exception */
+        $mapping = new class implements ExceptionMapping {
+            public function mappings(): ExceptionMappingTable
+            {
+                return ExceptionMappingTable::create()
+                    ->when(exceptionClass: RuntimeException::class)
+                    ->mapsTo(code: 'CONFIG_INVALID', status: 400, message: 'The configuration is invalid.');
+            }
+        };
+
+        /** @And a logger that expects exactly one error call */
+        $logger = $this->createMock(LoggerInterface::class);
+        $logger->expects(self::once())
+            ->method('error')
+            ->with(
+                'error',
+                self::callback(function (array $context) use ($exceptionMessage): bool {
+                    return $context['message'] === $exceptionMessage;
+                })
+            );
+
+        /** @And a middleware with fallback disabled but mapping configured */
+        $middleware = ErrorMiddleware::create()
+            ->withLogger(logger: $logger)
+            ->withMapping(mapping: $mapping)
+            ->withSettings(settings: ErrorHandlingSettings::from(
+                logErrors: true,
+                logErrorDetails: false,
+                displayErrorDetails: false
+            ))
+            ->withFallbackOnUnmapped(false)
+            ->build();
+
+        /** @When the middleware processes the request */
+        $actual = $middleware->process($request, $handler);
+
+        /** @Then the mapped response is returned (mapping resolved, so no rethrow) */
+        self::assertSame(Code::BAD_REQUEST->value, $actual->getStatusCode());
+    }
+
+    public function testProcessWhenHandlerThrowsAndMappingResolvesToMappedErrorThenMappedResponseIsReturned(): void
+    {
+        /** @Given a request */
+        $request = new ServerRequest('POST', '/orders');
+
+        /** @And a handler that throws an exception */
+        $handler = $this->createStub(RequestHandlerInterface::class);
+        $handler->method('handle')->willThrowException(new RuntimeException('Order not found'));
+
+        /** @And a mapping that maps the exception to a 404 response */
+        $mapping = new class implements ExceptionMapping {
+            public function mappings(): ExceptionMappingTable
+            {
+                return ExceptionMappingTable::create()
+                    ->when(exceptionClass: RuntimeException::class)
+                    ->mapsTo(code: 'ORDER_NOT_FOUND', status: 404, message: 'The requested order was not found.');
+            }
+        };
+
+        /** @And a middleware configured with the mapping */
+        $middleware = ErrorMiddleware::create()->withMapping(mapping: $mapping)->build();
+
+        /** @When the middleware processes the request */
+        $actual = $middleware->process($request, $handler);
+
+        /** @Then the response should have the mapped status code */
+        self::assertSame(Code::NOT_FOUND->value, $actual->getStatusCode());
+
+        /** @And the body should contain the mapped code and message */
+        $body = json_decode((string)$actual->getBody(), true);
+
+        self::assertSame('ORDER_NOT_FOUND', $body['code']);
+
+        /** @And the body should contain the mapped message */
+        self::assertSame('The requested order was not found.', $body['message']);
+
+        /** @And the body should not contain fallback keys */
+        self::assertArrayNotHasKey('exception', $body);
+    }
+
+    public function testProcessWhenHandlerThrowsAndMappingReturnsNullAndFallbackDisabledThenExceptionPropagates(): void
+    {
+        /** @Given a request */
+        $request = new ServerRequest('DELETE', '/account');
+
+        /** @And a handler that throws an exception */
+        $handler = $this->createStub(RequestHandlerInterface::class);
+        $handler->method('handle')->willThrowException(new RuntimeException('Cannot delete account'));
+
+        /** @And a middleware with fallback disabled */
+        $middleware = ErrorMiddleware::create()
+            ->withMapping(mapping: new UnmappedExceptions())
+            ->withFallbackOnUnmapped(false)
+            ->build();
+
+        /** @Then the original exception should propagate */
+        $this->expectException(RuntimeException::class);
+        $this->expectExceptionMessage('Cannot delete account');
+
+        /** @When the middleware processes the request */
+        $middleware->process($request, $handler);
+    }
+}
diff --git a/tests/Unit/ExceptionMappingRuleTest.php b/tests/Unit/ExceptionMappingRuleTest.php
new file mode 100644
index 0000000..26ab311
--- /dev/null
+++ b/tests/Unit/ExceptionMappingRuleTest.php
@@ -0,0 +1,103 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Test\TinyBlocks\HttpMiddlewareError\Unit;
+
+use PHPUnit\Framework\TestCase;
+use RuntimeException;
+use Throwable;
+use TinyBlocks\HttpMiddlewareError\ExceptionMappingTable;
+use TinyBlocks\HttpMiddlewareError\MappedError;
+
+final class ExceptionMappingRuleTest extends TestCase
+{
+    public function testMapsToWhenHeadersOmittedThenMappedErrorHasEmptyHeaders(): void
+    {
+        /** @Given a rule for RuntimeException with no headers specified */
+        $table = ExceptionMappingTable::create()
+            ->when(exceptionClass: RuntimeException::class)
+            ->mapsTo(code: 'ERR', status: 400, message: 'error');
+
+        /** @When mapping a RuntimeException */
+        $result = $table->mapTo(exception: new RuntimeException());
+
+        /** @Then the MappedError has an empty headers array */
+        self::assertNotNull($result);
+        self::assertSame([], $result->headers);
+    }
+
+    public function testMapsToWhenHeadersProvidedThenHeadersPropagatedToMappedError(): void
+    {
+        /** @Given a set of headers */
+        $headers = ['Retry-After' => '60'];
+
+        /** @And a rule that includes those headers */
+        $table = ExceptionMappingTable::create()
+            ->when(exceptionClass: RuntimeException::class)
+            ->mapsTo(code: 'ERR', status: 429, message: 'Too many requests.', headers: $headers);
+
+        /** @When mapping a RuntimeException */
+        $result = $table->mapTo(exception: new RuntimeException());
+
+        /** @Then the MappedError carries those headers */
+        self::assertNotNull($result);
+        self::assertSame($headers, $result->headers);
+    }
+
+    public function testResolvesWithWhenClosureReturnsMappedErrorThenMappedErrorIsReturned(): void
+    {
+        /** @Given a RuntimeException with a specific message */
+        $exception = new RuntimeException('Gateway unavailable.');
+
+        /** @And a table with a rule that builds a MappedError from the exception */
+        $table = ExceptionMappingTable::create()
+            ->when(exceptionClass: RuntimeException::class)
+            ->resolvesWith(
+                resolver: fn(Throwable $thrownException): MappedError => new MappedError(
+                    code: 'GATEWAY_UNAVAILABLE',
+                    status: 502,
+                    message: $thrownException->getMessage()
+                )
+            );
+
+        /** @When mapping the exception */
+        $result = $table->mapTo(exception: $exception);
+
+        /** @Then the MappedError reflects the exception's message */
+        self::assertNotNull($result);
+        self::assertSame('Gateway unavailable.', $result->message);
+    }
+
+    public function testMapsToReturnsNewTableInstance(): void
+    {
+        /** @Given a table to derive a rule from */
+        $originalTable = ExceptionMappingTable::create();
+
+        /** @When calling mapsTo on a rule derived from the original table */
+        $newTable = $originalTable->when(exceptionClass: RuntimeException::class)
+            ->mapsTo(code: 'ERR', status: 400, message: 'error');
+
+        /** @Then a new table instance is returned */
+        self::assertNotSame($originalTable, $newTable);
+    }
+
+    public function testResolvesWithReturnsNewTableInstance(): void
+    {
+        /** @Given a table to derive a rule from */
+        $originalTable = ExceptionMappingTable::create();
+
+        /** @When calling resolvesWith on a rule derived from the original table */
+        $newTable = $originalTable->when(exceptionClass: RuntimeException::class)
+            ->resolvesWith(
+                resolver: fn(Throwable $thrownException): MappedError => new MappedError(
+                    code: 'ERR',
+                    status: 500,
+                    message: $thrownException->getMessage()
+                )
+            );
+
+        /** @Then a new table instance is returned */
+        self::assertNotSame($originalTable, $newTable);
+    }
+}
diff --git a/tests/Unit/ExceptionMappingTableTest.php b/tests/Unit/ExceptionMappingTableTest.php
new file mode 100644
index 0000000..3351f4a
--- /dev/null
+++ b/tests/Unit/ExceptionMappingTableTest.php
@@ -0,0 +1,255 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Test\TinyBlocks\HttpMiddlewareError\Unit;
+
+use LogicException;
+use OverflowException;
+use PHPUnit\Framework\TestCase;
+use RuntimeException;
+use Throwable;
+use TinyBlocks\HttpMiddlewareError\ExceptionMappingTable;
+use TinyBlocks\HttpMiddlewareError\MappedError;
+
+final class ExceptionMappingTableTest extends TestCase
+{
+    public function testWhenMapsToReturnsNewTableInstance(): void
+    {
+        /** @Given an original empty table */
+        $originalTable = ExceptionMappingTable::create();
+
+        /** @When appending a rule via when()->mapsTo() */
+        $newTable = $originalTable->when(exceptionClass: RuntimeException::class)
+            ->mapsTo(code: 'ERR', status: 400, message: 'error');
+
+        /** @Then the returned table is a different instance from the original */
+        self::assertNotSame($originalTable, $newTable);
+    }
+
+    public function testMapToWhenTableIsEmptyThenReturnsNull(): void
+    {
+        /** @When mapping any exception on an empty table */
+        $result = ExceptionMappingTable::create()->mapTo(exception: new RuntimeException());
+
+        /** @Then null is returned */
+        self::assertNull($result);
+    }
+
+    public function testWhenAnyMapsToReturnsNewTableInstance(): void
+    {
+        /** @Given an original empty table */
+        $originalTable = ExceptionMappingTable::create();
+
+        /** @When appending a rule via whenAny()->mapsTo() */
+        $newTable = $originalTable->whenAny(exceptionClasses: [RuntimeException::class])
+            ->mapsTo(code: 'ERR', status: 400, message: 'error');
+
+        /** @Then the returned table is a different instance from the original */
+        self::assertNotSame($originalTable, $newTable);
+    }
+
+    public function testMapToWhenNoRuleMatchesThenReturnsNull(): void
+    {
+        /** @Given a table with a rule only for RuntimeException */
+        $table = ExceptionMappingTable::create()
+            ->when(exceptionClass: RuntimeException::class)
+            ->mapsTo(code: 'ERR', status: 400, message: 'error');
+
+        /** @When mapping a LogicException (not registered) */
+        $result = $table->mapTo(exception: new LogicException());
+
+        /** @Then null is returned */
+        self::assertNull($result);
+    }
+
+    public function testWhenSubclassOfMapsToReturnsNewTableInstance(): void
+    {
+        /** @Given an original empty table */
+        $originalTable = ExceptionMappingTable::create();
+
+        /** @When appending a rule via whenSubclassOf()->mapsTo() */
+        $newTable = $originalTable->whenSubclassOf(baseException: RuntimeException::class)
+            ->mapsTo(code: 'ERR', status: 400, message: 'error');
+
+        /** @Then the returned table is a different instance from the original */
+        self::assertNotSame($originalTable, $newTable);
+    }
+
+    public function testMapToWhenMultipleRulesMatchThenFirstRegisteredWins(): void
+    {
+        /** @Given a table with a specific rule for OverflowException registered first */
+        $table = ExceptionMappingTable::create()
+            ->when(exceptionClass: OverflowException::class)
+            ->mapsTo(code: 'OVERFLOW', status: 400, message: 'Overflow.')
+            ->whenSubclassOf(baseException: RuntimeException::class)
+            ->mapsTo(code: 'RUNTIME_FAMILY', status: 500, message: 'Runtime family.');
+
+        /** @When mapping an OverflowException (matches both rules) */
+        $result = $table->mapTo(exception: new OverflowException());
+
+        /** @Then the first registered rule wins */
+        self::assertNotNull($result);
+        self::assertSame('OVERFLOW', $result->code);
+    }
+
+    public function testMapToWhenSubclassOfBaseClassThenReturnsMappedError(): void
+    {
+        /** @Given a table with a rule for any subclass of RuntimeException */
+        $table = ExceptionMappingTable::create()
+            ->whenSubclassOf(baseException: RuntimeException::class)
+            ->mapsTo(code: 'RUNTIME_FAMILY', status: 500, message: 'Runtime family error.');
+
+        /** @When mapping an OverflowException (subclass of RuntimeException) */
+        $result = $table->mapTo(exception: new OverflowException());
+
+        /** @Then the MappedError for the base class rule is returned */
+        self::assertNotNull($result);
+        self::assertSame('RUNTIME_FAMILY', $result->code);
+    }
+
+    public function testMergedWithWhenOnlyOtherTableMatchesThenOtherRuleResolves(): void
+    {
+        /** @Given a table that only maps RuntimeException */
+        $primary = ExceptionMappingTable::create()
+            ->when(exceptionClass: RuntimeException::class)
+            ->mapsTo(code: 'RUNTIME', status: 409, message: 'Runtime translation.');
+
+        /** @And another table that maps LogicException */
+        $secondary = ExceptionMappingTable::create()
+            ->when(exceptionClass: LogicException::class)
+            ->mapsTo(code: 'LOGIC', status: 422, message: 'Logic translation.');
+
+        /** @When mapping a LogicException on the merged table */
+        $result = $primary->mergedWith(other: $secondary)->mapTo(exception: new LogicException());
+
+        /** @Then the other table's rule resolves the exception */
+        self::assertNotNull($result);
+        self::assertSame('LOGIC', $result->code);
+    }
+
+    public function testMergedWithWhenBothTablesMatchThenThisTableTakesPrecedence(): void
+    {
+        /** @Given a table that maps RuntimeException to a conflict */
+        $primary = ExceptionMappingTable::create()
+            ->when(exceptionClass: RuntimeException::class)
+            ->mapsTo(code: 'PRIMARY', status: 409, message: 'Primary translation.');
+
+        /** @And another table that maps the same exception to an unprocessable entity */
+        $secondary = ExceptionMappingTable::create()
+            ->when(exceptionClass: RuntimeException::class)
+            ->mapsTo(code: 'SECONDARY', status: 422, message: 'Secondary translation.');
+
+        /** @When mapping a RuntimeException on the merged table */
+        $result = $primary->mergedWith(other: $secondary)->mapTo(exception: new RuntimeException());
+
+        /** @Then this table's rule wins */
+        self::assertNotNull($result);
+        self::assertSame('PRIMARY', $result->code);
+    }
+
+    public function testMapToWhenSameClassRegisteredTwiceThenFirstRegistrationWins(): void
+    {
+        /** @Given a table with two rules for the same exception class */
+        $table = ExceptionMappingTable::create()
+            ->when(exceptionClass: RuntimeException::class)
+            ->mapsTo(code: 'FIRST', status: 400, message: 'first registration')
+            ->when(exceptionClass: RuntimeException::class)
+            ->mapsTo(code: 'SECOND', status: 404, message: 'second registration');
+
+        /** @When mapping a RuntimeException */
+        $result = $table->mapTo(exception: new RuntimeException());
+
+        /** @Then the first registration's code is returned */
+        self::assertNotNull($result);
+        self::assertSame('FIRST', $result->code);
+    }
+
+    public function testMapToWhenAnyExactClassMatchesListedExceptionThenReturnsMappedError(): void
+    {
+        /** @Given a table with a rule for two listed exception classes */
+        $table = ExceptionMappingTable::create()
+            ->whenAny(exceptionClasses: [RuntimeException::class, LogicException::class])
+            ->mapsTo(code: 'KNOWN_ERR', status: 400, message: 'Known error.');
+
+        /** @When mapping a LogicException (second in the list) */
+        $result = $table->mapTo(exception: new LogicException());
+
+        /** @Then the registered MappedError is returned */
+        self::assertNotNull($result);
+        self::assertSame('KNOWN_ERR', $result->code);
+    }
+
+    public function testMapToWhenSubclassOfBaseClassAndExactInstanceThenReturnsMappedError(): void
+    {
+        /** @Given a table with a whenSubclassOf rule for RuntimeException */
+        $table = ExceptionMappingTable::create()
+            ->whenSubclassOf(baseException: RuntimeException::class)
+            ->mapsTo(code: 'RUNTIME_FAMILY', status: 500, message: 'Runtime family error.');
+
+        /** @When mapping a RuntimeException (the exact base class) */
+        $result = $table->mapTo(exception: new RuntimeException());
+
+        /** @Then the MappedError is returned */
+        self::assertNotNull($result);
+        self::assertSame('RUNTIME_FAMILY', $result->code);
+    }
+
+    public function testMapToWhenExactClassMatchesRegisteredExceptionThenReturnsMappedError(): void
+    {
+        /** @Given a table with a RuntimeException rule */
+        $table = ExceptionMappingTable::create()
+            ->when(exceptionClass: RuntimeException::class)
+            ->mapsTo(code: 'RUNTIME_ERR', status: 500, message: 'Runtime error.');
+
+        /** @When mapping a RuntimeException */
+        $result = $table->mapTo(exception: new RuntimeException());
+
+        /** @Then the registered MappedError is returned with the correct fields */
+        self::assertNotNull($result);
+        self::assertSame('RUNTIME_ERR', $result->code);
+        self::assertSame(500, $result->status);
+
+        /** @And the message is as configured */
+        self::assertSame('Runtime error.', $result->message);
+    }
+
+    public function testMapToWhenAnyExactClassMatchesFirstListedExceptionThenReturnsMappedError(): void
+    {
+        /** @Given a table with a rule for two listed exception classes */
+        $table = ExceptionMappingTable::create()
+            ->whenAny(exceptionClasses: [RuntimeException::class, LogicException::class])
+            ->mapsTo(code: 'KNOWN_ERR', status: 400, message: 'Known error.');
+
+        /** @When mapping a RuntimeException (first in the list) */
+        $result = $table->mapTo(exception: new RuntimeException());
+
+        /** @Then the registered MappedError is returned */
+        self::assertNotNull($result);
+        self::assertSame('KNOWN_ERR', $result->code);
+    }
+
+    public function testMapToWhenExactClassMatchesAndClosureRegisteredThenClosureReceivesException(): void
+    {
+        /** @Given a RuntimeException with a specific message */
+        $exception = new RuntimeException('Payment gateway timeout.');
+
+        /** @And a table with a resolver that reads the exception message */
+        $table = ExceptionMappingTable::create()
+            ->when(exceptionClass: RuntimeException::class)
+            ->resolvesWith(
+                resolver: fn(Throwable $thrownException): MappedError => new MappedError(
+                    code: 'GATEWAY_ERR',
+                    status: 502,
+                    message: $thrownException->getMessage()
+                )
+            );
+
+        /** @When mapping the exception */
+        $result = $table->mapTo(exception: $exception);
+
+        /** @Then the MappedError reflects what the closure returned using the exception */
+        self::assertNotNull($result);
+        self::assertSame('Payment gateway timeout.', $result->message);
+    }
+}
diff --git a/tests/Unit/Internal/AnyExactClassMatcherTest.php b/tests/Unit/Internal/AnyExactClassMatcherTest.php
new file mode 100644
index 0000000..49d7f10
--- /dev/null
+++ b/tests/Unit/Internal/AnyExactClassMatcherTest.php
@@ -0,0 +1,62 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Test\TinyBlocks\HttpMiddlewareError\Unit\Internal;
+
+use LogicException;
+use OverflowException;
+use PHPUnit\Framework\TestCase;
+use RuntimeException;
+use TinyBlocks\HttpMiddlewareError\Internal\AnyExactClassMatcher;
+
+final class AnyExactClassMatcherTest extends TestCase
+{
+    public function testMatchesWhenExceptionClassIsFirstInListThenReturnsTrue(): void
+    {
+        /** @Given an AnyExactClassMatcher configured for RuntimeException and LogicException */
+        $matcher = new AnyExactClassMatcher(exceptionClasses: [RuntimeException::class, LogicException::class]);
+
+        /** @When matching a RuntimeException (first entry in the list) */
+        $result = $matcher->matches(exception: new RuntimeException());
+
+        /** @Then the result is true */
+        self::assertTrue($result);
+    }
+
+    public function testMatchesWhenExceptionClassIsLastInListThenReturnsTrue(): void
+    {
+        /** @Given an AnyExactClassMatcher configured for RuntimeException and LogicException */
+        $matcher = new AnyExactClassMatcher(exceptionClasses: [RuntimeException::class, LogicException::class]);
+
+        /** @When matching a LogicException (last entry in the list) */
+        $result = $matcher->matches(exception: new LogicException());
+
+        /** @Then the result is true */
+        self::assertTrue($result);
+    }
+
+    public function testMatchesWhenExceptionIsSubclassOfListedClassThenReturnsFalse(): void
+    {
+        /** @Given an AnyExactClassMatcher configured for RuntimeException only */
+        $matcher = new AnyExactClassMatcher(exceptionClasses: [RuntimeException::class]);
+
+        /** @When matching an OverflowException (subclass of RuntimeException) */
+        $result = $matcher->matches(exception: new OverflowException());
+
+        /** @Then the result is false because the matcher is exact-class only */
+        self::assertFalse($result);
+    }
+
+    public function testMatchesWhenExceptionIsUnrelatedTypeThenReturnsFalse(): void
+    {
+        /** @Given an AnyExactClassMatcher configured for RuntimeException only */
+        $matcher = new AnyExactClassMatcher(exceptionClasses: [RuntimeException::class]);
+
+        /** @When matching a LogicException (not in the list) */
+        $result = $matcher->matches(exception: new LogicException());
+
+        /** @Then the result is false */
+        self::assertFalse($result);
+    }
+}
diff --git a/tests/Unit/Internal/DynamicMappedErrorResolverTest.php b/tests/Unit/Internal/DynamicMappedErrorResolverTest.php
new file mode 100644
index 0000000..666698f
--- /dev/null
+++ b/tests/Unit/Internal/DynamicMappedErrorResolverTest.php
@@ -0,0 +1,58 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Test\TinyBlocks\HttpMiddlewareError\Unit\Internal;
+
+use PHPUnit\Framework\TestCase;
+use RuntimeException;
+use Throwable;
+use TinyBlocks\HttpMiddlewareError\Internal\DynamicMappedErrorResolver;
+use TinyBlocks\HttpMiddlewareError\MappedError;
+
+final class DynamicMappedErrorResolverTest extends TestCase
+{
+    public function testResolveWhenInvokedThenClosureReceivesTheThrownException(): void
+    {
+        /** @Given a RuntimeException to pass to the resolver */
+        $exception = new RuntimeException('Gateway timed out.');
+
+        /** @And a variable to capture the exception received by the closure */
+        $received = null;
+
+        /** @And a resolver whose closure captures what it receives */
+        $resolver = new DynamicMappedErrorResolver(
+            factory: function (Throwable $thrownException) use (&$received): MappedError {
+                $received = $thrownException;
+                return new MappedError(code: 'ERR', status: 500, message: 'Error.');
+            }
+        );
+
+        /** @When resolving with the exception */
+        $resolver->resolve(exception: $exception);
+
+        /** @Then the closure received the original exception instance */
+        self::assertSame($exception, $received);
+    }
+
+    public function testResolveWhenClosureReadsExceptionFieldsThenReturnsMappedErrorWithThoseFields(): void
+    {
+        /** @Given a RuntimeException whose message will drive the MappedError */
+        $exception = new RuntimeException('Gateway unavailable.');
+
+        /** @And a resolver that builds a MappedError from the exception message */
+        $resolver = new DynamicMappedErrorResolver(
+            factory: fn(Throwable $thrownException): MappedError => new MappedError(
+                code: 'GATEWAY_UNAVAILABLE',
+                status: 502,
+                message: $thrownException->getMessage()
+            )
+        );
+
+        /** @When resolving the exception */
+        $result = $resolver->resolve(exception: $exception);
+
+        /** @Then the resolved MappedError carries the exception message */
+        self::assertSame('Gateway unavailable.', $result->message);
+    }
+}
diff --git a/tests/Unit/Internal/ExactClassMatcherTest.php b/tests/Unit/Internal/ExactClassMatcherTest.php
new file mode 100644
index 0000000..c82210e
--- /dev/null
+++ b/tests/Unit/Internal/ExactClassMatcherTest.php
@@ -0,0 +1,63 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Test\TinyBlocks\HttpMiddlewareError\Unit\Internal;
+
+use Exception;
+use LogicException;
+use OverflowException;
+use PHPUnit\Framework\TestCase;
+use RuntimeException;
+use TinyBlocks\HttpMiddlewareError\Internal\ExactClassMatcher;
+
+final class ExactClassMatcherTest extends TestCase
+{
+    public function testMatchesWhenExceptionClassIsExactMatchThenReturnsTrue(): void
+    {
+        /** @Given an ExactClassMatcher configured for RuntimeException */
+        $matcher = new ExactClassMatcher(exceptionClass: RuntimeException::class);
+
+        /** @When matching a RuntimeException instance */
+        $result = $matcher->matches(exception: new RuntimeException());
+
+        /** @Then the result is true */
+        self::assertTrue($result);
+    }
+
+    public function testMatchesWhenExceptionIsParentClassThenReturnsFalse(): void
+    {
+        /** @Given an ExactClassMatcher configured for RuntimeException */
+        $matcher = new ExactClassMatcher(exceptionClass: RuntimeException::class);
+
+        /** @When matching an Exception instance (parent of RuntimeException) */
+        $result = $matcher->matches(exception: new Exception());
+
+        /** @Then the result is false */
+        self::assertFalse($result);
+    }
+
+    public function testMatchesWhenExceptionIsSubclassThenReturnsFalse(): void
+    {
+        /** @Given an ExactClassMatcher configured for RuntimeException */
+        $matcher = new ExactClassMatcher(exceptionClass: RuntimeException::class);
+
+        /** @When matching an OverflowException instance (subclass of RuntimeException) */
+        $result = $matcher->matches(exception: new OverflowException());
+
+        /** @Then the result is false */
+        self::assertFalse($result);
+    }
+
+    public function testMatchesWhenExceptionIsUnrelatedTypeThenReturnsFalse(): void
+    {
+        /** @Given an ExactClassMatcher configured for RuntimeException */
+        $matcher = new ExactClassMatcher(exceptionClass: RuntimeException::class);
+
+        /** @When matching a LogicException instance (unrelated type) */
+        $result = $matcher->matches(exception: new LogicException());
+
+        /** @Then the result is false */
+        self::assertFalse($result);
+    }
+}
diff --git a/tests/Unit/Internal/FixedMappedErrorResolverTest.php b/tests/Unit/Internal/FixedMappedErrorResolverTest.php
new file mode 100644
index 0000000..cc30017
--- /dev/null
+++ b/tests/Unit/Internal/FixedMappedErrorResolverTest.php
@@ -0,0 +1,44 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Test\TinyBlocks\HttpMiddlewareError\Unit\Internal;
+
+use LogicException;
+use PHPUnit\Framework\TestCase;
+use RuntimeException;
+use TinyBlocks\HttpMiddlewareError\Internal\FixedMappedErrorResolver;
+use TinyBlocks\HttpMiddlewareError\MappedError;
+
+final class FixedMappedErrorResolverTest extends TestCase
+{
+    public function testResolveWhenAnyExceptionProvidedThenReturnsConfiguredMappedError(): void
+    {
+        /** @Given a fixed MappedError */
+        $mappedError = new MappedError(code: 'NOT_FOUND', status: 404, message: 'Resource not found.');
+
+        /** @And a FixedMappedErrorResolver configured with that MappedError */
+        $resolver = new FixedMappedErrorResolver(error: $mappedError);
+
+        /** @When resolving with any exception */
+        $result = $resolver->resolve(exception: new RuntimeException());
+
+        /** @Then the exact same MappedError instance is returned */
+        self::assertSame($mappedError, $result);
+    }
+
+    public function testResolveWhenDifferentExceptionTypeProvidedThenAlwaysReturnsConfiguredMappedError(): void
+    {
+        /** @Given a fixed MappedError */
+        $mappedError = new MappedError(code: 'ERR', status: 500, message: 'Error.');
+
+        /** @And a FixedMappedErrorResolver configured with that MappedError */
+        $resolver = new FixedMappedErrorResolver(error: $mappedError);
+
+        /** @When resolving with a different exception type */
+        $result = $resolver->resolve(exception: new LogicException());
+
+        /** @Then the same MappedError instance is returned regardless of exception type */
+        self::assertSame($mappedError, $result);
+    }
+}
diff --git a/tests/Unit/Internal/MappingEntryTest.php b/tests/Unit/Internal/MappingEntryTest.php
new file mode 100644
index 0000000..af464a3
--- /dev/null
+++ b/tests/Unit/Internal/MappingEntryTest.php
@@ -0,0 +1,77 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Test\TinyBlocks\HttpMiddlewareError\Unit\Internal;
+
+use LogicException;
+use PHPUnit\Framework\TestCase;
+use RuntimeException;
+use Throwable;
+use TinyBlocks\HttpMiddlewareError\Internal\ExactClassMatcher;
+use TinyBlocks\HttpMiddlewareError\Internal\FixedMappedErrorResolver;
+use TinyBlocks\HttpMiddlewareError\Internal\MappedErrorResolver;
+use TinyBlocks\HttpMiddlewareError\Internal\MappingEntry;
+use TinyBlocks\HttpMiddlewareError\MappedError;
+
+final class MappingEntryTest extends TestCase
+{
+    public function testResolveWhenMatcherDoesNotMatchThenReturnsNull(): void
+    {
+        /** @Given a MappingEntry that matches only RuntimeException */
+        $entry = new MappingEntry(
+            matcher: new ExactClassMatcher(exceptionClass: RuntimeException::class),
+            resolver: new FixedMappedErrorResolver(error: new MappedError(code: 'ERR', status: 400, message: 'error'))
+        );
+
+        /** @When resolving a LogicException (not matched) */
+        $result = $entry->resolve(exception: new LogicException());
+
+        /** @Then null is returned */
+        self::assertNull($result);
+    }
+
+    public function testResolveWhenMatcherMatchesThenReturnsMappedError(): void
+    {
+        /** @Given a fixed MappedError for RuntimeException */
+        $mappedError = new MappedError(code: 'ERR', status: 500, message: 'error');
+
+        /** @And a MappingEntry that matches RuntimeException with that MappedError */
+        $entry = new MappingEntry(
+            matcher: new ExactClassMatcher(exceptionClass: RuntimeException::class),
+            resolver: new FixedMappedErrorResolver(error: $mappedError)
+        );
+
+        /** @When resolving a RuntimeException (matched) */
+        $result = $entry->resolve(exception: new RuntimeException());
+
+        /** @Then the MappedError is returned */
+        self::assertSame($mappedError, $result);
+    }
+
+    public function testResolveWhenMatcherDoesNotMatchThenResolverIsNotInvoked(): void
+    {
+        /** @Given a resolver that records whether it was invoked */
+        $resolver = new class implements MappedErrorResolver {
+            public bool $wasInvoked = false;
+
+            public function resolve(Throwable $exception): MappedError
+            {
+                $this->wasInvoked = true;
+                return new MappedError(code: 'UNUSED', status: 400, message: 'unused');
+            }
+        };
+
+        /** @And a MappingEntry that only matches RuntimeException */
+        $entry = new MappingEntry(
+            matcher: new ExactClassMatcher(exceptionClass: RuntimeException::class),
+            resolver: $resolver
+        );
+
+        /** @When resolving a LogicException (not matched) */
+        $entry->resolve(exception: new LogicException());
+
+        /** @Then the resolver was not invoked */
+        self::assertFalse($resolver->wasInvoked);
+    }
+}
diff --git a/tests/Unit/Internal/SubclassMatcherTest.php b/tests/Unit/Internal/SubclassMatcherTest.php
new file mode 100644
index 0000000..b9fa07a
--- /dev/null
+++ b/tests/Unit/Internal/SubclassMatcherTest.php
@@ -0,0 +1,50 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Test\TinyBlocks\HttpMiddlewareError\Unit\Internal;
+
+use LogicException;
+use OverflowException;
+use PHPUnit\Framework\TestCase;
+use RuntimeException;
+use TinyBlocks\HttpMiddlewareError\Internal\SubclassMatcher;
+
+final class SubclassMatcherTest extends TestCase
+{
+    public function testMatchesWhenExceptionIsExactBaseClassThenReturnsTrue(): void
+    {
+        /** @Given a SubclassMatcher configured for RuntimeException */
+        $matcher = new SubclassMatcher(baseException: RuntimeException::class);
+
+        /** @When matching a RuntimeException instance */
+        $result = $matcher->matches(exception: new RuntimeException());
+
+        /** @Then the result is true */
+        self::assertTrue($result);
+    }
+
+    public function testMatchesWhenExceptionIsSubclassOfBaseClassThenReturnsTrue(): void
+    {
+        /** @Given a SubclassMatcher configured for RuntimeException */
+        $matcher = new SubclassMatcher(baseException: RuntimeException::class);
+
+        /** @When matching an OverflowException (subclass of RuntimeException) */
+        $result = $matcher->matches(exception: new OverflowException());
+
+        /** @Then the result is true */
+        self::assertTrue($result);
+    }
+
+    public function testMatchesWhenExceptionIsUnrelatedTypeThenReturnsFalse(): void
+    {
+        /** @Given a SubclassMatcher configured for RuntimeException */
+        $matcher = new SubclassMatcher(baseException: RuntimeException::class);
+
+        /** @When matching a LogicException (not a subclass of RuntimeException) */
+        $result = $matcher->matches(exception: new LogicException());
+
+        /** @Then the result is false */
+        self::assertFalse($result);
+    }
+}
diff --git a/tests/Unit/MappedErrorTest.php b/tests/Unit/MappedErrorTest.php
new file mode 100644
index 0000000..16b4998
--- /dev/null
+++ b/tests/Unit/MappedErrorTest.php
@@ -0,0 +1,94 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Test\TinyBlocks\HttpMiddlewareError\Unit;
+
+use PHPUnit\Framework\TestCase;
+use TinyBlocks\HttpMiddlewareError\Exceptions\HttpStatusOutOfRange;
+use TinyBlocks\HttpMiddlewareError\MappedError;
+
+final class MappedErrorTest extends TestCase
+{
+    public function testConstructionWhenStatusIsAtLowerBoundaryThenNoExceptionIsThrown(): void
+    {
+        /** @Given the minimum valid HTTP error status */
+        $status = 400;
+
+        /** @When constructing a MappedError at the lower boundary */
+        $error = new MappedError(code: 'ERR', status: $status, message: 'msg');
+
+        /** @Then it should be created successfully with the expected status */
+        self::assertSame(400, $error->status);
+    }
+
+    public function testConstructionWhenStatusIsAtUpperBoundaryThenNoExceptionIsThrown(): void
+    {
+        /** @Given the maximum valid HTTP error status */
+        $status = 511;
+
+        /** @When constructing a MappedError at the upper boundary */
+        $error = new MappedError(code: 'ERR', status: $status, message: 'msg');
+
+        /** @Then it should be created successfully with the expected status */
+        self::assertSame(511, $error->status);
+    }
+
+    public function testConstructionWhenStatusIsBelowLowerBoundaryThenHttpStatusOutOfRangeIsThrown(): void
+    {
+        /** @Then an exception indicating the status is out of range should be thrown */
+        $this->expectException(HttpStatusOutOfRange::class);
+        $this->expectExceptionMessage('HTTP status <399> must be between 400 and 599.');
+
+        /** @When constructing a MappedError below the lower boundary */
+        new MappedError(code: 'ERR', status: 399, message: 'msg');
+    }
+
+    public function testConstructionWhenStatusExceedsUpperBoundaryThenHttpStatusOutOfRangeIsThrown(): void
+    {
+        /** @Then an exception indicating the status is out of range should be thrown */
+        $this->expectException(HttpStatusOutOfRange::class);
+        $this->expectExceptionMessage('HTTP status <600> must be between 400 and 599.');
+
+        /** @When constructing a MappedError above the upper boundary */
+        new MappedError(code: 'ERR', status: 600, message: 'msg');
+    }
+
+    public function testConstructionWhenHeadersAreOmittedThenDefaultsToEmptyArray(): void
+    {
+        /** @When constructing a MappedError without providing headers */
+        $error = new MappedError(code: 'ERR', status: 422, message: 'An error occurred.');
+
+        /** @Then headers should default to an empty array */
+        self::assertSame([], $error->headers);
+    }
+
+    public function testConstructionWhenHeadersAreProvidedThenAreExposed(): void
+    {
+        /** @Given a set of headers to include in the error response */
+        $headers = ['Retry-After' => '60'];
+
+        /** @When constructing a MappedError with those headers */
+        $error = new MappedError(
+            code: 'LOGIN_THROTTLED',
+            status: 429,
+            message: 'Too many failed login attempts.',
+            headers: $headers
+        );
+
+        /** @Then the headers should be preserved as provided */
+        self::assertSame($headers, $error->headers);
+    }
+
+    public function testConstructionWhenHeaderValueIsArrayThenMultiValueIsPreserved(): void
+    {
+        /** @Given a multi-value header */
+        $headers = ['X-Custom' => ['a', 'b']];
+
+        /** @When constructing a MappedError with multi-value headers */
+        $error = new MappedError(code: 'ERR', status: 422, message: 'An error occurred.', headers: $headers);
+
+        /** @Then the multi-value header should be preserved */
+        self::assertSame($headers, $error->headers);
+    }
+}
diff --git a/tests/Unit/UnmappedExceptions.php b/tests/Unit/UnmappedExceptions.php
new file mode 100644
index 0000000..465884f
--- /dev/null
+++ b/tests/Unit/UnmappedExceptions.php
@@ -0,0 +1,16 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Test\TinyBlocks\HttpMiddlewareError\Unit;
+
+use TinyBlocks\HttpMiddlewareError\ExceptionMapping;
+use TinyBlocks\HttpMiddlewareError\ExceptionMappingTable;
+
+final readonly class UnmappedExceptions implements ExceptionMapping
+{
+    public function mappings(): ExceptionMappingTable
+    {
+        return ExceptionMappingTable::create();
+    }
+}