@teqfw/di 2.5.1 → 2.6.0

package/ai/AGENTS.md

@@ -1,94 +1,62 @@
 # AGENTS.md
 
-Version: 20260331
+Version: 20260606
 
-## Package Purpose
+## Purpose
 
-This directory provides the **Agent Interface** of the package. It contains a compact usage-oriented description intended for LLM agents that use the package as a dependency. The documents describe how the package is applied by external code and exclude development methodology, repository organization, testing infrastructure, and other internal aspects of the project.
+This file defines the `ai/` level for agent-facing package documentation included in the distributable package.
 
-The package implements a **deterministic runtime dependency linker for ES modules** based on late binding. Dependencies between modules are resolved by the container using structured dependency identifiers and namespace resolution rules rather than application-level static imports. The container dynamically loads ES modules, instantiates exports according to CDC semantics, and returns linked frozen values.
+The `ai/` directory provides a compact machine-oriented interface for agents that need to understand and use the package correctly.
 
-## When to Use This Package
+## Level Boundary
 
-This package should be used when a system requires the following capabilities:
+This level defines:
 
-- runtime dependency injection
-- late binding between ES modules
-- deterministic dependency resolution
-- controlled instantiation of components
-- modules that remain environment-agnostic across Node.js and browser runtimes
-- explicit machine-readable dependency structure for agent-assisted maintenance
+- what documents exist in `ai/`;
+- what each document is for;
+- how an agent should navigate this directory;
+- which documents describe supported usage.
 
-The container serves as the **composition root** of the application. Application modules declare dependencies and receive instantiated objects from the container rather than resolving dependencies directly.
+This level does not define:
 
-This package is primarily a fit for:
+- repository organization;
+- development workflow;
+- testing strategy;
+- internal implementation details that are not part of the supported surface;
+- behavior not described by the documents in `ai/`.
 
-- modular monolith web applications
-- isomorphic JavaScript systems with shared browser/server code
-- pure JavaScript + JSDoc codebases
+## Level Map
 
-It is usually not a natural fit for TypeScript-first architectures built around decorators, metadata, or framework-managed DI conventions.
+- `AGENTS.md` — entry point for this level; defines scope, navigation, and authority.
+- `concepts.md` — core concepts behind runtime linking and dependency contracts.
+- `container.md` — container lifecycle, state model, and resolution pipeline.
+- `dependency-id.md` — normative CDC grammar and interpretation rules.
+- `extensions.md` — preprocess hooks, postprocess hooks, and wrapper exports.
+- `package-api.ts` — machine-readable contract of the supported programmatic surface.
+- `usage.md` — canonical usage patterns and short integration recipes.
 
-## Architectural Model
+## Reading Guide
 
-The system is based on four mechanisms:
+Read documents by task:
 
-- **Late binding of dependencies at runtime**, allowing modules to remain independent of specific implementations.
-- **A container responsible for dependency resolution and instantiation**, which loads modules and produces linked objects.
-- **Structured dependency identifiers**, interpreted by the container to determine how a dependency must be resolved.
-- **Namespace mapping rules**, which deterministically translate identifiers into module locations.
+- for supported imports and public surface, start with `package-api.ts`;
+- for CDC syntax and meaning, read `dependency-id.md`;
+- for runtime behavior of the container, read `container.md`;
+- for extension behavior, read `extensions.md`;
+- for practical integration examples, read `usage.md`;
+- for conceptual orientation, read `concepts.md`.
 
-Together these mechanisms form a deterministic runtime linking system for ES modules.
+If the task is broad or unclear, read in this order:
 
-## Runtime Linking Model
+1. `AGENTS.md`
+2. `package-api.ts`
+3. `usage.md`
+4. `dependency-id.md`
+5. `container.md`
+6. remaining documents as needed
 
-The container acts as a runtime linker for ES modules.
+## Authority
 
-Instead of relying on static `import` statements, modules declare dependency contracts through `__deps__` descriptors and CDC identifiers. When a dependency is requested, the container resolves the identifier, loads the required module, constructs the object graph, and returns the linked result.
+The documents in `ai/` define the supported agent-facing usage semantics of the package.
 
-In this model:
-
-- ES modules provide implementations.
-- CDC identifiers define dependency contracts.
-- the container performs deterministic runtime linking.
-- linked values are frozen before they are returned.
-
-This mechanism separates module implementation from dependency binding and allows systems to assemble component graphs dynamically while preserving deterministic behavior.
-
-## Reading Order
-
-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. **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.
-
-Agents that need a working integration should prefer:
-
-1. `package-api.ts` for the programmatic surface,
-2. `usage.md` for examples,
-3. `dependency-id.md` for CDC details,
-4. `container.md` for behavioral guarantees.
-
-## Interface Scope
-
-The documents in this directory define the supported usage semantics of the package. Behaviors not described here should be treated as undefined and should not be inferred. The interface intentionally contains only the information required to correctly apply the package in external code.
-
-## Relation to TeqFW
-
-The package follows architectural principles used in the **Tequila Framework (TeqFW)** platform, including:
-
-- late binding between components
-- separation of data structures and logic handlers
-- namespace-based module organization
-- development in modern JavaScript without compilation
-
-Understanding the broader TeqFW ecosystem is not required to use the package, but the container follows the same architectural philosophy.
-
-For agent usage, this directory is the package's machine-oriented interface. Prefer these documents over inferring behavior from repository-level prose.
+Agents should rely on these documents for package use and should treat behavior not described here as undefined.

package/ai/concepts.md

@@ -1,68 +1,25 @@
 # concepts.md
 
-Version: 20260331
-
-## Purpose of the Container
-
-The container provides a deterministic mechanism for linking ES modules at runtime. Instead of static imports between modules, dependencies are resolved through a central container that loads modules, instantiates exported factories, and returns linked objects. This approach separates module implementation from dependency resolution and allows systems to assemble components dynamically.
+Version: 20260606
 
 ## Late Binding
 
-Dependencies between modules are resolved at runtime rather than during module loading. Modules do not import their collaborators directly and therefore remain independent of concrete implementations. The container performs dependency resolution when an object is requested, which allows components to be replaced, extended, or mocked without modifying module code.
-
-Late binding enables the following properties:
-
-- reduced coupling between modules
-- runtime replacement of implementations
-- simplified testing through dependency substitution
-- compatibility with different runtime environments
-
-## Dependency Container
-
-The container acts as the composition root of the application. It receives dependency requests expressed as identifiers, resolves them into module locations, loads the corresponding ES modules, and produces linked objects.
-
-The container is responsible for:
-
-- translating dependency identifiers into module references
-- loading ES modules dynamically
-- instantiating exported factories
-- applying preprocessing and postprocessing steps
-- returning fully linked objects to the caller
-
-Application modules do not construct their dependencies directly and do not perform dependency resolution.
-
-## Dependency Identifiers
-
-Dependencies are addressed using structured identifiers interpreted by the container. An identifier describes how the dependency should be resolved and how the resulting object should be instantiated.
-
-Dependency identifiers define:
-
-- which module provides the dependency
-- which export must be used
-- whether the dependency represents a singleton or a new instance
-
-Module dependency descriptors complement CDCs by declaring export-scoped dependency maps. The canonical form is hierarchical and keyed by export name; a flat descriptor is shorthand for limited single-export cases; omission means there are no dependencies.
-
-The identifier syntax and resolution rules are described in **dependency-id.md**.
+Dependencies are resolved at runtime rather than through direct static imports between application modules. This keeps modules independent of concrete implementations and moves dependency binding into the container.
 
-## Namespaces
+## Runtime Linker
 
-Namespaces provide deterministic mapping between logical identifiers and module locations. Each package defines one or more namespace roots that map a CDC prefix to a module-specifier base.
+The container acts as a runtime linker for ES modules. It interprets CDC identifiers, resolves modules, selects exports, and produces linked values for callers.
 
-The container resolves identifiers by applying namespace rules that translate identifier prefixes into module specifiers. In Node.js this often means filesystem-backed paths. In browser-oriented or isomorphic systems this may also mean URL-based import roots.
+## Dependency Contracts
 
-Namespace resolution ensures:
+Dependencies are declared through CDC strings and module-level `__deps__` descriptors. Together they form the contract between module code and runtime composition.
 
-- predictable module addressing
-- isolation between packages
-- consistent mapping between identifiers and modules
+The canonical `__deps__` form is hierarchical and keyed by export name.
 
-## Immutable Linked Objects
+## Namespace Mapping
 
-Objects returned by the container represent linked components of the application and are treated as immutable values. After an object is created and linked, it is frozen to prevent runtime modification.
+Logical module identifiers are translated into module-specifier bases through namespace roots. This keeps dependency addressing independent from concrete filesystem paths or URL locations.
 
-Immutability ensures that:
+## Immutable Linked Values
 
-- components behave consistently after linking
-- shared instances cannot be altered by consumers
-- the container remains the single authority responsible for object construction
+Values returned by the container are frozen after linking. Consumers should treat them as stable resolved values rather than mutable construction targets.

package/ai/container.md

@@ -1,75 +1,84 @@
 # container.md
 
-Version: 20260331
+Version: 20260606
 
-## Role of the Container
+## Role
 
-The container provides the operational mechanism that links ES modules at runtime. It resolves dependency identifiers, loads modules, instantiates exported factories, and returns fully linked objects. The container serves as the composition root of the system and centralizes all dependency resolution.
+The container is the runtime composition root of the package. It interprets CDC identifiers, resolves them into modules, produces linked values, and returns frozen results.
 
-Application modules do not resolve dependencies themselves and do not construct collaborators directly. Instead, they request dependencies from the container using dependency identifiers.
+Application modules do not resolve dependencies themselves. They declare dependency contracts and rely on the container to perform linking.
 
-## Container Responsibilities
+## Configuration Stage
 
-The container performs the following responsibilities:
+Before the first `get()`, the container is in builder stage.
 
-- interpret dependency identifiers
-- resolve identifiers into module locations
-- load ES modules dynamically
-- instantiate exported factories
-- apply preprocess and postprocess handlers
-- manage object lifecycle semantics
-- freeze linked objects before returning them
+During this stage external code may:
 
-These responsibilities ensure deterministic runtime linking between modules.
+- register namespace roots with `addNamespaceRoot()`;
+- replace the CDC parser with `setParser()`;
+- add preprocess hooks with `addPreprocess()`;
+- add postprocess hooks with `addPostprocess()`;
+- enable diagnostics with `enableLogging()`;
+- enable test-only mock registration with `enableTestMode()` and `register()`.
 
-## Dependency Resolution Pipeline
+On the first `get()`:
 
-When a dependency is requested, the container processes the request through a deterministic pipeline consisting of the following stages:
+- configuration is locked;
+- namespace rules are snapshotted;
+- internal resolution infrastructure is created.
 
-1. **Parse** — interpret the dependency identifier.
-2. **Preprocess** — allow registered preprocess handlers to transform the identifier.
-3. **Resolve** — translate the identifier into a module reference.
-4. **Instantiate** — load the module and create the object using the selected export.
-5. **Postprocess** — apply wrapper handlers to the created object.
-6. **Lifecycle** — apply lifecycle semantics such as singleton caching or instance creation.
-7. **Freeze** — freeze the resulting object before returning it.
+After the first `get()`, builder-stage methods are no longer supported.
 
-This pipeline ensures that all dependencies are created and linked through a consistent process.
+## Resolution Pipeline
 
-## Container API
+For each `get(cdc)` request the container applies this pipeline:
 
-The container exposes a minimal public interface used by application code and configuration code.
+1. `Parse` — convert the CDC string into a DepId DTO.
+2. `Preprocess hooks` — transform the DepId DTO through ordered `addPreprocess()` hooks.
+3. `Resolve` — map the identifier to a concrete module location.
+4. `Instantiate` — load the module and either return the selected export as-is or instantiate it according to lifecycle composition rules.
+5. `Postprocess hooks` — apply ordered `addPostprocess()` value transforms.
+6. `Wrapper exports` — apply ordered wrapper exports selected by CDC suffixes.
+7. `Lifecycle` — apply singleton caching or transient behavior.
+8. `Freeze` — freeze the resolved value before returning it.
 
-The core operations are:
+The pipeline is deterministic for a fixed configuration and input CDC.
 
-- **addNamespaceRoot(prefix, target, defaultExt)** — register namespace resolution rule for Teq modules.
-- **register(identifier, value)** — register a predefined dependency or instance in the container.
-- **get(identifier)** — resolve a dependency identifier and return the linked object.
-- **addPreprocess(handler)** — register a handler that can transform dependency identifiers before resolution.
-- **addPostprocess(handler)** — register a handler that can modify created objects after instantiation.
+## State Model
 
-The exact semantics of dependency identifiers are defined in **dependency-id.md**. Dependency descriptors are export-scoped: canonical descriptors are hierarchical and keyed by export name, while flat descriptors are shorthand for limited single-export cases.
+The container operates in three states:
 
-`addNamespaceRoot(prefix, target, defaultExt)` accepts a module-specifier base. The `target` may point to a filesystem-backed path or to a URL-backed import base depending on runtime environment.
+- `builder` — configuration is still mutable.
+- `operational` — dependency resolution is active.
+- `failed` — a fatal pipeline error has occurred.
 
-## Container State Model
+State transitions:
 
-The container operates in three states:
+- construction starts in `builder`;
+- the first successful or failed `get()` transitions the container out of mutable builder configuration;
+- a fatal resolution error moves the container to `failed`.
 
-- **notConfigured** — the container is being configured and dependencies may be registered.
-- **operational** — the container resolves dependencies and produces linked objects.
-- **failed** — the container has encountered an unrecoverable error.
+## Freeze Semantics
 
-If an error occurs during dependency resolution or any pipeline stage, the container transitions to the **failed** state. Once the container enters this state, all subsequent dependency requests are rejected.
+Values returned by the container are frozen before they are returned to callers.
 
-This fail-fast behavior prevents partially linked systems from continuing execution.
+Freeze happens after:
+
+- instantiation;
+- postprocess hooks;
+- wrapper exports;
+- lifecycle application.
 
-## Object Linking and Freezing
+This means consumers receive stable linked values and should not mutate them.
 
-Objects returned by the container represent linked components of the application. After an object is created and all pipeline stages are completed, the container freezes the object before returning it.
+## Failure Semantics
 
-Freezing ensures that:
+If any fatal error occurs during parsing, preprocessing, resolution, instantiation, postprocessing, wrapping, or lifecycle handling, the container enters `failed` state.
 
-- linked objects cannot be modified by consumers
-- shared instances remain stable
-- the container remains the only authority responsible for object construction and linking
+Once in `failed` state:
+
+- the current `get()` request rejects;
+- all subsequent `get()` calls reject;
+- the container does not attempt partial recovery.
+
+This fail-fast behavior prevents partially linked systems from continuing execution.

package/ai/dependency-id.md

@@ -1,56 +1,52 @@
 # dependency-id.md
 
-Version: 20260331
+Version: 20260606
 
 ## Purpose
 
-Dependencies in the container are addressed using **Canonical Dependency Codes (CDC)**. A CDC is a structured identifier interpreted by the container to determine which module must be loaded, which export must be used, and how the resulting object must be instantiated.
+Dependencies in the container are addressed using **Canonical Dependency Codes (CDC)**. A CDC is a structured identifier interpreted by the container to determine which module must be loaded, which export must be selected, and whether the resolved value is returned as-is or instantiated with lifecycle semantics.
 
-CDC provides a stable logical addressing mechanism that is independent of file paths and runtime environments.
-
-## Canonical Form
-
-A CDC follows the canonical structure:
+## Grammar
 
 ```txt
-[PlatformPrefix]ModuleName[__ExportName][Lifecycle][WrapperSuffixes]
+CDC := [PlatformPrefix]ModuleName[__ExportName][Lifecycle][WrapperSuffixes]
 ```
 
-The components have the following roles:
+Component order is fixed.
+
+- `PlatformPrefix` is optional.
+- `__ExportName` is optional.
+- `Lifecycle` is optional.
+- `WrapperSuffixes` are optional and require a lifecycle marker.
 
-- **PlatformPrefix** — optional prefix identifying a platform module source.
-- **ModuleName** — logical module identifier within a namespace.
-- **ExportName** — optional named export selector.
-- **Lifecycle** — marker defining instantiation semantics.
-- **WrapperSuffixes** — optional sequence of wrapper identifiers.
+## Components
 
-Each CDC is interpreted deterministically by the container.
+- `PlatformPrefix` — optional source selector such as `node:` or `npm:`.
+- `ModuleName` — logical module identifier inside a namespace.
+- `__ExportName` — optional named export selector. Omission means the default export for composition, or whole-module namespace for as-is resolution.
+- `Lifecycle` — optional instantiation marker.
+- `WrapperSuffixes` — optional ordered wrapper export names appended after the lifecycle marker.
 
-## Platform Prefix
+## Platform Prefixes
 
-A CDC may reference modules provided by the runtime platform or external packages.
+Supported prefixes:
 
-The following prefixes are supported:
+- `node:` — reference a built-in Node.js module.
+- `npm:` — reference an npm package.
 
-- **`node:`** — reference a built-in Node.js module.
-- **`npm:`** — reference a module from the npm ecosystem.
+If no platform prefix is present, the identifier refers to an application module resolved through namespace roots.
 
 Examples:
 
 ```txt
-node:fs$
-npm:@humanfs/core$
-node:worker_threads$
-npm:lodash$
+node:fs
+npm:@humanfs/core
+App_Service_User$
 ```
 
-If no platform prefix is present, the identifier refers to an application module resolved through namespace mapping.
-
 ## Module Identification
 
-The **ModuleName** identifies the module that provides the dependency. Module identifiers use namespace-based naming and are translated into module specifiers according to namespace resolution rules described in **container.md**.
-
-Identifier segments separated by underscores correspond to directory boundaries in the module path.
+`ModuleName` identifies the provider module. Identifier segments separated by underscores correspond to path segments inside the configured namespace root.
 
 Example:
 
@@ -58,19 +54,17 @@ Example:
 App_Service_User
 ```
 
-maps to a module path such as:
+may map to a module-specifier base such as:
 
 ```txt
-AppRoot/Service/User.js
+AppRoot/Service/User.mjs
 ```
 
-In URL-backed namespace configurations the same logical name may instead map to a URL-based module specifier with the same segment structure.
+The base may be filesystem-backed or URL-backed depending on runtime configuration.
 
 ## Export Selection
 
-A CDC may reference either the default export of a module or a named export.
-
-Named exports are selected using a double underscore separator.
+Named exports are selected with a double underscore separator.
 
 Examples:
 
@@ -79,49 +73,73 @@ App_Service_User$
 App_Service_User__Factory$
 ```
 
-The first identifier resolves the module default export. The second resolves the named export `Factory`.
+- `App_Service_User$` selects the default export for lifecycle-based composition.
+- `App_Service_User__Factory$` selects the named export `Factory` for lifecycle-based composition.
 
 ## Lifecycle Markers
 
-Lifecycle markers define how the container instantiates and returns objects.
+Supported lifecycle markers:
 
-The following markers are supported:
+- `$` — singleton lifecycle; create once and reuse the same instance.
+- `$$` — transient lifecycle; create a new instance each time.
+- `$$$` — transient alias; behaves the same as `$$` in the current implementation.
 
-- **`$`** — singleton lifecycle; the container creates the object once and returns the same instance for subsequent requests.
-- **`$$`** — transient lifecycle; a new instance is created for each request.
-- **`$$$`** — transient lifecycle alias; behaves the same as `$$`.
+If the lifecycle marker is omitted, the selected module export is resolved **as-is** and is not instantiated by lifecycle rules.
+
+Examples:
 
-Lifecycle markers are appended at the end of the identifier.
+```txt
+App_Math
+App_Service$
+App_Task$$
+```
 
 ## Wrapper Suffixes
 
-Wrappers allow postprocessing of created objects. Wrapper identifiers are appended after the lifecycle marker and separated by underscores.
+Wrapper suffixes are appended after the lifecycle marker and separated by underscores.
 
 Example:
 
 ```txt
-App_Service_User$$_wrapLog_wrapTrace
+App_Service$$_wrapLog_wrapTrace
 ```
 
-In this example the container creates a new instance and applies the wrappers `wrapLog` and `wrapTrace` during the postprocess stage.
+In this example the container creates a transient instance, then applies wrapper exports `wrapLog` and `wrapTrace` in the declared order.
 
-Wrapper behavior is described in **extensions.md**.
+Wrapper exports are described in `extensions.md`.
 
-Platform-specific examples:
+## Interpretation Rules
 
-```txt
-node:worker_threads$
-npm:@humanfs/core$
-```
+When the container receives a CDC it interprets it in this order:
+
+1. determine the platform prefix and module namespace;
+2. resolve the module identifier into a module location;
+3. select the default export, a named export, or the whole module namespace for as-is resolution;
+4. apply lifecycle semantics if a lifecycle marker is present;
+5. apply wrapper exports if wrapper suffixes are present.
 
-## Resolution Semantics
+Important rules:
 
-When the container receives a CDC it performs the following interpretation steps:
+- no lifecycle marker means as-is resolution of the selected export;
+- wrapper suffixes are meaningful only for lifecycle-based composition;
+- named export selection does not by itself imply singleton or transient behavior;
+- lifecycle and wrappers are interpreted after export selection.
+
+## Canonical Examples
+
+```txt
+App_Math
+App_Service$
+App_Service__Factory$
+App_Task$$_wrapLog
+node:fs
+npm:@humanfs/core
+```
 
-1. determine the platform prefix and module namespace
-2. resolve the module identifier into a module location
-3. select the requested export
-4. apply lifecycle semantics
-5. apply wrapper suffixes if present
+These examples cover:
 
-These interpretation steps integrate with the dependency resolution pipeline described in **container.md**.
+- as-is module or export resolution;
+- singleton composition;
+- named export composition;
+- transient composition with wrapper exports;
+- platform module access.