pico-ioc 1.4.0__tar.gz → 1.5.0__tar.gz

{pico_ioc-1.4.0 → pico_ioc-1.5.0}/.llm/ARCHITECTURE.md

@@ -7,7 +7,7 @@
 
 ---
 
-## 1\) Design goals & non-goals
+## 1) Design goals & non-goals
 
 ### Goals
 
@@ -25,12 +25,12 @@
 
 ---
 
-## 2\) High-level model
+## 2) High-level model
 
   - **Component** → class marked with `@component`. Instantiated by the container.
   - **Config Component** → class marked with `@config_component`. Instantiated and populated from external sources like files or environment variables.
   - **Factory component** → class marked with `@factory_component`; owns provider methods via `@provides(key=TypeOrToken)`. Providers return *externals* (e.g., `Flask`, DB clients).
-  - **Interceptor** → class or function marked with `@interceptor`. Discovered automatically to apply cross-cutting logic.
+  - **Infrastructure** → class marked with `@infrastructure`. Discovered automatically to apply cross-cutting logic, such as registering interceptors.
   - **Container** → built by `pico_ioc.init(mod_or_list, ...)`; resolve with `container.get(KeyOrType)`.
 
 ### Bootstrap sequence
@@ -41,9 +41,9 @@ sequenceDiagram
     participant IOC as pico-ioc Container
     App->>IOC: init(packages, config, ...)
     IOC->>IOC: Create ConfigRegistry from sources
-    IOC->>App: scan decorators (@component, @config_component, @interceptor)
-    IOC->>IOC: register providers and collect interceptor declarations
-    IOC->>IOC: build and activate interceptors
+    IOC->>App: scan decorators (@component, @config_component, @infrastructure)
+    IOC->>IOC: register providers and collect infrastructure declarations
+    IOC->>IOC: build and activate infrastructure (which registers interceptors)
     IOC->>IOC: apply policy (e.g., @primary, @on_missing aliases)
     IOC->>IOC: apply overrides (replace providers/constants)
     IOC->>IOC: instantiate eager components
@@ -61,7 +61,7 @@ sequenceDiagram
       * `@component` classes → registered by a **key** (defaults to the class type).
       * `@config_component` classes → registered as special components whose instances are built from external configuration sources.
       * `@factory_component` classes → introspected for `@provides(key=...)` methods.
-      * `@interceptor` classes/functions → collected for activation.
+      * `@infrastructure` classes → collected for activation.
       * `@plugin` classes → if explicitly passed via `init(..., plugins=(...))`.
 3.  **Registry** (frozen after bootstrap):
       * Map **key → provider**. Keys are typically **types**; string tokens are also supported.
@@ -217,8 +217,8 @@ The policy engine respects definition order. While not a strict "last-wins", pro
 
 ```python
 c = init(app, overrides={
-    Repo: FakeRepo(),                      # constant instance
-    "fast_model": lambda: {"mock": True},  # provider
+    Repo: FakeRepo(),                  # constant instance
+    "fast_model": lambda: {"mock": True}, # provider
     "expensive": (lambda: object(), True), # provider with lazy=True
 })
 ```
@@ -230,31 +230,44 @@ c = init(app, overrides={
       * `key: instance`
       * `key: callable`
       * `key: (callable, lazy_bool)`
-  * With `reuse=True`, re-calling `init(..., overrides=...)` applies new overrides to the cached container.
+  * With `reuse=True`, re-calling `init()` with different `overrides` will create a new container, not mutate a cached one, as the configuration fingerprint changes.
 
 ---
 
 ## 11\) Interceptors (AOP & Lifecycle Hooks)
 
-Interceptors are components that apply cross-cutting logic like logging, metrics, or policy enforcement. They are discovered automatically via the `@interceptor` decorator.
+Interceptors apply cross-cutting logic like logging, metrics, or policy enforcement. They are **not discovered automatically**. Instead, they must be registered by an `@infrastructure` component during the container's bootstrap phase.
 
-`pico-ioc` supports two kinds of interceptors:
+This is a two-step process:
+
+1.  **Define the Interceptor**: Create a class that implements the `MethodInterceptor` or `ContainerInterceptor` protocol.
+2.  **Register it via an Infrastructure Component**: Create a class decorated with `@infrastructure` and use the `infra.intercept.add()` method inside its `configure` function to activate the interceptor and define which components it applies to.
 
 ### Method Interceptors
 
 These implement the `MethodInterceptor` protocol and wrap method calls on any component, enabling Aspect-Oriented Programming (AOP). They are ideal for tracing, timing, caching, or feature toggles.
 
 ```python
-from pico_ioc import interceptor
-from pico_ioc.interceptors import MethodInterceptor, Invocation
+from pico_ioc import infrastructure
+from pico_ioc.infra import Infra, Select
+from pico_ioc.interceptors import MethodInterceptor, MethodCtx
 
-@interceptor(order=-10) # lower order runs first
+# 1. Define the Interceptor
 class LoggingInterceptor(MethodInterceptor):
-    def __call__(self, inv: Invocation, proceed):
-        print(f"Calling {inv.method_name}...")
-        result = proceed()
-        print(f"Finished {inv.method_name}.")
+    def invoke(self, ctx: MethodCtx, call_next):
+        print(f"Calling {ctx.name}...")
+        result = call_next(ctx)
+        print(f"Finished {ctx.name}.")
         return result
+
+# 2. Register it
+@infrastructure
+class MyInfra:
+    def configure(self, infra: Infra):
+        infra.intercept.add(
+            interceptor=LoggingInterceptor(),
+            where=Select().class_name(".*") # Apply to all components
+        )
 ```
 
 ### Container Interceptors
@@ -263,12 +276,8 @@ These implement the `ContainerInterceptor` protocol and hook into the container'
 
 **Hook points**:
 
-  * `on_resolve(key, annotation, qualifiers)`
-  * `on_before_create(key)`
-  * `on_after_create(key, instance)` → may return a **wrapped/replaced** instance.
-  * `on_exception(key, exc)`
-
-**Registration:** Interceptors are discovered by the scanner during `init()` or `scope()`. There is no need to pass them manually. Their activation can be controlled with the same `@conditional` decorator and gates (`profiles`, `require_env`) used for other components.
+  * `around_resolve(self, ctx: ResolveCtx, call_next)`: Wraps the dependency resolution process for a specific key.
+  * `around_create(self, ctx: CreateCtx, call_next)`: Wraps the instantiation of a component. It can modify the provider or even return a completely different instance.
 
 ---
 
@@ -324,7 +333,7 @@ This preserves registration order and returns a stable list.
   * `before_eager(container, binder)`
   * `after_ready(container, binder)`
 
-Plugins are passed **explicitly** via `init(..., plugins=(MyPlugin(),))`. Prefer **interceptors** for fine-grained wiring events; use **plugins** for coarse lifecycle integration.
+Plugins are passed **explicitly** via `init(..., plugins=(MyPlugin(),))`. Prefer **infrastructure** for fine-grained wiring events; use **plugins** for coarse lifecycle integration.
 
 ---
 
@@ -384,13 +393,11 @@ classDiagram
       + qualifiers: tuple
     }
     class MethodInterceptor {
-      +__call__(inv, proceed)
+      +invoke(ctx, call_next)
     }
     class ContainerInterceptor {
-      +on_resolve()
-      +on_before_create()
-      +on_after_create()
-      +on_exception()
+      +around_resolve(ctx, call_next)
+      +around_create(ctx, call_next)
     }
     PicoContainer "1" o-- "*" MethodInterceptor
     PicoContainer "1" o-- "*" ContainerInterceptor
@@ -403,11 +410,11 @@ flowchart TD
     A[get(Type T)] --> B{Cached?}
     B -- yes --> Z[Return cached instance]
     B -- no --> D[Resolve dependencies for T (recurse)]
-    D --> I_BEFORE[ContainerInterceptors: on_before_create]
+    D --> I_BEFORE[ContainerInterceptors: around_create]
     I_BEFORE --> F[Instantiate T]
-    F -- exception --> I_EXC[ContainerInterceptors: on_exception]
+    F -- exception --> I_EXC[Error bubbles up]
     F -- success --> H[Wrap with MethodInterceptors if needed]
-    H --> I_AFTER[ContainerInterceptors: on_after_create]
+    H --> I_AFTER[around_create returns instance]
     I_AFTER --> G[Cache instance]
     G --> Z
 ```
@@ -420,9 +427,11 @@ flowchart TD
   * **Singleton-per-container**: matches typical Python app composition; simpler mental model.
   * **Explicit decorators**: determinism and debuggability over magical auto-wiring.
   * **Fail fast**: configuration and graph issues surface at startup, not mid-request.
-  * **Interceptors over AOP**: precise, opt-in hooks without full-blown aspect weavers.
+  * **Interceptors via Infrastructure**: precise, opt-in hooks without the complexity of auto-discovery.
 
 ---
 
 **TL;DR**
-`pico-ioc` builds a **deterministic, typed dependency graph** from decorated components, factories, and interceptors. It resolves by **type** (with qualifiers and collections), memoizes **singletons**, supports **type-safe configuration injection**, **overrides**, **plugins**, **conditionals/profiles**, and **scoped subgraphs**—keeping wiring **predictable, testable, and framework-agnostic**.
+`pico-ioc` builds a **deterministic, typed dependency graph** from decorated components, factories, and infrastructure. It resolves by **type** (with qualifiers and collections), memoizes **singletons**, supports **type-safe configuration injection**, **overrides**, **plugins**, **conditionals/profiles**, and **scoped subgraphs**—keeping wiring **predictable, testable, and framework-agnostic**.
+
+

{pico_ioc-1.4.0 → pico_ioc-1.5.0}/.llm/DECISIONS.md

@@ -72,7 +72,7 @@ Each entry includes a rationale and implications. If a decision is later changed
   - `key: instance` (constant)  
   - `key: callable` (provider, non-lazy)  
   - `key: (callable, lazy_bool)` (provider with explicit laziness)  
-- With `reuse=True`, subsequent `init(..., overrides=...)` mutates cached bindings.
+- If `reuse=True`, calling `init()` with different `overrides` will generate a new fingerprint and build a new container, not mutate the cached one.
 
 ---
 
@@ -87,20 +87,17 @@ Each entry includes a rationale and implications. If a decision is later changed
 
 ---
 
-### 11) **Interceptors API** (AOP & Lifecycle Hooks)
-**Decision**: Introduce two types of interceptors, auto-discovered via `@interceptor`, to observe or modify container and component behavior.
+### 11) **Infrastructure-based Interceptor API**
+**Decision**: Provide an extension mechanism for AOP and lifecycle hooks through **manually registered interceptors**. Instead of auto-discovery, interceptors are activated within `@infrastructure` components, giving developers explicit control over their application and order.
 **Kinds & Hooks**:
-- **`MethodInterceptor`**: Implements `__call__(self, inv: Invocation, proceed)`. Wraps method calls on components for Aspect-Oriented Programming (AOP) use cases like logging, tracing, or caching.
+- **`MethodInterceptor`**: Implements `invoke(self, ctx: MethodCtx, call_next)`. Wraps method calls on components for Aspect-Oriented Programming (AOP).
 - **`ContainerInterceptor`**: Implements container lifecycle hooks:
-    - `on_resolve(key, annotation, qualifiers)`
-    - `on_before_create(key)`
-    - `on_after_create(key, instance)` (may wrap/replace the instance)
-    - `on_exception(key, exc)`
-**Rationale**: Provides structured extension points for both cross-cutting concerns (AOP) and container lifecycle events without the complexity of full aspect weavers.
+    - `around_resolve(self, ctx: ResolveCtx, call_next)`
+    - `around_create(self, ctx: CreateCtx, call_next)`
+**Rationale**: This approach is more explicit and predictable than magic auto-discovery. It makes the wiring process easier to debug and ensures that the order of interceptors is controlled by the developer via the `order` parameter in `@infrastructure`.
 **Implications**:
-- Deterministic ordering via `order` (lower runs first).
-- Auto-registered via `@interceptor(...)` on classes or provider methods.
-- `on_exception` must re-raise if the error is not meant to be suppressed.
+- Interceptors are plain Python classes that implement a protocol; they do not require a decorator.
+- Their activation is tied to the lifecycle of the `@infrastructure` components that register them.
 
 ---
 
@@ -142,6 +139,21 @@ A true "last-wins" only occurs when binding the *exact same key* multiple times,
 
 ---
 
+### 16) Container Diagnostics API (`describe()`)
+
+**Decision**: Add a unified diagnostics method `container.describe(...)` that exports the initialization context, active interceptors, and the fully resolved dependency graph.  
+**Rationale**: Developers need a deterministic way to introspect the container state for debugging, documentation, and architectural analysis. A stable schema with IDs, provenance, and safe redaction makes this reliable and auditable.  
+**Implications**:
+- Public API: `container.describe(include_values=False, include_inactive=False, only_types=None, only_tags=None, redact_patterns=None, format="dict")`.
+- Default output is JSON-serializable with `schema_version`, `generated_at`, `status`, `initialization_context`, `active_interceptors`, and `dependency_graph`.
+- Sensitive values are **redacted by default**; explicit opt-in required via `include_values=True`.
+- Deterministic IDs and ordering allow snapshot diffs across runs.
+- Alternative outputs supported (`mermaid`, `dot`) for visualization.
+- Large graphs can be filtered (`only_types`, `only_tags`) to keep snapshots manageable.
+- Partial snapshots with `status="partial"` are returned if initialization fails, including error metadata.
+
+---
+
 ## ❌ Won’t-Do Decisions
 
 ### A) Alternative scopes (request/session)
@@ -176,10 +188,10 @@ _No entries currently._
 - **2025-08**: Minimum Python 3.10; name-first resolution; fail-fast clarified; typed keys preferred.  
 - **2025-09-08**: Introduced `init(..., overrides)` with defined precedence and laziness semantics.  
 - **2025-09-13**: Added `scope(...)` for bounded containers with tag pruning and strict mode.  
-- **2025-09-14**: Added **Interceptors API** and **Conditional providers** as first-class features; documented last-wins registration and concurrency stance.
+- **2025-09-14**: Replaced auto-discovered interceptors with an infrastructure-based registration model. Added **Conditional providers** as a first-class feature.
 
 ---
 
 **Summary**: pico-ioc remains **simple, deterministic, and fail-fast**.  
-We favor typed wiring, explicit registration, and small, composable primitives (overrides, scope, interceptors, conditionals) instead of heavyweight AOP or multi-scope lifecycles.
+We favor typed wiring, explicit registration, and small, composable primitives (overrides, scope, infrastructure, conditionals) instead of heavyweight AOP or multi-scope lifecycles.
 

pico_ioc-1.5.0/.llm/FEATURES/FEATURE-2025-0001-scope-subgraphs.md

@@ -0,0 +1,151 @@
+# FEATURE-2025-0001: Scoped Subgraphs with scope()
+
+  - **Date:** 2025-09-13
+  - **Status:** Delivered
+  - **Priority:** high
+  - **Related:** [ADR-0008: Lightweight Test Containers]
+
+-----
+
+## 1\) Summary
+
+This feature introduces `pico_ioc.scope()`, a powerful factory function for creating lightweight, temporary containers limited to a specific dependency subgraph. By defining one or more `roots`, the container will only include components and services required by those roots. This is extremely useful for fast, isolated unit and integration tests, as well as for CLI tools or serverless functions that only need a subset of the application's full dependency graph.
+
+-----
+
+## 2\) Goals
+
+  - To provide a mechanism for creating minimal IoC containers for testing or specialized tasks.
+  - To drastically reduce the overhead and complexity of bootstrapping the full application graph for a limited use case.
+  - To improve test performance by only scanning and instantiating necessary components.
+  - To allow fine-grained graph pruning through tag-based filtering.
+
+-----
+
+## 3\) Non-Goals
+
+  - `scope()` does not introduce new lifecycle scopes (like "request" or "session"). Components are still singletons within the created container.
+  - It is not intended to replace the main `pico_ioc.init()` for bootstrapping the full application.
+
+-----
+
+## 4\) User Impact / Stories (Given/When/Then)
+
+  - **Story 1: Isolated Service Test**
+
+      - **Given** a developer wants to test `RunnerService`, which depends on `Repo` but not on `WebService`.
+      - **When** they create a container with `scope(modules=["my_app"], roots=[RunnerService])`.
+      - **Then** the container contains `RunnerService` and `Repo`, but not `WebService`, making the test setup faster and more focused.
+
+  - **Story 2: Mocking Dependencies in a Test**
+
+      - **Given** a developer is testing a service that depends on an external `DockerClient`.
+      - **When** they use `scope(..., roots=[MyService], overrides={"docker.DockerClient": FakeDocker()})`.
+      - **Then** the `MyService` instance they retrieve from the container is injected with the `FakeDocker` mock instead of the real one.
+
+  - **Story 3: Pruning a Subgraph with Tags**
+
+      - **Given** an application has multiple `Notifier` implementations tagged with `"email"` or `"sms"`.
+      - **When** a developer builds a scope for a specific task using `scope(..., include_tags={"sms"})`.
+      - **Then** only the `SmsNotifier` and its dependencies are included in the graph, while the `EmailNotifier` is excluded.
+
+-----
+
+## 5\) Scope & Acceptance Criteria
+
+  - **In scope:**
+      - `pico_ioc.scope()` function with `modules`, `roots`, `overrides`, `strict`, `lazy`, `include_tags`, and `exclude_tags` parameters.
+      - Graph traversal logic to compute the dependency subgraph from the given roots.
+      - Tag filtering logic to prune providers before graph traversal.
+      - Support for use as a context manager.
+  - **Out of scope:**
+      - Runtime modification of a created scope.
+  - **Acceptance:**
+      - [x] A container created with `scope()` only contains providers transitively reachable from the specified `roots`.
+      - [x] The `overrides` parameter correctly replaces providers within the subgraph.
+      - [x] `strict=True` raises a `NameError` if a dependency cannot be found within the subgraph.
+      - [x] `include_tags` and `exclude_tags` correctly filter the set of available providers before the subgraph is calculated.
+      - [x] The `scope()` function works correctly when used as a `with` statement context manager.
+
+-----
+
+## 6\) API / UX Contract
+
+The feature is exposed through the `pico_ioc.scope()` function:
+
+```python
+def scope(
+    *,
+    modules: Iterable[Any] = (),
+    roots: Iterable[type] = (),
+    overrides: Optional[Dict[Any, Any]] = None,
+    strict: bool = True,
+    lazy: bool = True,
+    include_tags: Optional[set[str]] = None,
+    exclude_tags: Optional[set[str]] = None,
+) -> PicoContainer:
+    # ...
+```
+
+**Example:**
+
+```python
+# In a test file
+from pico_ioc import scope
+from src.runner_service import RunnerService
+from tests.fakes import FakeDocker
+import src
+
+def test_runner_in_isolation():
+    # Create a container with only what RunnerService needs
+    with scope(
+        modules=[src],
+        roots=[RunnerService],
+        overrides={"docker.DockerClient": FakeDocker()},
+        strict=True,
+    ) as container:
+        service = container.get(RunnerService)
+        # ... assertions
+```
+
+-----
+
+## 7\) Rollout & Guardrails
+
+  - The feature was shipped as a new, non-breaking minor feature in version **1.2.0**.
+  - It is fully backward-compatible and does not affect the existing `init()` function.
+
+-----
+
+## 8\) Telemetry
+
+  - The `pico-ioc` builder logs at the `INFO` level when a scope container is ready, which can be useful for debugging test setups.
+
+-----
+
+## 9\) Risks & Open Questions
+
+  - **Risk:** Developers might misunderstand `scope()` as a lifecycle feature (e.g., request scope) rather than a container construction tool.
+      - **Mitigation:** The documentation explicitly states that components are still singletons within the scope and that `scope()` is primarily for testing and specialized tasks.
+
+-----
+
+## 10\) Test Strategy
+
+  - **Unit Tests:** The graph traversal algorithm (`_compute_allowed_subgraph`) and tag filtering logic are unit-tested.
+  - **Integration Tests:** End-to-end tests verify that `scope()` correctly builds containers for various scenarios, including complex dependency chains, overrides, and strict mode enforcement.
+
+-----
+
+## 11\) Milestones
+
+  - **M1 Ready:** 2025-09-12 - Scope defined and accepted.
+  - **M2 Planned:** 2025-09-12 - Implementation started.
+  - **M3 Shipped:** 2025-09-13 - Feature merged, tested, and released in v1.2.0.
+
+-----
+
+## 12\) Documentation Impact
+
+  - The feature is documented in `GUIDE.md`, `ARCHITECTURE.md`, `DECISIONS.md`, `CHANGELOG.md`, `README.md`, and `OVERVIEW.md`.
+  - Practical examples for testing are included in the main user guide.

pico_ioc-1.5.0/.llm/FEATURES/FEATURE-2025-0003-interceptor-auto-registration.md

@@ -0,0 +1,148 @@
+# FEATURE-2025-0002: Interceptor Auto-Registration and Conditional Providers
+
+  - **Date:** 2025-09-14
+  - **Status:** Removed
+  - **Priority:** high
+  - **Related:** [ADR-0006: Declarative Cross-Cutting Concerns],[FEATURE-2025-0006]
+
+-----
+
+## 1\) Summary
+
+This feature introduces the `@interceptor` decorator to automatically discover, instantiate, and activate interceptors, simplifying how cross-cutting concerns like logging or transactions are applied. Additionally, it introduces the `@conditional` decorator, allowing any component (including interceptors) to be activated based on profiles, environment variables, or custom logic predicates. This enhances both the extensibility and environment-specific configuration of the container.
+
+-----
+
+## 2\) Goals
+
+  - To automate the discovery and registration of both `MethodInterceptor` and `ContainerInterceptor` implementations.
+  - To allow developers to define interceptors alongside their business logic, improving modularity.
+  - To provide a mechanism (`@conditional`) for activating or deactivating any component based on external factors without code changes.
+  - To support metadata for interceptor ordering (`order`) and conditional activation (`profiles`, etc.).
+
+-----
+
+## 3\) Non-Goals
+
+  - This feature does not change the underlying `MethodInterceptor` or `ContainerInterceptor` protocols.
+  - It does not introduce a complex Aspect-Oriented Programming (AOP) model beyond method interception.
+
+-----
+
+## 4\) User Impact / Stories (Given/When/Then)
+
+  - **Story 1: Automatic Logging Interceptor**
+
+      - **Given** a developer writes a `LoggingInterceptor` class that implements `MethodInterceptor`.
+      - **When** they decorate the class with `@interceptor`.
+      - **Then** all component method calls are automatically intercepted and logged without any manual registration code.
+
+  - **Story 2: Environment-Specific Component**
+
+      - **Given** an `InMemoryCache` component should only be used for local development and testing.
+      - **When** the developer decorates it with `@conditional(profiles=["dev", "test"])`.
+      - **Then** the `InMemoryCache` is only active when the container is initialized with the "dev" or "test" profile, and a `RedisCache` marked with `@conditional(profiles=["prod"])` can be used in production.
+
+  - **Story 3: Controlling Interceptor Order**
+
+      - **Given** a developer has a `TimingInterceptor` and a `SecurityInterceptor`.
+      - **When** they decorate them with `@interceptor(order=10)` and `@interceptor(order=20)` respectively.
+      - **Then** the `TimingInterceptor` will wrap the `SecurityInterceptor`, ensuring the total execution time is measured correctly.
+
+-----
+
+## 5\) Scope & Acceptance Criteria
+
+  - **In scope:**
+      - `@interceptor` decorator with `kind`, `order`, and conditional parameters.
+      - `@conditional` decorator with `profiles`, `require_env`, and `predicate` parameters.
+      - Integration with the scanner to discover these decorators on classes, methods, and functions.
+      - Integration with the builder to instantiate and register active interceptors.
+      - Integration with the policy engine to filter out inactive conditional components.
+  - **Out of scope:**
+      - Pointcut expressions or more advanced AOP features.
+  - **Acceptance:**
+      - [x] The scanner correctly identifies classes and functions decorated with `@interceptor`.
+      - [x] The builder correctly instantiates interceptors, injecting their dependencies.
+      - [x] The `order` parameter correctly influences the interceptor chain.
+      - [x] Components decorated with `@conditional` are only registered if their conditions (profiles, env vars, predicate) are met.
+      - [x] An inactive component causes a `NameError` at bootstrap if it's a required dependency for an eager component.
+
+-----
+
+## 6\) API / UX Contract
+
+The feature introduces the following public APIs:
+
+  - **Decorators:** `pico_ioc.interceptor(...)`, `pico_ioc.conditional(...)`
+
+**Example (Interceptor):**
+
+```python
+from pico_ioc import interceptor, component
+from pico_ioc.interceptors import MethodInterceptor, Invocation
+import time
+
+# Before: No standard mechanism for registration.
+
+# After: Simple, declarative, and auto-discovered.
+@interceptor(order=-100)
+class TimingInterceptor(MethodInterceptor):
+    def __call__(self, inv: Invocation, proceed):
+        start = time.time()
+        result = proceed()
+        duration = time.time() - start
+        print(f"{inv.method_name} took {duration:.2f}s")
+        return result
+
+@component
+class MyService:
+    def do_work(self):
+        time.sleep(1)
+
+# In main.py, `init("my_app")` is enough. The interceptor is found and applied.
+```
+
+-----
+
+## 7\) Rollout & Guardrails
+
+  - The feature was shipped as a new, non-breaking minor feature in version **1.3.0**.
+  - It is fully backward-compatible. Existing components without these decorators are unaffected.
+
+-----
+
+## 8\) Telemetry
+
+  - The `pico-ioc` builder logs at the `DEBUG` level which interceptors are activated and which are skipped due to conditional rules, aiding in diagnostics.
+
+-----
+
+## 9\) Risks & Open Questions
+
+  - **Risk:** The interaction between multiple conditionals or complex predicates could be confusing for users.
+      - **Mitigation:** The documentation provides clear examples for each conditional type and emphasizes the fail-fast nature of the container if a required dependency becomes inactive.
+
+-----
+
+## 10\) Test Strategy
+
+  - **Unit Tests:** The `@interceptor` and `@conditional` decorators are tested to ensure they attach the correct metadata.
+  - **Integration Tests:** Scenarios verify that the scanner, builder, and policy engine work together to activate/deactivate components and interceptors based on profiles and environment variables. Tests for interceptor ordering are included.
+
+-----
+
+## 11\) Milestones
+
+  - **M1 Ready:** 2025-09-13 - Scope defined and accepted.
+  - **M2 Planned:** 2025-09-13 - Implementation started.
+  - **M3 Shipped:** 2025-09-14 - Feature merged, tested, and released in v1.3.0.
+
+-----
+
+## 12\) Documentation Impact
+
+The following documents were created or updated:
+
+  - **Created:** `GUIDE_CREATING_PLUGINS_AND_INTERCEPTORS.md`
+  - **Updated:** `ARCHITECTURE.md`, `DECISIONS.md`, `GUIDE.md`, `CHANGELOG.md`, `README.md`, `OVERVIEW.md`