@teqfw/di 2.6.2 → 2.8.0

package/{ai → skills/teqfw-di/references}/extensions.md

@@ -1,6 +1,6 @@
 # extensions.md
 
-Version: 20260606
+Version: 20260730
 
 ## Purpose
 
@@ -12,9 +12,19 @@ The container supports controlled extension of dependency resolution through thr
 
 These mechanisms are related but not interchangeable.
 
+## Contents
+
+- [Preprocess Hooks](#preprocess-hooks)
+- [Postprocess Hooks](#postprocess-hooks)
+- [Wrapper Exports](#wrapper-exports)
+- [Execution Order](#execution-order)
+- [Constraints](#constraints)
+
 ## Preprocess Hooks
 
-Preprocess hooks transform CDC identities before resolution.
+Preprocess hooks transform parsed dependency identities before resolution.
+
+They apply to the root request and every dependency declaration discovered transitively in the requested graph, exactly once per occurrence.
 
 Signature:
 
@@ -31,10 +41,11 @@ Properties:
 
 Typical uses:
 
-- CDC alias rewriting;
+- Dependency Specifier alias rewriting;
 - policy-driven identifier normalization;
 - project-specific prefix adaptation.
 
+
 ## Postprocess Hooks
 
 Postprocess hooks transform resolved values after instantiation and before wrapper exports.
@@ -42,7 +53,7 @@ Postprocess hooks transform resolved values after instantiation and before wrapp
 Signature:
 
 ```js
-(value) => value
+(value, context) => value
 ```
 
 Properties:
@@ -50,7 +61,7 @@ Properties:
 - registered with `addPostprocess()`;
 - run for every resolved value;
 - run in declared order;
-- do not alter CDC parsing or module resolution.
+- do not alter dependency specifier parsing or module resolution.
 
 Typical uses:
 
@@ -60,7 +71,7 @@ Typical uses:
 
 ## Wrapper Exports
 
-Wrapper exports are selected directly from CDC suffixes and are resolved from the same module namespace as the dependency being composed.
+Wrapper exports are selected directly from dependency specifier suffixes and are resolved from the same module namespace as the dependency being composed.
 
 Signature:
 
@@ -71,7 +82,7 @@ Signature:
 Properties:
 
 - selected by wrapper suffixes such as `_wrapLog`;
-- applied only when present in the CDC;
+- applied only when present in the Dependency Specifier;
 - executed after postprocess hooks and before freeze;
 - not registered globally in the container.
 

package/{ai → skills/teqfw-di/references}/package-api.ts

@@ -66,28 +66,23 @@ export interface PackageApiContract {
  */
 export const PACKAGE_API: PackageApiContract = {
     packageName: '@teqfw/di',
-    packageRole: 'Deterministic runtime DI container for native ES modules with explicit CDC contracts.',
+    packageRole: 'Deterministic runtime DI container for native ES modules with explicit Dependency Specifier contracts.',
     canonicalEntrypoints: [
         '@teqfw/di',
-        '@teqfw/di/src/Config/NamespaceRegistry.mjs',
+        '@teqfw/di/node/registry/namespace',
+        '@teqfw/di/node/registry/package',
     ],
     publicRuntime: [
         {
             alias: 'TeqFw_Di_Container',
             kind: 'class',
-            role: 'Primary runtime composition root. Resolves CDC identifiers into frozen linked values.',
+            role: 'Primary runtime composition root. Resolves Dependency Specifiers into frozen linked values.',
             imports: [
                 {
                     specifier: '@teqfw/di',
                     exportName: 'default',
                     canonical: true,
                 },
-                {
-                    specifier: '@teqfw/di/src/Container.mjs',
-                    exportName: 'default',
-                    canonical: false,
-                    note: 'Explicit source subpath export. Prefer the package root import.',
-                },
             ],
             methods: [
                 {
@@ -100,7 +95,7 @@ export const PACKAGE_API: PackageApiContract = {
                     name: 'addNamespaceRoot',
                     signature: 'addNamespaceRoot(prefix: string, target: string, defaultExt: string): void',
                     stage: 'builder',
-                    summary: 'Registers one namespace root that maps a CDC prefix to a module-specifier base.',
+                    summary: 'Registers one namespace root that maps a Module Token prefix to a module-specifier base.',
                     constraints: [
                         'Allowed only before the first get().',
                         'The target may be filesystem-backed or URL-backed depending on runtime environment.',
@@ -111,10 +106,10 @@ export const PACKAGE_API: PackageApiContract = {
                     name: 'addPreprocess',
                     signature: 'addPreprocess(fn: (depId: TeqFw_Di_DepId$DTO) => TeqFw_Di_DepId$DTO): void',
                     stage: 'builder',
-                    summary: 'Adds an ordered CDC preprocessing hook.',
+                    summary: 'Adds an ordered parsed dependency identity preprocessing hook.',
                     constraints: [
                         'Allowed only before the first get().',
-                        'Each hook must return another DepId DTO.',
+                        'Each hook is invoked synchronously in registration order and must return another DepId DTO.',
                     ],
                 },
                 {
@@ -124,7 +119,7 @@ export const PACKAGE_API: PackageApiContract = {
                     summary: 'Adds an ordered value transform applied to every resolved value after instantiation.',
                     constraints: [
                         'Allowed only before the first get().',
-                        'Runs after instantiation and before wrapper exports.',
+                        'Runs synchronously in registration order after instantiation and before wrapper exports.',
                     ],
                 },
                 {
@@ -147,9 +142,9 @@ export const PACKAGE_API: PackageApiContract = {
                 },
                 {
                     name: 'register',
-                    signature: 'register(cdc: string, mock: unknown): void',
+                    signature: 'register(specifier: string, mock: unknown): void',
                     stage: 'builder',
-                    summary: 'Registers a mock by canonical DepId identity after parsing the provided CDC.',
+                    summary: 'Registers a mock by canonical DepId identity after parsing the provided Dependency Specifier.',
                     constraints: [
                         'Allowed only before the first get().',
                         'Requires enableTestMode() first.',
@@ -157,7 +152,7 @@ export const PACKAGE_API: PackageApiContract = {
                 },
                 {
                     name: 'get',
-                    signature: 'get(cdc: string): Promise<any>',
+                    signature: 'get(specifier: string): Promise<any>',
                     stage: 'runtime',
                     summary: 'Parses, preprocesses, resolves, instantiates, postprocesses, wraps, applies lifecycle, freezes, and returns a linked value.',
                     constraints: [
@@ -169,12 +164,22 @@ export const PACKAGE_API: PackageApiContract = {
             ],
         },
         {
-            alias: 'TeqFw_Di_Config_NamespaceRegistry',
+            alias: 'TeqFw_Di_Node_Registry_Package',
+            kind: 'class',
+            role: 'Node.js-only composition-stage static runtime package graph builder.',
+            imports: [{specifier: '@teqfw/di/node/registry/package', exportName: 'default', canonical: true}],
+            methods: [
+                {name: 'constructor', signature: 'new PackageRegistry({ fs, path, appRoot })', stage: 'composition', summary: 'Creates a static package graph builder.'},
+                {name: 'build', signature: 'build(): Promise<ReadonlyArray<PackageRecord>>', stage: 'composition', summary: 'Builds immutable dependency-first postorder package records; independent dependency names use ascending lexical order as the stable tie-breaker.', constraints: ['Reads only transitive dependencies and static package metadata.', 'Does not load modules or interpret application providers.']},
+            ],
+        },
+        {
+            alias: 'TeqFw_Di_Node_Registry_Namespace',
             kind: 'class',
-            role: 'Composition-stage helper that discovers namespace roots from the root package and installed npm dependencies.',
+            role: 'Node.js-only composition-stage helper that discovers namespace roots from the root package and installed npm dependencies.',
             imports: [
                 {
-                    specifier: '@teqfw/di/src/Config/NamespaceRegistry.mjs',
+                    specifier: '@teqfw/di/node/registry/namespace',
                     exportName: 'default',
                     canonical: true,
                 },
@@ -186,7 +191,7 @@ export const PACKAGE_API: PackageApiContract = {
                     stage: 'composition',
                     summary: 'Creates a registry builder over filesystem and path adapters.',
                     constraints: [
-                        'Intended for composition root code, not for DI-managed runtime modules.',
+                        'Intended only for Node.js composition root code, not for DI-managed or browser runtime modules.',
                         'Consumes static package.json metadata only.',
                     ],
                 },
@@ -196,13 +201,16 @@ export const PACKAGE_API: PackageApiContract = {
                     stage: 'composition',
                     summary: 'Builds an immutable namespace registry sorted by descending prefix length.',
                     constraints: [
-                        'Fails fast on invalid namespace metadata or duplicate canonical prefixes.',
+                        'Selects package.json#teqfw.fw.di.namespaces when present; otherwise temporarily falls back to the legacy package.json#teqfw.namespaces array.',
+                        'Both schemas require arrays; canonical metadata wins exclusively and the arrays are never merged.',
+                        'Fails fast on invalid selected metadata or duplicate prefixes with publisher attribution.',
                     ],
                 },
             ],
         },
     ],
     structuralContracts: [
+        {name: 'Runtime Package Record', kind: 'protocol', aliases: ['TeqFw_Di_Node_Registry_Package_Record'], summary: 'Immutable static package metadata record.', fields: {name: 'Declared package name.', rootAbs: 'Resolved package root.', rootReal: 'Canonical package root.', packageJson: 'Recursively frozen package metadata.'}},
         {
             name: 'DepId DTO',
             kind: 'dto',
@@ -215,7 +223,7 @@ export const PACKAGE_API: PackageApiContract = {
                 composition: '"A" | "F" in the current implementation.',
                 life: '"S" | "T" | null in the current implementation.',
                 wrappers: 'Ordered wrapper export names.',
-                origin: 'Original CDC string for diagnostics.',
+                origin: 'Original Dependency Specifier string for diagnostics.',
             },
             notes: [
                 'Identity excludes origin.',
@@ -245,8 +253,8 @@ export const PACKAGE_API: PackageApiContract = {
             kind: 'module-contract',
             summary: 'Shape expected from application modules resolved by the container.',
             fields: {
-                __deps__: 'Optional dependency descriptor. Canonical form is hierarchical Record<exportName, Record<dependencyKey, CDC string>>. Supported shorthand form is a flat Record<dependencyKey, CDC string> for default-export-only modules. Omission means there are no declared dependencies.',
-                moduleNamespace: 'Whole ES module namespace object returned for as-is CDC without selected export.',
+                __deps__: 'Optional dependency descriptor. Canonical form is hierarchical Record<exportName, Record<dependencyKey, Dependency Specifier string>>. Supported shorthand form is a flat Record<dependencyKey, Dependency Specifier string> for default-export-only modules. Omission means there are no declared dependencies.',
+                moduleNamespace: 'Whole ES module namespace object returned for as-is Dependency Specifier without selected export.',
                 defaultExport: 'Used when the parsed DepId selects exportName="default" for factory composition.',
                 namedExports: 'May be selected via __ExportName for factory composition and may also provide wrapper exports.',
                 wrapperExport: 'Named export whose identifier appears in depId.wrappers; it must be synchronous and unary.',
@@ -260,17 +268,30 @@ export const PACKAGE_API: PackageApiContract = {
     ],
     typeMapClassification: [
         {
-            alias: 'TeqFw_Di_Config_NamespaceRegistry',
-            source: './src/Config/NamespaceRegistry.mjs',
+            alias: 'TeqFw_Di_Node_Registry_Package',
+            source: './src/Node/Registry/Package.mjs',
+            exposure: 'public-runtime',
+            reason: 'Exported through package.json exports as the supported Node.js composition subpath.',
+            canonicalUse: 'Node.js composition-stage package graph imported from @teqfw/di/node/registry/package.',
+        },
+        {
+            alias: 'TeqFw_Di_Node_Registry_Package_Record',
+            source: './src/Node/Registry/Package.mjs#record',
+            exposure: 'public-structural',
+            reason: 'Public immutable record contract returned by PackageRegistry.build().',
+        },
+        {
+            alias: 'TeqFw_Di_Node_Registry_Namespace',
+            source: './src/Node/Registry/Namespace.mjs',
             exposure: 'public-runtime',
-            reason: 'Exported through package.json exports as a supported subpath entrypoint.',
-            canonicalUse: 'Composition-stage helper imported from @teqfw/di/src/Config/NamespaceRegistry.mjs.',
+            reason: 'Exported through package.json exports as the supported Node.js composition subpath.',
+            canonicalUse: 'Node.js composition-stage helper imported from @teqfw/di/node/registry/namespace.',
         },
         {
             alias: 'TeqFw_Di_Container',
             source: './src/Container.mjs',
             exposure: 'public-runtime',
-            reason: 'Default export of the package root and of the explicit source subpath.',
+            reason: 'Default export of the package root.',
             canonicalUse: 'Primary container API imported from @teqfw/di.',
         },
         {
@@ -280,25 +301,25 @@ export const PACKAGE_API: PackageApiContract = {
             reason: 'Internal immutable-core helper. Not exported via package.json.',
         },
         {
-            alias: 'TeqFw_Di_Container_Instantiate_Instantiator',
+            alias: 'TeqFw_Di_Container_Instantiate',
             source: './src/Container/Instantiate.mjs',
             exposure: 'internal',
             reason: 'Internal immutable-core helper. Not exported via package.json.',
         },
         {
-            alias: 'TeqFw_Di_Container_Lifecycle_Registry',
+            alias: 'TeqFw_Di_Container_Lifecycle',
             source: './src/Container/Lifecycle.mjs',
             exposure: 'internal',
             reason: 'Internal lifecycle cache component. Not exported via package.json.',
         },
         {
-            alias: 'TeqFw_Di_Container_Resolve_GraphResolver',
+            alias: 'TeqFw_Di_Container_GraphResolver',
             source: './src/Container/GraphResolver.mjs',
             exposure: 'internal',
             reason: 'Internal graph builder used by Container.get(). Not exported via package.json.',
         },
         {
-            alias: 'TeqFw_Di_Container_Wrapper_Executor',
+            alias: 'TeqFw_Di_Container_Executor',
             source: './src/Container/Executor.mjs',
             exposure: 'internal',
             reason: 'Internal wrapper-stage executor. Not exported via package.json.',
@@ -399,11 +420,13 @@ export const PACKAGE_API: PackageApiContract = {
         },
     ],
     operationalNotes: [
-        'Only two runtime entrypoints are supported by package.json exports: @teqfw/di and @teqfw/di/src/Config/NamespaceRegistry.mjs.',
+        'Canonical Node.js registry entrypoints are @teqfw/di/node/registry/namespace and @teqfw/di/node/registry/package. They must not be imported by browser runtime modules.',
+        'The legacy compatibility entry point @teqfw/di/src/Config/NamespaceRegistry.mjs is deprecated. Every other src/** path is internal and unsupported; new code must use @teqfw/di/node/registry/namespace.',
+        'NamespaceRegistry uses the canonical package.json#teqfw.fw.di.namespaces array and temporarily falls back to package.json#teqfw.namespaces only when canonical metadata is absent.',
         'Resolved values are frozen before being returned.',
         'The hierarchical export-scoped descriptor is canonical. The flat shorthand descriptor is supported only for default-export-only modules.',
         'Named wrapper exports are executed after addPostprocess() hooks and before freeze.',
-        'In the current implementation, CDC markers $$ and $$$ both end up as transient/no-cache behavior.',
+        '$$ selects transient lifecycle; $$$ explicitly selects direct lifecycle.',
         'types.d.ts is broader than the runtime import surface. Presence of an alias there does not by itself make the underlying module a supported runtime entrypoint.',
     ],
 } as const;

package/skills/teqfw-di/references/usage.md

@@ -0,0 +1,283 @@
+# usage.md
+
+Version: 20260730
+
+## Purpose
+
+This document shows canonical usage patterns for the container. Examples are intentionally short and prioritize supported, recommended forms over convenience shorthand.
+
+## Contents
+
+- [Canonical Module Descriptor](#canonical-module-descriptor)
+- [Canonical Container Setup](#canonical-container-setup)
+- [Lifecycle Composition](#lifecycle-composition)
+- [Test Mode And Mocks](#test-mode-and-mocks)
+- [Browser Entry Point](#browser-entry-point)
+- [Package-Backed Composition](#package-backed-composition)
+- [Package Namespace Metadata](#package-namespace-metadata)
+
+## Canonical Module Descriptor
+
+The preferred module exposes one Principal Application Value through `default export`. The `__deps__` export is declarative metadata listing the values required to link it. The canonical declaration form is hierarchical and keyed by export name.
+
+```js
+// @ts-check
+
+export const __deps__ = {
+  default: {
+    cast: "App_Helper_Cast$",
+  },
+};
+
+export default class App_Root {
+  /**
+   * @param {{cast: (value: unknown) => string}} deps
+   */
+  constructor({ cast }) {
+    return {
+      configure(params = {}) {
+        return {
+          name: cast(params.name ?? "app"),
+        };
+      },
+    };
+  }
+}
+```
+
+Dependency module:
+
+```js
+// @ts-check
+
+export default function App_Helper_Cast() {
+  return function cast(value) {
+    return String(value);
+  };
+}
+```
+
+Rules:
+
+- the hierarchical export-scoped form is canonical;
+- each export entry maps constructor dependency names to dependency specifiers;
+- if `__deps__` is omitted, the module has no declared dependencies;
+- dependencies are resolved recursively before instantiation.
+
+## Canonical Container Setup
+
+The container is configured in the composition root before the first resolution.
+
+```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 container = new Container();
+container.addNamespaceRoot("App_", path.resolve(__dirname, "./src/App"), ".mjs");
+```
+
+Namespace roots may also use URL-backed module-specifier bases:
+
+```js
+container.addNamespaceRoot("App_", "https://cdn.example.com/app", ".mjs");
+```
+
+## Resolve Root Dependency
+
+Applications typically resolve one root dependency and let the container build the full object graph.
+
+```js
+const root = await container.get("App_Root$");
+console.log(root.configure({name: 123}).name);
+console.log(Object.isFrozen(root));
+```
+
+## Named Export
+
+Named exports are a JavaScript ecosystem compatibility surface. They use the `__ExportName` segment in the Dependency Specifier and the same hierarchical `__deps__` structure.
+
+```js
+export const __deps__ = {
+  default: {
+    cast: "App_Helper_Cast$",
+  },
+  Factory: {
+    cast: "App_Helper_Cast$",
+  },
+};
+
+export default class RuntimeWrapper {
+  constructor() {
+    return {mode: "runtime"};
+  }
+}
+
+export class Factory {
+  constructor({ cast }) {
+    this.configure = function (params = {}) {
+      return {
+        mode: "factory",
+        name: cast(params.name ?? "app"),
+      };
+    };
+  }
+}
+```
+
+Resolution examples:
+
+```js
+const runtime = await container.get("App_Module$");
+const factory = await container.get("App_Module__Factory$");
+```
+
+Without a lifecycle marker, the export is resolved as-is — the class or function itself, not an instance:
+
+```js
+const FactoryClass = await container.get("App_Module__Factory");
+const factory = new FactoryClass({cast: resolvedCast});
+```
+
+## Lifecycle Composition
+
+Common lifecycle-based compositions:
+
+```txt
+App_Service$
+App_Task$$
+App_Task$$$
+```
+
+- `$` creates and reuses a singleton instance;
+- `$$` creates a new instance for each request;
+- `$$$` uses direct factory composition: it produces a value for the request without lifecycle caching.
+
+## Wrappers
+
+Wrapper exports are selected by dependency specifier suffixes and are applied after postprocess hooks.
+
+```txt
+App_Service$$_wrapLog_wrapTrace
+```
+
+This pattern is useful when runtime behavior should be decorated without changing the service module contract.
+
+## Platform Modules
+
+Dependency Specifier may refer to platform modules directly.
+
+```txt
+node:fs
+npm:@humanfs/core
+node:worker_threads
+```
+
+These forms resolve the selected platform module export as-is unless a lifecycle marker is explicitly added.
+
+## Non-Canonical Shorthand
+
+A flat `__deps__` object is a supported shorthand for default-export-only modules, but it is not the canonical model.
+
+```js
+export const __deps__ = {
+  cast: "App_Helper_Cast$",
+};
+
+export default class App_Short {
+  constructor({ cast }) {
+    this.cast = cast;
+  }
+}
+```
+
+Prefer the hierarchical form for new integrations and for any module that exposes named exports.
+
+## Empty Descriptor
+
+Modules with no declared dependencies omit `__deps__` entirely.
+
+```js
+export default class App_Empty {
+  constructor() {
+    this.ready = function () {
+      return true;
+    };
+  }
+}
+```
+
+## Package-Backed Composition
+
+In Node.js, a composition root may import `PackageRegistry` from `@teqfw/di/node/registry/package`, import `NamespaceRegistry` from `@teqfw/di/node/registry/namespace`, use the latter for namespace roots, and independently inspect each immutable package record for application-owned metadata. Package discovery reads only static manifests and transitive dependencies; it does not resolve container values or interpret providers. These imports are forbidden in browser runtime modules. All `src/**` package subpaths are unsupported except the deprecated `@teqfw/di/src/Config/NamespaceRegistry.mjs` compatibility import; new code must use `@teqfw/di/node/registry/namespace` instead.
+
+Build namespace roots and register each one before the first `get()`:
+
+```js
+import fs from "node:fs/promises";
+import path from "node:path";
+import Container from "@teqfw/di";
+import NamespaceRegistry from "@teqfw/di/node/registry/namespace";
+
+const appRoot = "/absolute/path/to/application";
+const container = new Container();
+const namespaces = await new NamespaceRegistry({fs, path, appRoot}).build();
+
+for (const {prefix, dirAbs, ext} of namespaces) {
+  container.addNamespaceRoot(prefix, dirAbs, ext);
+}
+
+const root = await container.get("App_Root$");
+```
+
+`appRoot` is the absolute application root containing its `package.json`. Do not assume that the current working directory is that root unless the host application guarantees it.
+
+## Test Mode And Mocks
+
+Enable test mode and register mocks before the first `get()`. A registered mock is selected by canonical Dependency Specifier identity, bypasses resolution and instantiation, and is frozen before it is returned.
+
+```js
+const container = new Container();
+container.enableTestMode();
+container.register("App_Service$", mockService);
+
+const service = await container.get("App_Service$");
+```
+
+Do not use test mode as an application-time substitution mechanism: configuration is locked by the first `get()`.
+
+## Browser Entry Point
+
+The container and URL-backed namespace roots can be used in browser ESM code. Node.js registry utilities are excluded from browser runtime code.
+
+```html
+<script type="module">
+  import Container from "https://cdn.jsdelivr.net/npm/@teqfw/di@2/+esm";
+
+  const container = new Container();
+  container.addNamespaceRoot("App_", "https://cdn.example.com/app", ".mjs");
+</script>
+```
+
+## Package Namespace Metadata
+
+A package declares namespace mappings in `package.json` using `teqfw.fw.di.namespaces`; the declaration is always an array, including one mapping.
+
+```json
+{
+  "teqfw": {
+    "fw": {
+      "di": {
+        "namespaces": [
+          {"prefix": "App_", "path": "./src", "ext": ".mjs"}
+        ]
+      }
+    }
+  }
+}
+```
+
+Each `path` is a non-empty relative path from its publishing package, must resolve to an existing directory inside that package, and must use an ESM-compatible extension. Canonical metadata takes precedence over the legacy `teqfw.namespaces` array; they are never merged. Build registries and add their roots during composition, before the first `container.get()`.

package/src/AGENTS.md

@@ -14,16 +14,12 @@ This file defines only implementation-level obligations. It does not redefine ar
 
 The following documents are mandatory:
 
-- `ctx/docs/code/structure.md`
-- `ctx/docs/code/container.md`
-- `ctx/docs/code/resolver.md`
-- `ctx/docs/code/parser.md`
-- `ctx/docs/code/depid.md`
-- `ctx/docs/code/testing.md`
-- `ctx/docs/code/jsdoc-spec.md`
-- `ctx/docs/code/convention/es6-modules.md`
-- `ctx/docs/code/convention/teqfw/dto.md`
-- `ctx/docs/code/convention/teqfw/enum.md`
+- `ctx/docs/code/layout/structure.md`
+- `ctx/docs/code/components/container.md`
+- `ctx/docs/code/components/resolver.md`
+- `ctx/docs/code/components/parser.md`
+- `ctx/docs/code/components/depid.md`
+- `ctx/docs/code/layout/testing.md`
 
 Agent MUST read and follow them before generating or modifying code.
 
@@ -33,7 +29,7 @@ Deviation from these documents constitutes non-compliance.
 
 Directory layout, namespace mapping, file naming, dependency direction, and static import rules MUST strictly follow:
 
-`ctx/docs/code/structure.md`
+`ctx/docs/code/layout/structure.md`
 
 In particular:
 
@@ -42,7 +38,7 @@ In particular:
 - Underscores in file names are prohibited.
 - Namespace hierarchy MUST be reflected in directory hierarchy.
 - Static dependency direction MUST follow the allowed layer graph.
-- `Container.mjs` is the only public entry point.
+- `Container.mjs` is the primary runtime entry point; the package also exposes canonical Node.js registry subpaths and one deprecated migration-only registry compatibility subpath.
 
 Structural violations are execution errors.
 
@@ -50,7 +46,7 @@ Structural violations are execution errors.
 
 JSDoc is mandatory and governed by:
 
-`ctx/docs/code/jsdoc-spec.md`
+`ctx/docs/code/layout/structure.md` (Section 8)
 
 All implementation files MUST:
 
@@ -72,8 +68,8 @@ Absence of required JSDoc constitutes non-compliance.
 
 All DTO and Enum implementations MUST strictly follow:
 
-- `ctx/docs/code/convention/teqfw/dto.md`
-- `ctx/docs/code/convention/teqfw/enum.md`
+- `ctx/docs/code/components/depid.md`
+- `ctx/docs/code/layout/structure.md`
 
 In particular:
 
@@ -116,7 +112,7 @@ Redundant validation logic constitutes architectural violation.
 
 Unit and integration tests MUST follow:
 
-`ctx/docs/code/testing.md`
+`ctx/docs/code/layout/testing.md`
 
 For every testable source module, exactly one corresponding unit test MUST exist under `test/unit/`, mirroring directory structure.
 
@@ -127,6 +123,14 @@ Tests MUST use:
 
 Isolation and determinism requirements are mandatory.
 
+## Validation Tooling
+
+This package follows classical JavaScript module conventions and is a foundational TeqFW package.
+
+The `teqfw-esm-validator` skill and CLI MUST NOT be used for this project because their application-module profiles are not applicable to this package.
+
+Source changes MUST be verified with the project-provided tests and applicable classical JavaScript checks, including `node --check`, local lint commands, and local type checks when available.
+
 ## Type Declaration Discipline
 
 The file `types.d.ts` defines exported structural type aliases corresponding to implementation modules.