@teqfw/di 2.6.2 → 2.8.0

package/README.md

@@ -1,628 +1,130 @@
 # @teqfw/di
 
-![npms.io](https://img.shields.io/npm/dm/@teqfw/di)
-![jsdelivr](https://img.shields.io/jsdelivr/npm/hm/@teqfw/di)
+**JavaScript applications do not need a compiler to gain late binding, explicit contracts, controlled composition, and agent-readable architecture.**
 
-**Enterprise-scale dependency architecture for pure JavaScript.**
+`@teqfw/di` brings these capabilities to native ESM without TypeScript, decorators, reflection, generated code, or transpilation. Business modules depend on stable logical tokens instead of concrete file paths; the host application decides which implementation to load, how to create it, how long to keep it, and which cross-cutting policies to apply.
 
-`@teqfw/di` replaces fragile file-path-based wiring with namespace-based component contracts and deterministic runtime linking, so large JavaScript codebases remain understandable to humans and reconstructible by coding agents.
+This is the runtime-linking foundation of Tequila Framework and a practical choice for long-lived applications maintained by developers together with coding agents.
 
-It is built for pure JavaScript ES modules.
+## Why use it
 
-No TypeScript metadata.
-No decorators.
-No reflection.
-No framework-managed injection.
-No transpilation requirement.
-
-The package uses dependency injection techniques, but its main purpose is architectural governance, not constructor convenience.
-
-## Why JavaScript Dependency Wiring Breaks at Scale
-
-JavaScript applications usually express dependencies through static imports:
-
-```javascript
-import Repository from "../repository/UserRepository.js";
-```
-
-This looks simple.
-
-But this line says two different things at once:
-
-1. what the module needs;
-2. where that dependency is physically located.
-
-That coupling is acceptable in small codebases.
-
-It becomes a structural problem when the application grows.
-
-As modules multiply, dependency intent becomes scattered across:
-
-- file paths;
-- package specifiers;
-- framework conventions;
-- bundler configuration;
-- generated code;
-- decorators;
-- local composition logic.
-
-The architecture becomes harder to supervise because the real dependency graph is embedded inside implementation details.
-
-A developer no longer sees a component dependency model.
-
-The developer sees a filesystem.
-
-## Why AI-Assisted Development Makes This More Important
-
-Coding agents change the practical scale of JavaScript development.
-
-One developer working with agents can now create and maintain systems whose size was previously more typical for enterprise teams.
-
-The bottleneck is no longer only code generation.
-
-The bottleneck is architectural control.
-
-Agents can generate files quickly. They can modify many modules in one iteration. They can refactor local code. But if the dependency structure is hidden inside file paths and framework conventions, both the agent and the human supervisor must reconstruct architectural intent indirectly.
-
-That does not scale well.
-
-Large AI-assisted JavaScript systems need dependency structure that is:
-
-- explicit;
-- stable;
-- reviewable;
-- machine-readable;
-- independent from local file layout;
-- deterministic at runtime.
-
-This is the problem `@teqfw/di` addresses.
-
-## The Enterprise Shift: From Files to Components
-
-Enterprise ecosystems such as Java and C# have long used namespaces, dependency inversion, IoC containers, component identifiers, explicit contracts, and runtime composition to keep large systems manageable.
-
-`@teqfw/di` brings that model of thinking to pure JavaScript.
-
-Instead of making a module depend on a file path:
-
-```javascript
-import Repository from "../repository/UserRepository.js";
-```
-
-the module declares a dependency on a component:
-
-```javascript
-export const __deps__ = {
-  repository: "App_User_Repository$",
-};
-```
-
-This declaration says:
-
-> This module needs the `App_User_Repository` component.
-
-It does not say where the source file is located.
-
-The physical module location is resolved later by the container through configured namespace roots.
-
-This is the central shift:
+Static imports bind a consumer to a concrete module:
 
 ```text
-from file paths
-to component addresses
-
-from local imports
-to explicit dependency contracts
-
-from scattered wiring
-to deterministic runtime composition
+consumer → file path → implementation
 ```
 
-## What @teqfw/di Is
-
-`@teqfw/di` is a runtime composition layer for pure JavaScript ES modules.
-
-It provides:
-
-- namespace-based component addressing;
-- Canonical Dependency Codes;
-- source-attached dependency declarations through `__deps__`;
-- deterministic runtime linking;
-- namespace root mapping for Node.js and browser environments;
-- lifecycle control for singleton and new-instance dependencies;
-- explicit replacement in test mode;
-- wrapper-based extension points;
-- immutable linked objects.
-
-The ES module system remains the underlying loading mechanism.
-
-The package does not replace ESM.
-
-It replaces application-level dependency wiring through static imports.
-
-## Product Goal
-
-The goal of `@teqfw/di` is to make enterprise-scale dependency architecture practical in pure JavaScript.
-
-The package gives JavaScript applications a dependency model that is:
-
-- based on stable namespace-based component addresses;
-- explicit in source artifacts;
-- deterministic under finalized runtime configuration;
-- usable across browser and Node.js environments;
-- readable by humans;
-- reconstructible by coding agents;
-- independent from TypeScript metadata, decorators, reflection, and framework-managed injection.
-
-The intended result is architectural supervision.
-
-A developer should be able to see what a component needs without tracing import paths across the filesystem.
-
-An agent should be able to modify code without silently destroying the dependency structure.
-
-A runtime should be able to link components through explicit contracts rather than inference.
-
-## Core Model
-
-The model follows this chain:
+`@teqfw/di` separates the contract from the implementation:
 
 ```text
-Namespace
-  -> Component Address
-  -> CDC
-  -> __deps__
-  -> Namespace Root
-  -> Runtime Linker
-  -> Linked Object
-```
-
-A **namespace** defines a stable application-level addressing space.
-
-A **component address** identifies a component inside that namespace.
-
-A **CDC** — Canonical Dependency Code — encodes the component address and linking semantics.
-
-A module declares its dependencies through `__deps__`.
-
-A **namespace root** maps a namespace prefix to a concrete runtime module location.
-
-The container resolves CDC values under finalized configuration, imports the required ES modules, links declared dependencies, and returns linked objects.
-
-The linking happens at runtime, but it is not heuristic. The container does not infer dependencies from behavior, constructor signatures, decorators, reflection, or naming guesses.
-
-For identical dependency declarations, CDC values, namespace roots, module exports, lifecycle rules, and finalized container configuration, the container must produce the same linked result or the same failure.
-
-## Example: File-Oriented vs Component-Oriented Wiring
-
-Traditional JavaScript wiring:
-
-```javascript
-import Repository from "../repository/UserRepository.js";
-```
-
-This is file-oriented.
-
-The module depends on a concrete module specifier.
-
-With `@teqfw/di`:
-
-```javascript
-export const __deps__ = {
-  repository: "App_User_Repository$",
-};
-```
-
-This is component-oriented.
-
-The module depends on a logical component address.
-
-The difference is not just technical.
-
-It changes the source of architectural truth.
-
-## Why It Matters for Coding Agents
-
-In agent-assisted development, dependency declarations become part of the shared cognitive field between the human developer, the coding agent, and the runtime system.
-
-A module can expose its dependency intent as data:
-
-```javascript
-export const __deps__ = {
-  repository: "App_User_Repository$",
-  logger: "App_Logger$",
-  config: "App_Config$",
-};
-```
-
-This structure is easy for agents to generate.
-
-It is easy for humans to review.
-
-It is deterministic for the container to execute.
-
-Agent readability is not a separate feature. It is a consequence of explicit namespace-based dependency structure.
-
-## Why It Matters for Browser and Node.js
-
-Browser and Node.js environments both support ES modules, but they do not provide one shared application-level dependency wiring model.
-
-Static imports usually depend on:
-
-- file layout;
-- package layout;
-- URL layout;
-- bundler behavior;
-- runtime-specific module resolution.
-
-`@teqfw/di` moves dependency intent away from those concrete specifiers.
-
-The same source module can declare:
-
-```javascript
-export const __deps__ = {
-  repository: "App_User_Repository$",
-};
-```
-
-In Node.js, `App_` may point to a filesystem directory.
-
-In a browser, `App_` may point to a URL base.
-
-The dependency declaration remains stable.
-
-Only the namespace root changes.
-
-## Who It Is For
-
-`@teqfw/di` is designed primarily for:
-
-- solo developers and small teams building long-lived web applications;
-- developers using coding agents as active implementation and maintenance participants;
-- modular monolith applications;
-- isomorphic JavaScript systems that share code between browser and server;
-- pure JavaScript + JSDoc codebases;
-- projects where explicit dependency structure is more important than minimal local ceremony;
-- applications expected to grow beyond prototype size.
-
-It is especially relevant when one human remains responsible for architectural supervision while agents participate in code generation, maintenance, and refactoring.
-
-## When It Is Not the Best Fit
-
-`@teqfw/di` is usually not the best fit when:
-
-- the project is a short-lived prototype;
-- the application is small enough for direct imports to remain clear;
-- the team is fully committed to a decorator-driven TypeScript framework;
-- framework conventions are more important than explicit dependency contracts;
-- minimal local ceremony is more valuable than architectural traceability;
-- runtime linking is not acceptable for the project’s deployment model.
-
-This package is a deliberate architectural tradeoff.
-
-It favors explicit structure over local simplicity.
-
-## How It Fits in JavaScript
-
-This approach is unusual in mainstream JavaScript.
-
-Most JavaScript and TypeScript projects express application dependency structure through some mix of:
-
-- static imports;
-- file paths;
-- package specifiers;
-- framework conventions;
-- TypeScript-first source architecture;
-- decorators or metadata-driven injection;
-- framework-managed DI;
-- bundler-controlled module graphs.
-
-`@teqfw/di` makes a different tradeoff.
-
-It favors namespace-based component addresses and explicit runtime contracts over hidden or inferred wiring.
-
-TypeScript has had a major influence on the JavaScript ecosystem, and that influence has been broadly positive. At the same time, TeqFW targets a different design space:
-
-- pure JavaScript + JSDoc;
-- no transpilation requirement;
-- isomorphic runtime behavior;
-- namespace-based addressing;
-- explicit dependency declarations;
-- source artifacts readable by humans and agents.
-
-This is not presented as the only correct way to structure JavaScript.
-
-It is a focused alternative for projects that need stronger runtime explicitness and machine-reconstructible structure.
-
-## Comparison
-
-| Concern                    | Common JS/TS Approach                                 | `@teqfw/di`                             |
-| -------------------------- | ----------------------------------------------------- | --------------------------------------- |
-| Dependency expression      | Static imports, decorators, framework wiring          | `__deps__` declarations with CDC values |
-| Addressing model           | File-based, package-based, or framework-defined       | Namespace-based component addressing    |
-| Resolution model           | Static, implicit, framework-driven, or bundler-driven | Deterministic runtime linking           |
-| Structural source of truth | Spread across code, metadata, config, and conventions | Source-attached dependency contracts    |
-| Cross-environment wiring   | Bundlers, adapters, duplicated specifiers             | Namespace roots                         |
-| Best fit                   | Framework-led or TypeScript-first applications        | Pure JavaScript + JSDoc modular systems |
-| Agent readability          | Mixed and often indirect                              | Explicit and reconstructible            |
-| Architectural mindset      | Local module graph                                    | Enterprise-scale component composition  |
-
-## Installation
-
-```bash
-npm install @teqfw/di
+consumer → dependency token → host policy → implementation
 ```
 
-## Quick Start
+That enables:
 
-Define one repository module and one service module that declares the repository as an explicit dependency.
+- late binding and replaceable implementations;
+- isomorphic modules for Node.js and browser environments;
+- explicit dependency graphs that agents can analyze;
+- lifecycle control for transient and singleton values;
+- preprocessing, postprocessing, wrappers, diagnostics, and test substitution at the composition boundary;
+- shallow hardening of resolved values against ordinary runtime patching.
 
-`src/App/User/Repository.mjs`
+The package uses native ESM, dynamic `import()`, JSDoc, and standard JavaScript runtime features. No compilation layer is required.
 
-```javascript
-export default function Repository() {
-  return {
-    async findNameById(id) {
-      return `User ${id}`;
-    },
-  };
-}
-```
+<details>
 
-`src/App/User/Service.mjs`
+<summary><strong>Quick Start</strong></summary>
 
-```javascript
+```js
 export default function Service({ repository }) {
   return {
     async getProfile(id) {
-      const name = await repository.findNameById(id);
-      return { id, name };
+      return { id, name: await repository.findNameById(id) };
     },
   };
 }
 
 export const __deps__ = {
-  repository: "App_User_Repository$",
+  default: {
+    repository: "App_User_Repository$",
+  },
 };
 ```
 
-Configure the container and request the dependency:
-
-```javascript
+```js
 import path from "node:path";
 import { fileURLToPath } from "node:url";
 import Container from "@teqfw/di";
 
-const __filename = fileURLToPath(import.meta.url);
-const __dirname = path.dirname(__filename);
+const rootDir = path.dirname(fileURLToPath(import.meta.url));
 
 const container = new Container();
-container.addNamespaceRoot("App_", path.resolve(__dirname, "./src/App"), ".mjs");
+container.addNamespaceRoot("App_", path.join(rootDir, "src/App"), ".mjs");
 
 const service = await container.get("App_User_Service$");
-
-const profile = await service.getProfile(42);
-
-console.log(profile);
-```
-
-Output:
-
-```javascript
-{ id: 42, name: "User 42" }
 ```
 
-In this flow the container:
+</details>
 
-- parses the dependency request;
-- resolves `App_` through the registered namespace root;
-- translates `App_User_Repository$` into a concrete ES module location;
-- imports the module;
-- reads `__deps__` for the selected export;
-- recursively links dependencies;
-- returns a frozen linked object.
+## Agent-ready package
 
-## Core Concepts
+The package ships with three aligned interfaces:
 
-### Namespace
+- runtime code in `src`;
+- type information through JSDoc and `types.d.ts`;
+- a version-matched Agent Skill in `skills/teqfw-di`.
 
-A namespace defines a stable addressing space for application components.
+The skill explains the token model, module contracts, lifecycle, configuration, testing, environment boundaries, and approved integration patterns. An agent does not need to reconstruct the package architecture from source code alone.
 
-In TeqFW, a dependency address such as:
+Mount it into the host project:
 
-```text
-App_User_Repository$
+```sh
+mkdir -p .agents/skills
+cd .agents/skills
+ln -s ../../node_modules/@teqfw/di/skills/teqfw-di
 ```
 
-uses `App_` as a namespace prefix.
-
-The namespace makes the dependency address independent from local file paths and runtime-specific module specifiers.
-
-### Component Address
-
-A component address identifies an application component inside a namespace.
-
-For example:
-
-```text
-App_User_Repository
-```
-
-identifies the `Repository` component inside the `App_` namespace.
-
-The component address is logical.
-
-It is not itself a file path or URL.
-
-### CDC
-
-A **Canonical Dependency Code** is the string contract used to request a dependency.
-
-General form:
-
-```text
-[PlatformPrefix]ModuleName[__ExportName][LifecycleAndWrappers]
-```
-
-Examples:
-
-```text
-App_User_Repository$
-App_User_Repository__Factory$$
-node:fs
-npm:lodash
-```
-
-Where:
-
-- `App_User_Repository` is the namespace-based component address;
-- `__Factory` selects a named export;
-- `$` means singleton lifecycle;
-- `$$` means new instance lifecycle;
-- `node:` and `npm:` address platform-specific modules.
-
-### `__deps__`
-
-`__deps__` is a source-attached dependency declaration.
-
-For a single-export module, dependencies can be declared in shorthand form:
-
-```javascript
-export const __deps__ = {
-  localName: "Dependency_CDC",
-};
-```
-
-Rules:
-
-- 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 export-scoped form:
-
-```javascript
-export const __deps__ = {
-  default: {
-    localName: "Dependency_CDC",
-  },
-  Factory: {
-    localName: "Dependency_CDC",
-  },
-};
-```
-
-### Namespace Root
-
-A namespace root maps a namespace prefix to a module-specifier base:
-
-```javascript
-container.addNamespaceRoot("App_", "/abs/path/to/src/App", ".mjs");
-```
-
-This lets the container translate logical module names such as `App_User_Repository$` into concrete ES module files or URL-based module specifiers.
-
-In Node.js, that often means filesystem-backed module roots:
-
-```javascript
-container.addNamespaceRoot("App_", "/project/src/App", ".mjs");
-```
-
-In a browser-oriented or isomorphic application, it can also mean URL-backed roots:
-
-```javascript
-container.addNamespaceRoot("App_", "https://cdn.example.com/app", ".mjs");
-container.addNamespaceRoot("Web_", "//cdn.example.com/web", ".mjs");
-```
-
-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.
-
-### Runtime Linking
-
-Runtime linking is the process of resolving CDC values under finalized container configuration, importing the corresponding ES modules, injecting declared dependencies, and returning linked objects.
-
-The mechanism is dynamic because it runs at runtime.
-
-The mechanism is deterministic because dependencies are declared explicitly and resolved through fixed namespace roots and configuration.
+Project instructions and application architecture remain authoritative. The package skill supplies product knowledge; the host supplies intent and policy.
 
 ## Public API
 
-Create a container:
+- `@teqfw/di` — `Container`;
+- `@teqfw/di/node/registry/namespace` — namespace discovery;
+- `@teqfw/di/node/registry/package` — package graph discovery.
 
-```javascript
-const container = new Container();
-```
-
-Configure it before the first `get(...)`:
+Do not import `@teqfw/di/src/**`.
 
-- `addNamespaceRoot(prefix, target, defaultExt)`
-- `addPreprocess(fn)`
-- `addPostprocess(fn)`
-- `enableLogging()`
-- `enableTestMode()`
-- `register(cdc, mock)`
+## Best fit
 
-Resolve dependencies:
+Use `@teqfw/di` for modular, long-lived, plugin-oriented ESM applications where implementations, environments, and integrations will evolve.
 
-```javascript
-await container.get(cdc);
-```
+Use direct imports for small applications where runtime composition adds no practical value.
 
-The container is builder-configurable until the first `get(...)`.
+## Add to a project
 
-After that point configuration is locked.
+Install the runtime package as a project dependency:
 
-## Test Mode
-
-Test mode allows registered mocks to be resolved before module instantiation:
-
-```javascript
-container.enableTestMode();
-container.register("App_Service$", mockService);
-```
-
-This keeps replacement explicit and local to container configuration.
-
-## Browser Usage
-
-```html
-<script type="module">
-  import Container from "https://cdn.jsdelivr.net/npm/@teqfw/di@2/+esm";
-
-  const container = new Container();
-</script>
+```sh
+npm install @teqfw/di
 ```
 
-## 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:
-
-- container usage;
-- dependency descriptors;
-- CDC behavior;
-- integration patterns.
-
-The package ships both a human-facing README and a machine-oriented interface for agents that need to use it as a dependency.
-
-## Further Reading
+For agent-assisted development, provide the coding agent with the skills relevant to its task:
 
-- Usage guide: `ai/usage.md`
-- Container API notes: `ai/container.md`
-- Dependency descriptor concepts: `ai/concepts.md`
-- Dependency ID format: `ai/dependency-id.md`
-- Extension points: `ai/extensions.md`
-- Project philosophy and intended application domain: `PHILOSOPHY.md`
+- `teqfw-di` — version-matched guidance for the `@teqfw/di` API, dependency tokens, module contracts, lifecycle, testing, and composition rules;
+- `teqfw-platform` — the architecture, philosophy, conventions, plugin model, and integration rules of the Tequila Framework;
+- `teqfw-esm-validator` — validation rules for native ESM modules and TeqFW-compatible JavaScript structure.
 
-## TeqFW Context
+The package includes `teqfw-di`. The other skills are installed or mounted separately by the host project. Project instructions and cognitive context remain authoritative over all package-level guidance.
 
-`@teqfw/di` is the core dependency-linking building block of the Tequila Framework.
+## Boundaries
 
-TeqFW is aimed at building modular monolith web applications with a unified JavaScript codebase across browser and server runtimes. The method favors namespace-based component addressing, late binding, explicit contracts, pure JavaScript, and source artifacts that remain legible to both humans and LLM agents.
+The package provides interface-like contracts, composition interception, and shallow value hardening. It does not claim language-level interfaces, full general-purpose AOP, or deep immutability of arbitrary object graphs.
 
-The broader TeqFW position is that AI-assisted development changes not only how code is written, but also what kind of structure a solo developer needs in order to supervise a growing application.
+## Development and Ecosystem
 
-When JavaScript applications reach enterprise scale under human-agent development, file-path-based dependency wiring becomes too local and too implicit.
+This product is developed by AI agents under the direction of Alex Gusev, following the Agent-Driven Software Management (ADSM) methodology. It is built for the Tequila Framework (TeqFW) platform and contributes to its ecosystem.
 
-`@teqfw/di` is one concrete answer to that change: enterprise-scale dependency architecture for pure JavaScript.
+- [Tequila Framework](https://teqfw.com/?teqfw-di)
+- [Alex Gusev's Personal Website](https://wiredgeese.com/?teqfw-di)
+- [Alex Gusev's Telegram Channel](https://t.me/alexgusev_lab_en)
+- [Agent-Driven Software Management: A Practical Guide](http://fly.wiredgeese.com/flancer/leanpub/adsm-en/?teqfw-di)