@mauroandre/velojs 0.0.57 → 0.0.59

package/README.md

@@ -467,6 +467,7 @@ A page value that must **track server state over time** — a total another
 person's request changes, data a background scheduler mutates — declares the
 channels that keep it fresh. No extra component, no manual subscription: the
 module exports `channels` next to its `loader`.
+The one-sentence model: the live loader keeps a page's state replica faithful to the server — the first payload arrives through the usual path (SSR, `__PAGE_DATA__`, the `?_data=1` refetch), and from then on every change is **addressed**, by the app's own rules, to the group of clients it concerns, **by duty or by interest**, each one receiving the state computed for its own scope.
 
 ```tsx
 // app/expenses/Expenses.tsx
@@ -768,6 +769,8 @@ partitions is internal information, and it never ships in a production build.
 
 ### The partition contract
 
+**Addressed, not broadcast.** A partition is not a filter applied after a broadcast. The `emit` is addressed: the runtime resolves the partition key and writes only to the connections of that group — a client outside the group never hears about the change, not even a byte. Two reasons make a partition matter, and they compose: **by duty** (authorization — the data belongs to that team, that family, that project; others must not see it) and **by interest** (relevance — the tab watching project 9 has nothing to wake up for when project 7 changes). The same `scope` serves both; the app decides which, or both at once.
+
 On subscribe the `scope` receives `{ user, params }`. `user` is `c.get("user")`
 — the house key, the same one the stream/socket channel resolvers use (a
 middleware that materializes the principal elsewhere should set it in `"user"`
@@ -869,6 +872,89 @@ surface) without advancing the fake timers through the window.
 
 ---
 
+## Telemetry
+
+The framework records its own bottlenecks — pages, `?_data=1` refetches,
+actions, endpoints, stream connects, socket setups, channel connects — plus
+every `emit()` gesture that runs outside the request cycle, as JSONL lines with
+duration, status, response bytes and child spans. Collection is transparent to
+the app code: no import, no wrapper, no change in a route module.
+
+### Activation: the destination is the trigger
+
+There is no on/off flag. `VELO_TELEMETRY_FILE` and/or `VELO_TELEMETRY_SINK_URL`
+present and non-empty turn the collection on; none of them — absent or empty —
+leaves the whole thing inert (no file, no event, no cost) in any environment,
+dev included. The framework never picks a path: there is no default file, and
+the values expand `~` and `$VAR`/`${VAR}`.
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `VELO_TELEMETRY_FILE` | — | Destination file (append-only JSONL). Present and non-empty activates the file collection. Expands `~`/`$VAR`; no default path |
+| `VELO_TELEMETRY_SINK_URL` | — | Destination sink. Present and non-empty activates the HTTP collection: one `POST` per event |
+| `VELO_TELEMETRY_MAX_MB` | `10` | Rotation limit of the file, in MB. The only pruning mechanism |
+
+```bash
+# .env — the operator's destination, in production or in dev
+VELO_TELEMETRY_FILE=$DATA_DIR/telemetry.jsonl
+VELO_TELEMETRY_MAX_MB=10
+```
+
+### The event
+
+One JSON object per line. `route` is always the path **pattern** (`/:mes`),
+never the materialized URL; `bytes` is the response size where there is a body
+(pages, data, actions, endpoints) — time and weight travel together. Every line
+carries the trace id and its own timestamp.
+
+```json
+{
+  "trace": "m3k9x1-4-f8a2q7",
+  "ts": "2026-10-07T18:22:03.482Z",
+  "type": "page",
+  "route": "/:mes",
+  "module": "MesPage",
+  "status": "ok",
+  "duration": 45.2,
+  "bytes": 122880,
+  "spans": [
+    { "name": "loader:AppLayout", "start": 0.8, "duration": 3.1, "status": "ok" },
+    { "name": "loader:MesPage", "start": 1.2, "duration": 43.9, "status": "ok" },
+    { "name": "render", "start": 44.3, "duration": 3.5, "status": "ok" }
+  ]
+}
+```
+
+Types: `page`, `data`, `action`, `endpoint`, `stream-connect`, `socket-connect`,
+`channel-connect`, `emit`, `delivery`, `close` and `boot`. The `emit` trace has
+no request parent — in the invalidation mode each re-executed loader is a child
+span. A long connection (channel, stream, socket) writes one light `delivery`
+line per frame, with the cumulative ordinal and the frame's bytes, and a final
+`close` line with the total and the lifetime.
+
+### File, boot and rotation
+
+The first line of every active destination is the boot record: the app version,
+the environment, the **effective** destination and the rotation limit in force.
+The effective file carries an instance suffix — `telemetry.jsonl` becomes
+`telemetry.8123-host.jsonl` — so replicas pointing the same path write distinct
+files. The file rotates by size (`VELO_TELEMETRY_MAX_MB`, default 10):
+`<effective>.<n>` keeps the past, the effective path keeps the newest lines.
+
+### The CLI
+
+```bash
+velojs telemetry              # resolves VELO_TELEMETRY_FILE (env or .env), instance files included
+velojs telemetry --last 60m   # the last hour of the file
+velojs telemetry ./t.prod.jsonl
+```
+
+Ranks the JSONL by route, action and channel — count, errors, p50/p95 and
+volume in bytes — and prints the timeline. The full reference lives in
+[site/docs/22-telemetry.md](site/docs/22-telemetry.md).
+
+---
+
 ## Actions
 
 Server-side functions callable from the client via RPC.
@@ -1686,6 +1772,9 @@ Callbacks queue until the server starts. If called after startup, executes immed
 | `HOST` | — | Bind interface, in dev and production. Overrides `defineConfig`'s `hostname`; in dev an explicit `--host`/`server.host` still wins |
 | `NODE_ENV` | — | Set automatically by `velojs start`. Enables static file serving |
 | `STATIC_BASE_URL` | `""` | CDN/bucket prefix for static assets |
+| `VELO_TELEMETRY_FILE` | — | Telemetry destination file — present and non-empty activates the native collection (see [Telemetry](#telemetry)). Expands `~`/`$VAR` |
+| `VELO_TELEMETRY_SINK_URL` | — | Telemetry sink — present and non-empty also POSTs every event |
+| `VELO_TELEMETRY_MAX_MB` | `10` | Telemetry file rotation limit, in MB |
 
 ---
 
@@ -2025,7 +2114,7 @@ velojs build
 
 Asset filenames include content hashes for long-term browser caching. The server build reads the Vite manifest to inject the correct filenames into `<Scripts>`.
 
-In production, `velojs start` sets `NODE_ENV=production` automatically and serves static files from `dist/client/`. HTML responses are served with `Cache-Control: no-cache` so browsers always fetch the latest HTML (which references the current hashed assets).
+In production, `velojs start` sets `NODE_ENV=production` automatically and serves static files from `dist/client/`. Assets carry content hashes and are **public by design**, so the server answers an existing file **before the app's route table** — a page route, an action endpoint or a route middleware (an auth guard redirecting to `/login`, for instance) never sees an asset path. Only the framework's own infra middlewares (trailing-slash normalization, the logger) run ahead of the asset lookup. Paths that are not files fall through to the app routes as usual (SSR pages, actions, streams, sockets, endpoints, the catch-all 404). HTML responses are served with `Cache-Control: no-cache` so browsers always fetch the latest HTML (which references the current hashed assets).
 
 ### Static assets on CDN
 
@@ -2035,7 +2124,7 @@ Set `STATIC_BASE_URL` to serve static assets from a CDN or S3 bucket:
 STATIC_BASE_URL=https://cdn.example.com/assets node dist/server.js
 ```
 
-The `<Scripts />` component and CSS `url()` references will use this prefix automatically.
+The `<Scripts />` component and CSS `url()` references will use this prefix automatically. When `STATIC_BASE_URL` starts with `http`, the server mounts no local static at all — every path is an app path, and the assets' public-by-design semantics come from the bucket/CDN.
 
 ---
 

package/agent/AGENTS.md

@@ -108,6 +108,8 @@ import { emit } from "@mauroandre/velojs/server";
 await emit("teamExpenses", { user: { teamId: 7 } });
 ```
 
+An `emit` is addressed to the partition's group — clients outside the group never hear about it (not a broadcast the client filters); partitions exist by duty (authorization) or by interest (relevance).
+
 Or, when the producer already holds the new value, it pushes it as a typed slice:
 
 ```ts

package/agent/skills/velojs-live-loader/SKILL.md

@@ -5,7 +5,7 @@ description: "Keep a loader value faithful to server state in real time: declare
 
 # Live loader
 
-A `loader` fetches a page's data once per request and re-fetches it on SPA navigation. That is everything a page needs when its data changes because of the user themselves — or not at all. A **value that must track server state over time** (a team total another person's request changes, data a background scheduler mutates) needs the loader to stay faithful. That is the live loader: the same `loader`, the same `useLoader()` read, plus a sibling `channels` export.
+A `loader` fetches a page's data once per request and re-fetches it on SPA navigation. That is everything a page needs when its data changes because of the user themselves — or not at all. A **value that must track server state over time** (a team total another person's request changes, data a background scheduler mutates) needs the loader to stay faithful. That is the live loader: the same `loader`, the same `useLoader()` read, plus a sibling `channels` export. The one-sentence model: the live loader keeps a page's state replica faithful to the server — the first payload arrives through the usual path (SSR, `__PAGE_DATA__`, the `?_data=1` refetch), and from then on every change is **addressed**, by the app's own rules, to the group of clients it concerns, **by duty or by interest**, each one receiving the state computed for its own scope.
 
 ## The three declarations
 
@@ -284,6 +284,8 @@ On a page with no `channels` the fields exist, the record is empty and the aggre
 
 ## The partition contract
 
+**Addressed, not broadcast.** A partition is not a filter applied after a broadcast. The `emit` is addressed: the runtime resolves the partition key and writes only to the connections of that group — a client outside the group never hears about the change, not even a byte. Two reasons make a partition matter, and they compose: **by duty** (authorization — the data belongs to that team, that family, that project; others must not see it) and **by interest** (relevance — the tab watching project 9 has nothing to wake up for when project 7 changes). The same `scope` serves both; the app decides which, or both at once.
+
 On subscribe the `scope` receives `{ user, params }`. `user` is whatever a middleware materialized under the house key `"user"` — the same key the stream/socket channel resolvers use; a middleware that materializes the principal somewhere else should set it in `"user"` too:
 
 ```ts

package/agent/skills/velojs-production-deploy/SKILL.md

@@ -25,6 +25,12 @@ npx velojs start
 
 This automatically sets `NODE_ENV=production` and starts the server. In production mode, VeloJS serves static files from `dist/client/` and handles SSR for all page routes.
 
+### Assets are served before the app routes
+
+`dist/client` assets are **public by design**: their names carry content hashes and their URLs are fetched by the browser with no session and no route logic attached. The server answers an existing file from `dist/client` **before the app's route table** — so a page route, an action endpoint or a route middleware (an auth guard redirecting to `/login`, for instance) never sees an asset path. Only the framework's own infra middlewares (trailing-slash normalization and the logger) run ahead of the asset lookup.
+
+Paths that are not files keep the normal flow: SSR pages, actions, streams, sockets, endpoints and the app's catch-all 404. A top-level dynamic route (`/:mes`) therefore means only app paths — `/client.<hash>.js` is served as a file, while `/2026-10` goes through the route's middlewares and loaders.
+
 ## Dockerfile
 
 Here's a production-ready Dockerfile with multi-stage build:
@@ -124,7 +130,7 @@ If you want to serve static assets (JS, CSS, images) from a CDN or S3 bucket ins
 STATIC_BASE_URL=https://cdn.example.com/assets npx velojs start
 ```
 
-The `<Scripts />` component and CSS `url()` references will automatically use this prefix. The server will skip serving static files when `STATIC_BASE_URL` points to an external URL.
+The `<Scripts />` component and CSS `url()` references will automatically use this prefix. When `STATIC_BASE_URL` starts with `http`, the server mounts no local static at all: every path is an app path, and the public-by-design semantics come from the bucket/CDN.
 
 ## Included dependencies
 

package/agent/skills/velojs-telemetry/SKILL.md

@@ -0,0 +1,182 @@
+---
+name: velojs-telemetry
+description: "Native telemetry: the framework records its own boundaries — the page SSR (with a span per hierarchy loader plus the render), the `?_data=1` refetch, the action, the endpoint, the stream connect, the socket setup, the channel connect and every `emit` — as JSONL lines carrying duration, status, response bytes, child spans and, on long connections, one delivery line per frame plus a closing line. Enable it by destination (`VELO_TELEMETRY_FILE` and/or `VELO_TELEMETRY_SINK_URL`, values expanding `~`/`$VAR`, instance-suffixed file, `VELO_TELEMETRY_MAX_MB` rotation) and rank the file with `velojs telemetry`. Use when a production page is slow, when a response is too fat, or to see which routes, loaders, actions and channels are actually being called."
+---
+
+# Telemetry
+
+The framework knows its own bottlenecks — they are finite: a page SSR (with the loaders of the hierarchy), a `?_data=1` refetch, an action, a declarative endpoint, a stream connect, a socket setup, a channel connect. It also knows the part that runs **outside any request**: when `emit()` invalidates a channel, the loader re-executes on an already-open connection, with no new request involved. Native telemetry turns each of those executions into one JSON line — duration, status, response bytes, child spans — and each long connection into one light line per delivery plus a final line when it closes.
+
+What this buys you: **which route is slow, how big its response is, and why**. A page trace names every loader that ran and how long each took; an emit trace names the channel, the partition and how many connections re-executed. The file is plain JSONL in an operator-chosen path — no dev overlay, no dashboard inside the app, nothing to attack in production.
+
+## The destination is the trigger
+
+There is no on/off flag. **The destination env is the activation**: `VELO_TELEMETRY_FILE` and/or `VELO_TELEMETRY_SINK_URL`, present and non-empty, turn collection on; none of them — absent or empty — leaves the module completely inert (no file, no event, no cost) in **any environment, dev included**. The dev server never turns telemetry on by itself: an app that wants it in development puts the env in its `.env`, like any other environment.
+
+The framework never picks a destination for you: there is no default file path anywhere. The path is the deployment's decision, read from the env. The values expand `~` (home) and `$VAR` / `${VAR}`, so an operator can point at `$ALGO_PRIVADO/telemetry.jsonl`; an undefined reference is kept literally, and the [boot record](#the-boot-record) shows the destination that was actually in force.
+
+| Variable | Default | Role |
+|----------|---------|------|
+| `VELO_TELEMETRY_FILE` | — | Destination file. Present and non-empty activates the file collection (append-only JSONL). Expands `~` and `$VAR`. No default path |
+| `VELO_TELEMETRY_SINK_URL` | — | Destination sink. Present and non-empty activates the HTTP collection: one `POST` per event with the JSON line as the body |
+| `VELO_TELEMETRY_MAX_MB` | `10` | Rotation limit of the file, in MB. The only pruning mechanism — there is no retention by days |
+
+Both destinations at once feed both; one alone is enough. The values are read from the process environment first and from the project's `.env` as the fallback (an env var exported in the shell wins over the file) — the same precedence the release script uses.
+
+```bash
+# .env — production, or a dev machine that wants the traces
+VELO_TELEMETRY_FILE=$DATA_DIR/telemetry.jsonl
+VELO_TELEMETRY_MAX_MB=10
+# ...or ship them somewhere:
+# VELO_TELEMETRY_SINK_URL=https://collector.example.com/ingest
+```
+
+## What gets recorded
+
+Each execution in one of the framework's bottlenecks produces a trace (type → fields):
+
+| Type | Produced by | Carries |
+|------|-------------|---------|
+| `page` | A page request (SSR HTML) | `route` (path pattern), `module` (the page's moduleId), duration, status, `bytes`, one child span per loader of the hierarchy (plus the `render` span) |
+| `data` | A `?_data=1` refetch (SPA navigation) | `route`, `module`, duration, status, `bytes` of the JSON, a span per loader executed |
+| `action` | `/_action/{moduleId}/{name}` | `route`, `module`, `name`, duration, status, `bytes` |
+| `endpoint` | A declarative `{ method, handler }` node | `method`, `route`, duration, status, `bytes` where there is a body |
+| `stream-connect` | A `stream_*` / standalone SSE connect | `route`, `module`, `name`, `channel`, duration, status |
+| `socket-connect` | A `socket_*` upgrade | `route`, `module`, `name`, duration, status |
+| `channel-connect` | A live-loader channel connect | `route`, `module`, `channel`, duration, status, the `snapshot` span of the connect snapshot |
+| `emit` | Every `emit()` gesture | `channel`, `partition`, `mode` (`invalidate` / `slice`), `connections` reached, duration; in the invalidation mode, one child span per loader re-execution per connection |
+| `delivery` | Every frame a long connection delivers | `channel`/`route`/`module`, the cumulative ordinal (`deliveries`), `bytes` of the frame |
+| `close` | The end of a long connection | `channel`/`route`/`module`, the total of `deliveries`, the connection's lifetime as `duration` |
+
+The emission is **transparent to the app**: no import, no wrapper, no change in a route module. The spans are automatic too — the trace of a page knows the loaders because the framework is the one executing them.
+
+## The event format
+
+One JSON object per line. The same envelope for every type:
+
+```json
+{
+  "trace": "m3k9x1-4-f8a2q7",
+  "ts": "2026-10-07T18:22:03.482Z",
+  "type": "page",
+  "route": "/:mes",
+  "module": "MesPage",
+  "status": "ok",
+  "duration": 45.2,
+  "bytes": 122880,
+  "spans": [
+    { "name": "loader:AppLayout", "start": 0.8, "duration": 3.1, "status": "ok" },
+    { "name": "loader:MesPage", "start": 1.2, "duration": 43.9, "status": "ok" },
+    { "name": "render", "start": 44.3, "duration": 3.5, "status": "ok" }
+  ]
+}
+```
+
+- **`trace`** identifies the execution (and ties a connection's delivery/close lines to its connect line); **`ts`** is the line's own timestamp — both exist on **every** type, including `delivery`, `close` and `boot`.
+- **`route`** is always the path **pattern** (`/:mes`), never the materialized URL — this is what makes aggregation by route possible. The channel and stream routes travel as their registered paths (`/_channel/{moduleId}/{channel}`, `/_event/{moduleId}/{name}`).
+- **`duration`** is in milliseconds, with decimals; **`status`** is `ok` or `error` (a loader, action or handler that throws). `bytes` is the size of the response body where there is one: pages, data refetches, actions and endpoints. Time and weight travel together, so a slow screen is either a slow server or a fat response — the trace says which.
+- **`spans`** are the children of the trace, when the type has them: `name`, `start` (relative to the trace), `duration` and `status` each. Loader spans are named after the module (`loader:MesPage`); `render` delimits the SSR itself. `total − (loaders + render)` is the gap of the middlewares, which this slice deliberately leaves uninstrumented.
+- **`deliveries`** is the cumulative ordinal of a connection's deliveries. A long connection is a stream of evidence: fifty snapshots on one channel is the symptom of "re-executing too much", and the volume is proportional to what it measures — whoever delivers a lot, records a lot. Rotation limits the rest.
+
+### Delivery and closing lines
+
+Long connections (channel, stream and socket) never keep one line growing: each delivered frame is a light line of its own — no spans — carrying the ordinal and the frame's bytes when there are any:
+
+```json
+{ "trace": "m3k9x1-4-f8a2q7", "ts": "…", "type": "delivery", "channel": "teamExpenses", "deliveries": 2, "bytes": 31 }
+```
+
+When the connection ends — the client left, the server closed it, the idle timeout elapsed — the final line reports the total and the lifetime:
+
+```json
+{ "trace": "m3k9x1-4-f8a2q7", "ts": "…", "type": "close", "channel": "teamExpenses", "deliveries": 2, "status": "ok", "duration": 120000.4 }
+```
+
+Heartbeats are transport, not delivery: a `: ping` comment never counts as a delivery and never moves the idle clock.
+
+### The emit chain
+
+The emit trace has **no request parent at all** — that is the point:
+
+```json
+{
+  "trace": "m3k9x2-1-b41c9d",
+  "ts": "…",
+  "type": "emit",
+  "channel": "teamExpenses",
+  "partition": "team:7",
+  "mode": "invalidate",
+  "connections": 2,
+  "status": "ok",
+  "duration": 12.7,
+  "spans": [
+    { "name": "loader:Expenses", "start": 0.1, "duration": 5.4, "status": "ok" },
+    { "name": "loader:Expenses", "start": 0.2, "duration": 6.1, "status": "ok" }
+  ]
+}
+```
+
+In the invalidation mode every re-executed loader is a child span — one per connection; a scope that resolves to a partition with no subscribers still produces the trace, with `connections: 0` (an emit that reaches nobody is exactly what you want to see). In the slice mode the producer already holds the value, so the trace carries the connections that received it and no spans. When the coalescing window folds a burst, each gesture that fell inside it gets its trace, carrying the round's spans.
+
+## The boot record
+
+The first event of every active destination — the file's first line, the sink's first POST — is the boot record, the cheap "where am I writing and how far can I grow" diagnosis:
+
+```json
+{ "trace": "m3k9x0-0-0a1b2c", "ts": "…", "type": "boot", "version": "1.4.2", "env": "production", "file": "/srv/app/logs/telemetry.8123-host.jsonl", "sink": null, "maxMb": 10 }
+```
+
+`version` is the served app's `package.json` version; `env` is `NODE_ENV`; `file` and `sink` are the **effective** destinations (a null one is off), and `maxMb` is the rotation limit in force — the default or the override.
+
+## File, instance and rotation
+
+The file destination is append-only JSONL. The **effective name carries an instance suffix** with the pid and the hostname — `telemetry.jsonl` becomes `telemetry.8123-host.jsonl` — so replicas of the same app sharing a volume write different files and a concurrent append never corrupts one another's JSONL.
+
+Rotation is by size only (`VELO_TELEMETRY_MAX_MB`, default `10`): when the next line would push the file past the limit, the file is renamed to `<effective>.<n>` and a fresh one takes its place — the effective path always holds the newest lines, and the rotated files stay behind it. There is no retention by days; the limit is the whole pruning policy.
+
+## The sink
+
+With `VELO_TELEMETRY_SINK_URL` set (alone or alongside `VELO_TELEMETRY_FILE`), every event also leaves as one `POST` with the JSON line as the body — that is what the consumer's platform ingests. Without the env, nothing leaves the machine. A sink failure — refused connection, non-2xx — is logged and **never** affects the request that produced the event.
+
+## The CLI
+
+`velojs telemetry` is the inaugural consumption surface: it ranks the JSONL by route, action and channel — count, errors, p50/p95 and volume in bytes — and prints the timeline. No UI, no server route: the operator's terminal.
+
+```bash
+# The whole file resolved from the env (or the project's .env), instance and
+# rotation files included:
+velojs telemetry
+
+# Only the last hour of a long-lived file:
+velojs telemetry --last 60m
+
+# A JSONL copied from production:
+velojs telemetry ./telemetry.prod.jsonl
+```
+
+The window is the whole file by default; `--last` accepts `ms`, `s`, `m`, `h` and `d` (`--last 60m`, `--last 2h`, `--last 7d`). Without a path, the destination comes from `VELO_TELEMETRY_FILE` (environment or `.env`), including every file that derives from it — the instance suffixes and the rotated ones. An explicit path reads exactly that file (or a directory of them).
+
+```
+VeloJS telemetry
+files:  1
+  /srv/app/logs/telemetry.8123-host.jsonl
+window: last 60m — since 2026-10-07T17:22:03.482Z
+events: 412
+
+By route
+  key                      count  errors     p50      p95     bytes
+  /:mes                       48       1   45.2ms   88.1ms    5.6MB
+  GET /api/health            120       0    1.2ms    3.0ms   12.0KB
+
+By action
+  key                      count  errors     p50      p95     bytes
+  Jobs/notify                  6       0   12.4ms   30.2ms    1.2KB
+
+By channel
+  key                      count  errors     p50      p95     bytes
+  teamExpenses                52       0   12.7ms   20.1ms    1.3KB
+```
+
+## What is not here yet
+
+The visual viewer over the route tree (`velojs telemetry --view`, following the `velojs graph --view` pattern), a manual `trace()` API for app spans, OTLP/OpenTelemetry export, middleware spans, client-side telemetry and the retention/continuous aggregation layer are deliberately out of this slice. The nested format is the one that will receive them without a migration — the model is already parent-and-children.

package/dist/channels.d.ts

@@ -57,6 +57,7 @@
  */
 import type { Context, Hono, MiddlewareHandler } from "hono";
 import type { LoaderArgs, RouteModule } from "./types.js";
+import { type TelemetryStatus, type TelemetryTrace } from "./telemetry.js";
 /** Result of a partition resolver. `null`/`undefined` denies the subscription. */
 export type ChannelScopeResult = string | null | undefined;
 /**
@@ -229,6 +230,12 @@ export interface ChannelConnection {
      * comments never touch it.
      */
     lastDeliveryAt?: number | undefined;
+    /**
+     * The connection's telemetry trace: `channel-connect` with the snapshot
+     * span, then one `delivery` line per snapshot/slice and the final `close`
+     * line. Absent (no-op) when collection is off.
+     */
+    telemetry?: TelemetryTrace | undefined;
 }
 /** One live group of a channel: the connections of one module in one partition. */
 export interface ChannelInspectGroup {
@@ -283,7 +290,7 @@ export declare function __resetChannels(): void;
  * instead of dying silently; a loader that returns a `Response` (a redirect
  * short-circuit) has no state to send.
  */
-export declare function pushSnapshot(conn: ChannelConnection): Promise<void>;
+export declare function pushSnapshot(conn: ChannelConnection): Promise<TelemetryStatus>;
 /**
  * Signals that a channel's partition changed: every connection in that
  * partition receives a fresh snapshot (its loader re-executed with the