@teqfw/di 2.0.3 → 2.0.4

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # Changelog
 
+## 2.0.4 - 2026-03-10 - LLM-first project positioning
+
+- Reframed `README.md` around TeqFW architecture, runtime linking, and LLM-agent-oriented development.
+- Rewrote `PHILOSOPHY.md` into a concise statement of TeqFW principles for human and machine-oriented development.
+- Updated package version metadata to `2.0.4`.
+
 ## 2.0.3 - 2026-03-07 - Package agent interface
 
 - Added `ai/` to the published package file list.

package/README.md

@@ -3,17 +3,141 @@
 ![npms.io](https://img.shields.io/npm/dm/@teqfw/di)
 ![jsdelivr](https://img.shields.io/jsdelivr/npm/hm/@teqfw/di)
 
-Deterministic runtime DI container for native ES modules.
+**Runtime dependency linker for JavaScript applications designed for development with LLM agents.**
 
-`@teqfw/di` uses explicit dependency contracts (CDC strings) and module-level dependency descriptors (`__deps__`).
-It does not infer dependencies from constructor signatures.
+`@teqfw/di` is the core infrastructure of the **Tequila Framework (TeqFW)** — an architectural approach for building web applications in which **humans design system architecture and specifications, while LLM agents generate and maintain the implementation.**
 
-## Version Line
+Instead of wiring modules through static imports, TeqFW applications declare **explicit dependency contracts**, and the container performs **deterministic runtime linking**.
 
-This branch is the v2 line.
+The result is an application architecture that is easier to:
 
-- package version: `2.0.0`
-- changelog starts from `2.0.0`
+- analyze
+- generate
+- refactor
+- extend
+
+— both for **human developers and AI agents**.
+
+## The Shift in Software Development
+
+Large language models are becoming a permanent part of the development process.
+
+However, most software architectures were designed for **human-written code**, not for **code generated and maintained by AI agents**.
+
+Typical JavaScript applications rely on:
+
+- static imports
+- implicit dependency graphs
+- tight coupling to file structure
+- constructor-based dependency inference
+
+These patterns work well for humans but are difficult for automated agents to reason about reliably.
+
+**TeqFW proposes a different architecture.**
+
+Modules declare **explicit dependency contracts**, and a runtime container resolves those contracts deterministically.
+
+This transforms the dependency graph into something that can be **analyzed, generated and modified programmatically.**
+
+## What This Library Provides
+
+`@teqfw/di` implements the runtime container that enables this architecture.
+
+It provides:
+
+- deterministic runtime linking of ES modules
+- explicit dependency contracts (**CDC — Canonical Dependency Codes**)
+- module dependency descriptors (`__deps__`)
+- namespace-based module resolution
+- runtime lifecycle management
+- wrapper-based behavioral extensions
+
+The container acts as a **runtime linker for JavaScript applications**.
+
+## Designed for Development with LLM Agents
+
+When software is generated or maintained by LLM agents, several structural problems appear.
+
+| Problem          | Traditional Architecture | TeqFW Approach     |
+| ---------------- | ------------------------ | ------------------ |
+| Dependencies     | implicit imports         | explicit contracts |
+| Dependency graph | implicit                 | deterministic      |
+| Refactoring      | fragile                  | stable             |
+| Testing          | manual wiring            | container driven   |
+| AI compatibility | accidental               | intentional        |
+
+TeqFW structures the application so that **LLM agents can reliably understand and modify the system.**
+
+## Agent-Driven Implementation
+
+Starting from version **2.0.0**, the source code of this library is **written primarily by Codex agents**.
+
+The development workflow follows **specification-driven development**:
+
+1. The human architect defines **product specifications**
+2. LLM agents generate the implementation
+3. The generated code is reviewed and integrated
+
+This workflow follows the **ADSM methodology (Agent-Driven Software Management)** developed by **Alex Gusev**.
+
+Earlier versions of the library (<2.0.0) were written manually.
+The current version demonstrates how software can be developed using **human-defined architecture and AI-generated code**.
+
+## Learn the Architecture (Interactive Onboarding)
+
+Understanding this architecture can take time.
+
+To make onboarding easier, an **interactive AI assistant** [is available](https://fly.wiredgeese.com/flancer/gpt/teqfw/guide/di/).
+
+The assistant can explain:
+
+- how the container works
+- what Canonical Dependency Codes are
+- how modules declare dependencies
+- how runtime linking works
+- how to integrate the library in real applications
+
+The assistant acts as **interactive documentation** for the project.
+
+Custom onboarding assistants like this can also be created **as a service** for other projects and libraries.
+
+## Agent Interface (Documentation for LLM Agents)
+
+This package includes **agent interface documentation** intended for LLM agents that use the library as an npm dependency.
+
+These documents are distributed inside the package in:
+
+```txt
+./ai/
+```
+
+The files in this directory describe the **public interface of the package in an agent-friendly form**.
+
+They explain:
+
+- the container API
+- dependency descriptors (`__deps__`)
+- Canonical Dependency Codes (CDC)
+- dependency resolution behavior
+- integration patterns
+
+Human developers typically read the README and source code, while **LLM agents can rely on the documentation in `./ai/`.**
+
+## Tequila Framework Philosophy
+
+`@teqfw/di` is the core building block of the **Tequila Framework (TeqFW)** ecosystem.
+
+TeqFW is based on several architectural principles:
+
+- runtime late binding between components
+- namespace-based module organization
+- modular monolith architecture
+- pure JavaScript without compilation
+- system structures optimized for collaboration with LLM agents
+
+Full philosophy:
+
+`PHILOSOPHY.md`
 
 ## Installation
 
@@ -21,13 +145,13 @@ This branch is the v2 line.
 npm install @teqfw/di
 ```
 
-## Quick Start
+## Quick Example
 
-### 1. Define modules with `__deps__`
+### Define modules
 
 `src/App/Child.mjs`
 
-```js
+```javascript
 export default function App_Child() {
   return { name: "child" };
 }
@@ -35,7 +159,7 @@ export default function App_Child() {
 
 `src/App/Root.mjs`
 
-```js
+```javascript
 export const __deps__ = {
   child: "App_Child$",
 };
@@ -48,9 +172,9 @@ export default function App_Root({ child }) {
 }
 ```
 
-### 2. Configure container in composition root
+### Configure container
 
-```js
+```javascript
 import path from "node:path";
 import { fileURLToPath } from "node:url";
 import Container from "@teqfw/di";
@@ -59,68 +183,73 @@ const __filename = fileURLToPath(import.meta.url);
 const __dirname = path.dirname(__filename);
 
 const container = new Container();
+
 container.addNamespaceRoot("App_", path.resolve(__dirname, "./src/App"), ".mjs");
 
 const root = await container.get("App_Root$");
-console.log(root.name); // root
-console.log(root.child.name); // child
-console.log(Object.isFrozen(root)); // true
+
+console.log(root.name);
+console.log(root.child.name);
 ```
 
-## Dependency Descriptor (`__deps__`)
+The container:
 
-`__deps__` is a static module export:
+- loads modules
+- resolves dependency contracts
+- constructs the object graph
+- returns **frozen linked objects**
 
-```js
+## Dependency Contracts (`__deps__`)
+
+Modules declare dependencies using a static export.
+
+```javascript
 export const __deps__ = {
-  localName: "Some_CDC",
+  localName: "Dependency_CDC",
 };
 ```
 
-Rules used by container runtime:
+Rules:
+
+- if `__deps__` is absent — module has no dependencies
+- keys correspond to constructor argument names
+- values are CDC dependency identifiers
+- dependencies are resolved recursively
 
-- if `__deps__` is missing: module has zero dependencies
-- keys are local argument names passed into factory/class constructor
-- values are CDC strings
-- dependencies are resolved recursively before instantiation
+## Canonical Dependency Codes (CDC)
 
-## CDC Grammar (Default Profile)
+CDC identifiers describe **how dependencies should be resolved**.
 
-Surface form:
+General form:
 
-```text
+```txt
 [PlatformPrefix]ModuleName[__ExportName][LifecycleAndWrappers]
 ```
 
-Where:
-
-- `PlatformPrefix`: `node_` | `npm_` | omitted (`teq` by default)
-- `Export segment`: `__ExportName`
-- `Lifecycle marker`: `$` | `$$` | `$$$`
-- `Wrappers`: `_<wrapperId>` suffixes after lifecycle marker
-
 Examples:
 
-- `App_Service` - whole module (`as-is`)
-- `App_Service$` - default export as factory with lifecycle marker
-- `App_Service__build$$` - named export `build` with lifecycle marker
-- `App_Service$$_wrapLog_wrapTrace` - wrapper chain in declared order
-- `node_fs` - Node builtin
-- `npm_lodash` - npm package
+```txt
+App_Service
+App_Service$
+App_Service__build$$
+App_Service$$_wrapLog_wrapTrace
+node_fs
+npm_lodash
+```
 
-Notes:
+Where:
 
-- explicit `teq_` prefix is forbidden
-- wrappers without lifecycle marker are invalid
-- parser is deterministic and fail-fast
+- `$` singleton lifecycle
+- `$$` new instance lifecycle
+- wrappers modify runtime behavior
 
 ## Public API
 
-```js
+```javascript
 const container = new Container();
 ```
 
-Builder stage methods (only before first `get`):
+Configuration methods (before first `get`):
 
 - `setParser(parser)`
 - `addNamespaceRoot(prefix, target, defaultExt)`
@@ -128,137 +257,79 @@ Builder stage methods (only before first `get`):
 - `addPostprocess(fn)`
 - `enableLogging()`
 - `enableTestMode()`
-- `register(cdc, mock)` (only in test mode)
-
-Resolution:
-
-- `await container.get(cdc)`
-
-Behavioral guarantees:
-
-- configuration is locked after first `get`
-- fail-fast pipeline
-- deterministic linking under identical contracts and config
-- produced values are frozen
-- container enters failed state after fatal linking error
-
-## Wrappers
-
-Wrappers are postprocess plugins registered during container configuration.
-They are activated by wrapper markers in the CDC string and applied to the produced value after instantiation.
-
-Wrappers:
+- `register(cdc, mock)`
 
-- are **container-level plugins**
-- are **not module exports**
-- are applied in declared order
-- must return synchronously
-- run before lifecycle enforcement and freeze
+Dependency resolution:
 
-Surface form:
-
-```text
-ModuleName$$_wrapperA_wrapperB
+```javascript
+await container.get(cdc);
 ```
 
-Wrappers are part of the dependency contract (CDC).
-They declaratively modify how a resolved value behaves.
-
----
-
-### Example: Logging Wrapper
+Behavior:
 
-Suppose we want to log all method calls of a service without modifying the service itself.
+- deterministic linking
+- fail-fast resolution pipeline
+- immutable returned objects
+- container enters failed state on fatal errors
 
-#### Service module
-
-```js
-export default function App_Service() {
-  return {
-    sum(a, b) {
-      return a + b;
-    },
-    multiply(a, b) {
-      return a * b;
-    },
-  };
-}
-```
-
-#### Container configuration
-
-```js
-container.addPostprocessWrapper("logIO", (value) => {
-  return new Proxy(value, {
-    get(target, prop, receiver) {
-      const original = Reflect.get(target, prop, receiver);
-
-      if (typeof original !== "function") {
-        return original;
-      }
-
-      return function (...args) {
-        console.log(`[CALL] ${String(prop)} ->`, args);
-        const result = original.apply(this, args);
-        console.log(`[RETURN] ${String(prop)} ->`, result);
-        return result;
-      };
-    },
-  });
-});
-```
+## Wrappers
 
-#### Request
+Wrappers allow cross-cutting behavior to be applied declaratively.
 
-```js
-const service = await container.get("App_Service$$_logIO");
+Example CDC:
 
-service.sum(2, 3);
-// [CALL] sum -> [2, 3]
-// [RETURN] sum -> 5
+```txt
+App_Service$$_log_trace
 ```
 
-The module remains unaware of logging.
-The wrapper applies cross-cutting behavior declaratively through CDC.
-
-This allows:
+Wrappers can implement:
 
+- logging
+- metrics
 - tracing
-- metrics collection
-- access control
+- security checks
 - behavioral instrumentation
 
-without modifying business logic or module structure.
-
-Wrappers therefore act as a declarative DI-level AOP mechanism.
+This acts as a lightweight **DI-level AOP mechanism.**
 
-## Test Mode and Mocks
+## Test Mode
 
-```js
+```javascript
 container.enableTestMode();
-container.register("App_Service$", { name: "mock-service" });
+
+container.register("App_Service$", mockService);
 ```
 
-Mock lookup uses canonical parsed dependency identity and is applied before resolver/instantiation.
+Mocks are resolved before module instantiation.
 
 ## Browser Usage
 
-ESM via jsDelivr:
-
 ```html
 <script type="module">
   import Container from "https://cdn.jsdelivr.net/npm/@teqfw/di@2/+esm";
+
   const container = new Container();
 </script>
 ```
 
-## Documentation Source
+## Documentation
+
+Detailed documentation lives in `ctx/`:
+
+- `ctx/docs/product/overview.md`
+- `ctx/docs/product/default-cdc-profile.md`
+- `ctx/docs/architecture/cdc-profile/default/grammar.md`
+- `ctx/docs/architecture/cdc-profile/default/transformation.md`
+- `ctx/docs/architecture/cdc-profile/default/validation.md`
+- `ctx/docs/code/components/container.md`
+
+## Author
+
+**Alex Gusev**
+
+Creator of:
 
-Normative docs live in `ctx/`:
+- **Tequila Framework (TeqFW)**
+- **ADSM (Agent-Driven Software Management)**
 
-- product overview: `ctx/docs/product/overview.md`
-- default CDC profile: `ctx/docs/product/default-cdc-profile.md`
-- grammar: `ctx/docs/architecture/cdc-profile/default/grammar.md`
-- transformation: `ctx/docs/architecture/cdc-profile/default/transformation.md`
-- validation: `ctx/docs/architecture/cdc-profile/default/validation.md`
-- container contract: `ctx/docs/code/components/container.md`
+The project explores how software architecture evolves when **LLM agents become active participants in the development process**.

package/ai/AGENTS.md

@@ -50,13 +50,14 @@ This mechanism separates module implementation from dependency binding and allow
 Agents should read the documents in this directory in the following order:
 
 1. **AGENTS.md** — overview of the package and navigation of the Agent Interface.
-2. **concepts.md** — architectural concepts and design principles.
-3. **container.md** — container responsibilities and dependency resolution pipeline.
-4. **dependency-id.md** — syntax and semantics of dependency identifiers.
-5. **extensions.md** — extension mechanisms such as preprocessors and wrappers.
-6. **usage.md** — minimal usage scenarios and examples.
-
-This sequence reflects the conceptual flow required to understand the package: architectural model → operational mechanism → dependency addressing → extension points → practical usage.
+2. **package-api.ts** — machine-readable contract of the supported programmatic API, public entrypoints, structural contracts, and internal exclusions.
+3. **concepts.md** — architectural concepts and design principles.
+4. **container.md** — container responsibilities and dependency resolution pipeline.
+5. **dependency-id.md** — syntax and semantics of dependency identifiers.
+6. **extensions.md** — extension mechanisms such as preprocessors and wrappers.
+7. **usage.md** — minimal usage scenarios and examples.
+
+This sequence reflects the intended agent workflow: contract surface first, then architectural model, operational mechanism, dependency addressing, extension points, and practical usage.
 
 ## Interface Scope
 

package/ai/package-api.ts

@@ -0,0 +1,440 @@
+export type ApiExposure =
+    | 'public-runtime'
+    | 'public-structural'
+    | 'internal';
+
+export interface ImportBinding {
+    readonly specifier: string;
+    readonly exportName: 'default' | string;
+    readonly canonical: boolean;
+    readonly note?: string;
+}
+
+export interface MethodContract {
+    readonly name: string;
+    readonly signature: string;
+    readonly stage?: 'builder' | 'runtime' | 'composition';
+    readonly summary: string;
+    readonly constraints?: readonly string[];
+}
+
+export interface RuntimeComponentContract {
+    readonly alias: string;
+    readonly kind: 'class';
+    readonly role: string;
+    readonly imports: readonly ImportBinding[];
+    readonly methods: readonly MethodContract[];
+}
+
+export interface StructuralContract {
+    readonly name: string;
+    readonly kind: 'dto' | 'enum' | 'protocol' | 'module-contract';
+    readonly summary: string;
+    readonly aliases?: readonly string[];
+    readonly fields?: Readonly<Record<string, string>>;
+    readonly values?: Readonly<Record<string, string>>;
+    readonly notes?: readonly string[];
+}
+
+export interface TypeAliasClassification {
+    readonly alias: string;
+    readonly source: string;
+    readonly exposure: ApiExposure;
+    readonly reason: string;
+    readonly canonicalUse?: string;
+    readonly sameAs?: readonly string[];
+}
+
+export interface PackageApiContract {
+    readonly packageName: '@teqfw/di';
+    readonly packageRole: string;
+    readonly canonicalEntrypoints: readonly string[];
+    readonly publicRuntime: readonly RuntimeComponentContract[];
+    readonly structuralContracts: readonly StructuralContract[];
+    readonly typeMapClassification: readonly TypeAliasClassification[];
+    readonly operationalNotes: readonly string[];
+}
+
+/**
+ * Public package contract intended for agents that consume `@teqfw/di`
+ * as an npm dependency.
+ *
+ * This file distinguishes between:
+ * - importable runtime API supported by `package.json#exports`
+ * - structural contracts that external code may rely on indirectly
+ * - internal implementation aliases present in `types.d.ts`
+ */
+export const PACKAGE_API: PackageApiContract = {
+    packageName: '@teqfw/di',
+    packageRole: 'Deterministic runtime DI container for native ES modules with explicit CDC contracts.',
+    canonicalEntrypoints: [
+        '@teqfw/di',
+        '@teqfw/di/src/Config/NamespaceRegistry.mjs',
+    ],
+    publicRuntime: [
+        {
+            alias: 'TeqFw_Di_Container',
+            kind: 'class',
+            role: 'Primary runtime composition root. Resolves CDC identifiers into frozen linked values.',
+            imports: [
+                {
+                    specifier: '@teqfw/di',
+                    exportName: 'default',
+                    canonical: true,
+                },
+                {
+                    specifier: '@teqfw/di/src/Container.mjs',
+                    exportName: 'default',
+                    canonical: false,
+                    note: 'Explicit source subpath export. Prefer the package root import.',
+                },
+            ],
+            methods: [
+                {
+                    name: 'constructor',
+                    signature: 'new Container()',
+                    stage: 'builder',
+                    summary: 'Creates a container in builder stage. The constructor accepts no arguments.',
+                },
+                {
+                    name: 'setParser',
+                    signature: 'setParser(parser: { parse(cdc: string): TeqFw_Di_DepId$DTO }): void',
+                    stage: 'builder',
+                    summary: 'Replaces the default CDC parser before the first resolution.',
+                    constraints: [
+                        'Allowed only before the first get().',
+                        'The parser contract is structural. The package does not export the default parser runtime class.',
+                    ],
+                },
+                {
+                    name: 'addNamespaceRoot',
+                    signature: 'addNamespaceRoot(prefix: string, target: string, defaultExt: string): void',
+                    stage: 'builder',
+                    summary: 'Registers one namespace-to-filesystem mapping rule.',
+                    constraints: [
+                        'Allowed only before the first get().',
+                        'Namespace rules are snapshotted and locked on the first get().',
+                    ],
+                },
+                {
+                    name: 'addPreprocess',
+                    signature: 'addPreprocess(fn: (depId: TeqFw_Di_DepId$DTO) => TeqFw_Di_DepId$DTO): void',
+                    stage: 'builder',
+                    summary: 'Adds an ordered CDC preprocessing hook.',
+                    constraints: [
+                        'Allowed only before the first get().',
+                        'Each hook must return another DepId DTO.',
+                    ],
+                },
+                {
+                    name: 'addPostprocess',
+                    signature: 'addPostprocess(fn: (value: unknown) => unknown): void',
+                    stage: 'builder',
+                    summary: 'Adds an ordered post-instantiation value transform applied to every resolved value.',
+                    constraints: [
+                        'Allowed only before the first get().',
+                        'Runs before wrapper exports and before freeze.',
+                    ],
+                },
+                {
+                    name: 'enableLogging',
+                    signature: 'enableLogging(): void',
+                    stage: 'builder',
+                    summary: 'Turns on diagnostic console logging without changing linking semantics.',
+                    constraints: [
+                        'Allowed only before the first get().',
+                    ],
+                },
+                {
+                    name: 'enableTestMode',
+                    signature: 'enableTestMode(): void',
+                    stage: 'builder',
+                    summary: 'Enables structural mock registration for tests.',
+                    constraints: [
+                        'Allowed only before the first get().',
+                    ],
+                },
+                {
+                    name: 'register',
+                    signature: 'register(cdc: string, mock: unknown): void',
+                    stage: 'builder',
+                    summary: 'Registers a mock by canonical DepId identity after parsing the provided CDC.',
+                    constraints: [
+                        'Allowed only before the first get().',
+                        'Requires enableTestMode() first.',
+                    ],
+                },
+                {
+                    name: 'get',
+                    signature: 'get(cdc: string): Promise<any>',
+                    stage: 'runtime',
+                    summary: 'Parses, resolves, instantiates, postprocesses, wraps, applies lifecycle, freezes, and returns a linked value.',
+                    constraints: [
+                        'The first get() locks configuration and creates internal infrastructure.',
+                        'Any fatal pipeline error moves the container into failed state.',
+                        'All subsequent get() calls reject once the container is failed.',
+                    ],
+                },
+            ],
+        },
+        {
+            alias: 'TeqFw_Di_Config_NamespaceRegistry',
+            kind: 'class',
+            role: 'Composition-stage helper that discovers namespace roots from the root package and installed npm dependencies.',
+            imports: [
+                {
+                    specifier: '@teqfw/di/src/Config/NamespaceRegistry.mjs',
+                    exportName: 'default',
+                    canonical: true,
+                },
+            ],
+            methods: [
+                {
+                    name: 'constructor',
+                    signature: 'new NamespaceRegistry({ fs, path, appRoot })',
+                    stage: 'composition',
+                    summary: 'Creates a registry builder over filesystem and path adapters.',
+                    constraints: [
+                        'Intended for composition root code, not for DI-managed runtime modules.',
+                        'Consumes static package.json metadata only.',
+                    ],
+                },
+                {
+                    name: 'build',
+                    signature: 'build(): Promise<ReadonlyArray<{ prefix: string; dirAbs: string; ext: string }>>',
+                    stage: 'composition',
+                    summary: 'Builds an immutable namespace registry sorted by descending prefix length.',
+                    constraints: [
+                        'Fails fast on invalid namespace metadata or duplicate canonical prefixes.',
+                    ],
+                },
+            ],
+        },
+    ],
+    structuralContracts: [
+        {
+            name: 'DepId DTO',
+            kind: 'dto',
+            aliases: ['TeqFw_Di_DepId$DTO', 'TeqFw_Di_Dto_DepId$DTO'],
+            summary: 'Canonical structural dependency identity passed to preprocess hooks and expected from custom parsers.',
+            fields: {
+                moduleName: 'Logical module identifier without platform prefix.',
+                platform: '"teq" | "node" | "npm".',
+                exportName: 'Named export or "default"; null means whole-module/as-is resolution.',
+                composition: '"A" | "F" in the current implementation.',
+                life: '"S" | "T" | null in the current implementation.',
+                wrappers: 'Ordered wrapper export names.',
+                origin: 'Original CDC string for diagnostics.',
+            },
+            notes: [
+                'Identity excludes origin.',
+                'Consumers should treat it as a structural protocol, not as a factory import surface.',
+            ],
+        },
+        {
+            name: 'Parser Protocol',
+            kind: 'protocol',
+            aliases: ['TeqFw_Di_Def_Parser'],
+            summary: 'Structural contract accepted by Container.setParser().',
+            fields: {
+                parse: '(cdc: string) => TeqFw_Di_DepId$DTO',
+            },
+            notes: [
+                'The package does not export the default parser runtime class through package exports.',
+                'External code may provide any object that satisfies the parse() contract.',
+            ],
+        },
+        {
+            name: 'DepId Enums',
+            kind: 'enum',
+            aliases: [
+                'TeqFw_Di_Enum_Composition',
+                'TeqFw_Di_Enum_Life',
+                'TeqFw_Di_Enum_Platform',
+            ],
+            summary: 'Current implementation literals used inside DepId DTO values.',
+            values: {
+                composition: 'AS_IS -> "A", FACTORY -> "F"',
+                life: 'SINGLETON -> "S", TRANSIENT -> "T"',
+                platform: 'TEQ -> "teq", NODE -> "node", NPM -> "npm"',
+            },
+            notes: [
+                'These aliases are useful for tooling and JSDoc, not for runtime imports from the package.',
+            ],
+        },
+        {
+            name: 'Module Contract',
+            kind: 'module-contract',
+            summary: 'Shape expected from application modules resolved by the container.',
+            fields: {
+                __deps__: 'Optional top-level Record<string, string> mapping constructor keys to CDC strings.',
+                moduleNamespace: 'Whole ES module namespace object returned for as-is CDC without selected export.',
+                defaultExport: 'Used when the parsed DepId selects exportName="default" for factory composition.',
+                namedExports: 'May be selected via __ExportName for factory composition and may also provide wrapper functions.',
+                wrapperExport: 'Named export whose identifier appears in depId.wrappers; it must be synchronous and unary.',
+            },
+            notes: [
+                'The current runtime reads namespace.__deps__ directly; it does not use export-scoped dependency maps.',
+                'Wrapper functions are exported by the same resolved module namespace, not registered globally in the container.',
+            ],
+        },
+    ],
+    typeMapClassification: [
+        {
+            alias: 'TeqFw_Di_Config_NamespaceRegistry',
+            source: './src/Config/NamespaceRegistry.mjs',
+            exposure: 'public-runtime',
+            reason: 'Exported through package.json exports as a supported subpath entrypoint.',
+            canonicalUse: 'Composition-stage helper imported from @teqfw/di/src/Config/NamespaceRegistry.mjs.',
+        },
+        {
+            alias: 'TeqFw_Di_Container',
+            source: './src/Container.mjs',
+            exposure: 'public-runtime',
+            reason: 'Default export of the package root and of the explicit source subpath.',
+            canonicalUse: 'Primary container API imported from @teqfw/di.',
+        },
+        {
+            alias: 'TeqFw_Di_Container_Instantiate_ExportSelector',
+            source: './src/Container/Instantiate/ExportSelector.mjs',
+            exposure: 'internal',
+            reason: 'Internal immutable-core helper. Not exported via package.json.',
+        },
+        {
+            alias: 'TeqFw_Di_Container_Instantiate_Instantiator',
+            source: './src/Container/Instantiate/Instantiator.mjs',
+            exposure: 'internal',
+            reason: 'Internal immutable-core helper. Not exported via package.json.',
+        },
+        {
+            alias: 'TeqFw_Di_Container_Lifecycle_Registry',
+            source: './src/Container/Lifecycle/Registry.mjs',
+            exposure: 'internal',
+            reason: 'Internal lifecycle cache component. Not exported via package.json.',
+        },
+        {
+            alias: 'TeqFw_Di_Container_Resolve_GraphResolver',
+            source: './src/Container/Resolve/GraphResolver.mjs',
+            exposure: 'internal',
+            reason: 'Internal graph builder used by Container.get(). Not exported via package.json.',
+        },
+        {
+            alias: 'TeqFw_Di_Container_Wrapper_Executor',
+            source: './src/Container/Wrapper/Executor.mjs',
+            exposure: 'internal',
+            reason: 'Internal wrapper-stage executor. Not exported via package.json.',
+        },
+        {
+            alias: 'TeqFw_Di_Def_Parser',
+            source: './src/Def/Parser.mjs',
+            exposure: 'public-structural',
+            reason: 'Container.setParser() accepts this structural contract, but the runtime class is not importable from the package.',
+            canonicalUse: 'Typing/protocol alias for custom parser implementations.',
+        },
+        {
+            alias: 'TeqFw_Di_DepId',
+            source: './src/Dto/DepId.mjs',
+            exposure: 'internal',
+            reason: 'Factory class behind the DepId DTO module. Not needed for the supported package runtime API.',
+            sameAs: ['TeqFw_Di_Dto_DepId'],
+        },
+        {
+            alias: 'TeqFw_Di_DepId$DTO',
+            source: './src/Dto/DepId.mjs#DTO',
+            exposure: 'public-structural',
+            reason: 'Public structural protocol used by preprocess hooks and parser replacement.',
+            canonicalUse: 'Primary type alias for canonical dependency identity.',
+            sameAs: ['TeqFw_Di_Dto_DepId$DTO'],
+        },
+        {
+            alias: 'TeqFw_Di_Dto_DepId',
+            source: './src/Dto/DepId.mjs',
+            exposure: 'internal',
+            reason: 'Legacy-namespaced alias of the DepId factory class; not part of the supported runtime import surface.',
+            sameAs: ['TeqFw_Di_DepId'],
+        },
+        {
+            alias: 'TeqFw_Di_Dto_DepId$DTO',
+            source: './src/Dto/DepId.mjs#DTO',
+            exposure: 'public-structural',
+            reason: 'Synonym of TeqFw_Di_DepId$DTO kept in the type map.',
+            sameAs: ['TeqFw_Di_DepId$DTO'],
+        },
+        {
+            alias: 'TeqFw_Di_Dto_Resolver_Config',
+            source: './src/Dto/Resolver/Config.mjs',
+            exposure: 'internal',
+            reason: 'Internal DTO factory used inside Container when bootstrapping Resolver.',
+        },
+        {
+            alias: 'TeqFw_Di_Dto_Resolver_Config$DTO',
+            source: './src/Dto/Resolver/Config.mjs#DTO',
+            exposure: 'internal',
+            reason: 'Internal resolver configuration DTO. External code configures the container through addNamespaceRoot() instead.',
+        },
+        {
+            alias: 'TeqFw_Di_Dto_Resolver_Config_Namespace',
+            source: './src/Dto/Resolver/Config/Namespace.mjs',
+            exposure: 'internal',
+            reason: 'Internal DTO factory for resolver namespace rules.',
+        },
+        {
+            alias: 'TeqFw_Di_Dto_Resolver_Config_Namespace$DTO',
+            source: './src/Dto/Resolver/Config/Namespace.mjs#DTO',
+            exposure: 'internal',
+            reason: 'Internal resolver namespace DTO alias retained for type-map completeness.',
+            sameAs: ['TeqFw_Di_Dto_Resolver_Config_Namespace$DTO$'],
+        },
+        {
+            alias: 'TeqFw_Di_Dto_Resolver_Config_Namespace$DTO$',
+            source: './src/Dto/Resolver/Config/Namespace.mjs#DTO',
+            exposure: 'internal',
+            reason: 'Duplicate DTO alias retained for compatibility inside implementation typings.',
+            sameAs: ['TeqFw_Di_Dto_Resolver_Config_Namespace$DTO'],
+        },
+        {
+            alias: 'TeqFw_Di_Enum_Composition',
+            source: './src/Enum/Composition.mjs',
+            exposure: 'public-structural',
+            reason: 'Useful static vocabulary for interpreting DepId.composition values.',
+            canonicalUse: 'Type/JSDoc vocabulary only; no package export for runtime import.',
+        },
+        {
+            alias: 'TeqFw_Di_Enum_Life',
+            source: './src/Enum/Life.mjs',
+            exposure: 'public-structural',
+            reason: 'Useful static vocabulary for interpreting DepId.life values.',
+            canonicalUse: 'Type/JSDoc vocabulary only; no package export for runtime import.',
+        },
+        {
+            alias: 'TeqFw_Di_Enum_Platform',
+            source: './src/Enum/Platform.mjs',
+            exposure: 'public-structural',
+            reason: 'Useful static vocabulary for interpreting DepId.platform values.',
+            canonicalUse: 'Type/JSDoc vocabulary only; no package export for runtime import.',
+        },
+        {
+            alias: 'TeqFw_Di_Internal_Logger',
+            source: './src/Internal/Logger.mjs',
+            exposure: 'internal',
+            reason: 'Diagnostic helper used only inside the container implementation.',
+        },
+        {
+            alias: 'TeqFw_Di_Resolver',
+            source: './src/Container/Resolver.mjs',
+            exposure: 'internal',
+            reason: 'Internal module resolver infrastructure. Consumers should configure the Container, not instantiate Resolver directly.',
+        },
+    ],
+    operationalNotes: [
+        'Only two runtime entrypoints are supported by package.json exports: @teqfw/di and @teqfw/di/src/Config/NamespaceRegistry.mjs.',
+        'Resolved values are frozen before being returned.',
+        'The current runtime reads __deps__ as a flat top-level map exported by the module namespace.',
+        'With the default parser, CDC without lifecycle returns the whole module namespace as-is; named export selection implies factory composition.',
+        'Named wrapper exports are executed after addPostprocess() hooks and before freeze.',
+        'In the current implementation, CDC markers $$ and $$$ both end up as transient/no-cache behavior.',
+        'types.d.ts is broader than the runtime import surface. Presence of an alias there does not by itself make the underlying module a supported runtime entrypoint.',
+    ],
+} as const;
+
+export default PACKAGE_API;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@teqfw/di",
-  "version": "2.0.3",
+  "version": "2.0.4",
   "description": "Dependency Injection container for ES6 modules that works in both browser and Node.js apps.",
   "keywords": [
     "dependency injection",