@telorun/http-server 0.17.1 → 0.18.1

package/CHANGELOG.md

@@ -1,5 +1,46 @@
 # @telorun/http-server
 
+## 0.18.1
+
+### Patch Changes
+
+- 8a9b494: Inbound dispatch now goes through `ctx.rootContext()` — the route handler, the
+  `notFoundHandler`, and a `contentTypeParsers` parser all receive a context
+  minted for the request rather than whatever was ambient when the route was
+  registered.
+
+  No behaviour changes for an app today: a route handler already ran on a
+  per-request cancellation context, and the other two are dispatched from socket
+  callbacks where the ambient is empty anyway. What changes is that the guarantee
+  is now _stated_ rather than incidental. Execution zones (`kernel/specs/execution-zones.md`
+  §7) make it a conformance obligation on every inbound registrant, and the
+  analyzer's hard error on `trigger.inbound` edges — a zone requirement reaching
+  an HTTP route is `ZONE_REQUIREMENT_UNSATISFIED` — rests on it holding. Before,
+  it held because every shipped inbound kind happens to be a `Telo.Service`,
+  which is a property of those kinds rather than of the edge.
+
+  - @telorun/http-dispatch@0.4.2
+
+## 0.18.0
+
+### Minor Changes
+
+- d23de89: Layered module artifacts: a published module is now one artifact of several layers instead of one tarball, and each layer is materialized only when something needs it.
+
+  `telo.yaml` gets its own layer, so reading a manifest no longer downloads (and discards) the whole payload. The rest of `files:` is partitioned into one layer per bundled-controller selector — `format` plus optional `os`/`arch`/`libc` PURL qualifiers — plus an `assets` layer for what the new optional `assets:` list claims and a `common` layer for everything else. A Node kernel never fetches a `napi` layer, a `linux/amd64` host never fetches the `darwin/arm64` binary, and an app that imports a module for its API alone never fetches its frontend.
+
+  This fixes a cold-start failure: bundled controllers used to resolve against an `oci://` base URI that was read as a filesystem path, because the payload was written to disk by a CLI hook running _after_ `kernel.load()`. The first run of any OCI-imported module with bundled controllers failed and the second succeeded. Controller layers now materialize at resolve time through a module-scoped `ModuleArtifact`, built during load where the pinned import ref and the verified manifest are both available — so verification stays anchored to the importer's `#sha256-` pin rather than to whatever is in the cache.
+
+  `ctx.resolveModuleFile(relative)` is the new, URI-returning way to reach a file that ships with a module; it materializes the asset layer on first use. `Http.Static`, `mcp-client`, `assert`'s manifest loader and `Test.Suite` all use it, which also fixes a silent bug where a non-`file://` module resolved a relative root against the process working directory and served the wrong directory instead of failing.
+
+  Also: `telo install --platform os/arch[/libc]` pre-fetches layers for a platform other than the build machine's, the layer index and selector grammar are specified normatively in `kernel/specs/module-artifact.md`, and the cross-process cache lock is shared between the npm loader and layer materialization instead of duplicated.
+
+  Modules published before layers keep resolving: the manifest read path still accepts a single-blob artifact, which contains `telo.yaml` — so nothing that ships no payload needs anything done to it, and npm-backed modules are entirely unaffected. What such an artifact cannot supply is a layer index, so a module that _does_ ship a payload resolves its manifest and then fails at the controller with an actionable "republish" error. That is the six modules shipping `files:` — `oauth-client`, `scheduler`, `kv-store-memory`, `kv-store-redis`, `kv-store-sql`, `idempotency` — which must be republished, with consumers bumping to the new versions.
+
+### Patch Changes
+
+- @telorun/http-dispatch@0.4.2
+
 ## 0.17.1
 
 ### Patch Changes

package/README.md

@@ -27,8 +27,8 @@ Language- and framework-agnostic HTTP server for Telo. Declarative routes, schem
 kind: Telo.Application
 metadata: { name: hello-http, version: 1.0.0 }
 imports:
-  Http: std/http-server@0.19.1
-  JS: std/javascript@0.7.0
+  Http: oci://ghcr.io/telorun/http-server@0.19.1
+  JS: oci://ghcr.io/telorun/javascript@0.7.0
 targets: [ !ref Server ]
 ---
 kind: Http.Server

package/dist/http-api-controller.js

@@ -139,7 +139,10 @@ export class HttpServerApi {
                 // Open a request span rooting this request's own trace: the handler (and
                 // its nested invokes) nest under it, and it's labelled with the route so
                 // the trace shows the actual method+path, attributed to this Http.Api.
-                const span = await this.ctx.openSpan(cancellation.context, {
+                // rootContext: an inbound registrant dispatches with a context that
+                // inherits nothing ambient — no zones, no trace parent, no caller token
+                // (the conformance obligation in kernel/specs/execution-zones.md §7).
+                const span = await this.ctx.openSpan(this.ctx.rootContext({ cancellation }), {
                     ref: { kind: "Http.Api", name: this.apiName },
                     label: `${route.request.method} ${route.request.path}`,
                     attributes: { method: route.request.method, path: route.request.path },

package/dist/http-server-controller.js

@@ -77,7 +77,12 @@ class HttpServer {
             else if (parser) {
                 this.app.addContentTypeParser(contentType, { parseAs: "string" }, async (_req, body, done) => {
                     try {
-                        done(null, await parser.invoke({ body }));
+                        // The bound entry point forwards every argument, so the root
+                        // context rides in as the InvokeContext — §7's obligation for an
+                        // inbound registrant. (This path still calls the instance
+                        // directly rather than going through `invokeResolved`, so it is
+                        // untraced; that predates zones and is tracked separately.)
+                        done(null, await parser.invoke({ body }, this.ctx.rootContext()));
                     }
                     catch (err) {
                         done(err, undefined);
@@ -230,7 +235,11 @@ class HttpServer {
                 };
                 let result;
                 try {
-                    result = await this.ctx.invoke(handler.kind, handler.name, invokeInput);
+                    // rootContext: an inbound registrant dispatches with a context that
+                    // inherits nothing ambient (kernel/specs/execution-zones.md §7).
+                    result = await this.ctx.invoke(handler.kind, handler.name, invokeInput, {
+                        ctx: this.ctx.rootContext(),
+                    });
                 }
                 catch (err) {
                     if (!isInvokeError(err))

package/dist/http-static-controller.js

@@ -1,6 +1,6 @@
 import fastifyStatic from "@fastify/static";
 import { readFile } from "node:fs/promises";
-import { dirname, isAbsolute, join, resolve } from "node:path";
+import { isAbsolute, join, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 /** Collapse a mount prefix to a single leading slash with no trailing slash;
  *  an empty/`"/"` prefix becomes `"/"`. Unlike Http.Api (which returns `""` and
@@ -23,8 +23,8 @@ class HttpStatic {
     spaFallback;
     maxAge;
     immutable;
-    constructor(resource, ctx) {
-        this.root = resolveRoot(resource.root, ctx);
+    constructor(resource, root) {
+        this.root = root;
         this.index = resource.index ?? "index.html";
         this.spaFallback = resource.spaFallback === true;
         this.maxAge = resource.maxAge;
@@ -76,17 +76,33 @@ class HttpStatic {
         }, { prefix: mountPrefix });
     }
 }
-/** Resolve the asset root relative to the manifest that declared the resource, so
- *  the frontend ships co-located with the app (same pattern as mcp-client). */
-function resolveRoot(root, ctx) {
+/**
+ * Resolve the asset root against the declaring module's own directory, so the
+ * frontend ships co-located with the app.
+ *
+ * `ctx.resolveModuleFile` is the only correct way to do this: for a published
+ * module the manifest URL is not where its payload lives, and it also materializes
+ * the module's asset layer on first access. Deriving the directory from
+ * `moduleContext.source` by hand silently fell back to the process working
+ * directory for any non-`file://` module — serving the wrong files instead of
+ * failing.
+ */
+async function resolveRoot(root, ctx) {
     if (isAbsolute(root))
         return root;
-    const source = ctx.moduleContext.source;
-    if (!source.startsWith("file://"))
-        return resolve(root);
-    const baseDir = dirname(fileURLToPath(source));
-    return resolve(baseDir, root);
+    // A directory reference: the trailing slash keeps URL resolution from treating
+    // the last segment as a sibling file.
+    // A module whose files cannot be located raises its own actionable error from
+    // `resolveModuleFile` (naming republication), so this only guards a scheme that
+    // resolved fine but is not servable from disk.
+    const uri = await ctx.resolveModuleFile(root.endsWith("/") ? root : `${root}/`);
+    if (!uri.startsWith("file://")) {
+        throw new Error(`Http.Static root '${root}' resolved to '${uri}'. A static root must be a local ` +
+            `directory, and this runtime can only serve files from one.`);
+    }
+    // Strip the trailing separator the directory form introduced.
+    return resolve(fileURLToPath(uri));
 }
 export async function create(resource, ctx) {
-    return new HttpStatic(resource, ctx);
+    return new HttpStatic(resource, await resolveRoot(resource.root, ctx));
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@telorun/http-server",
-  "version": "0.17.1",
+  "version": "0.18.1",
   "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.56.0"
+    "@telorun/sdk": "0.67.0"
   },
   "peerDependencies": {
     "@telorun/sdk": "*"

package/src/http-api-controller.ts

@@ -174,7 +174,10 @@ export class HttpServerApi implements ResourceInstance {
         // Open a request span rooting this request's own trace: the handler (and
         // its nested invokes) nest under it, and it's labelled with the route so
         // the trace shows the actual method+path, attributed to this Http.Api.
-        const span = await this.ctx.openSpan(cancellation.context, {
+        // rootContext: an inbound registrant dispatches with a context that
+        // inherits nothing ambient — no zones, no trace parent, no caller token
+        // (the conformance obligation in kernel/specs/execution-zones.md §7).
+        const span = await this.ctx.openSpan(this.ctx.rootContext({ cancellation }), {
           ref: { kind: "Http.Api", name: this.apiName },
           label: `${route.request.method} ${route.request.path}`,
           attributes: { method: route.request.method, path: route.request.path },

package/src/http-server-controller.ts

@@ -159,7 +159,12 @@ class HttpServer implements ResourceInstance {
           { parseAs: "string" },
           async (_req, body, done) => {
             try {
-              done(null, await parser.invoke({ body }));
+              // The bound entry point forwards every argument, so the root
+              // context rides in as the InvokeContext — §7's obligation for an
+              // inbound registrant. (This path still calls the instance
+              // directly rather than going through `invokeResolved`, so it is
+              // untraced; that predates zones and is tracked separately.)
+              done(null, await parser.invoke({ body }, this.ctx.rootContext()));
             } catch (err) {
               done(err as Error, undefined);
             }
@@ -322,7 +327,11 @@ class HttpServer implements ResourceInstance {
 
         let result: any;
         try {
-          result = await this.ctx.invoke(handler.kind, handler.name, invokeInput);
+          // rootContext: an inbound registrant dispatches with a context that
+          // inherits nothing ambient (kernel/specs/execution-zones.md §7).
+          result = await this.ctx.invoke(handler.kind, handler.name, invokeInput, {
+            ctx: this.ctx.rootContext(),
+          });
         } catch (err) {
           if (!isInvokeError(err)) throw err;
           return dispatchCatches(

package/src/http-static-controller.ts

@@ -2,7 +2,7 @@ import fastifyStatic from "@fastify/static";
 import { type ResourceContext, type ResourceInstance, type RuntimeResource } from "@telorun/sdk";
 import { FastifyInstance } from "fastify";
 import { readFile } from "node:fs/promises";
-import { dirname, isAbsolute, join, resolve } from "node:path";
+import { isAbsolute, join, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 
 type HttpStaticResource = RuntimeResource & {
@@ -35,8 +35,8 @@ class HttpStatic implements ResourceInstance {
   private readonly maxAge?: number;
   private readonly immutable: boolean;
 
-  constructor(resource: HttpStaticResource, ctx: ResourceContext) {
-    this.root = resolveRoot(resource.root, ctx);
+  constructor(resource: HttpStaticResource, root: string) {
+    this.root = root;
     this.index = resource.index ?? "index.html";
     this.spaFallback = resource.spaFallback === true;
     this.maxAge = resource.maxAge;
@@ -95,19 +95,38 @@ class HttpStatic implements ResourceInstance {
   }
 }
 
-/** Resolve the asset root relative to the manifest that declared the resource, so
- *  the frontend ships co-located with the app (same pattern as mcp-client). */
-function resolveRoot(root: string, ctx: ResourceContext): string {
+/**
+ * Resolve the asset root against the declaring module's own directory, so the
+ * frontend ships co-located with the app.
+ *
+ * `ctx.resolveModuleFile` is the only correct way to do this: for a published
+ * module the manifest URL is not where its payload lives, and it also materializes
+ * the module's asset layer on first access. Deriving the directory from
+ * `moduleContext.source` by hand silently fell back to the process working
+ * directory for any non-`file://` module — serving the wrong files instead of
+ * failing.
+ */
+async function resolveRoot(root: string, ctx: ResourceContext): Promise<string> {
   if (isAbsolute(root)) return root;
-  const source = ctx.moduleContext.source;
-  if (!source.startsWith("file://")) return resolve(root);
-  const baseDir = dirname(fileURLToPath(source));
-  return resolve(baseDir, root);
+  // A directory reference: the trailing slash keeps URL resolution from treating
+  // the last segment as a sibling file.
+  // A module whose files cannot be located raises its own actionable error from
+  // `resolveModuleFile` (naming republication), so this only guards a scheme that
+  // resolved fine but is not servable from disk.
+  const uri = await ctx.resolveModuleFile(root.endsWith("/") ? root : `${root}/`);
+  if (!uri.startsWith("file://")) {
+    throw new Error(
+      `Http.Static root '${root}' resolved to '${uri}'. A static root must be a local ` +
+        `directory, and this runtime can only serve files from one.`,
+    );
+  }
+  // Strip the trailing separator the directory form introduced.
+  return resolve(fileURLToPath(uri));
 }
 
 export async function create(
   resource: HttpStaticResource,
   ctx: ResourceContext,
 ): Promise<ResourceInstance> {
-  return new HttpStatic(resource, ctx);
+  return new HttpStatic(resource, await resolveRoot(resource.root, ctx));
 }

package/tests/request-cancel.test.ts

@@ -1,4 +1,9 @@
-import { ERR_INVOKE_CANCELLED, InvokeError, createCancellationSource } from "@telorun/sdk";
+import {
+  ERR_INVOKE_CANCELLED,
+  InvokeError,
+  UNCANCELLABLE_CONTEXT,
+  createCancellationSource,
+} from "@telorun/sdk";
 import Fastify from "fastify";
 import net from "node:net";
 import type { AddressInfo } from "node:net";
@@ -45,6 +50,12 @@ describe("http-server request cancellation", () => {
       ensureKindRef: () => ({ kind: "Test.Handler", name: "SlowWork" }),
       moduleContext: { expandWith: (value: unknown) => value },
       createCancellationSource: () => createCancellationSource(),
+      // As the kernel implements it: an inbound registrant dispatches through a
+      // context it minted rather than the ambient (execution-zones spec §7), and
+      // the request's cancellation token rides in on it — which is what makes
+      // the disconnect below reach the handler.
+      rootContext: (opts?: { cancellation?: { context: unknown } }) =>
+        opts?.cancellation?.context ?? UNCANCELLABLE_CONTEXT,
       invokeResolved: (_kind: string, _name: string, h: typeof handler, input: unknown, c: unknown) =>
         h.invoke(input, c as { cancellation?: any }),
       emitEvent: () => {},

package/tests/request-span.test.ts

@@ -1,4 +1,4 @@
-import { createCancellationSource } from "@telorun/sdk";
+import { UNCANCELLABLE_CONTEXT, createCancellationSource } from "@telorun/sdk";
 import Fastify from "fastify";
 import type { AddressInfo } from "node:net";
 import { describe, expect, it } from "vitest";
@@ -31,6 +31,10 @@ describe("http-server request span", () => {
       ensureKindRef: () => ({ kind: "JS.Script", name: "Echo" }),
       moduleContext: { expandWith: (value: unknown) => value },
       createCancellationSource: () => createCancellationSource(),
+      // The controller dispatches through a context it minted rather than the
+      // ambient — execution-zones spec §7 — so the mock must offer it.
+      rootContext: (opts?: { cancellation?: { context: unknown } }) =>
+        opts?.cancellation?.context ?? UNCANCELLABLE_CONTEXT,
       invokeResolved: (_kind: string, _name: string, h: typeof handler, input: unknown) =>
         h.invoke(input),
       emitEvent: () => {},