@telorun/http-server 0.3.4 → 0.5.0

package/CHANGELOG.md

@@ -1,5 +1,112 @@
 # @telorun/http-server
 
+## 0.5.0
+
+### Major Changes
+
+- b62e535: Streaming-Invocable convention, format-codec packages, and `Http.Api` `content:` map rewrite.
+
+  **Breaking** (`@telorun/http-server`, `@telorun/ai`):
+
+  - `Http.Api.routes[].returns[]` and `routes[].catches[]` (and the equivalent `Http.Server.notFoundHandler` lists) drop top-level `body` / `schema` in favour of a per-MIME `content:` map. Buffer-mode entries use `content[<mime>].body` / `content[<mime>].schema`; stream-mode entries use `content[<mime>].encoder` (ref to any `Codec.Encoder`). The map key is the canonical `Content-Type` — declaring `Content-Type` in `headers:` is rejected at load time. Multi-key `content:` maps are negotiated against the request's `Accept` header (RFC 9110 §12.5.1). Mismatch → `406 Not Acceptable`.
+  - `mode: stream` is forbidden in `catches:` (catches fire pre-stream; no upstream iterable to feed an encoder).
+  - Migration: every existing `returns: [..., body: ..., schema: ..., headers: { Content-Type: ... }]` rewrites mechanically to `returns: [..., content: { <mime>: { body, schema } }]`. In-tree manifests (`apps/registry`, `examples/*`, `tests/*`, `benchmarks/*`) migrated.
+  - `Ai.TextStream`: `format` field removed; controller no longer encodes the wire — it returns `{ output: Stream<StreamPart> }`. Pair with a format-codec encoder (`Ndjson.Encoder`, `Sse.Encoder`, `PlainText.Encoder`) for HTTP responses or other byte transports. `text-stream-drain-controller.ts` removed (replaced by inline source → encoder → decoder steps).
+  - `StreamPart.error` shape changed from native `Error` to `{ message, code?, data? }` so generic encoders can JSON-serialize error frames without bespoke translation.
+
+  **New** (`@telorun/codec`, `@telorun/plain-text-codec`, `@telorun/ndjson-codec`, `@telorun/sse-codec`, `@telorun/octet-codec`):
+
+  - `@telorun/codec` ships the `Encoder` and `Decoder` abstracts (no controllers — pure contracts).
+  - Format-codec packages each carry one or both directions: `PlainText.Encoder/.Decoder` (UTF-8 collect + emit), `Ndjson.Encoder` (one JSON record per line), `Sse.Encoder` (Server-Sent Events frames), `Octet.Encoder/.Decoder` (raw bytes pass-through and collect).
+  - All encoders implement `invoke({input}): Promise<{output: Stream<Uint8Array>}>` per the streaming-Invocable convention.
+
+  **New** (`@telorun/sdk`):
+
+  - `Stream<T>` class wrapping `AsyncIterable<T>`. Producers wrap their iterables in `new Stream(...)` so the value's constructor is recognized by CEL's runtime type-checker (which rejects unrecognized constructors like `AsyncGenerator` and Node `Readable`). The analyzer registers `Stream` as a CEL object type.
+
+  **Annotation** (`@telorun/kernel`, `@telorun/analyzer`):
+
+  - `x-telo-stream: true` schema annotation on input/output properties marks them as carrying a `Stream<T>`. CEL passes the value through by reference; analyzer's chain validator rejects `.field` / `[index]` access past a stream-marked property. Convention: streaming Invocables put the stream on `input` (inputs) and `output` (result).
+  - `Self.<Abstract>` magic alias auto-registered for every Telo.Library/Application — lets concrete kinds in the same library use `extends: Self.<Abstract>` without a self-import that would loop the loader.
+  - Analyzer's `buildReferenceFieldMap`, `resolveFieldValues`, `extractInlinesAtPath`, and `injectAtPath` (Phase 5) now recurse into `additionalProperties` via a `{}` path-segment marker. Required for refs nested inside open-keyed maps like `content[<mime>].encoder`.
+  - `isInlineResource` widened: bare-kind refs (`{kind: X}` with no `name` and no extra config) are now treated as inline-singleton definitions and Phase 2 extracts them as fresh stateless resources. Previously `{kind: X}` raised `INVALID_REFERENCE` (treated as a malformed named ref). This matches the runtime-side `resolveChildren` semantics already documented for `Run.Throw`-style stateless inlines, and lets `encoder: {kind: Ndjson.Encoder}` work without boilerplate. Manifests that had `{kind: X}` with the (broken) intent of resolving to an existing named resource will now silently extract a fresh resource — extremely unlikely in practice (those refs were already failing analysis), but worth flagging for downstream consumers.
+
+  **Behaviour changes worth flagging** (`@telorun/http-server`):
+
+  - **Single-key `content:` maps now do `Accept` negotiation.** A route declaring only `content: { application/json: ... }` returns `406 Not Acceptable` for `Accept: image/png` — RFC 9110 §15.5.7 compliant. Pre-PR, the legacy top-level `body:` shape ignored `Accept` entirely. To preserve "always send" behaviour, declare `*/*` as an explicit key.
+  - **Accept matching ignores media-type parameters** beyond the first `;`. `Accept: text/plain; charset=ascii` matches `content: { 'text/plain; charset=utf-8': ... }`. Q-values are still parsed for ranking; only the matching predicate ignores params. Authors needing parameter-level preference must declare distinct keys per parameter combo.
+  - **Load-time validators reject misconfigured `content:` shapes.** `validateContentEntryShape` rejects `body+encoder` together (mutually exclusive), missing `encoder` under `mode: stream`, `body` under `mode: stream`, and `encoder` under `mode: buffer`. Previously some of these slipped through to runtime where they manifested as 500-on-negotiation.
+  - **Mid-stream `pipeline()` failures emit `Http.Api.streamFailed` events.** Once `reply.hijack()` runs, mid-stream errors (encoder throws, broken pipe) bypass `catches:` by design (response is committed). They now emit a structured event with `path`, `method`, `status`, `mime`, and the error so operators can observe failures that would otherwise be silent.
+
+  **Other** (`@telorun/http-client`, `@telorun/javascript`):
+
+  - `HttpClient.Request` `mode: stream` returns `{ output: Stream<Uint8Array> }` instead of a bare `Readable` — fits the streaming-Invocable convention, pairs with `Octet.Encoder` for HTTP pass-through.
+  - `JS.Script` injects `Stream` into every script's scope (via the second function argument, destructured at the top of the wrapper). User code can `new Stream(asyncGen)` directly.
+
+  **Tests**:
+
+  - New Layer 1 hermetic streaming-contract test (`modules/ai/tests/text-stream-streaming-contract.yaml`) — three sub-targets, byte-exact NDJSON / SSE / PlainText.
+  - New Layer 2 live OpenAI streaming smoke (`modules/ai-openai/tests/openai-live-text-stream.yaml`) — env-gated; exercises `Ai.TextStream → Ndjson.Encoder → PlainText.Decoder` against the real provider.
+  - New http-server integration test (`modules/http-server/tests/text-stream-via-http.yaml`) — exercises three single-format routes plus a four-format negotiated route with five Accept variants.
+
+### Minor Changes
+
+- 0331069: Widen every "handler-shaped" `x-telo-ref` slot to accept both `telo#Invocable` and `telo#Runnable`, so dual-mode kinds — most commonly `Run.Sequence`, whose controller implements both `run()` and `invoke()` — pass static reference validation without each kind declaring secondary capabilities on its own definition.
+
+  Affected slots:
+
+  - `@telorun/http-server`: `Http.Server.parsers[].parser`, `Http.Server.notFoundHandler.invoke`, `Http.Api.routes[].handler`.
+  - `@telorun/mcp-server`: `Mcp.Tools.entries[].handler`, `Mcp.Resources.entries[].handler`, `Mcp.Prompts.entries[].handler`.
+  - `@telorun/lambda`: `Lambda.HttpApi.routes[].handler`, `Lambda.Sqs.handler`, `Lambda.Direct.handler`.
+
+  Mechanism: each slot's single `x-telo-ref: "telo#Invocable"` is replaced by an `anyOf:` block carrying both refs. The analyzer's reference-field-map walker already collects refs from `anyOf` branches and `checkKind` early-returns on the first match — so the union semantics are honoured without any analyzer change. AJV value-shape validation continues through the slot's existing `oneOf:` (string vs. object form), unchanged.
+
+  Runtime behaviour is unchanged: the kernel calls whichever method the handler's controller exposes (`.invoke()` or `.run()`). This release just lets the schema admit what the kernel already accepts.
+
+### Patch Changes
+
+- c0129c0: Align local `@telorun/http-server` version with the published `std/http-server@2.0.0` on the registry. The local manifest had diverged onto a parallel `1.x` line; this realigns the version stamp so the next publish bumps from `2.0.0` rather than backwards from `1.1.0`.
+
+- be79957: Move `@telorun/sdk` to `peerDependencies` across the kernel, analyzer, templating, and every module.
+
+  The SDK carries the `Stream` class registered with `@marcbachmann/cel-js` for stream-typed CEL values. cel-js identifies object types by constructor identity, so a second copy of `@telorun/sdk` in the install tree silently breaks streaming-typed evaluations with `Unsupported type: Stream`. The contract was previously enforced with three layered mechanisms (a generated `dist/generated/runtime-deps.json` driving install-root `dependencies`, `overrides` + `pnpm.overrides` blocks, and a `globalThis`-keyed singleton in `stream.ts`); the build artifact silently degraded when the kernel was run without a build step, defeating the layering.
+
+  The new shape:
+
+  - Every package that imports `@telorun/sdk` declares it as a `peerDependency`. Consumers (the kernel's install root, the CLI, apps) provide a single copy and `peerDependencies` cause npm/pnpm to resolve every transitive import to it.
+  - The kernel's `NpmControllerLoader` no longer reads `runtime-deps.json`; the realm-collapse name list is a hardcoded constant (`REALM_COLLAPSE_NAMES = ["@telorun/sdk"]`) in `npm-loader.ts`. The install-root `package.json` it writes drops the `overrides` and `pnpm.overrides` blocks — peer-dep resolution makes them redundant.
+  - `scripts/generate-runtime-deps.mjs` and the generated artifact are removed; `scripts/prepack-bake-overrides.mjs` no longer chains the runtime-deps regeneration.
+  - The `globalThis` singleton in `sdk/nodejs/src/stream.ts` is **kept** as a safety net for environments that still end up with mismatched SDK copies (e.g. a controller install from a tarball that predates this change).
+
+  Consumers installing `@telorun/kernel` or any module directly must now ensure `@telorun/sdk` is present in their dependency tree. The kernel already lists it via the install root for any manifest it boots, so kernel-driven usage is unaffected.
+
+- Updated dependencies [849f57a]
+- Updated dependencies [be79957]
+  - @telorun/sdk@0.12.0
+  - @telorun/http-dispatch@0.3.0
+
+- Updated dependencies [b62e535]
+  - @telorun/sdk@0.12.0
+
+## 0.4.0
+
+### Minor Changes
+
+- 0f80fc5: `Bench.Suite.scenarios[*]` and `Http.Server.notFoundHandler` follow the canonical sibling shape: `invoke:` describes the dispatch target only; `inputs:` carries the call-time arguments as a sibling. The previously-accepted nested `invoke.inputs` form is gone — the benchmark runtime now reads `scenario.inputs` and the http-server runtime now reads `notFoundHandler.inputs`. Five benchmark manifests, one example, and `apps/registry/telo.yaml` migrated to the sibling form.
+
+  Statically validate CEL expressions inside `Telo.Definition` template bodies. The analyzer now registers `self` (typed from the definition's `schema:`) and `inputs` (typed from `inputType:`, falling back to the `extends:`-declared abstract's `inputType:`) as available variables in `resources:` / `invoke:` / `run:` / `provide:` / top-level `inputs:` / top-level `result:` fields, catching typos at load time instead of first invocation.
+
+  Aligns Telo.Definition's template-body shape with how Run.Sequence steps factor dispatch from data: `invoke:` / `provide:` / `run:` describe the dispatch target only; `inputs:` (values passed to the target) and `result:` (provide-only post-call mapping) live as top-level siblings on the definition. The previous nested `invoke.inputs` shape is gone — the kernel template controller now reads `definition.inputs`, and `modules/sql-repository/Read` migrates to the sibling form.
+
+  Inside top-level `result:`, the `result` CEL variable is typed from the dispatch target's `outputType:`. The produced top-level `result` value is also AJV-checked against the abstract this definition `extends` (`outputType`); top-level `inputs` is AJV-checked against the dispatch target's `inputType` when declared. Mismatches surface as a new `TEMPLATE_TARGET_MISMATCH` diagnostic.
+
+  Adds two reusable context-annotation forms used by the `Telo.Definition` builtin schema and available to any module that needs the same capabilities:
+
+  - `x-telo-context-from-root: "<path>"` — root-anchored navigation (replace semantics), used to type variables sourced from a top-level field regardless of where the CEL appears.
+  - `x-telo-context-from-ref-kind: "<refPath>#<field>"` — reads a kind name from `manifestRoot.<refPath>`, resolves it via the definition registry, and returns that kind's `<field>` schema.
+
+  Schema-extracted contexts are now sorted by scope specificity (longest first) so the first-match-wins resolver picks the most-specific context. No existing module relied on the previous ordering (no overlapping scopes), so this change is observably backward-compatible.
+
 ## 0.3.4
 
 ### Patch Changes
@@ -66,60 +173,6 @@
 
 - d3ed5a5: Tighten `Http.Api.routes[].request.headers` to declare `additionalProperties: { type: "string" }`. Header values are matched as strings against the incoming request, so the schema now reflects what the runtime actually accepts. The telo editor renders this field as a key/value map editor instead of the JSON Schema designer.
 
-## 1.0.0
-
-### Major Changes
-
-- b62e535: Streaming-Invocable convention, format-codec packages, and `Http.Api` `content:` map rewrite.
-
-  **Breaking** (`@telorun/http-server`, `@telorun/ai`):
-
-  - `Http.Api.routes[].returns[]` and `routes[].catches[]` (and the equivalent `Http.Server.notFoundHandler` lists) drop top-level `body` / `schema` in favour of a per-MIME `content:` map. Buffer-mode entries use `content[<mime>].body` / `content[<mime>].schema`; stream-mode entries use `content[<mime>].encoder` (ref to any `Codec.Encoder`). The map key is the canonical `Content-Type` — declaring `Content-Type` in `headers:` is rejected at load time. Multi-key `content:` maps are negotiated against the request's `Accept` header (RFC 9110 §12.5.1). Mismatch → `406 Not Acceptable`.
-  - `mode: stream` is forbidden in `catches:` (catches fire pre-stream; no upstream iterable to feed an encoder).
-  - Migration: every existing `returns: [..., body: ..., schema: ..., headers: { Content-Type: ... }]` rewrites mechanically to `returns: [..., content: { <mime>: { body, schema } }]`. In-tree manifests (`apps/registry`, `examples/*`, `tests/*`, `benchmarks/*`) migrated.
-  - `Ai.TextStream`: `format` field removed; controller no longer encodes the wire — it returns `{ output: Stream<StreamPart> }`. Pair with a format-codec encoder (`Ndjson.Encoder`, `Sse.Encoder`, `PlainText.Encoder`) for HTTP responses or other byte transports. `text-stream-drain-controller.ts` removed (replaced by inline source → encoder → decoder steps).
-  - `StreamPart.error` shape changed from native `Error` to `{ message, code?, data? }` so generic encoders can JSON-serialize error frames without bespoke translation.
-
-  **New** (`@telorun/codec`, `@telorun/plain-text-codec`, `@telorun/ndjson-codec`, `@telorun/sse-codec`, `@telorun/octet-codec`):
-
-  - `@telorun/codec` ships the `Encoder` and `Decoder` abstracts (no controllers — pure contracts).
-  - Format-codec packages each carry one or both directions: `PlainText.Encoder/.Decoder` (UTF-8 collect + emit), `Ndjson.Encoder` (one JSON record per line), `Sse.Encoder` (Server-Sent Events frames), `Octet.Encoder/.Decoder` (raw bytes pass-through and collect).
-  - All encoders implement `invoke({input}): Promise<{output: Stream<Uint8Array>}>` per the streaming-Invocable convention.
-
-  **New** (`@telorun/sdk`):
-
-  - `Stream<T>` class wrapping `AsyncIterable<T>`. Producers wrap their iterables in `new Stream(...)` so the value's constructor is recognized by CEL's runtime type-checker (which rejects unrecognized constructors like `AsyncGenerator` and Node `Readable`). The analyzer registers `Stream` as a CEL object type.
-
-  **Annotation** (`@telorun/kernel`, `@telorun/analyzer`):
-
-  - `x-telo-stream: true` schema annotation on input/output properties marks them as carrying a `Stream<T>`. CEL passes the value through by reference; analyzer's chain validator rejects `.field` / `[index]` access past a stream-marked property. Convention: streaming Invocables put the stream on `input` (inputs) and `output` (result).
-  - `Self.<Abstract>` magic alias auto-registered for every Telo.Library/Application — lets concrete kinds in the same library use `extends: Self.<Abstract>` without a self-import that would loop the loader.
-  - Analyzer's `buildReferenceFieldMap`, `resolveFieldValues`, `extractInlinesAtPath`, and `injectAtPath` (Phase 5) now recurse into `additionalProperties` via a `{}` path-segment marker. Required for refs nested inside open-keyed maps like `content[<mime>].encoder`.
-  - `isInlineResource` widened: bare-kind refs (`{kind: X}` with no `name` and no extra config) are now treated as inline-singleton definitions and Phase 2 extracts them as fresh stateless resources. Previously `{kind: X}` raised `INVALID_REFERENCE` (treated as a malformed named ref). This matches the runtime-side `resolveChildren` semantics already documented for `Run.Throw`-style stateless inlines, and lets `encoder: {kind: Ndjson.Encoder}` work without boilerplate. Manifests that had `{kind: X}` with the (broken) intent of resolving to an existing named resource will now silently extract a fresh resource — extremely unlikely in practice (those refs were already failing analysis), but worth flagging for downstream consumers.
-
-  **Behaviour changes worth flagging** (`@telorun/http-server`):
-
-  - **Single-key `content:` maps now do `Accept` negotiation.** A route declaring only `content: { application/json: ... }` returns `406 Not Acceptable` for `Accept: image/png` — RFC 9110 §15.5.7 compliant. Pre-PR, the legacy top-level `body:` shape ignored `Accept` entirely. To preserve "always send" behaviour, declare `*/*` as an explicit key.
-  - **Accept matching ignores media-type parameters** beyond the first `;`. `Accept: text/plain; charset=ascii` matches `content: { 'text/plain; charset=utf-8': ... }`. Q-values are still parsed for ranking; only the matching predicate ignores params. Authors needing parameter-level preference must declare distinct keys per parameter combo.
-  - **Load-time validators reject misconfigured `content:` shapes.** `validateContentEntryShape` rejects `body+encoder` together (mutually exclusive), missing `encoder` under `mode: stream`, `body` under `mode: stream`, and `encoder` under `mode: buffer`. Previously some of these slipped through to runtime where they manifested as 500-on-negotiation.
-  - **Mid-stream `pipeline()` failures emit `Http.Api.streamFailed` events.** Once `reply.hijack()` runs, mid-stream errors (encoder throws, broken pipe) bypass `catches:` by design (response is committed). They now emit a structured event with `path`, `method`, `status`, `mime`, and the error so operators can observe failures that would otherwise be silent.
-
-  **Other** (`@telorun/http-client`, `@telorun/javascript`):
-
-  - `HttpClient.Request` `mode: stream` returns `{ output: Stream<Uint8Array> }` instead of a bare `Readable` — fits the streaming-Invocable convention, pairs with `Octet.Encoder` for HTTP pass-through.
-  - `JS.Script` injects `Stream` into every script's scope (via the second function argument, destructured at the top of the wrapper). User code can `new Stream(asyncGen)` directly.
-
-  **Tests**:
-
-  - New Layer 1 hermetic streaming-contract test (`modules/ai/tests/text-stream-streaming-contract.yaml`) — three sub-targets, byte-exact NDJSON / SSE / PlainText.
-  - New Layer 2 live OpenAI streaming smoke (`modules/ai-openai/tests/openai-live-text-stream.yaml`) — env-gated; exercises `Ai.TextStream → Ndjson.Encoder → PlainText.Decoder` against the real provider.
-  - New http-server integration test (`modules/http-server/tests/text-stream-via-http.yaml`) — exercises three single-format routes plus a four-format negotiated route with five Accept variants.
-
-### Patch Changes
-
-- Updated dependencies [b62e535]
-  - @telorun/sdk@0.7.0
-
 ## 0.2.4
 
 ### Patch Changes

package/LICENSE

@@ -1,6 +1,6 @@
 # SUSTAINABLE USE LICENSE (Fair-code)
 
-Copyright (c) 2026 DiglyAI
+Copyright (c) 2026 CodeNet Sp. z o.o.
 
 Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to use, copy, modify, and distribute the Software for any purpose—including commercial purposes—subject to the following conditions:
 
@@ -14,4 +14,4 @@ Permission is hereby granted, free of charge, to any person obtaining a copy of
 
 5. DISCLAIMER: The Software is provided "as is", without warranty of any kind, express or implied, including but not limited to the warranties of merchantability, fitness for a particular purpose and noninfringement. In no event shall the authors or copyright holders be liable for any claim, damages or other liability, whether in an action of contract, tort or otherwise, arising from, out of or in connection with the Software or the use or other dealings in the Software.
 
-For commercial licensing, managed hosting exemptions, or enterprise inquiries, please contact DiglyAI.
+For commercial licensing, managed hosting exemptions, or enterprise inquiries, please contact <contact@codenet.pl>.

package/README.md

@@ -1,36 +1,89 @@
-# Telo HTTP Standard Specification (v1.0 Draft)
+# HTTP Server
 
-## Overview
+Language- and framework-agnostic HTTP server for Telo. Declarative routes, schema-validated requests, and a typed return/catch rendering pipeline.
 
-The `Http.Server` and `Http.Api` manifests in Telo are designed to be strictly **language-agnostic** and **framework-agnostic**. To maintain the "Zero Lock-in" promise, the underlying HTTP engine (e.g., Fastify in Node.js, Actix in Rust) is treated purely as an implementation detail.
+## Why use this
 
-All HTTP modules integrated into the Telo kernel **must** adhere to this behavioral contract. This ensures that a YAML manifest written today will execute with exactly the same I/O and validation behavior regardless of the underlying language or framework.
+- **Framework-neutral** — the underlying engine (Fastify, Actix, …) is an implementation detail; the same manifest runs on any compliant adapter.
+- **OpenAPI-style paths** — `/users/{id}` syntax everywhere; the adapter translates to its native router.
+- **Schema-driven validation** — `request.schema` (`body`, `query`, `params`, `headers`) yields a standardized HTTP 400 with `details[]` on failure.
+- **Typed returns and catches** — render successful values and structured `InvokeError`s into status + headers + per-MIME bodies via CEL.
+- **Composable mounts** — attach `Telo.Mount` resources (HTTP APIs, MCP endpoints, custom mounts) under any path prefix.
+- **CORS and content-type parsers** — first-class manifest fields; no controller code needed.
 
+## Kinds
+
+| Kind | Purpose |
+| --- | --- |
+| `Http.Server` | Long-lived HTTP listener that hosts mounts on configured paths and ports. |
+| `Http.Api` | Mountable router exposing route definitions with returns/catches rendering. |
+
+## Example
+
+```yaml
+kind: Telo.Application
+metadata: { name: hello-http, version: 1.0.0 }
+targets: [Server]
+---
+kind: Telo.Import
+metadata: { name: Http }
+source: pkg:npm/@telorun/http-server@^1.0.0
 ---
+kind: Telo.Import
+metadata: { name: JS }
+source: pkg:npm/@telorun/javascript@^1.0.0
+---
+kind: Http.Server
+metadata: { name: Server }
+port: 8080
+mounts:
+  - path: /api
+    type: Api
+---
+kind: Http.Api
+metadata: { name: Api }
+routes:
+  - request: { method: GET, path: /hello/{name} }
+    inputs:
+      name: "${{ request.params.name }}"
+    handler: { kind: JS.Script, name: Greet }
+    returns:
+      - status: 200
+        content:
+          application/json:
+            body: { message: "${{ result.message }}" }
+---
+kind: JS.Script
+metadata: { name: Greet }
+code: |
+  return { message: `Hello, ${inputs.name}!` };
+```
 
-## 1. Routing Contract (Path Definitions)
+## Reference
 
-Different web frameworks use different syntaxes for path parameters (e.g., `/users/:id` vs. `/users/{id}`).
+- [`Http.Server` / `Http.Api` returns & catches](docs/returns-and-catches.md) — outcome lists, MIME negotiation, stream mode.
 
-Telo standardizes on the **OpenAPI specification format** for paths.
+## Implementation Contract
 
-- **Standard:** Path parameters MUST be enclosed in curly braces: `{parameterName}`.
-- **Module Responsibility:** The underlying HTTP module must parse the Telo path and translate it into its framework's native routing syntax at startup.
+The `Http.Server` and `Http.Api` manifests in Telo are designed to be strictly language-agnostic and framework-agnostic. To maintain the "Zero Lock-in" promise, the underlying HTTP engine (e.g. Fastify in Node.js, Actix in Rust) is treated purely as an implementation detail. All HTTP modules integrated into the Telo kernel MUST adhere to this behavioural contract.
 
-**Example Manifest Path:** `/api/v1/users/{userId}`
+### 1. Routing (path definitions)
 
-- _Node.js (Fastify) Adapter translates to:_ `/api/v1/users/:userId`
-- _Rust (Actix) Adapter translates to:_ `/api/v1/users/{userId}`
+Telo standardizes on the OpenAPI specification format for paths.
 
----
+- **Standard:** path parameters MUST be enclosed in curly braces: `{parameterName}`.
+- **Module responsibility:** the underlying HTTP module must parse the Telo path and translate it into its framework's native routing syntax at startup.
+
+**Example manifest path:** `/api/v1/users/{userId}`
 
-## 2. The I/O Context Contract
+- Node.js (Fastify) adapter translates to: `/api/v1/users/:userId`
+- Rust (Actix) adapter translates to: `/api/v1/users/{userId}`
 
-When an incoming HTTP request is received, the underlying framework must normalize it into a standard **Telo Request Object** before passing it to the Handler/CEL engine. Conversely, it must accept a standard **Telo Response Object** to send back to the client.
+### 2. I/O context contract
 
-### 2.1. Standardized Telo Request Object (Input)
+When an incoming HTTP request is received, the underlying framework must normalize it into a standard Telo Request Object before passing it to the handler/CEL engine. Conversely, it must accept a standard Telo Response Object to send back to the client.
 
-The HTTP module must construct and pass the following exact payload to the execution environment:
+#### 2.1 Standardized Telo Request Object (input)
 
 ```json
 {
@@ -51,12 +104,12 @@ The HTTP module must construct and pass the following exact payload to the execu
 }
 ```
 
-- **Constraint:** All `headers` keys MUST be normalized to lowercase.
-- **Constraint:** If the `content-type` is `application/json`, the `body` MUST be parsed into a native object/dictionary before evaluation.
+- All `headers` keys MUST be normalized to lowercase.
+- If the `content-type` is `application/json`, the `body` MUST be parsed into a native object/dictionary before evaluation.
 
-### 2.2. Standardized Telo Response Object (Output)
+#### 2.2 Standardized Telo Response Object (output)
 
-After the Handler executes and the `response.mapping` evaluates, the engine will return an object to the HTTP module. The module must map this directly to the native HTTP response.
+After the handler executes and the `response.mapping` evaluates, the engine returns an object to the HTTP module. The module must map this directly to the native HTTP response.
 
 ```json
 {
@@ -72,17 +125,9 @@ After the Handler executes and the `response.mapping` evaluates, the engine will
 }
 ```
 
----
-
-## 3. Validation & Error Handling Contract
-
-When a request fails schema validation (defined in the `request.schema` of the manifest), the underlying engine (e.g., AJV in Fastify) will generate native errors. **These internal errors must not leak to the client.**
+### 3. Validation and error handling
 
-All Telo HTTP modules MUST intercept framework-specific validation errors and return a standardized HTTP 400 Bad Request payload.
-
-### Standardized Validation Error Format
-
-The response body must strictly follow this JSON structure:
+When a request fails schema validation (defined in the `request.schema` of the manifest), the underlying engine (e.g. AJV in Fastify) will generate native errors. These internal errors must not leak to the client. All Telo HTTP modules MUST intercept framework-specific validation errors and return a standardized HTTP 400 Bad Request payload.
 
 ```json
 {
@@ -104,12 +149,10 @@ The response body must strictly follow this JSON structure:
 }
 ```
 
-- **`location` enum:** `body` | `query` | `params` | `headers`
-- **Module Responsibility:** The module author must write an error handler/mapper that transforms the native framework's validation output into the Telo `details` array.
-
----
+- **`location` enum:** `body` | `query` | `params` | `headers`.
+- **Module responsibility:** the module author must write an error handler/mapper that transforms the native framework's validation output into the Telo `details` array.
 
-## 4. Manifest Schema Upgrades
+### 4. Manifest schema upgrades
 
 To fully support this contract, the `Http.Api` JSON Schema definition includes the following structural definitions for the `request` block:
 

package/dist/http-server-controller.d.ts

@@ -36,6 +36,7 @@ type HttpServerResource = RuntimeResource & {
     }>;
     notFoundHandler?: {
         invoke: KindRef<Invocable>;
+        inputs?: Record<string, unknown>;
         returns?: ReturnEntry[];
         catches?: CatchEntry[];
     };

package/dist/http-server-controller.js

@@ -138,9 +138,22 @@ class HttpServer {
                 };
                 const acceptHeader = request.headers["accept"]?.toString();
                 const sink = fastifyReplySink(reply);
+                // Expand the `inputs:` sibling template against the request context,
+                // then pass the merged shape (spread for convenience + `inputs:` field
+                // for handlers that read it explicitly) to the dispatch target. Same
+                // contract Api.routes[*] uses. When no `inputs:` is declared, the
+                // request context itself is forwarded so existing manifests that read
+                // `request.*` directly continue to work.
+                const resolvedInputs = handler.inputs && Object.keys(handler.inputs).length > 0
+                    ? (this.ctx.moduleContext.expandWith(handler.inputs, requestContext) ?? {})
+                    : requestContext;
+                const invokeInput = {
+                    ...resolvedInputs,
+                    inputs: resolvedInputs,
+                };
                 let result;
                 try {
-                    result = await this.ctx.invoke(handler.kind, handler.name, requestContext);
+                    result = await this.ctx.invoke(handler.kind, handler.name, invokeInput);
                 }
                 catch (err) {
                     if (!isInvokeError(err))
@@ -206,7 +219,7 @@ export async function create(resource, ctx) {
         resolvedNotFoundHandler = {
             kind,
             name,
-            inputs: invoke?.inputs ?? {},
+            inputs: resource.notFoundHandler.inputs ?? {},
             returns: resource.notFoundHandler.returns,
             catches: resource.notFoundHandler.catches,
         };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@telorun/http-server",
-  "version": "0.3.4",
+  "version": "0.5.0",
   "description": "Telo HTTP Server module - HTTP server and API resource kinds for Telo manifests.",
   "keywords": [
     "telo",
@@ -43,14 +43,16 @@
     "ajv": "^8.17.1",
     "ajv-formats": "^3.0.1",
     "fastify": "^5.7.2",
-    "@telorun/http-dispatch": "0.2.2",
-    "@telorun/sdk": "0.11.1"
+    "@telorun/http-dispatch": "0.3.0"
   },
   "devDependencies": {
     "@types/node": "^20.0.0",
     "typescript": "^5.0.0",
     "vitest": "^2.1.8"
   },
+  "peerDependencies": {
+    "@telorun/sdk": "0.12.0"
+  },
   "scripts": {
     "build": "tsc -p tsconfig.lib.json",
     "test": "vitest run",

package/src/http-server-controller.ts

@@ -54,6 +54,7 @@ type HttpServerResource = RuntimeResource & {
   }>;
   notFoundHandler?: {
     invoke: KindRef<Invocable>;
+    inputs?: Record<string, unknown>;
     returns?: ReturnEntry[];
     catches?: CatchEntry[];
   };
@@ -221,9 +222,24 @@ class HttpServer implements ResourceInstance {
 
         const sink = fastifyReplySink(reply);
 
+        // Expand the `inputs:` sibling template against the request context,
+        // then pass the merged shape (spread for convenience + `inputs:` field
+        // for handlers that read it explicitly) to the dispatch target. Same
+        // contract Api.routes[*] uses. When no `inputs:` is declared, the
+        // request context itself is forwarded so existing manifests that read
+        // `request.*` directly continue to work.
+        const resolvedInputs: Record<string, any> =
+          handler.inputs && Object.keys(handler.inputs).length > 0
+            ? ((this.ctx.moduleContext.expandWith(handler.inputs, requestContext) as any) ?? {})
+            : requestContext;
+        const invokeInput: Record<string, any> = {
+          ...resolvedInputs,
+          inputs: resolvedInputs,
+        };
+
         let result: any;
         try {
-          result = await this.ctx.invoke(handler.kind, handler.name, requestContext);
+          result = await this.ctx.invoke(handler.kind, handler.name, invokeInput);
         } catch (err) {
           if (!isInvokeError(err)) throw err;
           return dispatchCatches(
@@ -310,7 +326,7 @@ export async function create(
     resolvedNotFoundHandler = {
       kind,
       name,
-      inputs: (invoke as any)?.inputs ?? {},
+      inputs: resource.notFoundHandler.inputs ?? {},
       returns: resource.notFoundHandler.returns,
       catches: resource.notFoundHandler.catches,
     };