@telorun/kernel 0.66.0 → 0.68.0

package/dist/zone-context.js

@@ -0,0 +1,272 @@
+/**
+ * The kernel half of execution zones — `kernel/specs/execution-zones.md`.
+ *
+ * Everything a `ResourceContext` needs to open a zone declared by one of its
+ * own slots, and to assert it is inside one: annotation resolution in the
+ * kind's *declaring* scope, correlation-pointer resolution over the resource's
+ * own (Phase-5-injected) manifest, `extends`-aware kind matching, and the
+ * ambient-stack search.
+ *
+ * It lives beside `resource-handle.ts` rather than inside `resource-context.ts`
+ * because it is a subsystem with its own state, not a few accessors: the
+ * context delegates and keeps its own file about the resource lifecycle.
+ *
+ * **Resolution is memoized per annotated field.** Everything a match needs —
+ * the resolved zone kind, the accepted-kind set, and the correlation handle —
+ * is a function of `(kind, field)` and the injected manifest, all fixed once
+ * `create()` has returned. A statement resolves them on *every* dispatch
+ * otherwise, and this sits on the SQL hot path.
+ */
+import { InvokeError, RuntimeError, UNCANCELLABLE_CONTEXT, deriveContext, getRefIdentity, sameResource, } from "@telorun/sdk";
+import { readProvidesZone, readRequiresZone } from "@telorun/analyzer";
+import { isRefSentinel } from "@telorun/templating";
+import { ambientInvokeContext, runWithAmbientContext } from "./evaluation-context.js";
+import { handleOfInstance } from "./resource-handle.js";
+export class ZoneContext {
+    #host;
+    /** Field → resolved requirement. See the file docstring. */
+    #requirements = new Map();
+    /** Slot → resolved correlation handle for a providing slot. */
+    #providers = new Map();
+    constructor(host) {
+        this.#host = host;
+    }
+    async withZone(slot, fn, base) {
+        const provider = this.resolveProvider(slot);
+        // Every field derived: kind = the declaring kind, provider = this resource,
+        // key = the annotation's pointer over this resource's own manifest — which
+        // is the runtime half of why a schema cannot claim another module's zone.
+        const entry = Object.freeze({
+            kind: this.#host.resolvedKind,
+            provider: this.#host.self,
+            ...(provider.key ? { key: provider.key } : {}),
+        });
+        const from = base ?? ambientInvokeContext() ?? UNCANCELLABLE_CONTEXT;
+        const derived = deriveContext(from, { zones: [...(from.zones ?? []), entry] });
+        return runWithAmbientContext(derived, () => fn(derived, entry));
+    }
+    requireZone(field, ctx) {
+        const resolved = this.resolveRequirement(field);
+        const entry = this.match(resolved, ctx);
+        if (entry)
+            return entry;
+        const where = resolved.keyHandle
+            ? ` on ${resolved.keyHandle.ref.kind} '${resolved.keyHandle.ref.name}'`
+            : "";
+        const reason = resolved.requirement.reason ? `: ${resolved.requirement.reason}` : "";
+        throw new InvokeError("ERR_ZONE_REQUIRED", `${this.#host.resolvedKind} '${this.#host.resourceName}': no ${resolved.requiredKind} zone open${where}${reason}`);
+    }
+    findZone(field, ctx) {
+        return this.match(this.resolveRequirement(field), ctx);
+    }
+    zonesFor(instance, ctx) {
+        const zones = (ctx ?? ambientInvokeContext())?.zones;
+        if (!zones || zones.length === 0)
+            return [];
+        const handle = handleOfInstance(instance);
+        if (!handle)
+            return [];
+        const out = [];
+        for (let i = zones.length - 1; i >= 0; i--) {
+            const entry = zones[i];
+            if (entry.key && sameResource(entry.key, handle))
+                out.push(entry);
+        }
+        return out;
+    }
+    // ── resolution ────────────────────────────────────────────────────────────
+    resolveProvider(slot) {
+        const cached = this.#providers.get(slot);
+        if (cached)
+            return cached;
+        const provides = readProvidesZone(this.slotSchema(slot));
+        if (!provides) {
+            throw new RuntimeError("ERR_ZONE_ANNOTATION_MISSING", `[${this.#host.resourceName}] withZone('${slot}'): schema.properties.${slot} of ` +
+                `${this.#host.resolvedKind} carries no x-telo-provides-zone — the controller and its ` +
+                `schema disagree`);
+        }
+        const key = provides.key ? this.resolveCorrelationHandle([provides.key]) : undefined;
+        const resolved = key ? { key } : {};
+        this.#providers.set(slot, resolved);
+        return resolved;
+    }
+    resolveRequirement(field) {
+        const cached = this.#requirements.get(field);
+        if (cached)
+            return cached;
+        const requirement = readRequiresZone(this.slotSchema(field));
+        if (!requirement) {
+            throw new RuntimeError("ERR_ZONE_ANNOTATION_MISSING", `[${this.#host.resourceName}] requireZone('${field}'): schema.properties.${field} of ` +
+                `${this.#host.resolvedKind} carries no x-telo-requires-zone — the controller and its ` +
+                `schema disagree`);
+        }
+        const requiredKind = this.resolveZoneKind(requirement.zone);
+        const resolved = {
+            requirement,
+            requiredKind,
+            accepts: this.acceptancePredicate(requiredKind),
+            // When no pointer resolves, the requirement discharges uncorrelated — any
+            // zone of the right type. Inventing a correlation the manifest does not
+            // state would manufacture failures from a guess.
+            keyHandle: requirement.key.length > 0 ? this.resolveCorrelationHandle(requirement.key) : undefined,
+        };
+        this.#requirements.set(field, resolved);
+        return resolved;
+    }
+    /** Innermost first — the order a nested zone must win in. */
+    match(resolved, ctx) {
+        const zones = (ctx ?? ambientInvokeContext())?.zones ?? [];
+        for (let i = zones.length - 1; i >= 0; i--) {
+            const entry = zones[i];
+            if (!resolved.accepts(entry.kind))
+                continue;
+            if (resolved.keyHandle && !(entry.key && sameResource(entry.key, resolved.keyHandle))) {
+                continue;
+            }
+            return entry;
+        }
+        return undefined;
+    }
+    /** The schema node for one of this kind's own top-level fields — the site the
+     *  zone annotations live on. */
+    slotSchema(field) {
+        const def = this.ownDefinition();
+        return def.schema
+            ?.properties?.[field];
+    }
+    ownDefinition() {
+        const def = this.#host.resolveDefinition(this.#host.resolvedKind);
+        if (!def) {
+            throw new RuntimeError("ERR_ZONE_ANNOTATION_MISSING", `[${this.#host.resourceName}] no registered definition for kind '${this.#host.resolvedKind}'`);
+        }
+        return def;
+    }
+    /** Resolve the annotation's zone kind to canonical `<module>.<Kind>`.
+     *  `resolveSchemaRefKinds` already rewrote it in the DECLARING module's scope
+     *  during analysis; the scoped lookup is the fallback for an un-analyzed load. */
+    resolveZoneKind(zone) {
+        const def = this.#host.resolveDefinitionIn(zone, this.ownDefinition().metadata.module);
+        if (!def) {
+            throw new RuntimeError("ERR_ZONE_UNRESOLVED", `[${this.#host.resourceName}] x-telo-requires-zone names '${zone}', which resolves to no ` +
+                `registered kind`);
+        }
+        return `${def.metadata.module}.${def.metadata.name}`;
+    }
+    /**
+     * Acceptance for one requirement: the required kind, or anything that
+     * transitively `extends` it.
+     *
+     * A predicate rather than a precomputed set because the kernel's registry has
+     * no `extendedBy` index — only the upward `extends` link — so the set of
+     * acceptable kinds is not enumerable from the requirement alone. Each
+     * candidate walks UP instead, and only ever for a kind actually seen on the
+     * stack. The verdict is cached per entry kind, so a repeated dispatch through
+     * the same shape costs one map lookup.
+     */
+    acceptancePredicate(requiredKind) {
+        const verdicts = new Map([[requiredKind, true]]);
+        return (entryKind) => {
+            const known = verdicts.get(entryKind);
+            if (known !== undefined)
+                return known;
+            const verdict = this.extendsChainReaches(entryKind, requiredKind);
+            verdicts.set(entryKind, verdict);
+            return verdict;
+        };
+    }
+    extendsChainReaches(entryKind, requiredKind) {
+        let current = entryKind;
+        const seen = new Set();
+        while (current !== undefined && !seen.has(current)) {
+            if (current === requiredKind)
+                return true;
+            seen.add(current);
+            const def = this.#host.resolveDefinition(current);
+            if (typeof def?.extends !== "string")
+                return false;
+            const parent = this.#host.resolveDefinitionIn(def.extends, def.metadata.module);
+            current = parent ? `${parent.metadata.module}.${parent.metadata.name}` : undefined;
+        }
+        return false;
+    }
+    /** First pointer that resolves to a live instance wins — the manifest-level
+     *  transcription of a controller's own `a ?? b` derivation. */
+    resolveCorrelationHandle(pointers) {
+        for (const pointer of pointers) {
+            const handle = this.resolveKeyPointer(pointer);
+            if (handle)
+                return handle;
+        }
+        return undefined;
+    }
+    resolveKeyPointer(pointer) {
+        const segments = pointer.split("/").filter((s) => s.length > 0);
+        if (segments.length === 0)
+            return undefined;
+        let manifest = this.#host.manifest;
+        let value;
+        for (let i = 0; i < segments.length; i++) {
+            if (i > 0) {
+                // A pointer may traverse a `!ref` into the referenced resource's own
+                // manifest: read field → resolve reference → read field. Purely
+                // mechanical — no kind is named here.
+                const name = this.referencedName(value);
+                manifest = name ? this.#host.resolveLocalManifest(name) : undefined;
+                if (!manifest)
+                    return undefined;
+            }
+            value = manifest[segments[i]];
+            if (value === undefined || value === null)
+                return undefined;
+        }
+        return this.handleOfValue(value);
+    }
+    /**
+     * The LOCAL name a reference value points at, in any of its three shapes.
+     *
+     * A cross-module `!ref Alias.name` yields undefined: it names an instance in
+     * another module's scope, and this resolver is scope-local, so taking the
+     * bare name would bind to whatever local resource happened to share it.
+     * Leaving it uncorrelated is the under-approximating direction. The analyzer's
+     * `refName` holds the identical rule, so the two halves agree about what a
+     * traversing pointer means.
+     */
+    referencedName(value) {
+        if (value === null || typeof value !== "object")
+            return undefined;
+        const id = getRefIdentity(value) ?? handleOfInstance(value)?.ref;
+        if (id)
+            return id.name;
+        if (isRefSentinel(value)) {
+            const source = value.source;
+            const dot = source.indexOf(".");
+            if (dot <= 0)
+                return source;
+            return source.slice(0, dot) === "Self" ? source.slice(dot + 1) : undefined;
+        }
+        const v = value;
+        const pure = typeof v.kind === "string" &&
+            typeof v.name === "string" &&
+            Object.keys(v).every((k) => k === "kind" || k === "name" || k === "alias");
+        if (!pure)
+            return undefined;
+        if (typeof v.alias === "string" && v.alias !== "Self")
+            return undefined;
+        return v.name;
+    }
+    /** The handle a pointer's terminal value identifies: a live instance's own
+     *  handle, or the handle of the instance a reference resolves to. */
+    handleOfValue(value) {
+        if (value === null || typeof value !== "object")
+            return undefined;
+        const direct = handleOfInstance(value);
+        if (direct)
+            return direct;
+        const name = this.referencedName(value);
+        if (!name)
+            return undefined;
+        const instance = this.#host.resolveLocalInstance(name);
+        return instance ? handleOfInstance(instance) : undefined;
+    }
+}
+//# sourceMappingURL=zone-context.js.map

package/dist/zone-context.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"zone-context.js","sourceRoot":"","sources":["../src/zone-context.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@telorun/kernel",
-  "version": "0.66.0",
+  "version": "0.68.0",
   "description": "Telo Runtime - A lightweight, polyglot execution host.",
   "keywords": [
     "telo",
@@ -61,9 +61,9 @@
   "dependencies": {
     "@marcbachmann/cel-js": "^7.6.1",
     "@sinclair/typebox": "^0.34.48",
-    "@telorun/analyzer": "0.53.0",
+    "@telorun/analyzer": "0.55.0",
     "@telorun/glob": "0.2.0",
-    "@telorun/templating": "0.11.1",
+    "@telorun/templating": "0.12.0",
     "ajv": "^8.17.1",
     "ajv-formats": "^3.0.1",
     "packageurl-js": "^2.0.1",
@@ -75,7 +75,7 @@
     "@types/tar-stream": "^3.1.3",
     "typescript": "^5.0.0",
     "vitest": "^2.1.8",
-    "@telorun/sdk": "0.65.0"
+    "@telorun/sdk": "0.68.0"
   },
   "optionalDependencies": {
     "esbuild": "^0.25.12"

package/src/application-env.ts

@@ -1,7 +1,19 @@
-import { type DefResolver, effectiveAuthorSchema, residualEntrySchema } from "@telorun/analyzer";
-import type { ResourceDefinition } from "@telorun/sdk";
+import {
+  type DefResolver,
+  effectiveAuthorSchema,
+  residualEntrySchema,
+  withStreamPropertiesSkipped,
+} from "@telorun/analyzer";
+import type {
+  ResourceContext,
+  ResourceDefinition,
+  ResourceManifest,
+  TypeRule,
+} from "@telorun/sdk";
 import { RuntimeError } from "@telorun/sdk";
+import { create as createJsonSchemaType } from "./controllers/type/json-schema-controller.js";
 import { SchemaValidator } from "./schema-validator.js";
+import { resolveTypeFieldSchema } from "./type-field-schema.js";
 
 type EntryType = "string" | "integer" | "number" | "boolean" | "object" | "array";
 
@@ -144,6 +156,63 @@ export function precompileApplicationEnvSchemas(
   }
 }
 
+/**
+ * Register every `Telo.JsonSchema` resource's resolved schema into `validator`,
+ * ahead of the contract warm below.
+ *
+ * A contract declared as `{kind: Telo.JsonSchema, schema: {$ref: "telo:m/X"}}`
+ * — what `oauth-client` and `vector-store` write — is compiled at runtime from
+ * the schema registered under that id, reached by following the alias. With no
+ * types registered the warm follows it to the `$ref` wrapper itself, AJV refuses
+ * the unresolvable reference, and the entry is silently not baked while the
+ * runtime goes on compiling something else: a guaranteed miss for exactly the
+ * modules that declare their shapes once and reference them.
+ *
+ * Runs the REAL type controller rather than re-deriving registration here. The
+ * three names a type registers under, the canonical `telo:` id and the `extends`
+ * merge are its rules; a second implementation would drift into baking schemas
+ * under keys the runtime never asks for — the failure this whole pass exists to
+ * remove. The loop mirrors the kernel's multi-pass init (`create` returns null
+ * while a parent type is unregistered) and stops as soon as a pass registers
+ * nothing new, so an unresolvable parent ends it instead of spinning.
+ *
+ * The deprecated `Type.JsonSchema` is not warmed: it is a module kind with its
+ * own controller, and reaching for this one would be assuming the two stayed
+ * identical.
+ */
+export async function precompileTypeSchemas(
+  manifests: Array<Record<string, any>>,
+  validator: SchemaValidator,
+): Promise<void> {
+  const ctx = {
+    lookupSchema: (name: string) => validator.getSchema(name),
+    registerSchema: (name: string, schema: object) => validator.addSchema(name, schema),
+    registerTypeRules: (name: string, rules: TypeRule[]) => validator.addTypeRules(name, rules),
+  } as unknown as ResourceContext;
+
+  let pending = manifests.filter(
+    (m) =>
+      m?.kind === "Telo.JsonSchema" &&
+      m.schema &&
+      typeof m.metadata?.name === "string" &&
+      typeof m.metadata?.module === "string",
+  );
+  while (pending.length > 0) {
+    const deferred: Array<Record<string, any>> = [];
+    for (const m of pending) {
+      try {
+        if ((await createJsonSchemaType(m as unknown as ResourceManifest, ctx)) === null) {
+          deferred.push(m);
+        }
+      } catch {
+        // A broken type surfaces through analysis / runtime, not the warm pass.
+      }
+    }
+    if (deferred.length === pending.length) break;
+    pending = deferred;
+  }
+}
+
 /**
  * Build-time cache warm for resource-config validators. The runtime
  * `_createInstance` compiles the declaring `Telo.Definition`'s `schema` to
@@ -188,11 +257,31 @@ export function precompileDefinitionSchemas(
       // Broken schemas are reported by analysis / runtime, not the warm pass.
     }
   };
+  const lookup = (name: string) => validator.getSchema(name);
+  // A contract validator is compiled from the RESOLVED schema with its
+  // `x-telo-stream` properties stripped, never from the declaration — see
+  // `resolveBoundContract`. Baking the declaration instead bakes a validator for
+  // `{kind, schema}`, which no dispatch asks for. A declaration that needs the
+  // runtime type registry (a bare name, a `{kind, name}` ref) resolves to
+  // nothing here — named types register when their resources initialize, long
+  // after the warm — so it is skipped rather than baked wrong.
+  const compileContract = (declared: unknown): void => {
+    if (declared === undefined || declared === null) return;
+    try {
+      const schema = resolveTypeFieldSchema(declared, lookup);
+      if (!schema) return;
+      compile(withStreamPropertiesSkipped(schema, (ref) => lookup(ref) as any));
+    } catch {
+      // An unresolvable contract is a dispatch-time error, not a warm failure.
+    }
+  };
   for (const m of manifests) {
+    // A per-instance contract overrides the kind's, so a resource declaring its
+    // own narrowing is what the runtime compiles for that instance.
+    compileContract(m?.inputType);
+    compileContract(m?.outputType);
     if (m?.kind !== "Telo.Definition") continue;
     compile(m.schema);
-    compile(m.inputType);
-    compile(m.outputType);
     if (resolverFor && m.extends) {
       // Mirrors the runtime stamp in `resource-definition-controller`; sharing
       // `effectiveAuthorSchema` is what keeps the two keys identical.

package/src/controller-loader.ts

@@ -183,14 +183,16 @@ export class ControllerLoader {
    * Resolve a controller without importing it: pick the first candidate this
    * environment can host (same ordering + env-missing fallback as {@link load}),
    * verify it's present, and return a {@link ResolvedController} whose
-   * `importInstance` defers the actual import/eval. Used by lazy controller
-   * loading so a `Telo.Definition` fails fast at boot when its controller can't
-   * load at all, while the expensive import is paid only on first instantiation.
+   * `importInstance` defers the actual import/eval. Lazy controller loading
+   * calls this from the kind's first instantiation — never at boot — so a
+   * definition whose candidate list nothing in this environment can host
+   * registers fine and errors only when a resource of it is declared (matching
+   * the Rust kernel's deferral).
    *
    * Silent by design — no lifecycle events here; the caller emits
    * ControllerLoading/Loaded around `importInstance` so the events fire when the
-   * load actually happens. A total resolution failure throws (the boot-time
-   * fail-fast), mirroring {@link load}'s aggregated error.
+   * load actually happens. A total resolution failure throws, mirroring
+   * {@link load}'s aggregated error.
    */
   async resolve(
     purlCandidates: string[],

package/src/controllers/resource-definition/resource-definition-controller.ts

@@ -161,32 +161,39 @@ class ResourceDefinition implements ResourceInstance {
       cacheRoot: host.getCacheRoot?.(),
       log: ctx.log,
     });
-    // Eager resolve — verify the controller is hostable now (so a broken
-    // `controllers:` candidate fails fast at boot), but defer the expensive
-    // import/eval and the controller's `register()` to the kind's first
-    // instantiation. Definitions whose kind is never instantiated never import.
     // The artifact of the module that DECLARED this kind — a bundled controller
     // ships in its own module's payload, not the consumer's. It owns the pinned
     // ref and the verified layer index, so the loader picks a candidate and asks
     // it for that selector's directory rather than fetching anything itself.
     const artifact = host.getModuleArtifact?.(this.resource.metadata.source);
-    const resolved = await loader.resolve(
-      this.resource.controllers,
-      this.resource.metadata.source,
-      ctx.getControllerPolicy(),
-      artifact,
-    );
     ctx.registerDefinition(this.resource);
 
     const moduleName = this.resource.metadata.module;
     const kindName = this.resource.metadata.name;
-    // Emitted here (not in the loader) so ControllerLoading / ControllerLoaded /
-    // ControllerLoadFailed — and the import duration — surface when the load
-    // actually happens (first instantiation), with the resolved PURL + source.
+    const controllers = this.resource.controllers;
+    const source = this.resource.metadata.source;
+    const policy = ctx.getControllerPolicy();
+    // Resolution AND import are deferred to the kind's first instantiation,
+    // matching the Rust kernel: a definition whose candidate list nothing in
+    // this environment can host registers fine and errors — naming the kind —
+    // only when a resource of it is declared. That is what lets both kernels
+    // load a partially-covered module (e.g. console's stream kinds with no Rust
+    // controller) instead of rejecting it over kinds nobody uses.
+    // Lifecycle events are emitted here (not in the loader) so ControllerLoading
+    // / ControllerLoaded / ControllerLoadFailed — and the import duration —
+    // surface when the load actually happens, with the resolved PURL + source.
     host.registerLazyController(
       moduleName,
       kindName,
       async () => {
+        const resolved = await loader
+          .resolve(controllers, source, policy, artifact)
+          .catch((err) => {
+            if (err instanceof RuntimeError) {
+              throw new RuntimeError(err.code, `kind '${moduleName}.${kindName}': ${err.message}`);
+            }
+            throw err;
+          });
         await ctx.emit("ControllerLoading", { purl: resolved.purl });
         const startedAt = Date.now();
         const instance = await resolved.importInstance().catch(async (err) => {
@@ -241,6 +248,17 @@ export function register(ctx: ControllerContext): void {
 }
 
 export async function create(resource: any, ctx: ResourceContext): Promise<ResourceDefinition> {
+  // Named preflight for the one capability the schema rejects by omission: the
+  // AJV oneOf failure it produces never says WHY, and this is the mistake an
+  // author migrating a multi-kind slot is most likely to make.
+  if (resource?.capability === "Telo.Executable") {
+    throw new Error(
+      `Invalid ResourceDefinition "${resource.metadata?.name}": capability 'Telo.Executable' ` +
+        `is an x-telo-ref slot constraint (the parent Telo.Invocable and Telo.Runnable ` +
+        `extend), not a declarable lifecycle role. Declare 'Telo.Invocable' (invoke) or ` +
+        `'Telo.Runnable' (run) instead.`,
+    );
+  }
   // Validate incoming resource definition against schema
   if (!validateResourceDefinition(resource)) {
     throw new Error(

package/src/evaluation-context.ts

@@ -1,6 +1,7 @@
 import { AsyncLocalStorage } from "node:async_hooks";
 import { formatSpanCounter } from "./logging/span-id.js";
 import {
+  deriveContext,
   getRefIdentity,
   isCompiledValue,
   isInvokeError,
@@ -263,6 +264,15 @@ export function ambientInvokeContext(): InvokeContext | undefined {
   return cancellationStore.getStore();
 }
 
+/**
+ * Establish `ctx` as the ambient invocation context for the duration of `fn`.
+ * The seam `withZone` uses to make an opened zone ambient without owning the
+ * store — the store itself stays kernel-internal, never on the SDK surface.
+ */
+export function runWithAmbientContext<T>(ctx: InvokeContext, fn: () => T): T {
+  return cancellationStore.run(ctx, fn);
+}
+
 /** Marks a scope built by {@link EvaluationContext.bindScope}, whose properties
  *  are getters. `expandWith` merges such a scope by descriptor rather than by
  *  value — reading the value here is what a lazy binding must not do. */
@@ -1189,11 +1199,13 @@ export class EvaluationContext implements IEvaluationContext {
         outcome,
         phase === "end" && rootScope ? { ...detail, context: rootScope } : detail,
       );
-    // When tracing, a fresh context carries the new id down the tree so nested
+    // When tracing, a derived context carries the new id down the tree so nested
     // invokes read it as their parent; it is never `=== ambient`, so the call
-    // always (re)establishes the ALS scope.
+    // always (re)establishes the ALS scope. Derived, never a fresh literal: a
+    // literal drops every field it does not restate (`zones`), making
+    // propagation differ between tracing on and off.
     const invokeCtx: InvokeContext = tracing
-      ? { cancellation: token, invocationId, parentInvocationId, traceId }
+      ? deriveContext(baseCtx, { invocationId, parentInvocationId, traceId })
       : baseCtx;
 
     // Pre-dispatch gate: a sub-invoke reached after the tree was cancelled is
@@ -1391,12 +1403,14 @@ export class EvaluationContext implements IEvaluationContext {
       );
 
     await this.emit(`${opts.ref.name}.Requesting`, payload("start", undefined));
-    const context: InvokeContext = {
-      cancellation: ctx.cancellation,
+    // Derived so the span context keeps whatever `base` carries beyond the span
+    // ids — with tracing off this method returns `base` unchanged, and tracing
+    // must not change what propagates.
+    const context: InvokeContext = deriveContext(ctx, {
       invocationId: spanId,
       parentInvocationId: parentSpanId,
       traceId,
-    };
+    });
     let settled = false;
     return {
       context,
@@ -1460,7 +1474,7 @@ export class EvaluationContext implements IEvaluationContext {
         phase === "end" && rootScope ? { ...detail, context: rootScope } : detail,
       );
     const invokeCtx: InvokeContext = tracing
-      ? { cancellation: token, invocationId, parentInvocationId, traceId }
+      ? deriveContext(baseCtx, { invocationId, parentInvocationId, traceId })
       : baseCtx;
 
     // Refuse a target reached after the boot run was cancelled.