@telorun/http-server 0.18.1 → 0.20.0

package/CHANGELOG.md

@@ -1,5 +1,115 @@
 # @telorun/http-server
 
+## 0.20.0
+
+### Minor Changes
+
+- c8d457b: One value-type annotation: `x-telo-type` says what a value IS, and the
+  vocabulary is data both runtimes read.
+
+  Three annotations answered one question — _what is the value at this slot, beyond
+  what JSON Schema's `type` vocabulary can say?_ — and each answered it
+  differently: `x-telo-type: TcpPort` (a nominal brand from a closed kernel table),
+  `x-telo-binary: true` (raw bytes, the one annotation that emitted validation
+  code), `x-telo-stream: true` (a live handle, exempt from schema walks). They
+  differ in _posture_ toward the JSON Schema layer — refine, replace, exempt — not
+  in kind, so a fourth cost eleven files across four packages, and three defects
+  followed from the spread: an unrecognized brand degraded silently, a byte slot's
+  expression typed as `dyn` because nothing consulted `x-telo-binary`, and a module
+  string-matched the keyword because a module may import `@telorun/sdk` and there
+  was nothing there to read.
+
+  - **The vocabulary is DATA; the binding to a language is not.** A type is one
+    JSON file under `sdk/value-types/`, copied into the SDK by its `prepare` and
+    embedded by Rust with `include_str!` — the `analyzer/migrations/` arrangement,
+    for the same reason. An entry declares `name`, `representation` (`json` + a
+    `base`, or `instance` + a symbolic `binding`), `live`, `parameters` and a
+    `description`, and nothing about any runtime. Each runtime carries its own
+    table mapping `binding` to its own identity; a binding with **no row is a hard
+    startup error**, never a skipped assertion, because a type that cannot be
+    asserted would silently exempt every slot declaring it.
+  - **`registerTeloKeywords`** replaces five drifted AJV registration sites — the
+    analyzer's `createAjv` and the kernel's `schema-validator`, `resource-context`,
+    `observed-state` and `manifest-schemas`, which registered overlapping lists of
+    twelve, four, one and one. Drift there is not cosmetic: a keyword that emits
+    code was simply missing from any instance that forgot it, so one schema
+    validated two ways depending on which AJV saw it.
+  - **Exemption is a property of the TYPE, not of a position.** The old walk
+    neutralized only a key it found in a `properties` map, so an array-of-streams
+    element was reached and left constrained even though it descended into `items`.
+    Reading liveness off the declared type makes an item, a union branch and a
+    property one case. It is exemption from **validation**, never from **typing**:
+    a live type's arguments still travel through every schema-typing walk.
+  - **Value types are generic.** An entry declares named type parameters and the
+    annotation's object form supplies arguments — `{ name: Telo.Stream, of:
+Telo.Bytes }`. An argument is a schema node, so it nests with no new grammar,
+    and a bare name is sugar for a node carrying only the annotation, normalized in
+    the single reader. Comparison is **covariant and gradual**: an omitted argument
+    is _any_ in both directions, so every producer and consumer that has not
+    declared an element keeps checking exactly as it did. A definite conflict is
+    `CEL_TYPE_ARGUMENT_MISMATCH`, reported where a produced value's schema meets a
+    consuming slot's — a step's `inputs:` against the invoked target's contract,
+    which is the one place both halves are in hand.
+  - **A shape is named with `!ref`**, Telo's one reference grammar, and `use:
+schema` has been in the `x-telo-ref` vocabulary for exactly this relation all
+    along. The loader normalizes it to the canonical `telo:<module>/<Type>` `$ref`
+    — authoring surface and internal form, the split `resolveRefSentinels` and
+    `resolveSchemaRefKinds` already have. Normalizing rather than inlining is what
+    preserves schema identity (the compiled-validator cache is keyed on it) and
+    leaves a recursive shape expressible; carrying the owning module is what makes
+    resolution alias-aware, where matching a bare `metadata.name` across a
+    flattened list silently dropped the alias.
+  - **A tag's produced type is declared by its ENGINE.** `TemplatingEngine` gains
+    `producedType()`; `!include-bytes` declares `Telo.Bytes` and `!include-text`
+    declares `type: string`, and `substituteCelFields` loses its tag-name branch —
+    the only place a tag's produced type was written down, written in the consumer.
+  - **`X_TELO_TYPE_UNKNOWN`** (Levenshtein-suggested) and
+    **`X_TELO_TYPE_ARGUMENT_UNKNOWN`** replace the silent degrade, on every
+    schema-bearing field of every manifest — not only definition docs, since an
+    inline `inputType:` on an ordinary resource carries a schema too.
+  - **The migration selector gains a schema region.** `inSchema: true` bounds a
+    rule to the kernel's own schema-valued keys, and only with it may `inKind` /
+    `under` be `["*"]`, and only for a rule keyed on an `x-telo-*` annotation. That
+    pairing is the containment: an annotation keyword occurs in author-written
+    schema fragments inside ordinary resource documents, and that set of kinds is
+    open, so enumerating it would be both incomplete and a violation of the
+    topology-driven constraint.
+
+  **Breaking:** `x-telo-binary` and `x-telo-stream` are rewritten to `x-telo-type`
+  at load by the `normalize-value-types` migration, so every published manifest
+  keeps working and `telo migrate` repairs a file in place. `binaryKeyword` /
+  `isBinarySlot` / `X_TELO_BINARY` are removed from `@telorun/analyzer` in favour
+  of `registerTeloKeywords` and the SDK accessors; `withStreamPropertiesSkipped` is
+  now `withLiveValuesSkipped`. Value brands are `Telo.`-qualified (`TcpPort` →
+  `Telo.TcpPort`), which the same migration rewrites.
+
+### Patch Changes
+
+- @telorun/http-dispatch@0.4.2
+
+## 0.19.0
+
+### Minor Changes
+
+- 07fca98: `Http.Server` emits its own access record instead of passing Fastify's through, so the log is the kind's contract rather than one framework's prose — which is what lets a Rust or Go implementation of the kind produce records a single consumer can read.
+
+  Each record carries an `event_name` (`http.server.started`, `http.server.request`, `http.server.request.started`, `http.server.stopped`); consumers key on that, never on the message text. Attributes follow OpenTelemetry conventions: `http.route` (the low-cardinality matched template) rather than `url.path`, and `http.server.request.duration` in seconds.
+
+  Behaviour changes worth knowing about:
+
+  - **One `info` record per request** on completion, instead of Fastify's two. The received-side record moves to `debug`, where it still catches a request that hangs and never completes.
+  - **Severity follows the response** — `info`, except a 5xx which is `error`.
+  - **A mount entry may carry `logging.level`**, so a health endpoint polled every second, or a static mount serving a built SPA, can go quiet (`level: warn`) while the rest of the server keeps logging. The import-scoped threshold cannot express this: one server is a single resource in a single scope. A quietened mount still reports its own 500, because that is logged at `error`.
+  - **`http.route` is omitted when no route matched.** Falling back to the concrete URL let an unauthenticated 404 scan write unbounded cardinality into the `info`-level attribute dashboards group on; OpenTelemetry requires omission when there is no match.
+  - **`http.server.stopped` is emitted only for a server that actually listened**, so a consumer pairing start with stop never sees an unmatched close.
+  - **`url.scheme` reports the socket**, not `baseUrl` — the advertised URL is routinely `https://` behind a TLS terminator while the socket is plaintext.
+
+  The Telo-backed logger adapter is now injected unconditionally. Gating it on `info` handed Fastify its null logger at `level: warn` and silently dropped every diagnostic Fastify owns — its error-handler failures, reply-send failures and aborted-request hooks — which are exactly the records `warn` is meant to keep.
+
+### Patch Changes
+
+- @telorun/http-dispatch@0.4.2
+
 ## 0.18.1
 
 ### Patch Changes

package/README.md

@@ -81,6 +81,7 @@ code: |
 
 - [`Http.Server` / `Http.Api` returns & catches](docs/returns-and-catches.md) — outcome lists, MIME negotiation, stream mode.
 - [Serving static files & frontends](docs/static-files.md) — `Http.Static`, manifest-relative roots, SPA fallback, asset caching.
+- [Log events](docs/log-events.md) — the `event_name` and attributes every implementation of this kind emits, and how to turn request logging off.
 
 ## Implementation Contract
 
@@ -236,3 +237,29 @@ never a framework's proxy-config object:
   (a client with direct network access could otherwise spoof the headers).
 - When `trustForwardedHeaders` is set, the request protocol/host exposed to handlers
   MUST also reflect the forwarded headers.
+
+### 6. Log events
+
+Every implementation emits the same log events — `http.server.started`,
+`http.server.request.started`, `http.server.request`, `http.server.stopped` —
+with the same OpenTelemetry attributes. See [log events](docs/log-events.md) for
+the table.
+
+The `event_name` and the attributes are the contract; the message text is not.
+Message strings come from whatever framework is underneath and differ per
+runtime, so **a consumer MUST key on `event_name`, never on the message**.
+
+Severity follows the response: `info`, except a **5xx**, which is `error`. A
+mount entry MAY carry `logging.level` to set its own floor — `warn` silences a
+health check polled every second, while its 5xx still surfaces because that is
+logged at `error`.
+
+Two consequences for an implementer:
+
+- **Disable the framework's own request logging** and emit from middleware
+  (Fastify's `onResponse`, a `tower` layer, an `http.Handler` wrapper). Passing a
+  framework's own access lines through is how a runtime ends up shipping Pino's
+  or `tower-http`'s record shape instead of this kind's.
+- **One `info` record per request, on completion.** The received-side record is
+  `debug`; it exists only so a request that hangs and never completes still
+  leaves a trace.

package/dist/fastify-telo-logger.d.ts

@@ -25,5 +25,17 @@ export interface FastifyLogger {
     silent(...args: unknown[]): void;
     child(bindings: Record<string, unknown>, options?: unknown): FastifyLogger;
 }
+/**
+ * The text the controller substitutes for Fastify's listen announcement, via
+ * `listenTextResolver` on `app.listen()`. The controller emits
+ * `http.server.started` with the address in attributes, so this line is dropped
+ * rather than shipped beside it.
+ *
+ * A constant this module PRODUCES, not a pattern matched against Fastify's
+ * wording. That distinction is the whole point: this kind's contract says a
+ * message is prose and nothing should match on it, so suppressing by matching
+ * Fastify's own sentence would break the rule it exists to state.
+ */
+export declare const LISTEN_SUPERSEDED = "\0telo:listen-superseded";
 export declare function createFastifyTeloLogger(log: Logger): FastifyLogger;
 export { pinoLevelForSeverity, severityForPinoLevel };

package/dist/http-api-controller.js

@@ -1,6 +1,6 @@
 import { Type } from "@sinclair/typebox";
 import { CatchEntry, dispatchCatches, dispatchReturns, ReturnEntry, validateNoContentTypeHeader, validateStreamWhenDoesNotReferenceResult, } from "@telorun/http-dispatch";
-import { InvokeError, isCancellationError, isInvokeError, Ref, Stream, } from "@telorun/sdk";
+import { InvokeError, isCancellationError, isInvokeError, isLiveSlot, Ref, Stream, } from "@telorun/sdk";
 import { fastifyReplySink } from "./fastify-reply-sink.js";
 const HttpApiRouteManifest = Type.Object({
     request: Type.Object({
@@ -61,10 +61,16 @@ export class HttpServerApi {
         const handlerName = handlerRef?.name ?? "";
         const translatedPath = joinMountPath(prefix, translateOpenApiPath(route.request.path));
         const schema = { response: {} };
-        // A stream-marked body is delivered as a raw `Stream<Uint8Array>` (see the
+        // A live-typed body is delivered as a raw `Stream<Uint8Array>` (see the
         // server's `contentTypeParsers[].stream`); it is opaque to AJV, so skip
         // body-schema registration and wrap the raw request stream in the handler.
-        const streamBody = route.request.schema?.body?.["x-telo-stream"] === true;
+        //
+        // Read through the SDK accessor rather than by string-matching the keyword.
+        // A module may import `@telorun/sdk` and nothing else, and before the value
+        // types were unified there was nothing on that surface to read — so this was
+        // a literal key comparison, the same shape as the four surfaces that
+        // string-matched `x-telo-ref` before `ref-slot.ts`.
+        const streamBody = isLiveSlot(route.request.schema?.body);
         if (route.request.schema?.query)
             schema.querystring = route.request.schema.query;
         if (route.request.schema?.params)

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

@@ -1,5 +1,5 @@
 import { CatchEntry, ReturnEntry } from "@telorun/http-dispatch";
-import { type Invocable, type KindRef, type ResourceContext, type ResourceInstance, type RuntimeResource } from "@telorun/sdk";
+import { type Invocable, type KindRef, type LevelName, type ResourceContext, type ResourceInstance, type RuntimeResource } from "@telorun/sdk";
 import { FastifyInstance } from "fastify";
 /** A mounted Telo.Mount instance (Http.Api, Mcp.HttpEndpoint, …). The kernel injects the
  *  live instance into a mount's `mount` slot (x-telo-ref `Telo.Mount`) — cross-module refs
@@ -42,6 +42,9 @@ type HttpServerResource = RuntimeResource & {
     mounts?: Array<{
         path?: string;
         mount?: Mountable;
+        logging?: {
+            level?: LevelName;
+        };
     }>;
     notFoundHandler?: {
         invoke: KindRef<Invocable>;

package/dist/http-server-controller.js

@@ -1,14 +1,17 @@
 import cors from "@fastify/cors";
-import { createFastifyTeloLogger } from "./fastify-telo-logger.js";
+import { createFastifyTeloLogger, LISTEN_SUPERSEDED } from "./fastify-telo-logger.js";
 import swagger from "@fastify/swagger";
 import apiReference from "@scalar/fastify-api-reference";
 import { dispatchCatches, dispatchReturns, } from "@telorun/http-dispatch";
-import { isInvokeError, SEVERITY, } from "@telorun/sdk";
+import { isInvokeError, SEVERITY, severityForLevel, } from "@telorun/sdk";
 import addFormats from "ajv-formats";
 import Fastify from "fastify";
 import { fastifyReplySink } from "./fastify-reply-sink.js";
 class HttpServer {
     releaseHold = null;
+    /** Whether a socket actually opened, so `http.server.stopped` is only emitted
+     *  for a server that emitted `http.server.started`. */
+    listening = false;
     pluginsInitialized = false;
     app;
     host;
@@ -35,24 +38,28 @@ class HttpServer {
         // it, the legacy `trustForwardedHeaders` boolean still applies.
         const trustProxy = resource.trustProxy ?? this.trustForwardedHeaders;
         // §13.3: replacement, not bridging — Fastify's Pino instance is swapped for
-        // a Telo-backed adapter, so request records are Telo records at the source
-        // and inherit the root `logging:` block's level, encoding, redaction, and
-        // sinks.
+        // a Telo-backed adapter, so its records are Telo records at the source and
+        // inherit the root `logging:` block's level, encoding, redaction, and sinks.
         //
-        // Whether to instrument requests at all is derived from the resolved scope
-        // threshold, not a manifest flag: Fastify's per-request access lines are
-        // `info`-severity, so we instrument iff `info` is enabled for this server's
-        // scope. Raise the http-server import to `level: warn` and the per-request
-        // work is skipped entirely (Fastify's null logger) rather than built and
-        // discarded per request. This is a construction-time decision — a *runtime*
-        // threshold change (§12.4) still gates output through the adapter, but does
-        // not re-instrument a server booted with logging off.
+        // The adapter is injected UNCONDITIONALLY. It used to be gated on `info`
+        // being enabled, because that was what avoided building a per-request record
+        // at a raised threshold — but `disableRequestLogging` now removes that cost
+        // outright, so the gate's only remaining effect was to hand Fastify its null
+        // logger at `level: warn` and silently drop every diagnostic it owns: the
+        // error handler's own failures, reply-send failures, aborted-request hooks.
+        // Those are exactly the records `warn` is supposed to KEEP. The adapter's
+        // `emit` short-circuits on `log.enabled`, so a quiet server pays one
+        // predicate per suppressed record and keeps its errors.
         //
         // A custom logger *instance* must be passed via Fastify 5's `loggerInstance`
         // option; passing it to `logger:` throws FST_ERR_LOG_INVALID_LOGGER_CONFIG.
-        const requestLogging = this.ctx.log.enabled(SEVERITY.info);
         this.app = Fastify({
-            ...(requestLogging ? { loggerInstance: createFastifyTeloLogger(this.ctx.log) } : {}),
+            loggerInstance: createFastifyTeloLogger(this.ctx.log),
+            // Fastify's own per-request lines are off: this kind emits its own from
+            // `onRequest` / `onResponse` instead (see `installRequestLogging`), so the
+            // access record's shape is this KIND's contract rather than Pino's prose —
+            // which is what lets a Rust or Go implementation emit the same thing.
+            disableRequestLogging: true,
             trustProxy,
             ajv: { customOptions: { useDefaults: true }, plugins: [addFormats.default] },
         });
@@ -64,7 +71,101 @@ class HttpServer {
         }
         this.setupRoutes();
     }
+    /**
+     * The access log, emitted by this kind rather than by Fastify.
+     *
+     * The contract is `event_name` plus OTel attributes — never the message text,
+     * which is prose and differs per framework. That is what makes the record
+     * readable across runtimes: an axum or net/http implementation registers the
+     * equivalent middleware and emits the same `http.server.request`.
+     *
+     * One `info` record per request, on completion — the convention every access
+     * log follows (nginx, Caddy, tower-http). The received-side record is `debug`
+     * because it carries no outcome; its one real use is a request that HANGS and
+     * never completes, which otherwise leaves no trace at all.
+     */
+    /**
+     * Per-mount access-log floors, longest prefix first so the match is the first
+     * hit. Built once at init rather than per request — the mount set is fixed.
+     *
+     * A mount's `logging.level` exists because the import-scoped threshold (§12.2)
+     * governs a whole module instance: one `Http.Server` is one resource in one
+     * scope, so it cannot quieten `/health` while leaving `/api` alone. This can.
+     */
+    mountLogFloors() {
+        return (this.resource.mounts ?? [])
+            .flatMap((mount) => {
+            const level = mount.logging?.level;
+            if (!level)
+                return [];
+            return [{ prefix: mount.path || "", floor: severityForLevel(level) }];
+        })
+            .sort((a, b) => b.prefix.length - a.prefix.length);
+    }
+    installRequestLogging() {
+        const log = this.ctx.log;
+        const floors = this.mountLogFloors();
+        /**
+         * `http.route` is the matched TEMPLATE (`/todos/:id`), never the concrete
+         * path: low-cardinality, which is what an access log is aggregated on.
+         *
+         * When nothing matched — every 404 — there IS no template, and the key is
+         * omitted rather than filled with the concrete URL. Falling back would let
+         * an unauthenticated caller write arbitrary strings into the `info`-level
+         * attribute a dashboard groups on: one 404 scan, unbounded cardinality.
+         * Omission is also what OTel requires when there is no match.
+         *
+         * `routeOptions` is a getter that rebuilds an options object on every access,
+         * so it is read once per hook and passed around as the resolved value.
+         */
+        const routeAttribute = (route) => route === undefined ? {} : { "http.route": route };
+        /** The floor this request must clear: its mount's, or none. Matched on the
+         *  concrete URL, since that is what a mount prefix attaches to. */
+        const floorFor = (request) => {
+            for (const { prefix, floor } of floors) {
+                if (prefix === "" || request.url === prefix || request.url.startsWith(`${prefix}/`)) {
+                    return floor;
+                }
+            }
+            return 0;
+        };
+        /** A 5xx is not the same class of event as a 200, and both were `info`.
+         *  Deriving severity from the status is also what makes a quietened mount
+         *  safe: `level: warn` on a health check still surfaces it returning 500,
+         *  rather than going blind on the path that matters most.
+         *
+         *  4xx stays `info` deliberately — a 404 or a 401 is ordinary traffic, and
+         *  promoting it would make a scanner walking random URLs read as an incident. */
+        const severityForStatus = (status) => status >= 500 ? SEVERITY.error : SEVERITY.info;
+        this.app.addHook("onRequest", async (request) => {
+            if (!log.enabled(SEVERITY.debug) || SEVERITY.debug < floorFor(request))
+                return;
+            log.debug("Request received", {
+                "http.request.method": request.method,
+                ...routeAttribute(request.routeOptions?.url),
+                "url.path": request.url,
+                "httpserver.request_id": String(request.id),
+            }, { eventName: "http.server.request.started" });
+        });
+        this.app.addHook("onResponse", async (request, reply) => {
+            const severity = severityForStatus(reply.statusCode);
+            if (!log.enabled(severity) || severity < floorFor(request))
+                return;
+            log.log(severity, "Request completed", {
+                "http.request.method": request.method,
+                ...routeAttribute(request.routeOptions?.url),
+                "http.response.status_code": reply.statusCode,
+                // OTel's name in OTel's unit: seconds, as a double. Fastify measures in
+                // milliseconds at full `hrtime` precision, so this is rounded to
+                // microseconds — finer than anything an access log needs, and without
+                // it the division prints seventeen digits of float noise.
+                "http.server.request.duration": Math.round(reply.elapsedTime * 1000) / 1e6,
+                "httpserver.request_id": String(request.id),
+            }, { eventName: "http.server.request" });
+        });
+    }
     async setupPlugins() {
+        this.installRequestLogging();
         for (const { contentType, parser, stream } of this.resource.contentTypeParsers ?? []) {
             if (stream) {
                 // Raw passthrough: omit `parseAs` so Fastify hands the handler the
@@ -261,7 +362,27 @@ class HttpServer {
     async run() {
         this.releaseHold = this.ctx.acquireHold();
         try {
-            await this.app.listen({ host: this.host, port: this.port });
+            await this.app.listen({
+                host: this.host,
+                port: this.port,
+                // Fastify announces "Server listening at http://…" through the injected
+                // logger, interpolating the address into prose — unparseable, and exactly
+                // what §4.1 routes into attributes. Replacing the text with a constant
+                // this module owns lets the adapter drop it without pattern-matching
+                // Fastify's wording, which is the thing this kind's own contract forbids.
+                listenTextResolver: () => LISTEN_SUPERSEDED,
+            });
+            this.listening = true;
+            this.ctx.log.info("Listening", {
+                "server.address": this.host,
+                "server.port": this.port,
+                // The SOCKET's scheme, which this kind only ever opens as plain HTTP —
+                // there is no TLS field on `Http.Server`. `baseUrl` is the ADVERTISED
+                // url and is routinely `https://` behind a terminator, so deriving from
+                // it would claim TLS for a plaintext socket on the most common
+                // production deployment there is.
+                "url.scheme": "http",
+            }, { eventName: "http.server.started" });
             await this.ctx.emitEvent(`${this.resource.metadata.name}.Listening`, {
                 port: this.port,
                 host: this.host,
@@ -285,6 +406,14 @@ class HttpServer {
             this.releaseHold = null;
         }
         await this.app.close();
+        // Only if a socket actually opened. A server that initialized but was never
+        // listed in `targets:`, or whose `listen()` threw, would otherwise report a
+        // close for something that never started — and a consumer pairing the two
+        // events for uptime or leak detection sees an unmatched close.
+        if (this.listening) {
+            this.listening = false;
+            this.ctx.log.info("Stopped listening", { "server.address": this.host, "server.port": this.port }, { eventName: "http.server.stopped" });
+        }
     }
 }
 export async function create(resource, ctx) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@telorun/http-server",
-  "version": "0.18.1",
+  "version": "0.20.0",
   "description": "Telo HTTP Server module - HTTP server and API resource kinds for Telo manifests.",
   "keywords": [
     "telo",
@@ -55,7 +55,7 @@
     "@types/node": "^20.0.0",
     "typescript": "^5.0.0",
     "vitest": "^2.1.8",
-    "@telorun/sdk": "0.67.0"
+    "@telorun/sdk": "0.73.0"
   },
   "peerDependencies": {
     "@telorun/sdk": "*"

package/src/http-api-controller.ts

@@ -14,6 +14,7 @@ import {
   InvokeError,
   isCancellationError,
   isInvokeError,
+  isLiveSlot,
   KindRef,
   Ref,
   ResourceContext,
@@ -95,10 +96,16 @@ export class HttpServerApi implements ResourceInstance {
 
     const schema: any = { response: {} };
 
-    // A stream-marked body is delivered as a raw `Stream<Uint8Array>` (see the
+    // A live-typed body is delivered as a raw `Stream<Uint8Array>` (see the
     // server's `contentTypeParsers[].stream`); it is opaque to AJV, so skip
     // body-schema registration and wrap the raw request stream in the handler.
-    const streamBody = route.request.schema?.body?.["x-telo-stream"] === true;
+    //
+    // Read through the SDK accessor rather than by string-matching the keyword.
+    // A module may import `@telorun/sdk` and nothing else, and before the value
+    // types were unified there was nothing on that surface to read — so this was
+    // a literal key comparison, the same shape as the four surfaces that
+    // string-matched `x-telo-ref` before `ref-slot.ts`.
+    const streamBody = isLiveSlot(route.request.schema?.body);
 
     if (route.request.schema?.query) schema.querystring = route.request.schema.query;
     if (route.request.schema?.params) schema.params = route.request.schema.params;

package/src/http-server-controller.ts

@@ -1,5 +1,5 @@
 import cors from "@fastify/cors";
-import { createFastifyTeloLogger } from "./fastify-telo-logger.js";
+import { createFastifyTeloLogger, LISTEN_SUPERSEDED } from "./fastify-telo-logger.js";
 import swagger from "@fastify/swagger";
 import apiReference from "@scalar/fastify-api-reference";
 import {
@@ -11,14 +11,16 @@ import {
 import {
   isInvokeError,
   SEVERITY,
+  severityForLevel,
   type Invocable,
   type KindRef,
+  type LevelName,
   type ResourceContext,
   type ResourceInstance,
   type RuntimeResource,
 } from "@telorun/sdk";
 import addFormats from "ajv-formats";
-import Fastify, { FastifyInstance } from "fastify";
+import Fastify, { FastifyInstance, type FastifyRequest } from "fastify";
 import { fastifyReplySink } from "./fastify-reply-sink.js";
 
 /** A mounted Telo.Mount instance (Http.Api, Mcp.HttpEndpoint, …). The kernel injects the
@@ -62,6 +64,7 @@ type HttpServerResource = RuntimeResource & {
     // x-telo-ref `Telo.Mount`: Phase 5 replaces this slot with the live mounted
     // instance (Http.Api, Mcp.HttpEndpoint, …), local or imported.
     mount?: Mountable;
+    logging?: { level?: LevelName };
   }>;
   notFoundHandler?: {
     invoke: KindRef<Invocable>;
@@ -81,6 +84,9 @@ type ResolvedHandler = {
 
 class HttpServer implements ResourceInstance {
   private releaseHold: (() => void) | null = null;
+  /** Whether a socket actually opened, so `http.server.stopped` is only emitted
+   *  for a server that emitted `http.server.started`. */
+  private listening = false;
   private pluginsInitialized = false;
   private readonly app: FastifyInstance;
   private readonly host: string;
@@ -113,24 +119,28 @@ class HttpServer implements ResourceInstance {
     // it, the legacy `trustForwardedHeaders` boolean still applies.
     const trustProxy = resource.trustProxy ?? this.trustForwardedHeaders;
     // §13.3: replacement, not bridging — Fastify's Pino instance is swapped for
-    // a Telo-backed adapter, so request records are Telo records at the source
-    // and inherit the root `logging:` block's level, encoding, redaction, and
-    // sinks.
+    // a Telo-backed adapter, so its records are Telo records at the source and
+    // inherit the root `logging:` block's level, encoding, redaction, and sinks.
     //
-    // Whether to instrument requests at all is derived from the resolved scope
-    // threshold, not a manifest flag: Fastify's per-request access lines are
-    // `info`-severity, so we instrument iff `info` is enabled for this server's
-    // scope. Raise the http-server import to `level: warn` and the per-request
-    // work is skipped entirely (Fastify's null logger) rather than built and
-    // discarded per request. This is a construction-time decision — a *runtime*
-    // threshold change (§12.4) still gates output through the adapter, but does
-    // not re-instrument a server booted with logging off.
+    // The adapter is injected UNCONDITIONALLY. It used to be gated on `info`
+    // being enabled, because that was what avoided building a per-request record
+    // at a raised threshold — but `disableRequestLogging` now removes that cost
+    // outright, so the gate's only remaining effect was to hand Fastify its null
+    // logger at `level: warn` and silently drop every diagnostic it owns: the
+    // error handler's own failures, reply-send failures, aborted-request hooks.
+    // Those are exactly the records `warn` is supposed to KEEP. The adapter's
+    // `emit` short-circuits on `log.enabled`, so a quiet server pays one
+    // predicate per suppressed record and keeps its errors.
     //
     // A custom logger *instance* must be passed via Fastify 5's `loggerInstance`
     // option; passing it to `logger:` throws FST_ERR_LOG_INVALID_LOGGER_CONFIG.
-    const requestLogging = this.ctx.log.enabled(SEVERITY.info);
     this.app = Fastify({
-      ...(requestLogging ? { loggerInstance: createFastifyTeloLogger(this.ctx.log) } : {}),
+      loggerInstance: createFastifyTeloLogger(this.ctx.log),
+      // Fastify's own per-request lines are off: this kind emits its own from
+      // `onRequest` / `onResponse` instead (see `installRequestLogging`), so the
+      // access record's shape is this KIND's contract rather than Pino's prose —
+      // which is what lets a Rust or Go implementation emit the same thing.
+      disableRequestLogging: true,
       trustProxy,
       ajv: { customOptions: { useDefaults: true }, plugins: [addFormats.default as any] },
     });
@@ -144,7 +154,115 @@ class HttpServer implements ResourceInstance {
     this.setupRoutes();
   }
 
+  /**
+   * The access log, emitted by this kind rather than by Fastify.
+   *
+   * The contract is `event_name` plus OTel attributes — never the message text,
+   * which is prose and differs per framework. That is what makes the record
+   * readable across runtimes: an axum or net/http implementation registers the
+   * equivalent middleware and emits the same `http.server.request`.
+   *
+   * One `info` record per request, on completion — the convention every access
+   * log follows (nginx, Caddy, tower-http). The received-side record is `debug`
+   * because it carries no outcome; its one real use is a request that HANGS and
+   * never completes, which otherwise leaves no trace at all.
+   */
+  /**
+   * Per-mount access-log floors, longest prefix first so the match is the first
+   * hit. Built once at init rather than per request — the mount set is fixed.
+   *
+   * A mount's `logging.level` exists because the import-scoped threshold (§12.2)
+   * governs a whole module instance: one `Http.Server` is one resource in one
+   * scope, so it cannot quieten `/health` while leaving `/api` alone. This can.
+   */
+  private mountLogFloors(): ReadonlyArray<{ prefix: string; floor: number }> {
+    return (this.resource.mounts ?? [])
+      .flatMap((mount) => {
+        const level = mount.logging?.level;
+        if (!level) return [];
+        return [{ prefix: mount.path || "", floor: severityForLevel(level) }];
+      })
+      .sort((a, b) => b.prefix.length - a.prefix.length);
+  }
+
+  private installRequestLogging() {
+    const log = this.ctx.log;
+    const floors = this.mountLogFloors();
+    /**
+     * `http.route` is the matched TEMPLATE (`/todos/:id`), never the concrete
+     * path: low-cardinality, which is what an access log is aggregated on.
+     *
+     * When nothing matched — every 404 — there IS no template, and the key is
+     * omitted rather than filled with the concrete URL. Falling back would let
+     * an unauthenticated caller write arbitrary strings into the `info`-level
+     * attribute a dashboard groups on: one 404 scan, unbounded cardinality.
+     * Omission is also what OTel requires when there is no match.
+     *
+     * `routeOptions` is a getter that rebuilds an options object on every access,
+     * so it is read once per hook and passed around as the resolved value.
+     */
+    const routeAttribute = (route: string | undefined): { "http.route"?: string } =>
+      route === undefined ? {} : { "http.route": route };
+
+    /** The floor this request must clear: its mount's, or none. Matched on the
+     *  concrete URL, since that is what a mount prefix attaches to. */
+    const floorFor = (request: FastifyRequest): number => {
+      for (const { prefix, floor } of floors) {
+        if (prefix === "" || request.url === prefix || request.url.startsWith(`${prefix}/`)) {
+          return floor;
+        }
+      }
+      return 0;
+    };
+
+    /** A 5xx is not the same class of event as a 200, and both were `info`.
+     *  Deriving severity from the status is also what makes a quietened mount
+     *  safe: `level: warn` on a health check still surfaces it returning 500,
+     *  rather than going blind on the path that matters most.
+     *
+     *  4xx stays `info` deliberately — a 404 or a 401 is ordinary traffic, and
+     *  promoting it would make a scanner walking random URLs read as an incident. */
+    const severityForStatus = (status: number): number =>
+      status >= 500 ? SEVERITY.error : SEVERITY.info;
+
+    this.app.addHook("onRequest", async (request) => {
+      if (!log.enabled(SEVERITY.debug) || SEVERITY.debug < floorFor(request)) return;
+      log.debug(
+        "Request received",
+        {
+          "http.request.method": request.method,
+          ...routeAttribute(request.routeOptions?.url),
+          "url.path": request.url,
+          "httpserver.request_id": String(request.id),
+        },
+        { eventName: "http.server.request.started" },
+      );
+    });
+
+    this.app.addHook("onResponse", async (request, reply) => {
+      const severity = severityForStatus(reply.statusCode);
+      if (!log.enabled(severity) || severity < floorFor(request)) return;
+      log.log(
+        severity,
+        "Request completed",
+        {
+          "http.request.method": request.method,
+          ...routeAttribute(request.routeOptions?.url),
+          "http.response.status_code": reply.statusCode,
+          // OTel's name in OTel's unit: seconds, as a double. Fastify measures in
+          // milliseconds at full `hrtime` precision, so this is rounded to
+          // microseconds — finer than anything an access log needs, and without
+          // it the division prints seventeen digits of float noise.
+          "http.server.request.duration": Math.round(reply.elapsedTime * 1000) / 1e6,
+          "httpserver.request_id": String(request.id),
+        },
+        { eventName: "http.server.request" },
+      );
+    });
+  }
+
   private async setupPlugins() {
+    this.installRequestLogging();
     for (const { contentType, parser, stream } of this.resource.contentTypeParsers ?? []) {
       if (stream) {
         // Raw passthrough: omit `parseAs` so Fastify hands the handler the
@@ -371,7 +489,31 @@ class HttpServer implements ResourceInstance {
   async run(): Promise<void> {
     this.releaseHold = this.ctx.acquireHold();
     try {
-      await this.app.listen({ host: this.host, port: this.port });
+      await this.app.listen({
+        host: this.host,
+        port: this.port,
+        // Fastify announces "Server listening at http://…" through the injected
+        // logger, interpolating the address into prose — unparseable, and exactly
+        // what §4.1 routes into attributes. Replacing the text with a constant
+        // this module owns lets the adapter drop it without pattern-matching
+        // Fastify's wording, which is the thing this kind's own contract forbids.
+        listenTextResolver: () => LISTEN_SUPERSEDED,
+      });
+      this.listening = true;
+      this.ctx.log.info(
+        "Listening",
+        {
+          "server.address": this.host,
+          "server.port": this.port,
+          // The SOCKET's scheme, which this kind only ever opens as plain HTTP —
+          // there is no TLS field on `Http.Server`. `baseUrl` is the ADVERTISED
+          // url and is routinely `https://` behind a terminator, so deriving from
+          // it would claim TLS for a plaintext socket on the most common
+          // production deployment there is.
+          "url.scheme": "http",
+        },
+        { eventName: "http.server.started" },
+      );
       await this.ctx.emitEvent(`${this.resource.metadata.name}.Listening`, {
         port: this.port,
         host: this.host,
@@ -395,6 +537,18 @@ class HttpServer implements ResourceInstance {
       this.releaseHold = null;
     }
     await this.app.close();
+    // Only if a socket actually opened. A server that initialized but was never
+    // listed in `targets:`, or whose `listen()` threw, would otherwise report a
+    // close for something that never started — and a consumer pairing the two
+    // events for uptime or leak detection sees an unmatched close.
+    if (this.listening) {
+      this.listening = false;
+      this.ctx.log.info(
+        "Stopped listening",
+        { "server.address": this.host, "server.port": this.port },
+        { eventName: "http.server.stopped" },
+      );
+    }
   }
 }