Release/2.0.2 (#25)

Author: gustavofreze

.claude/CLAUDE.md

@@ -0,0 +1,32 @@
+# Project
+
+PHP library (tiny-blocks ecosystem). Self-contained package: immutable models, zero infrastructure
+dependencies in core, small public surface area. Public API at `src/` root; implementation details
+under `src/Internal/`.
+
+## Rules
+
+All coding standards, architecture, naming, testing, and documentation conventions
+are defined in `rules/`. Read the applicable rule files before generating any code or documentation.
+
+## Commands
+
+- `make test` — run tests with coverage.
+- `make mutation-test` — run mutation testing (Infection).
+- `make review` — run lint.
+- `make help` — list all available commands.
+
+## Post-change validation
+
+After any code change, run `make review`, `make test`, and `make mutation-test`.
+If any fails, iterate on the fix while respecting all project rules until all pass.
+Never deliver code that breaks lint, tests, or leaves surviving mutants.
+
+## File formatting
+
+Every file produced or modified must:
+
+- Use **LF** line endings. Never CRLF.
+- Have no trailing whitespace on any line.
+- End with a single trailing newline.
+- Have no consecutive blank lines (max one blank line between blocks).

.claude/rules/github-workflows.md

@@ -0,0 +1,78 @@
+---
+description: Naming, ordering, inputs, security, and structural rules for all GitHub Actions workflow files.
+paths:
+  - ".github/workflows/**/*.yml"
+  - ".github/workflows/**/*.yaml"
+---
+
+# Workflows
+
+Structural and stylistic rules for GitHub Actions workflow files. Refer to `shell-scripts.md` for Bash conventions used
+inside `run:` steps, and to `terraforms.md` for Terraform conventions used in `terraform/`.
+
+## Pre-output checklist
+
+Verify every item before producing any workflow YAML. If any item fails, revise before outputting.
+
+1. File name follows the convention: `ci-<runtime>.yml` for reusable CI, `cd-<purpose>.yml` for dispatch CD.
+2. `name` field follows the pattern `CI — <Context>` or `CD — <Context>`, using sentence case after the dash
+   (e.g., `CD — Run migration`, not `CD — Run Migration`).
+3. Reusable workflows use `workflow_call` trigger. CD workflows use `workflow_dispatch` trigger.
+4. Each workflow has a single responsibility. CI tests code. CD deploys it. Never combine both.
+5. Every input has a `description` field. Descriptions use American English and end with a period.
+6. Input names use `kebab-case`: `service-name`, `dry-run`, `skip-build`.
+7. Inputs are ordered: required first, then optional. Each group by **name length ascending**.
+8. Choice input options are in **alphabetical order**.
+9. `env`, `outputs`, and `with` entries are ordered by **key length ascending**.
+10. `permissions` keys are ordered by **key length ascending** (`contents` before `id-token`).
+11. Top-level workflow keys follow canonical order: `name`, `on`, `concurrency`, `permissions`, `env`, `jobs`.
+12. Job-level properties follow canonical order: `if`, `name`, `needs`, `uses`, `with`, `runs-on`,
+    `environment`, `timeout-minutes`, `strategy`, `outputs`, `permissions`, `env`, `steps`.
+13. All other YAML property names within a block are ordered by **name length ascending**.
+14. Jobs follow execution order: `load-config` → `lint` → `test` → `build` → `deploy`.
+15. Step names start with a verb and use sentence case: `Setup PHP`, `Run lint`, `Resolve image tag`.
+16. Runtime versions are resolved from the service repo's native dependency file (`composer.json`, `go.mod`,
+    `package.json`). No version is hardcoded in any workflow.
+17. Service-specific overrides live in a pipeline config file (e.g., `.pipeline.yml`) in the service repo,
+    not in the workflows repository.
+18. The `load-config` job reads the pipeline config file at runtime with safe fallback to defaults when absent.
+19. Top-level `permissions` defaults to read-only (`contents: read`). Jobs escalate only the permissions they
+    need.
+20. AWS authentication uses OIDC federation exclusively. Static access keys are forbidden.
+21. Secrets are passed via `secrets: inherit` from callers. No secret is hardcoded.
+22. Sensitive values fetched from SSM are masked with `::add-mask::` before assignment.
+23. Third-party actions are pinned to the latest available full commit SHA with a version comment:
+    `uses: aws-actions/configure-aws-credentials@<latest-sha> # v4.0.2`. Always verify the latest
+    version before generating a workflow.
+24. First-party actions (`actions/*`) are pinned to the latest major version tag available:
+    `actions/checkout@v4`. Always check for the most recent major version before generating a workflow.
+25. Production deployments require GitHub Environments protection rules (manual approval).
+26. Every job sets `timeout-minutes` to prevent indefinite hangs. CI jobs: 10–15 minutes. CD jobs: 20–30
+    minutes. Adjust only with justification in a comment.
+27. CI workflows set `concurrency` with `group` scoped to the PR and `cancel-in-progress: true` to avoid
+    redundant runs.
+28. CD workflows set `concurrency` with `group` scoped to the environment and `cancel-in-progress: false` to
+    prevent interrupted deployments.
+29. CD workflows use `if: ${{ !cancelled() }}` to allow to deploy after optional build steps.
+30. Inline logic longer than 3 lines is extracted to a script in `scripts/ci/` or `scripts/cd/`.
+
+## Style
+
+- All text (workflow names, step names, input descriptions, comments) uses American English with correct
+  spelling and punctuation. Sentences and descriptions end with a period.
+
+## Callers
+
+- Callers trigger on `pull_request` targeting `main` only. No `push` trigger.
+- Callers in service repos are static (~10 lines) and pass only `service-name` or `app-name`.
+- Callers reference workflows with `@main` during development. Pin to a tag or SHA for production.
+
+## Image tagging
+
+- CD deploy builds: `<environment>-sha-<short-hash>` + `latest`.
+
+## Migrations
+
+- Migrations run **before** service deployment (schema first, code second).
+- `cd-migrate.yml` supports `dry-run` mode (`flyway validate`) for pre-flight checks.
+- Database credentials are fetched from SSM at runtime, never stored in workflow files.

.claude/rules/php-library-code-style.md

@@ -0,0 +1,154 @@
+---
+description: Pre-output checklist, naming, typing, complexity, and PHPDoc rules for all PHP files in libraries.
+paths:
+    - "src/**/*.php"
+    - "tests/**/*.php"
+---
+
+# Code style
+
+Semantic code rules for all PHP files. Formatting rules (PSR-1, PSR-4, PSR-12, line length) are enforced by `phpcs.xml`
+and are not repeated here. Refer to `php-library-modeling.md` for library modeling rules.
+
+## 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 classes are `final readonly` by default. Use `class` (without `final` or `readonly`) only when the class is
+   designed as an extension point for consumers (e.g., `Collection`, `ValueObject`). Use `final class` without
+   `readonly` only when the parent class is not readonly (e.g., extending a third-party abstract class).
+3. All parameters, return types, and properties have explicit types.
+4. Constructor property promotion is used.
+5. Named arguments are used at call sites for own code, tests, and third-party library methods (e.g., tiny-blocks).
+   Never use named arguments on native PHP functions (`array_map`, `in_array`, `preg_match`, `is_null`,
+   `iterator_to_array`, `sprintf`, `implode`, etc.) or PHPUnit assertions (`assertEquals`, `assertSame`,
+   `assertTrue`, `expectException`, etc.).
+6. No `else` or `else if` exists anywhere. Use early returns, polymorphism, or map dispatch instead.
+7. No abbreviations appear in identifiers. Use `$index` instead of `$i`, `$account` instead of `$acc`.
+8. No generic identifiers exist. Use domain-specific names instead:
+   `$data` → `$payload`, `$value` → `$totalAmount`, `$item` → `$element`,
+   `$info` → `$currencyDetails`, `$result` → `$conversionOutcome`.
+9. No raw arrays exist where a typed collection or value object is available. Use the `tiny-blocks/collection`
+   fluent API (`Collection`, `Collectible`) when data is `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" below for the full rule and example.
+10. No private methods exist except private constructors for factory patterns. Inline trivial logic at the call site
+    or extract it to a collaborator or value object.
+11. Members are ordered: constants first, then constructor, then static methods, then instance methods. Within each
+    group, order by body size ascending (number of lines between `{` and `}`). Constants and enum cases, which have
+    no body, are ordered by name length ascending.
+12. Constructor parameters are ordered by parameter name length ascending (count the name only, without `$` or type),
+    except when parameters have an implicit semantic order (e.g., `$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: `$id` (2) → `$value` (5) → `$status` (6) → `$precision` (9).
+13. Time and space complexity are first-class design concerns.
+    - No `O(N²)` or worse time complexity exists unless the problem inherently requires it and the cost is
+      documented in PHPDoc on the interface method.
+    - Space complexity is kept minimal: prefer lazy/streaming pipelines (`createLazyFrom`) over materializing
+      intermediate collections.
+    - Never re-iterate the same source; fuse stages when possible.
+    - Public interface methods document time and space complexity in Big O form (see "PHPDoc" section).
+14. No logic is duplicated across two or more places (DRY).
+15. No abstraction exists without real duplication or isolation need (KISS).
+16. All identifiers, comments, and documentation are written in American English.
+17. No justification comments exist (`// NOTE:`, `// REASON:`, etc.). Code speaks for itself.
+18. `// TODO: <reason>` is used when implementation is unknown, uncertain, or intentionally deferred.
+    Never leave silent gaps.
+19. All class references use `use` imports at the top of the file. Fully qualified names inline are prohibited.
+20. No dead or unused code exists. Remove unreferenced classes, methods, constants, and imports.
+21. Never create public methods, constants, or classes in `src/` solely to serve tests. If production code does not
+    need it, it does not exist.
+22. Always use the most current and clean syntax available in the target PHP version. Prefer match to switch,
+    first-class callables over `Closure::fromCallable()`, readonly promotion over manual assignment, enum methods
+    over external switch/if chains, named arguments over positional ambiguity (except where excluded by rule 5),
+    and `Collection::map` over foreach accumulation.
+23. No vertical alignment of types in parameter lists or property declarations. Use a single space between
+    type and variable name. Never pad with extra spaces to align columns:
+    `public OrderId $id` — not `public OrderId     $id`.
+24. Opening brace `{` follows PSR-12: on a **new line** for classes, interfaces, traits, enums, and methods
+    (including constructors); on the **same line** for closures and control structures (`if`, `for`, `foreach`,
+    `while`, `switch`, `match`, `try`).
+25. Never pass an argument whose value equals the parameter's default. Omit the argument entirely.
+    Example — `toArray(KeyPreservation $keyPreservation = KeyPreservation::PRESERVE)`:
+    `$collection->toArray(keyPreservation: KeyPreservation::PRESERVE)` → `$collection->toArray()`.
+    Only pass the argument when the value differs from the default.
+26. No trailing comma in any multi-line list. This applies to parameter lists (constructors, methods,
+    closures), argument lists at call sites, array literals, match arms, and any other comma-separated
+    multi-line structure. The last element never has a comma after it. PHP accepts trailing commas in
+    parameter lists, but this project prohibits them for visual consistency.
+    Example — correct:
+    ```
+    new Precision(
+        value: 2,
+        rounding: RoundingMode::HALF_UP
+    );
+    ```
+    Example — prohibited:
+    ```
+    new Precision(
+        value: 2,
+        rounding: RoundingMode::HALF_UP,
+    );
+    ```
+
+## Casing conventions
+
+- Internal code (variables, methods, classes): **`camelCase`**.
+- Constants and enum-backed values when representing codes: **`SCREAMING_SNAKE_CASE`**.
+
+## Naming
+
+- Names describe **what** in domain terms, not **how** technically: `$monthlyRevenue` instead of `$calculatedValue`.
+- Generic technical verbs are avoided. See `php-library-modeling.md` — Nomenclature.
+- Booleans use predicate form: `isActive`, `hasPermission`, `wasProcessed`.
+- Collections are always plural: `$orders`, `$lines`.
+- Methods returning bool use prefixes: `is`, `has`, `can`, `was`, `should`.
+
+## 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:
+`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
+
+- PHPDoc is restricted to interfaces only, documenting obligations, `@throws`, and complexity.
+- Never add PHPDoc to concrete classes.
+- Document `@throws` for every exception the method may raise.
+- Document time and space complexity in Big O form. When a method participates in a fused pipeline (e.g., collection
+  pipelines), express cost as a two-part form: call-site cost + fused-pass contribution. Include a legend defining
+  variables (e.g., `N` for input size, `K` for number of stages).
+
+## 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` + accumulation. The same applies to `filter()`,
+`reduce()`, `each()`, and all other `Collectible` operations. Chain them fluently. Never materialize with
+`iterator_to_array` to then pass into a raw `array_*` function.
+
+**Prohibited — `array_map` + `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()` + `toArray()`:**
+
+```php
+$names = $collection
+    ->map(transformations: static fn(Element $element): string => $element->name())
+    ->toArray(keyPreservation: KeyPreservation::DISCARD);
+```

.claude/rules/php-library-documentation.md

@@ -0,0 +1,40 @@
+---
+description: Standards for README files and all project documentation in PHP libraries.
+paths:
+    - "**/*.md"
+---
+
+# Documentation
+
+## README
+
+1. Include an anchor-linked table of contents.
+2. Start with a concise one-line description of what the library does.
+3. Include a **badges** section (license, build status, coverage, latest version, PHP version).
+4. Provide an **Overview** section explaining the problem the library solves and its design philosophy.
+5. **Installation** section: Composer command (`composer require vendor/package`).
+6. **How to use** section: complete, runnable code examples covering the primary use cases. Each example
+   includes a brief heading describing what it demonstrates.
+7. If the library exposes multiple entry points, strategies, or container types, document each with its own
+   subsection and example.
+8. **FAQ** section: include entries for common pitfalls, non-obvious behaviors, or design decisions that users
+   frequently ask about. Each entry is a numbered question as heading (e.g., `### 01. Why does X happen?`)
+   followed by a concise explanation. Only include entries that address real confusion points.
+9. **License** and **Contributing** sections at the end.
+10. Write strictly in American English. See `php-library-code-style.md` American English section for spelling
+    conventions.
+
+## Structured data
+
+1. When documenting constructors, factory methods, or configuration options with more than 3 parameters,
+   use tables with columns: Parameter, Type, Required, Description.
+2. Prefer tables to prose for any structured information.
+
+## Style
+
+1. Keep language concise and scannable.
+2. Never include placeholder content (`TODO`, `TBD`).
+3. Code examples must be syntactically correct and self-contained.
+4. Code examples include every `use` statement needed to compile. Each example stands alone — copyable into
+   a fresh file without modification.
+5. Do not document `Internal/` classes or private API. Only document what consumers interact with.