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

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

@@ -5,9 +5,9 @@
 >
 > ⚠️ **Requires Python 3.10+** (uses `typing.Annotated` with `include_extras=True`).
 
------
+---
 
-## 1\) Design goals & non-goals
+## 1) Design goals & non-goals
 
 ### Goals
 
@@ -23,13 +23,14 @@
   - Hot reload or runtime graph mutation beyond explicit overrides.
   - Magical filesystem-wide auto-imports.
 
------
+---
 
-## 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
@@ -38,10 +39,11 @@
 sequenceDiagram
     participant App as Your package(s)
     participant IOC as pico-ioc Container
-    App->>IOC: init(packages, ...)
-    IOC->>App: scan decorators (@component, @factory_component, @interceptor)
-    IOC->>IOC: register providers and collect interceptor declarations
-    IOC->>IOC: build and activate interceptors
+    App->>IOC: init(packages, config, ...)
+    IOC->>IOC: Create ConfigRegistry from sources
+    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
@@ -50,22 +52,23 @@ sequenceDiagram
     IOC-->>App: instance(Service)
 ```
 
------
+---
 
 ## 3\) Discovery & registration
 
 1.  **Scan inputs** passed to `init(...)`: module or list of modules/packages.
 2.  **Collect**:
       * `@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.
 
 **Precedence:** If multiple providers are active for the same key (e.g., one with `@primary`, another regular), a deterministic policy is applied to choose the winner. Direct overrides are applied last, having the final say.
 
------
+---
 
 ## 4\) Resolution algorithm (deterministic)
 
@@ -94,7 +97,7 @@ If the constructor requests `list[T]` or `list[Annotated[T, Q]]`:
   * Registration order is preserved; no implicit sorting.
   * Returns an empty list if no matches.
 
------
+---
 
 ## 5\) Lifecycles & scopes
 
@@ -103,7 +106,7 @@ If the constructor requests `list[T]` or `list[Annotated[T, Q]]`:
 
 **Rationale:** Most Python app composition (config, clients, web apps) fits singleton-per-container; it’s simple and fast.
 
------
+---
 
 ## 6\) Factories & providers
 
@@ -127,7 +130,7 @@ Guidelines:
   * Providers should be **pure constructors** (no long-running work).
   * Prefer **typed keys** (e.g., `Flask`) over strings.
 
------
+---
 
 ## 7\) Concurrency model
 
@@ -135,7 +138,7 @@ Guidelines:
   * Caches & resolution are **thread/async safe** (internal isolation; no global singletons).
   * Instances you create **must** be safe for your usage patterns; the container cannot fix non-thread-safe libraries.
 
------
+---
 
 ## 8\) Error handling & diagnostics
 
@@ -147,22 +150,60 @@ Guidelines:
 
 **Tip:** Keep constructors **cheap**; push I/O to explicit start/serve methods.
 
------
+---
 
 ## 9\) Configuration
 
-Treat config as a **component**:
+Configuration is treated as a first-class, type-safe component using a dedicated injection system.
 
-```python
-@component
-class Config:
-    WORKERS: int = int(os.getenv("WORKERS", "4"))
-    DEBUG: bool = os.getenv("DEBUG", "0") == "1"
-```
+1.  **Define a Config Class**: Create a class (preferably a `dataclass`) and mark it with `@config_component`. An optional `prefix` can be used for environment variables.
+
+    ```python
+    from pico_ioc import config_component
+    from dataclasses import dataclass
+
+    @config_component(prefix="APP_")
+    @dataclass(frozen=True)
+    class Settings:
+        db_url: str
+        timeout: int = 30
+    ```
+
+2.  **Provide Sources**: At bootstrap, pass an ordered tuple of `ConfigSource` objects to the `config` parameter of `init()`. The order defines precedence (first source wins).
+
+    ```python
+    from pico_ioc import init
+    from pico_ioc.config import EnvSource, FileSource
+
+    container = init(
+        "my_app",
+        config=(
+            EnvSource(prefix="APP_"), # Highest priority
+            FileSource("config.prod.yml", optional=True),
+            FileSource("config.yml"), # Lowest priority
+        ),
+    )
+    ```
+
+3.  **Inject and Use**: Inject the config class into other components just like any other dependency.
 
-Inject `Config` where needed; avoid scattered `os.getenv` calls.
+    ```python
+    from pico_ioc import component
 
------
+    @component
+    class Database:
+        def __init__(self, settings: Settings):
+            self.connection = connect(settings.db_url)
+    ```
+
+### Resolution Logic
+
+  - **Automatic Binding**: By default, `pico-ioc` binds fields automatically. For a field like `db_url`, it checks for keys like `APP_DB_URL` (in `EnvSource`), `DB_URL`, or `db_url` (in `FileSource`).
+  - **Manual Overrides**: For more complex cases where keys don't align, you can use field-level helpers like `Env["CUSTOM_VAR"]`, `File["key.in.file"]`, or `Path.file["nested.key"]` to specify the exact key to use.
+
+This system ensures that configuration is **type-safe**, **externalized**, and **testable**, while remaining simple for the common cases.
+
+---
 
 ## 10\) Overrides & composition
 
@@ -176,9 +217,9 @@ 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
-    "expensive": (lambda: object(), True),    # provider with lazy=True
+    Repo: FakeRepo(),                  # constant instance
+    "fast_model": lambda: {"mock": True}, # provider
+    "expensive": (lambda: object(), True), # provider with lazy=True
 })
 ```
 
@@ -189,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.
+
+This is a two-step process:
 
-`pico-ioc` supports two kinds of interceptors:
+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
@@ -222,14 +276,10 @@ 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.
 
------
+---
 
 ## 12\) Profiles & conditional providers
 
@@ -260,7 +310,7 @@ class InMemoryCache(Cache): ...
   * `predicate=callable` → must return a truthy value to activate.
   * If no active provider satisfies a required type and something depends on it → **bootstrap error** (fail fast).
 
------
+---
 
 ## 13\) Qualifiers & collection injection
 
@@ -271,7 +321,7 @@ Attach qualifiers to group/select implementations using `@qualifier`.
 
 This preserves registration order and returns a stable list.
 
------
+---
 
 ## 14\) Plugins
 
@@ -283,9 +333,9 @@ 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.
 
------
+---
 
 ## 15\) Scoped subgraphs (`scope`)
 
@@ -320,7 +370,7 @@ Providers may carry `tags` (via `@component(tags=...)` or `@provides(..., tags=.
 
 **Use cases:** fast unit tests, integration-lite, CLI tools, microbenchmarks.
 
------
+---
 
 ## 16\) Diagnostics & diagrams
 
@@ -343,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
@@ -362,16 +410,16 @@ 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
 ```
 
------
+---
 
 ## 17\) Rationale & trade-offs
 
@@ -379,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 **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.3.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.
 
 ---
 
@@ -131,6 +128,32 @@ A true "last-wins" only occurs when binding the *exact same key* multiple times,
 
 ---
 
+### 15) Configuration Injection
+**Decision**: Provide `@config_component` for strongly typed configuration classes, populated from ordered `ConfigSource`s (`EnvSource`, `FileSource`, etc.).  
+**Rationale**: Type-safe configuration with minimal boilerplate, supporting both automatic autowiring by field name and manual overrides (`Env`, `File`, `Path`, `Value`).  
+**Implications**:
+- Precedence is explicit: `overrides` > sources (in order) > field defaults.
+- Missing required fields (no default and not resolvable) raise `NameError`.
+- Supported formats: env vars, JSON, INI, dotenv, YAML (if available).
+- Encourages using `dataclass(frozen=True)` for immutable, validated settings.
+
+---
+
+### 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)
@@ -165,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.