Replace string-based references with targeted parameter attributes

- Add AssuranceParameter (TARGET_PARAMETER) for constructor and assertion
  method parameter annotation, replacing Assurance's $parameter and $input
  string properties
- Add ComposableParameter (TARGET_PARAMETER) for prefix parameter promotion,
  replacing Composable's $prefixParameter boolean
- Add Assurance, AssuranceFrom, AssuranceCompose, AssuranceModifier attributes
  for type narrowing metadata
- Add AssuranceAssertion (TARGET_METHOD) replacing class-level FluentAssertion
- Change Composable to store raw class-strings; consumers resolve via
  FluentResolver instead of internal toPrefix()
- Change Composable $prefix to nullable (null = not a prefix class)
- Change Assurance $composeRange from string to array{int, int|null}
- Use private(set) visibility on Assurance and FluentNamespace properties
- Add FluentBuilder TSure/TSureNot template parameters
- Add unit tests for Composable and AssuranceAssertion
- Complete API documentation in docs/api.md

Author: alganet

README.md

@@ -1,3 +1,8 @@
+<!--
+SPDX-FileCopyrightText: (c) Respect Project Contributors
+SPDX-License-Identifier: ISC
+SPDX-FileContributor: Alexandre Gomes Gaigalas <alganet@gmail.com>
+-->
 # Respect\Fluent
 
 Build fluent interfaces from class namespaces. PHP 8.5+, zero dependencies.
@@ -104,7 +109,7 @@ namespace App\Middleware;
 
 use Respect\Fluent\Attributes\Composable;
 
-#[Composable('optional')]
+#[Composable(self::class)]
 final readonly class Optional implements Middleware
 {
     public function __construct(private Middleware $inner) {}
@@ -161,232 +166,50 @@ A **FluentNode** carries the resolution state between resolvers and factories:
 a name, constructor arguments, and an optional wrapper.
 
 ```
-                         +-----------+
-  'notEmail' -------->   |  Resolver |   ------>  FluentNode('Email', wrapper: FluentNode('Not'))
-                         +-----------+
+                         +----------+
+  'notEmail' -------->   | Resolver |  ------>  FluentNode('Email', wrapper: FluentNode('Not'))
+                         +----------+
                               |
                               v
-                         +-----------+
-  FluentNode ----------->  |  Factory  |   ------>  Not(Email())
-                         +-----------+
+                         +----------+
+  FluentNode --------->  | Factory  |  ------>  Not(Email())
+                         +----------+
 ```
 
 **NamespaceLookup vs ComposingLookup:** use `NamespaceLookup` for simple
 name-to-class mapping. Wrap it with `ComposingLookup` when you need prefix
 composition like `notEmail()` → `Not(Email())`. `ComposingLookup` supports
 recursive unwrapping, so `notNullOrEmail()` → `Not(NullOr(Email()))` works too.
 
-## API Reference
+## Assurance attributes
 
-### FluentNamespace (attribute)
+Node classes can declare what they assure about their input via `#[Assurance]`.
+Assertion methods are marked with `#[AssuranceAssertion]`, and `#[AssuranceParameter]`
+identifies specific parameters. Constructor parameters for composition use
+`#[ComposableParameter]`.
 
-Declares the factory configuration for a builder class. Both the runtime
-(`factoryFromAttribute()`) and static analysis (FluentAnalysis) read from this
-single source of truth:
+This metadata is available at runtime through reflection and is also consumed
+by tools like [FluentAnalysis](https://github.com/Respect/FluentAnalysis)
+for static type narrowing.
 
 ```php
-use Respect\Fluent\Attributes\FluentNamespace;
-
-// Simple lookup
-#[FluentNamespace(new NamespaceLookup(new Ucfirst(), null, 'App\\Handlers'))]
-
-// With type validation
-#[FluentNamespace(new NamespaceLookup(new Ucfirst(), Handler::class, 'App\\Handlers'))]
-
-// With prefix composition
-#[FluentNamespace(new ComposingLookup(
-    new NamespaceLookup(new Ucfirst(), Validator::class, 'App\\Validators'),
-))]
-```
-
-### Builders
-
-Abstract base `FluentBuilder` provides `__call`, `__callStatic`, `getNodes()`,
-`withNamespace()`, `factoryFromAttribute()`, and the abstract `attach()` method.
-Two concrete builders:
-
-**`Append`** — each `attach()` appends nodes to the end:
-
-```php
-$builder = new Append($factory);
-$chain = $builder->cors()->auth('bearer');
-$chain->getNodes();                      // [Cors(), Auth('bearer')]
-$chain->attach($manualNode);             // add pre-built objects
-$chain->withNamespace('Extra\\Ns');      // prepend a search namespace
-```
-
-**`Prepend`** — each `attach()` prepends nodes to the front:
-
-```php
-$builder = new Prepend($factory);
-$chain = $builder->cors()->auth('bearer');
-$chain->getNodes();                      // [Auth('bearer'), Cors()]
-```
-
-Both are `readonly` and not `final`, extend them and add your domain methods.
-`__callStatic` calls `new static()` by default; override it if your subclass
-needs a different way to obtain a default instance.
-
-### FluentFactory
-
-Interface implemented by both factories:
+#[Assurance(type: 'int')]
+final readonly class IntType implements Validator { /* ... */ }
 
-```php
-interface FluentFactory
+final readonly class ValidatorBuilder extends Append
 {
-    public function create(string $name, array $arguments = []): object;
-    public function withNamespace(string $namespace): static;
-}
-```
-
-#### NamespaceLookup
-
-The primary factory. Searches namespaces in order for a matching class.
-
-```php
-$lookup = new NamespaceLookup(
-    new Ucfirst(),             // resolver: 'email' → 'Email'
-    MyInterface::class,        // optional type validation
-    'App\\Handlers',           // primary namespace
-    'App\\Handlers\\Fallback', // fallback namespace
-);
-
-$lookup->create('email', ['strict' => true]);  // new App\Handlers\Email(strict: true)
-$lookup->resolve('email');                      // ReflectionClass (without instantiating)
-```
-
-The `$resolver` and `$namespaces` properties are `public private(set)`, you
-can read them (useful for tooling like FluentAnalysis) but not reassign them.
-
-Immutable builders: `withNamespace()` prepends a namespace, `withNodeType()`
-adds type validation. Both return new instances.
-
-#### ComposingLookup
-
-Wraps a `NamespaceLookup` to handle prefix composition. When the resolver
-produces a wrapper FluentNode, ComposingLookup creates the inner instance
-first, then wraps it. Supports recursive unwrapping for nested wrappers.
-
-```php
-$nested = new ComposingLookup($lookup);  // defaults to ComposableAttributes
-$nested->create('notEmail');             // Not(Email())
-```
-
-You can pass a custom resolver as the second argument if you don't want
-automatic `#[Composable]` attribute discovery:
-
-```php
-$nested = new ComposingLookup($lookup, new ComposableMap(
-    composable: ['not' => true],
-));
-```
-
-### FluentResolver
+    #[AssuranceAssertion]
+    public function assert(#[AssuranceParameter] mixed $input): void { /* ... */ }
 
-Interface for name transformers. Each resolver can `resolve` a method name
-into a class name, and `unresolve` it back:
-
-```php
-interface FluentResolver
-{
-    public function resolve(FluentNode $nodeSpec): FluentNode;
-    public function unresolve(FluentNode $nodeSpec): FluentNode;
-}
-```
-
-The `unresolve` method is the inverse of `resolve`: it converts a class name
-back to the method name that would produce it. This is used by FluentAnalysis
-to derive method maps from discovered classes.
-
-#### Ucfirst
-
-Capitalizes the first letter: `'email'` → `'Email'`.
-Unresolve does the opposite: `'Email'` → `'email'`.
-
-#### Suffix
-
-Strips a prefix and appends a suffix: `Suffix('of', 'Handler')` turns
-`'ofArray'` → `'ArrayHandler'`.
-Unresolve reverses it: `'ArrayHandler'` → `'ofArray'`.
-
-#### Composable (attribute)
-
-A PHP attribute that marks a class as a prefix wrapper for composition.
-Constraints (`without`, `with`, `optIn`) are enforced at resolve time:
-
-```php
-#[Composable('not', without: ['not'])]  // prevents notNot()
-final readonly class Not implements Validator
-{
-    public function __construct(private Validator $validator) {}
+    #[AssuranceAssertion]
+    public function isValid(#[AssuranceParameter] mixed $input): bool { /* ... */ }
 }
 ```
 
-Attribute properties:
-
-| Property          | Type     | Purpose                                         |
-|-------------------|----------|-------------------------------------------------|
-| `prefix`          | `string` | Registers this class as a composition prefix    |
-| `prefixParameter` | `bool`   | First argument goes to the wrapper              |
-| `optIn`           | `bool`   | Only compose with prefixes listed in `with`     |
-| `without`         | `array`  | Prefixes this class should not be composed with |
-| `with`            | `array`  | Prefixes this class should be composed with     |
-
-#### ComposableAttributes
-
-Discovers `#[Composable]` attributes at runtime and decomposes prefixed names:
-`'notEmail'` → `FluentNode('Email', wrapper: FluentNode('Not'))`.
-
-```php
-$resolver = new ComposableAttributes($lookup);
-```
-
-Caches prefix discoveries, suffix constraints, and negative lookups for
-performance. Unresolve flattens wrapper structures back to flat names.
-
-#### ComposableMap
-
-Pre-built resolver using a compiled prefix map instead of runtime discovery.
-Useful for code-generated setups where all prefixes are known ahead of time:
-
-```php
-$resolver = new ComposableMap(
-    composable: ['not' => true, 'nullOr' => true],
-    composableWithArgument: ['key' => true],
-    forbidden: ['Not' => ['not' => true]],  // suffix => [prefix => true]
-);
-```
-
-### FluentNode
-
-Readonly data class carrying resolution state:
-
-```php
-new FluentNode(
-    name: 'Email',
-    arguments: ['strict' => true],
-    wrapper: new FluentNode('Not'),  // optional
-);
-```
-
-### Exceptions
-
-All exceptions implement `FluentException` (a `Throwable` marker interface),
-so you can catch all Fluent errors with a single type:
-
-```php
-use Respect\Fluent\Exceptions\FluentException;
+See `Assurance`, `AssuranceParameter`, `ComposableParameter`, and the enum
+types in the [API reference](docs/api.md#assurance) for the full set of options.
 
-try {
-    $factory->create('nonExistent');
-} catch (FluentException $e) {
-    // ...
-}
-```
-
-| Exception         | Parent                     | Thrown when                                    |
-|-------------------|----------------------------|------------------------------------------------|
-| `CouldNotResolve` | `InvalidArgumentException` | Name not found in any registered namespace     |
-| `CouldNotCreate`  | `InvalidArgumentException` | Instantiation failed or type validation failed |
+## API Reference
 
-Both extend `InvalidArgumentException` for backwards compatibility.
+See [docs/api.md](docs/api.md) for the complete API reference covering
+attributes, builders, factories, resolvers, and exceptions.