Add Assurance subject/exactness model for IDE type narrowing

Extend the #[Assurance] vocabulary so consumers (FluentGen, FluentAnalysis)
can derive how a composable prefix transforms the wrapped node's assured type:

- Add #[AssuranceSubject] with AssuranceSubjectMode (Wrap / Elements / Container)
  describing whether a prefix wraps, iterates, or derives the subject.
- Add the `exact` flag to #[Assurance]; remove AssuranceModifier::Nullable, now
  expressed as AssuranceSubject(Wrap) + type: 'null'. This is a BC break (3.0).
- Thread a TExact template through the fluent builders for analyzer state.
- Correct the README composition claim: prefix resolution is single-level.

Author: alganet

.gitattributes

@@ -0,0 +1,12 @@
+/* export-ignore
+
+# Project files
+/README.md -export-ignore
+/composer.json -export-ignore
+/docs -export-ignore
+/src -export-ignore
+
+# SBOM information
+/LICENSE -export-ignore
+/LICENSES -export-ignore
+/REUSE.toml -export-ignore

README.md

@@ -178,15 +178,18 @@ a name, constructor arguments, and an optional wrapper.
 
 **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.
+composition like `notEmail()` → `Not(Email())`. Composition resolves a single
+prefix level (e.g. `notEmail`, `nullOrEmail`); deeper nesting such as
+`notNullOrEmail` is not decomposed.
 
 ## Assurance attributes
 
 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]`.
+`#[ComposableParameter]`. Composable prefixes declare how they relate to the
+wrapped node's subject with `#[AssuranceSubject]` (`Wrap`, `Elements`, or
+`Container`).
 
 This metadata is available at runtime through reflection and is also consumed
 by tools like [FluentAnalysis](https://github.com/Respect/FluentAnalysis)

composer.json

@@ -47,5 +47,10 @@
         "allow-plugins": {
             "dealerdirect/phpcodesniffer-composer-installer": true
         }
+    },
+    "extra": {
+        "branch-alias": {
+            "dev-ide-narrowing": "3.0.x-dev"
+        }
     }
 }

docs/api.md

@@ -346,24 +346,32 @@ final readonly class When implements Validator
     public function __construct(Validator $when, Validator $then, Validator $else) {}
 }
 
-// Modifier: exclude type instead of asserting it
+// Exact: passes if and only if the input is of the declared type
+#[Assurance(type: 'int', exact: true)]
+final readonly class IntType implements Validator { /* ... */ }
+
+// Modifier on a Wrap prefix: negate the wrapped node's assurance
 #[Assurance(modifier: AssuranceModifier::Exclude)]
+#[AssuranceSubject(AssuranceSubjectMode::Wrap)]
 final readonly class Not implements Validator { /* ... */ }
 
-// Modifier: add null to the assured type
-#[Assurance(modifier: AssuranceModifier::Nullable)]
+// Bypass set on a Wrap prefix: 'null' is admitted in union with the
+// wrapped node's assurance (nullOrIntType() assures int|null)
+#[Assurance(type: 'null', exact: true)]
+#[AssuranceSubject(AssuranceSubjectMode::Wrap)]
 final readonly class NullOr implements Validator { /* ... */ }
 ```
 
 Properties:
 
-| Property       | Type                     | Purpose                                                          |
-|----------------|--------------------------|------------------------------------------------------------------|
-| `type`         | `?string`                | Fixed type string (e.g. `'int'`, `'string'`)                     |
-| `from`         | `?AssuranceFrom`         | Derive type from a method argument                               |
-| `compose`      | `?AssuranceCompose`      | Combine assurances from child validators                         |
-| `composeRange` | `?array{int, int\|null}` | Subset of arguments to compose (`[from, to]`, null = open-ended) |
-| `modifier`     | `?AssuranceModifier`     | Modify how the assurance is applied                              |
+| Property       | Type                         | Purpose                                                          |
+|----------------|------------------------------|------------------------------------------------------------------|
+| `type`         | `string\|list<string>\|null` | Fixed type string (e.g. `'int'`); a list means their union       |
+| `from`         | `?AssuranceFrom`             | Derive type from a method argument                               |
+| `compose`      | `?AssuranceCompose`          | Combine assurances from child validators                         |
+| `composeRange` | `?array{int, int\|null}`     | Subset of arguments to compose (`[from, to]`, null = open-ended) |
+| `modifier`     | `?AssuranceModifier`         | Modify how the assurance is applied                              |
+| `exact`        | `bool`                       | The node passes *iff* the input is of the declared type          |
 
 ### AssuranceFrom (enum)
 
@@ -388,7 +396,37 @@ Determines how child assurances are combined:
 
 Modifies how an assurance is applied:
 
-| Case       | Meaning                                  |
-|------------|------------------------------------------|
-| `Exclude`  | Removes the type instead of asserting it |
-| `Nullable` | Adds `null` to the assured type          |
+| Case      | Meaning                                                               |
+|-----------|-----------------------------------------------------------------------|
+| `Exclude` | The wrapped node's assurance is negated: passing implies NOT the type |
+
+### AssuranceSubject
+
+Declares how a `#[Composable]` prefix relates to its wrapped node's subject.
+A prefix without it yields no assurance for composed names: tools must drop,
+not copy, the wrapped node's assurance.
+
+```php
+// Same subject, modified: notEmail() negates Email's assurance
+#[Assurance(modifier: AssuranceModifier::Exclude)]
+#[AssuranceSubject(AssuranceSubjectMode::Wrap)]
+final readonly class Not implements Validator { /* ... */ }
+
+// Derived subject: keyEmail('name') assures only the container type
+#[Assurance(type: ['array', 'ArrayAccess'])]
+#[AssuranceSubject(AssuranceSubjectMode::Container)]
+final readonly class Key implements Validator { /* ... */ }
+```
+
+### AssuranceSubjectMode (enum)
+
+| Case        | Meaning                                                                          |
+|-------------|----------------------------------------------------------------------------------|
+| `Wrap`      | Same subject as the wrapped node: its assurance passes through, modified         |
+| `Elements`  | The wrapped node validates each element: assurance becomes `iterable<T>`         |
+| `Container` | The wrapped node validates a derived subject: only the container type is assured |
+
+A `Wrap` prefix's own `#[Assurance(type:)]` declares its *bypass set*: inputs
+it admits itself, in union with whatever the wrapped node assures. It is only
+meaningful in composition, never as a claim about direct calls; `exact` on it
+means the bypass set is an exact characterization.

src/Attributes/Assurance.php

@@ -25,6 +25,7 @@ public function __construct(
         public AssuranceCompose|null $compose = null,
         public array|null $composeRange = null,
         public AssuranceModifier|null $modifier = null,
+        public bool $exact = false,
     ) {
     }
 }

src/Attributes/AssuranceModifier.php

@@ -12,6 +12,6 @@
 
 enum AssuranceModifier: string
 {
+    /** The wrapped node's assurance is negated: passing implies NOT the type */
     case Exclude = 'exclude';
-    case Nullable = 'nullable';
 }

src/Attributes/AssuranceSubject.php

@@ -0,0 +1,30 @@
+<?php
+
+/*
+ * SPDX-License-Identifier: ISC
+ * SPDX-FileCopyrightText: (c) Respect Project Contributors
+ * SPDX-FileContributor: Alexandre Gomes Gaigalas <alganet@gmail.com>
+ */
+
+declare(strict_types=1);
+
+namespace Respect\Fluent\Attributes;
+
+use Attribute;
+
+/**
+ * Declares how a composable prefix relates to its wrapped node's subject.
+ *
+ * A prefix without this attribute yields no assurance for composed names:
+ * tools must drop, not copy, the wrapped node's assurance.
+ */
+#[Attribute(Attribute::TARGET_CLASS)]
+final readonly class AssuranceSubject
+{
+    /** @param string|list<string>|null $type Container type assured about the input */
+    public function __construct(
+        public AssuranceSubjectMode $mode,
+        public string|array|null $type = null,
+    ) {
+    }
+}

src/Attributes/AssuranceSubjectMode.php

@@ -0,0 +1,30 @@
+<?php
+
+/*
+ * SPDX-License-Identifier: ISC
+ * SPDX-FileCopyrightText: (c) Respect Project Contributors
+ * SPDX-FileContributor: Alexandre Gomes Gaigalas <alganet@gmail.com>
+ */
+
+declare(strict_types=1);
+
+namespace Respect\Fluent\Attributes;
+
+enum AssuranceSubjectMode: string
+{
+    /**
+     * Same subject as the wrapped node: its assurance passes through, modified.
+     *
+     * A Wrap prefix's own #[Assurance(type:)] declares its bypass set — inputs
+     * it admits itself, in union with whatever the wrapped node assures. It is
+     * only meaningful in composition, never as a claim about direct calls;
+     * `exact` on it means the bypass set is an exact characterization.
+     */
+    case Wrap = 'wrap';
+
+    /** The wrapped node validates each element: assurance becomes iterable<T> */
+    case Elements = 'elements';
+
+    /** The wrapped node validates a derived subject: only the container type is assured */
+    case Container = 'container';
+}

src/Builders/Append.php

@@ -12,7 +12,7 @@
 
 use function array_values;
 
-/** @extends FluentBuilder<list<object>, mixed, never> */
+/** @extends FluentBuilder<list<object>, mixed, never, true> */
 readonly class Append extends FluentBuilder
 {
     public function attach(object ...$nodes): static

src/Builders/FluentBuilder.php

@@ -20,6 +20,7 @@
  * @template TNodes of list<object>
  * @template TSure
  * @template TSureNot
+ * @template TExact of bool = true
  */
 abstract readonly class FluentBuilder
 {