Release/1.1.1 (#3)

Author: gustavofreze

.claude/CLAUDE.md

@@ -1,10 +1,12 @@
 # Project
 
-PHP microservices platform. Hexagonal architecture (ports & adapters), DDD, CQRS.
+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, documentation, and OpenAPI conventions
+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

.claude/rules/php-domain.md

@@ -1,14 +1,14 @@
 ---
-description: Pre-output checklist, naming, typing, comparisons, and PHPDoc rules for all PHP files in libraries.
+description: Pre-output checklist, naming, typing, complexity, and PHPDoc rules for all PHP files in libraries.
 paths:
-  - "src/**/*.php"
-  - "tests/**/*.php"
+    - "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 `rules/domain.md` for domain modeling rules.
+and are not repeated here. Refer to `php-library-modeling.md` for library modeling rules.
 
 ## Pre-output checklist
 
@@ -29,19 +29,27 @@ Verify every item before producing any PHP code. If any item fails, revise befor
 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 `tiny-blocks/collection`
-   (`Collection`, `Collectible`) instead of raw `array` for any list of domain objects. Raw arrays are acceptable
-   only for primitive configuration data, variadic pass-through, or interop at system boundaries.
+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. The same rule applies to named arguments at call sites.
+    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. No O(N²) or worse complexity exists.
+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.
@@ -59,8 +67,31 @@ Verify every item before producing any PHP code. If any item fails, revise befor
 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 `{` goes on the same line as the closing parenthesis `)` for constructors, methods, and
-    closures: `): ReturnType {` — not `): ReturnType\n    {`. Parameters with default values go last.
+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
 
@@ -70,9 +101,7 @@ Verify every item before producing any PHP code. If any item fails, revise befor
 ## Naming
 
 - Names describe **what** in domain terms, not **how** technically: `$monthlyRevenue` instead of `$calculatedValue`.
-- Generic technical verbs (`process`, `handle`, `execute`, `mark`, `enforce`, `manage`, `ensure`, `validate`,
-  `check`, `verify`, `assert`, `transform`, `parse`, `compute`, `sanitize`, `normalize`) **should be avoided**.
-  Prefer names that describe the domain operation.
+- 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`.
@@ -93,12 +122,19 @@ All identifiers, enum values, comments, and error codes use American English spe
 
 ## PHPDoc
 
-- PHPDoc is restricted to interfaces only, documenting obligations and `@throws`.
+- 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.
+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:**
 
@@ -116,6 +152,3 @@ $names = $collection
     ->map(transformations: static fn(Element $element): string => $element->name())
     ->toArray(keyPreservation: KeyPreservation::DISCARD);
 ```
-
-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.

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

@@ -1,7 +1,7 @@
 ---
 description: Standards for README files and all project documentation in PHP libraries.
 paths:
-  - "**/*.md"
+    - "**/*.md"
 ---
 
 # Documentation
@@ -21,7 +21,8 @@ paths:
    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 `rules/code-style.md` American English section for spelling conventions.
+10. Write strictly in American English. See `php-library-code-style.md` American English section for spelling
+    conventions.
 
 ## Structured data
 
@@ -34,4 +35,6 @@ paths:
 1. Keep language concise and scannable.
 2. Never include placeholder content (`TODO`, `TBD`).
 3. Code examples must be syntactically correct and self-contained.
-4. Do not document `Internal/` classes or private API. Only document what consumers interact with.
+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.