@teqfw/di 2.5.1 → 2.6.0

package/ai/extensions.md

@@ -1,73 +1,103 @@
 # extensions.md
 
-Version: 20260331
+Version: 20260606
 
 ## Purpose
 
-The container supports controlled extension of the dependency resolution process through **preprocess handlers** and **postprocess wrappers**. These mechanisms allow the behavior of dependency resolution and object creation to be adjusted without modifying container internals.
+The container supports controlled extension of dependency resolution through three distinct mechanisms:
 
-Extensions are registered during container configuration and become part of the deterministic resolution pipeline.
+- preprocess hooks;
+- postprocess hooks;
+- wrapper exports.
 
-## Extension Points
+These mechanisms are related but not interchangeable.
 
-Two extension points are available:
+## Preprocess Hooks
 
-- **Preprocess handlers** — transform dependency identifiers before resolution.
-- **Postprocess wrappers** — modify or decorate created objects after instantiation.
+Preprocess hooks transform CDC identities before resolution.
 
-These extension points correspond to the preprocess and postprocess stages of the container pipeline described in **container.md**.
+Signature:
 
-## Preprocess Handlers
+```js
+(depId) => depId
+```
+
+Properties:
+
+- registered with `addPreprocess()`;
+- run in declared order;
+- receive and return DepId DTO values;
+- affect identifier interpretation before module resolution.
+
+Typical uses:
+
+- CDC alias rewriting;
+- policy-driven identifier normalization;
+- project-specific prefix adaptation.
+
+## Postprocess Hooks
 
-Preprocess handlers receive a dependency identifier before it is interpreted by the container. A handler may transform the identifier and return a modified value that continues through the resolution pipeline.
+Postprocess hooks transform resolved values after instantiation and before wrapper exports.
 
-Typical uses of preprocess handlers include:
+Signature:
 
-- rewriting dependency identifiers
-- applying identifier aliases
-- enforcing project-specific identifier conventions
+```js
+(value) => value
+```
+
+Properties:
+
+- registered with `addPostprocess()`;
+- run for every resolved value;
+- run in declared order;
+- do not alter CDC parsing or module resolution.
 
-Preprocess handlers operate only on identifiers and do not interact with instantiated objects.
+Typical uses:
 
-## Postprocess Wrappers
+- global instrumentation;
+- value normalization;
+- cross-cutting adaptation applied uniformly to all resolved values.
 
-Postprocess wrappers operate on objects created by the container. A wrapper receives the instantiated object and may return a modified or decorated version.
+## Wrapper Exports
 
-Wrappers are typically used for:
+Wrapper exports are selected directly from CDC suffixes and are resolved from the same module namespace as the dependency being composed.
 
-- logging or tracing
-- instrumentation
-- capability injection
-- runtime adaptation of object behavior
+Signature:
 
-Wrappers do not modify the dependency resolution logic itself and operate only after object instantiation.
+```js
+(value) => value
+```
 
-## Wrapper Selection
+Properties:
 
-Wrappers are applied when their identifiers appear in a CDC. Wrapper identifiers are appended after the lifecycle marker and separated by underscores.
+- selected by wrapper suffixes such as `_wrapLog`;
+- applied only when present in the CDC;
+- executed after postprocess hooks and before freeze;
+- not registered globally in the container.
 
 Example:
 
 ```txt
-App_Service_User$$_wrapLog_wrapTrace
+App_Service$$_wrapLog_wrapTrace
 ```
 
-In this example the container creates a new instance of the dependency and applies the wrappers `wrapLog` and `wrapTrace` during the postprocess stage.
-
-Wrappers do not change the structure of `__deps__`. Dependency descriptors remain either hierarchical export-scoped descriptors, shorthand flat descriptors for limited single-export cases, or omitted entirely for empty-descriptor modules.
+In this example the container composes the dependency, applies postprocess hooks, then applies wrapper exports `wrapLog` and `wrapTrace` in that order.
 
 ## Execution Order
 
-Multiple wrappers may be applied to a single dependency. Wrappers are executed in the order in which they appear in the CDC.
-
-Each wrapper receives the object returned by the previous wrapper and may return a new object that becomes the input to the next wrapper.
+The extension-related execution order is:
 
-## Extension Constraints
+1. preprocess hooks;
+2. instantiation or as-is resolution;
+3. postprocess hooks;
+4. wrapper exports;
+5. freeze.
 
-Extensions must satisfy the following constraints:
+## Constraints
 
-- they must be registered before the container becomes active
-- they must be deterministic and free of side effects that alter container state
-- they must not bypass lifecycle semantics enforced by the container
+Extensions must satisfy these constraints:
 
-These constraints ensure that extensions do not compromise deterministic dependency resolution.
+- they must be registered before the first `get()` if they use container registration APIs;
+- they should be deterministic for the same input;
+- they must not rely on mutating frozen returned values;
+- they must not bypass lifecycle semantics enforced by the container.

package/ai/package-api.ts

@@ -110,9 +110,10 @@ export const PACKAGE_API: PackageApiContract = {
                     name: 'addNamespaceRoot',
                     signature: 'addNamespaceRoot(prefix: string, target: string, defaultExt: string): void',
                     stage: 'builder',
-                    summary: 'Registers one namespace-to-filesystem mapping rule.',
+                    summary: 'Registers one namespace root that maps a CDC prefix to a module-specifier base.',
                     constraints: [
                         'Allowed only before the first get().',
+                        'The target may be filesystem-backed or URL-backed depending on runtime environment.',
                         'Namespace rules are snapshotted and locked on the first get().',
                     ],
                 },
@@ -130,10 +131,10 @@ export const PACKAGE_API: PackageApiContract = {
                     name: 'addPostprocess',
                     signature: 'addPostprocess(fn: (value: unknown) => unknown): void',
                     stage: 'builder',
-                    summary: 'Adds an ordered post-instantiation value transform applied to every resolved value.',
+                    summary: 'Adds an ordered value transform applied to every resolved value after instantiation.',
                     constraints: [
                         'Allowed only before the first get().',
-                        'Runs before wrapper exports and before freeze.',
+                        'Runs after instantiation and before wrapper exports.',
                     ],
                 },
                 {
@@ -168,7 +169,7 @@ export const PACKAGE_API: PackageApiContract = {
                     name: 'get',
                     signature: 'get(cdc: string): Promise<any>',
                     stage: 'runtime',
-                    summary: 'Parses, resolves, instantiates, postprocesses, wraps, applies lifecycle, freezes, and returns a linked value.',
+                    summary: 'Parses, preprocesses, 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.',
@@ -220,7 +221,7 @@ export const PACKAGE_API: PackageApiContract = {
             fields: {
                 moduleName: 'Logical module identifier without platform prefix.',
                 platform: '"teq" | "node" | "npm".',
-                exportName: 'Named export or "default"; null means whole-module/as-is resolution.',
+                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.',
@@ -267,15 +268,16 @@ export const PACKAGE_API: PackageApiContract = {
             kind: 'module-contract',
             summary: 'Shape expected from application modules resolved by the container.',
             fields: {
-                __deps__: 'Optional dependency descriptor. Accepted forms are: absent/empty, a flat Record<dependencyKey, CDC string> for a dependency-free default export or limited single-export shorthand, or a hierarchical Record<exportName, Record<dependencyKey, CDC string>> for named exports.',
+                __deps__: 'Optional dependency descriptor. Canonical form is hierarchical Record<exportName, Record<dependencyKey, CDC string>>. Supported shorthand form is a flat Record<dependencyKey, CDC string> for default-export-only modules. Omission means there are no declared dependencies.',
                 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.',
+                namedExports: 'May be selected via __ExportName for factory composition and may also provide wrapper exports.',
                 wrapperExport: 'Named export whose identifier appears in depId.wrappers; it must be synchronous and unary.',
             },
             notes: [
-                'The runtime accepts hierarchical descriptors for named exports and the flat shorthand form for dependency-free default exports or limited single-export cases.',
-                'Wrapper functions are exported by the same resolved module namespace, not registered globally in the container.',
+                'The hierarchical export-scoped descriptor is canonical.',
+                'The flat shorthand descriptor is supported only for default-export-only modules and does not replace the canonical hierarchical model.',
+                'Wrapper exports are resolved from the same module namespace and are not globally registered in the container.',
             ],
         },
     ],
@@ -429,8 +431,8 @@ export const PACKAGE_API: PackageApiContract = {
     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.',
-        'Dependency descriptors are canonical when hierarchical and export-scoped; flat descriptors are shorthand for limited single-export cases; omission means no dependencies.',
-        'With the default parser, CDC without lifecycle returns the whole module namespace as-is; named export selection implies factory composition.',
+        'The hierarchical export-scoped descriptor is canonical. The flat shorthand descriptor is supported only for default-export-only modules.',
+        'With the default parser, CDC without lifecycle resolves the selected module export as-is.',
         '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.',

package/ai/usage.md

@@ -1,26 +1,22 @@
 # usage.md
 
-Version: 20260331
+Version: 20260606
 
 ## Purpose
 
-This document describes typical usage patterns of the container. The examples illustrate how modules declare dependencies, how the container is configured in the composition root, and how Canonical Dependency Codes (CDC) control dependency resolution, instantiation, and behavioral modification.
+This document shows canonical usage patterns for the container. Examples are intentionally short and prioritize supported, recommended forms over convenience shorthand.
 
-The container performs deterministic runtime linking of ES modules and returns frozen object graphs constructed from explicitly declared dependency contracts.
+## Canonical Module Descriptor
 
-## Module Structure
-
-Modules intended for container linking may expose a default export, a named export, or both. The static dependency descriptor `__deps__` is canonical when it is hierarchical and keyed by export name. It describes the dependencies of the export selected by the CDC.
-
-Dependencies are injected into the constructor as a single structured object. In TeqFW-style modules the public API is defined inside the constructor through assignments to `this`, while internal state may be held in constructor-local variables captured by closures.
-
-Minimal single-export example:
+The canonical form of `__deps__` is hierarchical and keyed by export name.
 
 ```js
 // @ts-check
 
 export const __deps__ = {
-  cast: "App_Helper_Cast$",
+  default: {
+    cast: "App_Helper_Cast$",
+  },
 };
 
 export default class App_Root {
@@ -53,48 +49,14 @@ export default function App_Helper_Cast() {
 
 Rules:
 
-- the canonical form of `__deps__` is hierarchical and keyed by export name
-- each export entry maps constructor dependency names to CDC identifiers
-- if `__deps__` is absent the module has no dependencies
-- a flat `__deps__` object is shorthand for a dependency-free default export or limited single-export cases
-- a named export may declare dependencies without requiring a `default` entry
-- dependencies are resolved recursively before instantiation
-
-When the CDC selects `App_Module$`, the container uses the default export. When the CDC selects `App_Module__Factory$`, the container uses the named export `Factory`.
-
-Canonical export-scoped form:
-
-```js
-export const __deps__ = {
-  default: {
-    cast: "App_Helper_Cast$",
-  },
-  Factory: {
-    cast: "App_Helper_Cast$",
-  },
-};
-
-export default class RuntimeWrapper {
-  constructor() {
-    return {mode: "wrapper"};
-  }
-}
-
-export class Factory {
-  constructor({ cast }) {
-    this.configure = function (params = {}) {
-      return {
-        mode: "factory",
-        name: cast(params.name ?? "app"),
-      };
-    };
-  }
-}
-```
+- the hierarchical export-scoped form is canonical;
+- each export entry maps constructor dependency names to CDC identifiers;
+- if `__deps__` is omitted, the module has no declared dependencies;
+- dependencies are resolved recursively before instantiation.
 
-## Container Configuration
+## Canonical Container Setup
 
-The container is configured in the composition root of the application. Namespace roots define how CDC prefixes map to module locations.
+The container is configured in the composition root before the first resolution.
 
 ```js
 import path from "node:path";
@@ -105,230 +67,128 @@ const __filename = fileURLToPath(import.meta.url);
 const __dirname = path.dirname(__filename);
 
 const container = new Container();
-
 container.addNamespaceRoot("App_", path.resolve(__dirname, "./src/App"), ".mjs");
 ```
 
-Configuration must be completed before the first dependency resolution.
-
-Browser-oriented or isomorphic configuration may also use URL-based import roots:
+Namespace roots may also use URL-backed module-specifier bases:
 
 ```js
 container.addNamespaceRoot("App_", "https://cdn.example.com/app", ".mjs");
-container.addNamespaceRoot("Web_", "//cdn.example.com/web", ".mjs");
 ```
 
-## Resolving Dependencies
+## Resolve Root Dependency
 
-Dependencies are obtained using CDC identifiers.
+Applications typically resolve one root dependency and let the container build the full object graph.
 
 ```js
 const root = await container.get("App_Root$");
-```
-
-The container:
-
-- parses the CDC
-- loads the module
-- resolves dependencies declared in `__deps__`
-- instantiates modules
-- links the dependency graph
-- freezes the produced value
-
-Example usage:
-
-```js
 console.log(root.configure({name: 123}).name);
 console.log(Object.isFrozen(root));
 ```
 
-## Typical CDC Usage Patterns
-
-CDC identifiers define how the container interprets a dependency. The following patterns represent common usage scenarios.
-
-### Module As-Is
-
-A CDC without lifecycle marker returns the module export as-is.
-
-```text
-App_Service
-```
-
-Typical usage:
-
-- utility modules
-- stateless helpers
-- constant providers
-
-Example:
-
-```js
-const math = await container.get("App_Math");
-```
-
-### Singleton from Default Export
-
-A lifecycle marker `$` creates a singleton instance.
-
-```text
-App_Service$
-```
-
-Typical usage:
-
-- application services
-- repositories
-- infrastructure adapters
-
-### Transient Instance
-
-Marker `$$` creates a new instance for every request.
-
-```text
-App_Service$$
-```
-
-Typical usage:
-
-- request objects
-- short-lived workers
-- task processors
-
-### Named Export Resolution
-
-CDC may reference a named export using the `__ExportName` segment.
-
-```text
-App_Module__build$
-```
-
-Typical usage:
-
-- builders
-- factory entry points
-- specialized constructors
+## Named Export
 
-For modules with a runtime default export and a DI-managed named export, the canonical descriptor follows the export-scoped hierarchical form, for example:
+Named exports use the `__ExportName` segment in the CDC and the same hierarchical `__deps__` structure.
 
 ```js
 export const __deps__ = {
   default: {
-    cast: "Fl32_Web_Helper_Cast$",
+    cast: "App_Helper_Cast$",
   },
   Factory: {
-    cast: "Fl32_Web_Helper_Cast$",
+    cast: "App_Helper_Cast$",
   },
 };
 
 export default class RuntimeWrapper {
   constructor() {
-    return {mode: "wrapper"};
+    return {mode: "runtime"};
   }
 }
 
 export class Factory {
   constructor({ cast }) {
     this.configure = function (params = {}) {
-      return {cast, params};
+      return {
+        mode: "factory",
+        name: cast(params.name ?? "app"),
+      };
     };
   }
 }
 ```
 
-### Wrapper Application
+Resolution examples:
 
-Wrappers modify the produced value through postprocess plugins.
-
-```text
-App_Service$$_log_trace
+```js
+const runtime = await container.get("App_Module$");
+const factory = await container.get("App_Module__Factory$");
 ```
 
-The container creates the dependency and applies wrappers in declared order.
+## Singleton And Transient
 
-### Shorthand Form
+Common lifecycle-based compositions:
 
-Some single-export modules may use a flat `__deps__` object as shorthand.
-
-```js
-export const __deps__ = {
-  cast: "App_Helper_Cast$",
-};
+```txt
+App_Service$
+App_Task$$
+App_Task$$$
 ```
 
-This form is a convenience for limited cases and does not replace the canonical hierarchical model.
+- `$` creates and reuses a singleton instance;
+- `$$` creates a new instance for each request;
+- `$$$` is a transient alias in the current implementation.
 
-### Empty Descriptor
+## Wrappers
 
-Modules with no declared dependencies omit `__deps__` entirely.
+Wrapper exports are selected by CDC suffixes and are applied after postprocess hooks.
 
-```js
-export default class App_Empty {
-  constructor() {
-    this.ready = function () {
-      return true;
-    };
-  }
-}
+```txt
+App_Service$$_wrapLog_wrapTrace
 ```
 
-Typical usage:
+This pattern is useful when runtime behavior should be decorated without changing the service module contract.
 
-- logging
-- tracing
-- metrics collection
-- behavioral instrumentation
+## Platform Modules
 
-### Platform Dependencies
+CDC may refer to platform modules directly.
 
-CDC may reference runtime platform modules.
-
-```text
+```txt
 node:fs
 npm:@humanfs/core
 node:worker_threads
-npm:lodash
 ```
 
-These identifiers provide access to Node.js built-ins and npm packages.
-
-Typical usage:
+These forms resolve the selected platform module export as-is unless a lifecycle marker is explicitly added.
 
-- `node:worker_threads` for Node.js worker-thread primitives
-- `npm:@humanfs/core` for a scoped npm package dependency
+## Non-Canonical Shorthand
 
-### Root Graph Resolution
-
-Applications typically resolve a single root dependency.
+A flat `__deps__` object is a supported shorthand for default-export-only modules, but it is not the canonical model.
 
 ```js
-const root = await container.get("App_Root$");
-```
-
-The container recursively resolves all dependencies declared through `__deps__` and constructs the object graph. Empty descriptor modules omit `__deps__` entirely.
-
-## Wrapper-Based Behavioral Composition
-
-Wrappers enable declarative behavioral composition at the dependency level. By attaching wrapper identifiers to CDC strings the caller can modify the runtime behavior of a dependency without modifying its module implementation.
-
-Example:
+export const __deps__ = {
+  cast: "App_Helper_Cast$",
+};
 
-```text
-App_Service$$_log
+export default class App_Short {
+  constructor({ cast }) {
+    this.cast = cast;
+  }
+}
 ```
 
-The service module remains unaware of logging. The wrapper introduces cross-cutting behavior during the container postprocess stage.
-
-This mechanism enables patterns similar to aspect-oriented programming while preserving deterministic dependency resolution.
+Prefer the hierarchical form for new integrations and for any module that exposes named exports.
 
-## Minimal Smoke Pattern
+## Empty Descriptor
 
-A minimal integration scenario demonstrating container operation:
+Modules with no declared dependencies omit `__deps__` entirely.
 
 ```js
-const container = new Container();
-container.addNamespaceRoot("Fx_", FIXTURE_DIR, ".mjs");
-
-const value = await container.get("Fx_Root$");
+export default class App_Empty {
+  constructor() {
+    this.ready = function () {
+      return true;
+    };
+  }
+}
 ```
-
-The container loads modules, resolves dependencies, instantiates objects, and returns a frozen result.