@teqfw/di 2.4.0 → 2.5.1

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # Changelog
 
+## 2.5.1 - 2026-04-12 - Documentation refresh and dependency fix
+
+* Fixed named-only `__deps__` resolution in the container and updated the related tests.
+* Rewrote the README and refreshed the `ai/` agent documentation for the current release line.
+* Updated package version metadata to `2.5.1`.
+
+## 2.5.0 - 2026-04-04 - Parser and documentation refinement
+
+* Clarified JSDoc typing and module headers to align with TeqFW specifications.
+* Allowed parser recognition of Node.js built-ins that include underscores in their names.
+* Updated package version metadata to `2.5.0`.
+
 ## 2.4.0 - 2026-03-31 - Test coverage cleanup
 
 * Removed low-value unit tests in favor of broader integration coverage.

package/README.md

@@ -3,141 +3,65 @@
 ![npms.io](https://img.shields.io/npm/dm/@teqfw/di)
 ![jsdelivr](https://img.shields.io/jsdelivr/npm/hm/@teqfw/di)
 
-**Runtime dependency linker for JavaScript applications designed for development with LLM agents.**
+**Deterministic runtime dependency linker for ES modules, built for pure JavaScript applications with explicit contracts.**
 
-`@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.**
+`@teqfw/di` is a runtime container for JavaScript applications that want **late binding**, **explicit dependency declarations**, and **deterministic runtime linking** instead of application-level wiring through static imports.
 
-Instead of wiring modules through static imports, TeqFW applications declare **explicit dependency contracts**, and the container performs **deterministic runtime linking**.
+It is the reference implementation of the **Tequila Framework (TeqFW)** method: a way to structure modular monolith and isomorphic web applications around **Canonical Dependency Codes (CDC)** and module-level dependency descriptors (`__deps__`).
 
-The result is an application architecture that is easier to:
+In practice, "reference implementation of a method" means this package is not only a container library. It is also the concrete runtime model for a broader way of structuring JavaScript applications around explicit contracts, namespace-based addressing, and late binding.
 
-- analyze
-- generate
-- refactor
-- extend
+This package is designed primarily for:
 
-— both for **human developers and AI agents**.
+- modular monolith web applications;
+- isomorphic JavaScript systems that share code between browser and server;
+- pure JavaScript + JSDoc codebases;
+- projects developed or maintained with significant LLM-agent involvement.
 
-## The Shift in Software Development
+## Why Use It
 
-Large language models are becoming a permanent part of the development process.
+`@teqfw/di` provides:
 
-However, most software architectures were designed for **human-written code**, not for **code generated and maintained by AI agents**.
+- deterministic runtime linking of ES modules;
+- explicit dependency contracts through CDC and `__deps__`;
+- namespace-based module resolution;
+- lifecycle control for singleton and new-instance dependencies;
+- immutable linked objects;
+- wrapper-based extension points for cross-cutting behavior.
 
-Typical JavaScript applications rely on:
+The result is an application structure that is easier to analyze, test, replace, and evolve when dependency relationships need to remain explicit.
 
-- static imports
-- implicit dependency graphs
-- tight coupling to file structure
-- constructor-based dependency inference
+## How It Fits in JavaScript
 
-These patterns work well for humans but are difficult for automated agents to reason about reliably.
+This approach is unusual in mainstream JavaScript.
 
-**TeqFW proposes a different architecture.**
+Most JavaScript and TypeScript projects express dependency structure through some mix of:
 
-Modules declare **explicit dependency contracts**, and a runtime container resolves those contracts deterministically.
+- static imports;
+- framework conventions;
+- TypeScript-first source architecture;
+- decorators or metadata-driven injection;
+- framework-managed DI.
 
-This transforms the dependency graph into something that can be **analyzed, generated and modified programmatically.**
+`@teqfw/di` makes a different tradeoff. It favors **explicit runtime contracts** over hidden or inferred wiring. Instead of relying on TypeScript metadata or decorator-driven injection, modules declare dependencies directly as data and the container resolves them deterministically at runtime.
 
-## What This Library Provides
+That tradeoff is intentional.
 
-`@teqfw/di` implements the runtime container that enables this architecture.
+TypeScript has had a major influence on the JavaScript ecosystem, and that influence has been broadly positive. At the same time, JavaScript itself continues to evolve every year, steadily narrowing part of the gap in developer ergonomics and language expressiveness.
 
-It provides:
+For TypeScript-first ecosystems, other DI approaches are often a more natural fit because those ecosystems already rely on compile-time metadata, annotations, and framework or container conventions. TeqFW targets a different design space: **pure JavaScript + JSDoc**, isomorphic runtime behavior, and codebases where a single explicit structural representation is more valuable than TypeScript-oriented convenience.
 
-- 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
+This is not presented as the only correct way to structure JavaScript. It is a deliberate alternative for projects that benefit from stronger runtime explicitness and machine-reconstructible structure.
 
-The container acts as a **runtime linker for JavaScript applications**.
+## Comparison
 
-## 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`
+| Concern | Common TS/JS Approach | `@teqfw/di` |
+| --- | --- | --- |
+| Dependency structure | static imports, decorators, framework wiring | explicit CDC + `__deps__` |
+| Resolution model | partly implicit or framework-driven | deterministic runtime linking |
+| Structural source of truth | spread across code, metadata, config | declared in module contracts |
+| Best fit | TypeScript-first applications | pure JavaScript + JSDoc, isomorphic modular systems |
+| LLM readability | mixed, often indirect | intentionally explicit |
 
 ## Installation
 
@@ -145,17 +69,9 @@ Full philosophy:
 npm install @teqfw/di
 ```
 
-## Quick Example
-
-### Define modules
+## Quick Start
 
-`src/App/Child.mjs`
-
-```javascript
-export default function App_Child() {
-  return { name: "child" };
-}
-```
+Define one helper module and one module that declares its dependency explicitly.
 
 `src/App/Helper/Cast.mjs`
 
@@ -174,28 +90,20 @@ export const __deps__ = {
   cast: "App_Helper_Cast$",
 };
 
-export default class RuntimeWrapper {
-  constructor() {
-    return {
-      mode: "runtime-wrapper",
-    };
-  }
-}
-
-export class Factory {
+export default class App_Root {
   constructor({ cast }) {
-    this.configure = function (params = {}) {
-      return {
-        name: "factory",
-        cast,
-        params,
-      };
+    return {
+      configure(params = {}) {
+        return {
+          name: cast(params.name ?? "app"),
+        };
+      },
     };
   }
 }
 ```
 
-### Configure container
+Configure the container and request the dependency:
 
 ```javascript
 import path from "node:path";
@@ -206,116 +114,57 @@ 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 factory = await container.get("App_Root__Factory$");
+const app = await container.get("App_Root$");
 
-console.log(factory.configure().mode);
+console.log(app.configure({ name: 123 }).name);
+// "123"
 ```
 
-The container:
+In this flow the container:
+
+- parses the dependency request;
+- resolves the module through the registered namespace root;
+- reads `__deps__` for the selected export;
+- recursively links dependencies;
+- returns a frozen linked object.
 
-- loads modules
-- resolves dependency contracts
-- constructs the object graph
-- returns **frozen linked objects**
+## Core Concepts
 
-## Dependency Contracts (`__deps__`)
+### `__deps__`
 
-Modules declare dependencies using a static export descriptor.
+For a single-export module, dependencies can be declared in shorthand form:
 
 ```javascript
 export const __deps__ = {
-  default: {
-    localName: "Dependency_CDC",
-  },
-  Factory: {
-    localName: "Dependency_CDC",
-  },
+  localName: "Dependency_CDC",
 };
 ```
 
 Rules:
 
-- the canonical form is hierarchical and keyed by export name
-- each export entry maps constructor argument names to CDC dependency identifiers
-- if `__deps__` is absent — module has no dependencies
-- a flat `__deps__` object is a shorthand allowed only for limited single-export cases
-- dependencies are resolved recursively
+- the canonical form is hierarchical and keyed by export name;
+- each export entry maps constructor argument names to CDC strings;
+- if `__deps__` is absent, the export has no declared dependencies;
+- a flat `__deps__` object is shorthand for limited single-export cases.
 
-Canonical example:
+Canonical export-scoped form:
 
 ```javascript
 export const __deps__ = {
   default: {
-    cast: "Fl32_Web_Helper_Cast$",
+    localName: "Dependency_CDC",
   },
   Factory: {
-    cast: "Fl32_Web_Helper_Cast$",
+    localName: "Dependency_CDC",
   },
 };
-
-export default class RuntimeWrapper {
-  constructor() {
-    return {
-      mode: "runtime-wrapper",
-    };
-  }
-}
-
-export class Factory {
-  constructor({ cast }) {
-    this.configure = function (params = {}) {
-      // DI-managed component
-    };
-  }
-}
 ```
 
-In this pattern:
+### CDC
 
-- the default export is the runtime wrapper or module shell
-- the named `Factory` export is the DI-managed component
-- `__deps__` applies to the export selected by the CDC, such as `App_Module__Factory$`
-
-Shorthand example for a single-export module:
-
-```javascript
-export const __deps__ = {
-  cast: "Fl32_Web_Helper_Cast$",
-};
-
-export default class RuntimeWrapper {
-  constructor() {
-    return {
-      mode: "runtime-wrapper",
-    };
-  }
-}
-```
-
-Empty descriptor example:
-
-```javascript
-export default class App_Empty {
-  constructor() {
-    this.ready = function () {
-      return true;
-    };
-  }
-}
-```
-
-In this pattern:
-
-- the module has no declared dependencies
-- `__deps__` is omitted entirely
-- the empty form is valid and intentionally explicit through omission
-
-## Canonical Dependency Codes (CDC)
-
-CDC identifiers describe **how dependencies should be resolved**.
+A **Canonical Dependency Code** is the string contract used to request a dependency.
 
 General form:
 
@@ -326,89 +175,80 @@ General form:
 Examples:
 
 ```txt
-App_Service
 App_Service$
-App_Service__build$$
-App_Service$$_wrapLog_wrapTrace
+App_Service__Factory$$
 node:fs
-npm:@humanfs/core
-node:worker_threads
 npm:lodash
 ```
 
 Where:
 
-- `node:` platform prefix for Node.js built-in modules
-- `npm:` platform prefix for npm packages
-- `$` singleton lifecycle
-- `$$` new instance lifecycle
-- wrappers modify runtime behavior
+- `__Factory` selects a named export;
+- `$` means singleton lifecycle;
+- `$$` means new instance lifecycle;
+- `node:` and `npm:` address platform-specific modules.
 
-## Public API
+### Namespace Root
+
+A namespace root maps a CDC prefix to a module-specifier base:
 
 ```javascript
-const container = new Container();
+container.addNamespaceRoot("App_", "/abs/path/to/src/App", ".mjs");
 ```
 
-Configuration methods (before first `get`):
-
-- `setParser(parser)`
-- `addNamespaceRoot(prefix, target, defaultExt)`
-- `addPreprocess(fn)`
-- `addPostprocess(fn)`
-- `enableLogging()`
-- `enableTestMode()`
-- `register(cdc, mock)`
+This lets the container translate logical module names such as `App_Root__Factory$` into concrete ES module files or URL-based module specifiers.
 
-Dependency resolution:
+In Node.js, that often means filesystem-backed module roots:
 
 ```javascript
-await container.get(cdc);
+container.addNamespaceRoot("App_", "/project/src/App", ".mjs");
 ```
 
-Behavior:
+In a web-oriented or isomorphic application, it can also mean URL-backed roots for browser imports:
 
-- deterministic linking
-- fail-fast resolution pipeline
-- immutable returned objects
-- container enters failed state on fatal errors
+```javascript
+container.addNamespaceRoot("App_", "https://cdn.example.com/app", ".mjs");
+container.addNamespaceRoot("Web_", "//cdn.example.com/web", ".mjs");
+```
 
-## Wrappers
+This keeps dependency addressing stable while allowing the same logical naming model to work across shared application code, browser-facing modules, and different runtime environments.
 
-Wrappers allow cross-cutting behavior to be applied declaratively.
+## Public API
 
-Example CDC:
+Create a container:
 
-```txt
-App_Service$$_log_trace
+```javascript
+const container = new Container();
 ```
 
-Wrappers can implement:
+Configure it before the first `get(...)`:
 
-- logging
-- metrics
-- tracing
-- security checks
-- behavioral instrumentation
-
-This acts as a lightweight **DI-level AOP mechanism.**
+- `setParser(parser)`
+- `addNamespaceRoot(prefix, target, defaultExt)`
+- `addPreprocess(fn)`
+- `addPostprocess(fn)`
+- `enableLogging()`
+- `enableTestMode()`
+- `register(cdc, mock)`
 
-Platform-specific examples:
+Resolve dependencies:
 
-```txt
-node:worker_threads
-npm:@humanfs/core
+```javascript
+await container.get(cdc);
 ```
 
+The container is builder-configurable until the first `get(...)`. After that point configuration is locked.
+
 ## Test Mode
 
+Test mode allows registered mocks to be resolved before module instantiation:
+
 ```javascript
 container.enableTestMode();
-
 container.register("App_Service$", mockService);
 ```
 
-Mocks are resolved before module instantiation.
+This keeps replacement explicit and local to container configuration.
 
 ## Browser Usage
 
@@ -420,24 +260,59 @@ Mocks are resolved before module instantiation.
 </script>
 ```
 
-## Documentation
+## LLM-Oriented Development
+
+This package is designed for codebases where LLM agents participate in implementation and maintenance.
+
+That affects the architecture directly. In many human-oriented JavaScript codebases, local explicitness is treated as extra ceremony. Here it is a deliberate tradeoff: dependency structure stays visible where it is needed, instead of being inferred from decorators, reflection, framework conventions, or scattered configuration.
+
+This increases local structural surface area, but it reduces ambiguity. For LLM-driven maintenance, that makes dependency structure easier to reconstruct, edit, and verify from source code alone.
+
+## When This Fits
+
+This approach is a good fit when you want:
+
+- a modular monolith with explicit component boundaries;
+- shared JavaScript code across browser and Node.js;
+- runtime late binding instead of static application wiring;
+- explicit, machine-readable dependency structure;
+- a pure JavaScript + JSDoc stack instead of TypeScript-first architecture.
+
+## When It Probably Does Not
+
+This approach is probably a poor fit when:
+
+- your project is deeply committed to TypeScript-first conventions;
+- you prefer decorator-based or framework-managed injection;
+- your team values minimal local ceremony over explicit structural contracts;
+- you do not need isomorphic runtime structure or late binding;
+- the codebase is optimized only for human authorship and not for machine-assisted maintenance.
+
+## Documentation for Agents
+
+This package includes a machine-oriented package interface under `./ai/`.
+
+Those files are intended for system prompts, examples, and agent consumption. They describe:
 
-Detailed documentation lives in `ctx/`:
+- container usage;
+- dependency descriptors;
+- CDC behavior;
+- integration patterns.
 
-- `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`
+In other words, the package ships a human-facing README and a machine-oriented interface for agents that need to use it as a dependency.
 
-## Author
+## Further Reading
 
-**Alex Gusev**
+- Product overview: `ctx/docs/product/overview.md`
+- Product scope and boundaries: `ctx/docs/product/scope.md`
+- Default CDC profile and compatibility surface: `ctx/docs/product/default-cdc-profile.md`
+- Architecture overview: `ctx/docs/architecture/overview.md`
+- Runtime linking model: `ctx/docs/architecture/linking-model.md`
+- Container implementation contract: `ctx/docs/code/components/container.md`
+- Project philosophy and intended application domain: `PHILOSOPHY.md`
 
-Creator of:
+## TeqFW Context
 
-- **Tequila Framework (TeqFW)**
-- **ADSM (Agent-Driven Software Management)**
+`@teqfw/di` is the core building block of the Tequila Framework (TeqFW).
 
-The project explores how software architecture evolves when **LLM agents become active participants in the development process**.
+TeqFW is aimed at building modular monolith web applications with a unified JavaScript codebase across browser and server runtimes. The method favors late binding, namespace-based structure, explicit contracts, and source artifacts that remain legible to both humans and LLM agents.

package/ai/AGENTS.md

@@ -6,7 +6,7 @@ Version: 20260331
 
 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.
 
-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 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.
 
 ## When to Use This Package
 
@@ -17,9 +17,18 @@ This package should be used when a system requires the following capabilities:
 - 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
 
 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 package is primarily a fit for:
+
+- modular monolith web applications
+- isomorphic JavaScript systems with shared browser/server code
+- pure JavaScript + JSDoc codebases
+
+It is usually not a natural fit for TypeScript-first architectures built around decorators, metadata, or framework-managed DI conventions.
+
 ## Architectural Model
 
 The system is based on four mechanisms:
@@ -42,6 +51,7 @@ 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.
 
@@ -59,6 +69,13 @@ Agents should read the documents in this directory in the following order:
 
 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.
@@ -73,3 +90,5 @@ The package follows architectural principles used in the **Tequila Framework (Te
 - 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.

package/ai/concepts.md

@@ -47,9 +47,9 @@ The identifier syntax and resolution rules are described in **dependency-id.md**
 
 ## Namespaces
 
-Namespaces provide deterministic mapping between logical identifiers and module locations. Each package defines a namespace root that corresponds to a directory containing source modules.
+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 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.
+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.
 
 Namespace resolution ensures: