@flancer32/teq-web 0.4.0 → 0.5.0

package/CHANGELOG.md

@@ -1,5 +1,25 @@
 # Changelog
 
+## [0.5.0] - 2026-03-13
+
+### Added
+- Added `ai/` documentation for agent-oriented project materials.
+- Added a non-resettable request-context attribute.
+- Added component type conventions to the cognitive context.
+
+### Changed
+- Updated `README.md` with package and agent-interface documentation refinements.
+- Migrated dependency injection to `@teqfw/di` v2 and updated package metadata accordingly.
+- Refined architecture and terminology around the dispatcher, request context, and transport boundary.
+- Reworked source files to codex-generated module layout and aligned exported namespace style with the `$` convention.
+- Verified modules in `src/` against updated TeqFW ES module conventions and aligned DTO component types with those rules.
+- Restructured and cleaned up `ctx/docs`, including TeqFW convention documents and removal of the obsolete composition level.
+- Moved the accept test into the integration test suite.
+- Refreshed runtime and development dependencies.
+
+### Removed
+- Removed legacy code, tests, and the shared `common.mjs` unit-test helper.
+
 ## [0.4.0] - 2025-12-20
 
 ### Added

package/README.md

@@ -1,152 +1,240 @@
 # @flancer32/teq-web
 
-**@flancer32/teq-web** is a modular request dispatcher and web server for Node.js applications.  
-It follows the principles of the [TeqFW](https://github.com/flancer32/teqfw) architecture but works independently and
-can be integrated into any Node.js project.  
-The plugin offers a flexible, pluggable HTTP/2-capable server with three-stage handler processing and dependency-driven
-execution order.
+Infrastructure web server and deterministic request pipeline for TeqFW packages.
 
----
+`@flancer32/teq-web` is an infrastructural component of the **Tequila Framework (TeqFW)** platform.
+
+The package provides a deterministic **request lifecycle pipeline** and a built-in **Node.js web server** that other TeqFW packages can use as the runtime environment for processing HTTP requests.
+
+Within the TeqFW ecosystem, this package plays a role similar to how **Express** or **Fastify** are used in typical Node.js applications: it acts as the **web runtime layer** used by higher-level packages.
+
+Unlike general-purpose web frameworks, this package focuses only on coordinating **request lifecycle execution through a deterministic handler pipeline**.
+
+The package requires the dependency container **@teqfw/di**.
+
+Platform website: <https://teqfw.com/>
 
 ## Overview
 
-This package provides:
+The package provides infrastructure for processing web requests inside a TeqFW application.
+
+Core responsibilities:
+
+- deterministic **request lifecycle coordination**
+- ordered **handler execution pipeline**
+- **Node.js server integration** (`http`, `http2`, `https`)
+- **handler registration metadata**
+- **static file handler**
+- DTO factories and enums used by handler implementations
+
+The package does **not** provide:
+
+- routing frameworks
+- controllers
+- application architecture
+- persistence
+- session management
+- business logic abstractions
+
+Its sole responsibility is coordinating the **lifecycle of a web request**.
+
+## Role in the TeqFW Ecosystem
+
+| Layer                | Responsibility                            |
+| -------------------- | ----------------------------------------- |
+| Application packages | business logic, handlers                  |
+| `@flancer32/teq-web` | web server and request lifecycle pipeline |
+| `@teqfw/di`          | runtime dependency linking                |
+
+TeqFW applications are composed of multiple packages that declare dependencies through the DI container.
+
+`@flancer32/teq-web` provides the **web runtime layer** in which those packages handle incoming requests.
+
+## Request Lifecycle
+
+Each request is processed through a fixed three-stage pipeline:
+
+```text
+INIT → PROCESS → FINALIZE
+```
 
-- A **dispatcher** that processes HTTP requests in three well-defined stages: `pre`, `process`, `post`.
-- A **handler interface** for modular request handling across plugins or components.
-- A **built-in server** based on Node.js libraries (`http`, `http2`), supporting TLS via `http2.createSecureServer()`.
-- Support for **relative handler ordering** using `before` / `after` declarations and topological sorting.
-- Compatibility with **external servers** like Express/Fastify by using the dispatcher as middleware.
-- Minimal dependencies and full support for dependency injection via `@teqfw/di`.
+Stage semantics:
 
----
+| Stage    | Purpose                                           |
+| -------- | ------------------------------------------------- |
+| INIT     | request preparation (logging, enrichment, guards) |
+| PROCESS  | request handling                                  |
+| FINALIZE | cleanup and post-processing                       |
 
-## Architecture
+Processing stops when a `PROCESS` handler marks the request as completed.
 
-The dispatcher runs HTTP requests through a consistent three-phase pipeline:
+If no handler handles the request, the system produces **404 Not Found**.
 
-1. **Pre-processing (`pre`)** — All handlers are executed in a defined order (e.g., logging, authentication).
-2. **Processing (`process`)** — Handlers are checked sequentially until one returns `true` (request handled).
-3. **Post-processing (`post`)** — All handlers are executed unconditionally, even after errors.
+## Core Components
 
-Each handler provides its registration metadata via the `getRegistrationInfo()` method. Execution order is resolved with
-a built-in implementation of Kahn's algorithm.
+### Pipeline Engine
 
-Example handler definition:
+The **Pipeline Engine** is the single lifecycle coordination authority.
 
-```js
-const My_Handler = {
-    getRegistrationInfo: () => Object.freeze({
-        name: 'My_Handler',
-        stage: 'process', // can be 'pre', 'process', or 'post'
-        before: [],
-        after: [],
-    }),
+Responsibilities:
 
-    handle: async (req, res) => {
-        res.writeHead(200, {'Content-Type': 'text/plain'});
-        res.end('Hello from My_Handler!');
-        return true;
-    },
+- handler registration
+- deterministic handler ordering
+- request lifecycle execution
+- request completion control
+- runtime error handling
+
+Handlers are ordered based on declarative metadata (`before` / `after` constraints).
+
+### Server
+
+The built-in server connects the Node.js transport layer to the request pipeline.
+
+Supported server types:
+
+- `http`
+- `http2`
+- `https`
+
+The server locks the handler pipeline before entering the execution phase.
+
+### Handlers
+
+Handlers are independent modules participating in request processing.
+
+Each handler provides registration metadata:
+
+- unique handler name
+- execution stage
+- relative ordering constraints
+
+Handlers do not coordinate with each other directly. Execution order is derived from metadata and is deterministic.
+
+## Example (TeqFW Style)
+
+```javascript
+// App/Web/Handler/Hello.mjs
+
+export const __deps__ = {
+  dtoInfoFactory: "Fl32_Web_Back_Dto_Info__Factory$",
+  STAGE: "Fl32_Web_Back_Enum_Stage$",
 };
 
-export default My_Handler;
-````
-
----
-
-## Usage
-
-This example shows how to create a minimal application that:
-
-* Registers two handlers: a logger and a static file server
-* Starts a secure HTTPS server using built-in components
-
-The static handler reads from one or more **sources** described by the
-`Handler_Source` DTO. To expose selected files from `node_modules`, create a
-source with `root: 'node_modules'` and pass it to `Handler_Static` during
-initialization.
-
-```js
-import Container from '@teqfw/di';
-import {readFileSync} from 'node:fs';
-import {join, resolve} from 'node:path';
-import {fileURLToPath} from 'node:url';
-
-// Resolve working directory
-const __filename = fileURLToPath(import.meta.url);
-const __dirname = resolve(__filename, '..');
-const webRoot = join(__dirname, 'web');
-const certs = join(__dirname, 'certs');
-
-// DI container setup
-const container = new Container();
-const resolver = container.getResolver();
-resolver.addNamespaceRoot('Fl32_Web_', './node_modules/@flancer32/teq-web/src');
-
-// Get and configure built-in handlers
-const logHandler = await container.get('Fl32_Web_Back_Handler_Pre_Log$');
-const staticHandler = await container.get('Fl32_Web_Back_Handler_Static$');
-const SourceCfg = await container.get('Fl32_Web_Back_Dto_Handler_Source$');
-const srcNpm = SourceCfg.create({
-    root: 'node_modules',
-    prefix: '/node_modules/',
-    allow: {
-        vue: ['dist/vue.global.prod.js'],
-        '@teqfw/di': ['src/Container.js'],
-    }
-});
-const srcWeb = SourceCfg.create({ root: webRoot, prefix: '/' });
-await staticHandler.init({sources: [srcNpm, srcWeb]});
-
-// Register handlers
-const dispatcher = await container.get('Fl32_Web_Back_Dispatcher$');
-dispatcher.addHandler(logHandler);
-dispatcher.addHandler(staticHandler);
-
-// Create and start the server
-const server = await container.get('Fl32_Web_Back_Server$');
-await server.start({
-    port: 3443,
-    type: 'https',
-    tls: {
-        key: readFileSync(join(certs, 'key.pem'), 'utf8'),
-        cert: readFileSync(join(certs, 'cert.pem'), 'utf8'),
-        ca: readFileSync(join(certs, 'ca.pem'), 'utf8'),
-    }
-});
+export default class App_Web_Handler_Hello {
+  constructor({ dtoInfoFactory, STAGE }) {
+    const info = dtoInfoFactory.create({
+      name: "App_Web_Handler_Hello",
+      stage: STAGE.PROCESS,
+    });
+
+    this.getRegistrationInfo = () => info;
+
+    this.handle = async function (context) {
+      const { response } = context;
+
+      response.writeHead(200, { "Content-Type": "text/plain" });
+      response.end("ok");
+
+      context.complete();
+    };
+  }
+}
+```
+
+```javascript
+// App/Web/Server/Start.mjs
+
+export const __deps__ = {
+  pipeline: "Fl32_Web_Back_PipelineEngine$",
+  server: "Fl32_Web_Back_Server$",
+  helloHandler: "App_Web_Handler_Hello$",
+};
+
+export default class App_Web_Server_Start {
+  constructor({ pipeline, server, helloHandler }) {
+    this.execute = async function () {
+      pipeline.addHandler(helloHandler);
+
+      await server.start({
+        port: 3000,
+        type: "http",
+      });
+    };
+  }
+}
+```
+
+Application entry point:
+
+```javascript
+const app = await container.get("App_Web_Server_Start$");
+await app.execute();
 ```
 
-This will start an HTTPS server on port `3443` with:
+## Designed for Development with LLM Agents
+
+TeqFW is an architectural approach designed for software development in which **LLM agents participate directly in the development process**.
+
+Traditional software architectures assume that all code is written and maintained by humans.
+
+TeqFW assumes a different workflow:
+
+- humans design the **architecture and specifications**
+- LLM agents generate and maintain the **implementation**
+
+To support this workflow, TeqFW structures applications so they are easier for automated agents to analyze and modify.
+
+Key design principles include:
+
+- explicit dependency contracts
+- deterministic runtime linking
+- predictable module structure
+- namespace-based component addressing
+- minimal hidden coupling between modules
+
+This allows systems to be more reliably:
 
-* `Fl32_Web_Back_Handler_Pre_Log` logging each request method and URL;
-* `Fl32_Web_Back_Handler_Static` serving files from `node_modules` and the `/web` folder.
+- analyzed
+- generated
+- refactored
+- extended
 
----
+by both **human developers and AI agents**.
 
-### Using with Express or Fastify
+## Agent-Driven Implementation
 
-The dispatcher can be connected to external web frameworks instead of the built-in server.
+TeqFW libraries are developed using **Agent-Driven Software Management (ADSM)**, a methodology created by **Alex Gusev**.
 
-```js
-// Express
-const app = Express();
-app.use(async (req, res) => {
-    await dispatcher.onEventRequest(req, res);
-});
-app.listen(3000);
+The workflow is:
 
-// Fastify
-const fastify = Fastify();
-fastify.all('*', async (request, reply) => {
-    const req = request.raw;
-    const res = reply.raw;
-    await dispatcher.onEventRequest(req, res);
-});
-await fastify.listen({port: 3000});
+1. A human architect defines the **product model and specifications**
+2. **LLM agents (Codex)** generate the implementation
+3. The human architect reviews and integrates the generated code
+
+This package is part of that experiment and demonstrates how **human-designed architecture can be implemented by AI agents**.
+
+## Agent Interface
+
+This package includes **agent interface documentation** intended for LLM agents that use the library as a dependency.
+
+These documents are distributed inside the package in:
+
+```text
+./ai/
 ```
 
----
+For a quick integration reference, see:
+
+- `ai/examples/minimal-server.md`
+
+They describe:
+
+- runtime abstractions
+- request lifecycle semantics
+- handler contracts
+- integration rules for TeqFW applications
+
+Human developers typically read the README and source code, while **LLM agents can rely on the documentation in `./ai/`.**
 
 ## Installation
 
@@ -154,11 +242,32 @@ await fastify.listen({port: 3000});
 npm install @flancer32/teq-web
 ```
 
-This plugin requires a configured `@teqfw/di` container and optionally integrates with TeqFW-based apps.
+The package requires a configured `@teqfw/di` container.
+
+## Tequila Framework
+
+`@flancer32/teq-web` is part of the **Tequila Framework (TeqFW)** ecosystem.
+
+More information about the platform:
+[https://teqfw.com/](https://teqfw.com/)
+
+TeqFW is an experimental platform exploring how software architecture changes when **AI agents become active participants in the development process**.
+
+Key architectural ideas include:
+
+- modular monolith architecture
+- runtime dependency linking
+- namespace-based component addressing
+- pure JavaScript without compilation
+- system structures optimized for collaboration with LLM agents
+
+## Author
+
+**Alex Gusev**
 
----
+Creator of:
 
-## Status
+- **Tequila Framework (TeqFW)**
+- **ADSM (Agent-Driven Software Management)**
 
-This package is under active development and already used in real-world applications. Documentation is built using the
-**3DP** method (Dialog-Driven Development Process) and evolves alongside actual use cases.
+This project explores how software architecture evolves when **LLM agents become active participants in the development process**.

package/ai/AGENTS.md

@@ -0,0 +1,36 @@
+# AGENTS.md
+
+Version: 20260311
+
+## Package Purpose
+
+This directory provides the Agent Interface of `@flancer32/teq-web`. It contains a compact usage-oriented projection of the package intended for LLM agents that consume the package as a dependency inside TeqFW applications.
+
+The interface describes how external code should use the package and excludes repository organization, development workflow, testing strategy, and other internal project concerns.
+
+## TeqFW Usage Model
+
+`@flancer32/teq-web` is designed for TeqFW-style runtime composition with `@teqfw/di`.
+
+Dependencies should be linked through Canonical Dependency Codes and constructor injection rather than through direct static imports between application modules. External code should treat the package as infrastructure resolved by the container:
+
+- application modules declare dependencies through `__deps__`;
+- the container resolves `Fl32_Web_*` identifiers at runtime;
+- orchestration is performed inside DI-managed application services;
+- handlers and server components are configured before the server enters execution phase.
+
+## Reading Order
+
+Agents should read the documents in this directory in the following order:
+
+1. `AGENTS.md` — overview of the agent interface and navigation.
+2. `overview.md` — package role, intended usage boundary, and main entry points.
+3. `abstractions.md` — core runtime concepts and consumer-facing abstractions.
+4. `rules.md` — mandatory usage constraints and invariants.
+5. `examples/minimal-server.md` — minimal TeqFW-style orchestration example.
+
+## Interface Scope
+
+The documents in this directory define only the supported usage semantics relevant to package consumers. Behaviors not described here should be treated as undefined and should not be inferred from internal implementation details.
+
+Internal helper modules and deep implementation paths are outside the preferred consumer interface unless a task explicitly requires them.

package/ai/abstractions.md

@@ -0,0 +1,75 @@
+# Core Abstractions
+
+## Pipeline Engine
+
+`Fl32_Web_Back_PipelineEngine$` is the single lifecycle coordinator. It owns handler registration, derives deterministic order from handler metadata, creates one request context per request, and executes handlers in this fixed order:
+
+`INIT -> PROCESS -> FINALIZE`
+
+Main methods:
+
+- `addHandler(handler)` or `registerHandler(handler)` registers a handler before the pipeline is locked;
+- `lockHandlers()` freezes handler order explicitly;
+- `onEventRequest(req, res)` or `handleRequest(req, res)` executes one request lifecycle.
+
+## Server
+
+`Fl32_Web_Back_Server$` is the built-in transport adapter around Node.js `http` and `http2`. On `start(cfg)` it locks the pipeline, creates the server instance, binds request events to the Pipeline Engine, and starts listening.
+
+Config is created with `Fl32_Web_Back_Server_Config$`. Supported transport modes come from `Fl32_Web_Back_Enum_Server_Type$`:
+
+- `http`
+- `http2`
+- `https`
+
+`https` requires TLS config.
+
+## Handler Contract
+
+Custom handlers implement `Fl32_Web_Back_Api_Handler`:
+
+- `getRegistrationInfo()` returns handler metadata;
+- `handle(context)` performs work for one request.
+
+Handler metadata is created with `Fl32_Web_Back_Dto_Info__Factory$` and contains:
+
+- `name`: unique handler name;
+- `stage`: `INIT`, `PROCESS`, or `FINALIZE`;
+- `before`: handler names that must run after this handler;
+- `after`: handler names that must run before this handler.
+
+Ordering is resolved once from this metadata and is deterministic within each stage.
+
+## Request Context
+
+The Pipeline Engine passes one request-scoped context to every handler. Its stable fields are:
+
+- `request`: Node.js request object;
+- `response`: Node.js response object;
+- `data`: mutable per-request shared storage for handlers;
+- `completed`: completion flag;
+- `complete()`: marks request processing as completed;
+- `isCompleted()`: reads the completion state.
+
+Handlers may mutate `data` and may read the rest of the context. They must not replace the context object.
+
+## Stage Semantics
+
+- `INIT`: always runs first; use for setup, logging, request enrichment, or guard preparation.
+- `PROCESS`: runs until completion is marked; use for actual request handling.
+- `FINALIZE`: always runs last; use for cleanup and post-processing.
+
+Only `PROCESS` handlers may mark the request as completed.
+
+## Built-in Static Handler
+
+`Fl32_Web_Back_Handler_Static$` is a PROCESS-stage handler for static file delivery. Before use, call `init({sources})` with source DTOs created by `Fl32_Web_Back_Dto_Source$Factory`.
+
+Each source describes:
+
+- `root`: filesystem root;
+- `prefix`: URL prefix matched by the handler;
+- `allow`: optional allowlist map for paths under the source;
+- `defaults`: optional fallback filenames for directory requests.
+
+If the static handler serves a file successfully, it marks the request as completed.

package/ai/examples/minimal-server.md

@@ -0,0 +1,78 @@
+# Minimal Server Example
+
+This example shows the preferred TeqFW-style usage path: external code resolves one application service from the container, and that service receives web infrastructure through constructor injection.
+
+```js
+// App/Web/Handler/Hello.mjs
+// @ts-check
+
+export const __deps__ = {
+    dtoInfoFactory: 'Fl32_Web_Back_Dto_Info__Factory$',
+    STAGE: 'Fl32_Web_Back_Enum_Stage$',
+};
+
+export default class App_Web_Handler_Hello {
+    /**
+     * @param {{
+     *   dtoInfoFactory: Fl32_Web_Back_Dto_Info$Factory,
+     *   STAGE: Fl32_Web_Back_Enum_Stage,
+     * }} deps
+     */
+    constructor({dtoInfoFactory, STAGE}) {
+        const info = dtoInfoFactory.create({
+            name: 'App_Web_Handler_Hello',
+            stage: STAGE.PROCESS,
+        });
+
+        this.getRegistrationInfo = () => info;
+
+        this.handle = async function (context) {
+            const {response} = context;
+            response.writeHead(200, {'Content-Type': 'text/plain; charset=utf-8'});
+            response.end('ok');
+            context.complete();
+        };
+    }
+}
+```
+
+```js
+// App/Web/Server/Start.mjs
+// @ts-check
+
+export const __deps__ = {
+    pipeline: 'Fl32_Web_Back_PipelineEngine$',
+    server: 'Fl32_Web_Back_Server$',
+    helloHandler: 'App_Web_Handler_Hello$',
+};
+
+export default class App_Web_Server_Start {
+    /**
+     * @param {{
+     *   pipeline: Fl32_Web_Back_PipelineEngine,
+     *   server: Fl32_Web_Back_Server,
+     *   helloHandler: App_Web_Handler_Hello,
+     * }} deps
+     */
+    constructor({pipeline, server, helloHandler}) {
+        this.execute = async function () {
+            pipeline.addHandler(helloHandler);
+            await server.start({port: 3000, type: 'http'});
+        };
+    }
+}
+```
+
+```js
+// composition root
+const app = await container.get('App_Web_Server_Start$');
+await app.execute();
+```
+
+Consumer notes:
+
+- The composition root configures namespace roots once and resolves one application entry service.
+- Application modules do not construct collaborators directly and do not call `new` for DI-managed handlers or infrastructure services.
+- `server.start()` locks handler registration for the runtime lifetime of that server instance.
+- If your application already has its own transport layer, inject `Fl32_Web_Back_PipelineEngine$` and call `pipeline.onEventRequest(req, res)` from that adapter instead of using `Fl32_Web_Back_Server$`.
+- A correct PROCESS handler ends the response and then marks the context completed.

package/ai/overview.md

@@ -0,0 +1,27 @@
+# Package Overview
+
+`@flancer32/teq-web` is server-side request coordination infrastructure for TeqFW applications. It provides a deterministic handler pipeline for web requests and a built-in Node.js server that feeds requests into that pipeline.
+
+This package is not a general-purpose web framework. It does not define routing, controllers, domain models, persistence, session handling, or application structure. Its role is limited to coordinating one request lifecycle inside a TeqFW modular monolith.
+
+The package assumes `@teqfw/di` and exposes its runtime surface through DI-managed modules under the `Fl32_Web_` namespace rooted at the published `src/` tree. In normal usage, application modules receive these dependencies through constructor injection and orchestrate them from DI-managed services rather than creating containers or wiring collaborators manually inside feature code.
+
+Use this package when external code needs one of these roles:
+
+- accept HTTP, HTTPS, or HTTP/2 requests with the built-in server;
+- run request handlers through a fixed three-stage lifecycle;
+- register multiple independent handlers with deterministic ordering;
+- serve static files through the built-in PROCESS-stage handler.
+
+Do not use this package as:
+
+- a manually wired standalone web platform outside TeqFW DI;
+- a replacement for an application router or MVC framework;
+- a browser, CLI, or serverless runtime component.
+
+The main consumer entry points are:
+
+- `Fl32_Web_Back_PipelineEngine$` for request lifecycle coordination;
+- `Fl32_Web_Back_Server$` for the built-in Node.js server;
+- `Fl32_Web_Back_Api_Handler` plus `Fl32_Web_Back_Dto_Info__Factory$` and `Fl32_Web_Back_Dto_Info` for custom handlers;
+- `Fl32_Web_Back_Handler_Static$` plus `Fl32_Web_Back_Dto_Source` values for static file serving.