@teqfw/di 2.5.0 → 2.6.0

package/ai/AGENTS.md

@@ -1,75 +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 **dependency container for ES modules** based on runtime late binding. Dependencies between modules are resolved by the container using structured dependency identifiers and deterministic namespace resolution rules rather than static imports. The container dynamically loads ES modules, instantiates exported factories, and returns linked objects according to dependency identifier semantics.
+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
+- 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:
 
-## Architectural Model
+- 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/`.
 
-The system is based on four mechanisms:
+## Level Map
 
-- **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.
+- `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.
 
-Together these mechanisms form a deterministic runtime linking system for ES modules.
+## Reading Guide
 
-## Runtime Linking Model
+Read documents by task:
 
-The container acts as a runtime linker for ES modules.
+- 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`.
 
-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.
+If the task is broad or unclear, read in this order:
 
-In this model:
+1. `AGENTS.md`
+2. `package-api.ts`
+3. `usage.md`
+4. `dependency-id.md`
+5. `container.md`
+6. remaining documents as needed
 
-- ES modules provide implementations.
-- CDC identifiers define dependency contracts.
-- the container performs deterministic runtime linking.
+## Authority
 
-This mechanism separates module implementation from dependency binding and allows systems to assemble component graphs dynamically while preserving deterministic behavior.
+The documents in `ai/` define the supported agent-facing usage semantics of the package.
 
-## 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.
-
-## 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.
+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 a namespace root that corresponds to a directory containing source modules.
+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 filesystem paths. This mechanism allows modules to be referenced through stable logical names instead of file paths.
+## 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,72 +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.
 
-- **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:
 
-## Container State Model
+- `builder` — configuration is still mutable.
+- `operational` — dependency resolution is active.
+- `failed` — a fatal pipeline error has occurred.
 
-The container operates in three states:
+State transitions:
 
-- **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.
+- 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`.
 
-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.
+## Freeze Semantics
 
-This fail-fast behavior prevents partially linked systems from continuing execution.
+Values returned by the container are frozen before they are returned to callers.
+
+Freeze happens after:
 
-## Object Linking and Freezing
+- instantiation;
+- postprocess hooks;
+- wrapper exports;
+- lifecycle application.
 
-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.
+This means consumers receive stable linked values and should not mutate them.
 
-Freezing ensures that:
+## Failure Semantics
 
-- linked objects cannot be modified by consumers
-- shared instances remain stable
-- the container remains the only authority responsible for object construction and linking
+If any fatal error occurs during parsing, preprocessing, resolution, instantiation, postprocessing, wrapping, or lifecycle handling, the container enters `failed` state.
+
+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 filesystem paths 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,17 +54,17 @@ Example:
 App_Service_User
 ```
 
-maps to a module located at:
+may map to a module-specifier base such as:
 
 ```txt
-AppRoot/Service/User.js
+AppRoot/Service/User.mjs
 ```
 
-## Export Selection
+The base may be filesystem-backed or URL-backed depending on runtime configuration.
 
-A CDC may reference either the default export of a module or a named export.
+## Export Selection
 
-Named exports are selected using a double underscore separator.
+Named exports are selected with a double underscore separator.
 
 Examples:
 
@@ -77,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.
 
-Lifecycle markers are appended at the end of the identifier.
+Examples:
+
+```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.