@telorun/kernel 0.30.2 → 0.32.0

package/dist/tracing.d.ts

@@ -0,0 +1,19 @@
+import type { Tracer } from "@telorun/sdk";
+/**
+ * The kernel's invocation tracer: a monotonic counter plus the `enabled` gate a
+ * debug consumer flips on attach (`Kernel.setTracing`). One instance per kernel,
+ * shared by reference across the whole context tree, so invocation ids are unique
+ * within the run and `enabled` toggles everywhere at once.
+ *
+ * When `enabled` is `false` (the default), `invoke` skips id minting and the extra
+ * ALS scope entirely — tracing costs nothing until someone is watching.
+ */
+export declare class KernelTracer implements Tracer {
+    #private;
+    enabled: boolean;
+    next(): number;
+    /** A fresh OTel-compatible 16-byte hex trace id. Globally unique, so a trace
+     *  stays identifiable once it crosses process boundaries. */
+    newTraceId(): string;
+}
+//# sourceMappingURL=tracing.d.ts.map

package/dist/tracing.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tracing.d.ts","sourceRoot":"","sources":["../src/tracing.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,cAAc,CAAC;AAE3C;;;;;;;;GAQG;AACH,qBAAa,YAAa,YAAW,MAAM;;IACzC,OAAO,UAAS;IAGhB,IAAI,IAAI,MAAM;IAKd;iEAC6D;IAC7D,UAAU,IAAI,MAAM;CAGrB"}

package/dist/tracing.js

@@ -0,0 +1,39 @@
+var __classPrivateFieldGet = (this && this.__classPrivateFieldGet) || function (receiver, state, kind, f) {
+    if (kind === "a" && !f) throw new TypeError("Private accessor was defined without a getter");
+    if (typeof state === "function" ? receiver !== state || !f : !state.has(receiver)) throw new TypeError("Cannot read private member from an object whose class did not declare it");
+    return kind === "m" ? f : kind === "a" ? f.call(receiver) : f ? f.value : state.get(receiver);
+};
+var __classPrivateFieldSet = (this && this.__classPrivateFieldSet) || function (receiver, state, value, kind, f) {
+    if (kind === "m") throw new TypeError("Private method is not writable");
+    if (kind === "a" && !f) throw new TypeError("Private accessor was defined without a setter");
+    if (typeof state === "function" ? receiver !== state || !f : !state.has(receiver)) throw new TypeError("Cannot write private member to an object whose class did not declare it");
+    return (kind === "a" ? f.call(receiver, value) : f ? f.value = value : state.set(receiver, value)), value;
+};
+var _KernelTracer_next;
+import { randomBytes } from "node:crypto";
+/**
+ * The kernel's invocation tracer: a monotonic counter plus the `enabled` gate a
+ * debug consumer flips on attach (`Kernel.setTracing`). One instance per kernel,
+ * shared by reference across the whole context tree, so invocation ids are unique
+ * within the run and `enabled` toggles everywhere at once.
+ *
+ * When `enabled` is `false` (the default), `invoke` skips id minting and the extra
+ * ALS scope entirely — tracing costs nothing until someone is watching.
+ */
+export class KernelTracer {
+    constructor() {
+        this.enabled = false;
+        _KernelTracer_next.set(this, 0);
+    }
+    next() {
+        __classPrivateFieldSet(this, _KernelTracer_next, __classPrivateFieldGet(this, _KernelTracer_next, "f") + 1, "f");
+        return __classPrivateFieldGet(this, _KernelTracer_next, "f");
+    }
+    /** A fresh OTel-compatible 16-byte hex trace id. Globally unique, so a trace
+     *  stays identifiable once it crosses process boundaries. */
+    newTraceId() {
+        return randomBytes(16).toString("hex");
+    }
+}
+_KernelTracer_next = new WeakMap();
+//# sourceMappingURL=tracing.js.map

package/dist/tracing.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tracing.js","sourceRoot":"","sources":["../src/tracing.ts"],"names":[],"mappings":";;;;;;;;;;;;AAAA,OAAO,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAG1C;;;;;;;;GAQG;AACH,MAAM,OAAO,YAAY;IAAzB;QACE,YAAO,GAAG,KAAK,CAAC;QAChB,6BAAQ,CAAC,EAAC;IAYZ,CAAC;IAVC,IAAI;QACF,yGAAc,CAAC,MAAA,CAAC;QAChB,OAAO,uBAAA,IAAI,0BAAM,CAAC;IACpB,CAAC;IAED;iEAC6D;IAC7D,UAAU;QACR,OAAO,WAAW,CAAC,EAAE,CAAC,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC;IACzC,CAAC;CACF"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@telorun/kernel",
-  "version": "0.30.2",
+  "version": "0.32.0",
   "description": "Telo Runtime - A lightweight, polyglot execution host.",
   "keywords": [
     "telo",
@@ -59,7 +59,7 @@
     "@types/node": "^20.0.0",
     "typescript": "^5.0.0",
     "vitest": "^2.1.8",
-    "@telorun/sdk": "0.26.0"
+    "@telorun/sdk": "0.32.0"
   },
   "optionalDependencies": {
     "esbuild": "^0.28.1"

package/src/dependency-injection.ts

@@ -1,4 +1,4 @@
-import { ResourceInstance, ResourceManifest, RuntimeError } from "@telorun/sdk";
+import { ResourceInstance, ResourceManifest, RuntimeError, stampRefIdentity } from "@telorun/sdk";
 
 /**
  * Walks `resource` following `fieldPath` (dot notation, `[]` = array traversal,
@@ -29,6 +29,12 @@ export function injectAtPath(
         `Cross-module reference '${alias}.${String(ref.name)}' is not available yet (import not initialized)`,
       );
     }
+    // Tag the instance with the kind+name it resolved from, so a consumer that
+    // holds only the bare instance (an invoke-step target) can dispatch it
+    // through the traced chokepoint rather than calling `.invoke()` directly.
+    if (instance && typeof ref.kind === "string" && typeof ref.name === "string") {
+      stampRefIdentity(instance, ref.kind, ref.name);
+    }
     return instance;
   }
 

package/src/evaluation-context.ts

@@ -10,6 +10,8 @@ import {
   type InstanceFactory,
   type InvokeContext,
   type LifecycleState,
+  type OpenSpan,
+  type OpenSpanOptions,
   type PreInitHook,
   type ResourceDefinition,
   type ResourceInstance,
@@ -17,6 +19,7 @@ import {
   type RuntimeDiagnostic,
   type ScopeContext,
   type ScopeHandle,
+  type Tracer,
 } from "@telorun/sdk";
 import { RuntimeError } from "@telorun/sdk";
 
@@ -179,6 +182,12 @@ export class EvaluationContext implements IEvaluationContext {
    */
   getDefinition?: (kind: string) => ResourceDefinition | undefined;
 
+  /**
+   * Per-kernel invocation tracer. Set by the kernel on the root context and
+   * propagated through spawnChild(); gates invocation-id minting in runInvoke().
+   */
+  tracer?: Tracer;
+
   constructor(
     readonly source: string,
     context: Record<string, unknown>,
@@ -259,6 +268,9 @@ export class EvaluationContext implements IEvaluationContext {
     if (this.getDefinition && !child.getDefinition) {
       child.getDefinition = this.getDefinition;
     }
+    if (this.tracer && !child.tracer) {
+      child.tracer = this.tracer;
+    }
     return child;
   }
 
@@ -594,6 +606,50 @@ export class EvaluationContext implements IEvaluationContext {
     return this.runInvoke(kind, name, instance, inputs, ctx);
   }
 
+  /**
+   * Build the structured trace payload every capability dispatch emits. The
+   * event *name* stays human-meaningful (`<name>.Invoked`) for bus subscribers;
+   * everything a debug consumer needs to rebuild the call tree rides here, so the
+   * consumer never parses the dotted name. `spanId`/`parentSpanId` are the
+   * tracer's `invocationId`/`parentInvocationId` (present only while tracing);
+   * `ref` carries the kind+name the name no longer encodes; `detail` is the
+   * per-capability data (inputs/outputs, error fields, cancellation reason).
+   */
+  /**
+   * A redacted snapshot of the CEL root scope a debug consumer should see for a
+   * trace — `variables`, masked `secrets`, resource `snapshots`, `ports`. Attached
+   * to a trace's *root* span so the consumer can inspect what data the execution
+   * could reference (beyond its own inputs/outputs). Only a `ModuleContext` owns a
+   * root scope; child scopes return undefined. Host `env` is deliberately omitted
+   * (it is the raw process environment — too broad/sensitive to dump).
+   */
+  protected traceRootScope(): Record<string, unknown> | undefined {
+    return undefined;
+  }
+
+  protected tracePayload(
+    kind: string,
+    name: string,
+    spanId: number | undefined,
+    parentSpanId: number | undefined,
+    traceId: string | undefined,
+    capability: "invoke" | "run" | "provide" | "request",
+    phase: "start" | "end",
+    outcome: "ok" | "failed" | "rejected" | "cancelled" | undefined,
+    detail: Record<string, unknown>,
+  ): Record<string, unknown> {
+    return {
+      traceId,
+      spanId,
+      parentSpanId,
+      capability,
+      phase,
+      ...(outcome !== undefined ? { outcome } : {}),
+      ref: { kind, name },
+      ...detail,
+    };
+  }
+
   private async runInvoke<TInputs>(
     kind: string,
     name: string,
@@ -605,19 +661,64 @@ export class EvaluationContext implements IEvaluationContext {
     // tree token; otherwise open a fresh, never-cancellable scope. The token
     // reaches the controller only as the explicit argument below.
     const ambient = cancellationStore.getStore();
-    const invokeCtx = ctx ?? ambient ?? UNCANCELLABLE_CONTEXT;
-    const token = invokeCtx.cancellation;
+    const baseCtx = ctx ?? ambient ?? UNCANCELLABLE_CONTEXT;
+    const token = baseCtx.cancellation;
+
+    // Tracing gate (a debug consumer is attached): mint a monotonic id for this
+    // invocation, parent it to the ambient one, and ride both in every event's
+    // payload so the consumer can rebuild the call tree. Off by default —
+    // `invokeCtx` stays `baseCtx` and the fast `=== ambient` skip is preserved.
+    const tracing = this.tracer?.enabled === true;
+    const invocationId = tracing ? this.tracer!.next() : undefined;
+    // Parent precedence mirrors the token: an explicit seed `ctx` wins, then the
+    // ambient (ALS) invocation. A caller threading its own `ctx.invocationId` thus
+    // has it honored as the parent, not silently dropped for the ALS value.
+    const parentInvocationId = ctx?.invocationId ?? ambient?.invocationId;
+    // Inherit the trace from the parent (explicit ctx wins, then ambient); mint a
+    // fresh one only at a root. Carried on every span so an OTel exporter groups
+    // the trace without walking the parent chain.
+    const traceId = tracing
+      ? (ctx?.traceId ?? ambient?.traceId ?? this.tracer!.newTraceId())
+      : undefined;
+    // Capture the root CEL scope once, on the trace's root span's terminal event.
+    const rootScope = tracing && parentInvocationId === undefined ? this.traceRootScope() : undefined;
+    const span = (
+      phase: "start" | "end",
+      outcome: "ok" | "failed" | "rejected" | "cancelled" | undefined,
+      detail: Record<string, unknown>,
+    ) =>
+      this.tracePayload(
+        kind,
+        name,
+        invocationId,
+        parentInvocationId,
+        traceId,
+        "invoke",
+        phase,
+        outcome,
+        phase === "end" && rootScope ? { ...detail, context: rootScope } : detail,
+      );
+    // When tracing, a fresh 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.
+    const invokeCtx: InvokeContext = tracing
+      ? { cancellation: token, invocationId, parentInvocationId, traceId }
+      : baseCtx;
 
     // Pre-dispatch gate: a sub-invoke reached after the tree was cancelled is
     // refused without ever touching the controller.
     if (token.isCancelled) {
-      await this.emit(`${kind}.${name}.InvokeCancelled`, { reason: token.reason });
+      await this.emit(`${name}.InvokeCancelled`, span("end", "cancelled", { inputs, reason: token.reason }));
       throw new RuntimeError(
         "ERR_INVOKE_CANCELLED",
         `Invoke ${kind}.${name} was cancelled${token.reason ? `: ${token.reason}` : ""}`,
       );
     }
 
+    // Start span — only under tracing, so non-traced behaviour stays exactly
+    // one terminal event per call (subscribers to `<name>.Invoked` are unaffected).
+    if (tracing) await this.emit(`${name}.Invoking`, span("start", undefined, { inputs }));
+
     try {
       // Only (re)establish the ALS scope when the token differs from the ambient
       // one — nested invokes that inherited it skip the redundant `run`.
@@ -633,35 +734,35 @@ export class EvaluationContext implements IEvaluationContext {
       const outputs = await (invokeCtx === ambient
         ? call()
         : cancellationStore.run(invokeCtx, call));
-      await this.emit(`${kind}.${name}.Invoked`, { outputs });
+      await this.emit(`${name}.Invoked`, span("end", "ok", { inputs, outputs }));
       return outputs;
     } catch (err) {
       // Cooperative mid-flight cancellation (`throwIfCancelled`) joins the same
       // observable event family rather than masquerading as a rejection/failure.
       if (isCancellationError(err)) {
         const reason = err instanceof Error ? err.message : String(err);
-        await this.emit(`${kind}.${name}.InvokeCancelled`, { reason });
+        await this.emit(`${name}.InvokeCancelled`, span("end", "cancelled", { inputs, reason }));
         throw err;
       }
       if (isInvokeError(err)) {
-        const payload = { code: err.code, message: err.message, data: err.data };
-        await this.emit(`${kind}.${name}.InvokeRejected`, payload);
+        const detail = { inputs, code: err.code, message: err.message, data: err.data };
+        await this.emit(`${name}.InvokeRejected`, span("end", "rejected", detail));
         const declaredCodes = this.getDeclaredThrowCodes(kind);
         if (declaredCodes && !declaredCodes.has(err.code)) {
-          await this.emit(`${kind}.${name}.InvokeRejected.Undeclared`, payload);
+          await this.emit(`${name}.InvokeRejected.Undeclared`, span("end", "rejected", detail));
         }
         throw err;
       }
       if (err instanceof Error) {
-        await this.emit(`${kind}.${name}.InvokeFailed`, {
-          name: err.name,
-          message: err.message,
-        });
+        await this.emit(
+          `${name}.InvokeFailed`,
+          span("end", "failed", { inputs, name: err.name, message: err.message }),
+        );
       } else {
-        await this.emit(`${kind}.${name}.InvokeFailed`, {
-          name: "UnknownError",
-          message: String(err),
-        });
+        await this.emit(
+          `${name}.InvokeFailed`,
+          span("end", "failed", { inputs, name: "UnknownError", message: String(err) }),
+        );
       }
       // Already enriched at an inner invoke: keep the innermost (most
       // specific) resource as the failure location.
@@ -682,6 +783,26 @@ export class EvaluationContext implements IEvaluationContext {
     }
   }
 
+  /**
+   * The declared capability of a kind, or undefined if unknown. Definitions are
+   * keyed by their canonical `<module>.<Kind>`, but a resource carries the alias
+   * kind it was written with (`Http.Server`), so resolve the alias first.
+   * Best-effort: `resolveKind` exists only on a `ModuleContext` and throws for
+   * unqualified / ungated kinds, so guard and fall back to the raw kind.
+   */
+  /** Resolve an alias kind (`Http.Server`) to its canonical `<module>.<Kind>`.
+   *  Only a `ModuleContext` carries the import-alias table; the base returns the
+   *  kind unchanged. A typed seam (overridden in `ModuleContext`), matching the
+   *  `traceRootScope()` pattern, rather than reaching across the boundary. */
+  protected resolveKindSafe(kind: string): string {
+    return kind;
+  }
+
+  private capabilityOf(kind: string): string | undefined {
+    const resolved = this.resolveKindSafe(kind);
+    return this.getDefinition?.(resolved)?.capability ?? this.getDefinition?.(kind)?.capability;
+  }
+
   private getDeclaredThrowCodes(kind: string): Set<string> | null {
     if (!this.getDefinition) return null;
     const def = this.getDefinition(kind);
@@ -700,28 +821,178 @@ export class EvaluationContext implements IEvaluationContext {
 
   async run(name: string, ctx?: InvokeContext): Promise<void> {
     const entry = this.resourceInstances.get(name);
-    if (entry && typeof entry.instance.run === "function") {
-      const ambient = cancellationStore.getStore();
-      const invokeCtx = ctx ?? ambient ?? UNCANCELLABLE_CONTEXT;
-      const token = invokeCtx.cancellation;
-      // Refuse a target reached after the boot run was cancelled.
-      if (token.isCancelled) {
-        await this.emit(`${entry.resource.kind}.${name}.RunCancelled`, { reason: token.reason });
-        throw new RuntimeError(
-          "ERR_INVOKE_CANCELLED",
-          `Run ${entry.resource.kind}.${name} was cancelled${token.reason ? `: ${token.reason}` : ""}`,
+    if (!(entry && typeof entry.instance.run === "function")) {
+      throw new RuntimeError(
+        "ERR_RESOURCE_NOT_RUNNABLE",
+        `Resource ${name} is not runnable or not found. Available resources: ${[...this.resourceInstances.keys()].join(", ")}`,
+      );
+    }
+    return this.runInstance(entry.resource.kind as string, name, entry.instance, ctx);
+  }
+
+  /**
+   * Like run(), but the caller has already resolved the instance (e.g. a
+   * Phase-5-injected `!ref` boot target). Shares the single span-emitting path so
+   * a pre-resolved runnable is instrumented exactly like a by-name dispatch
+   * instead of escaping the chokepoint with a direct `instance.run()` call.
+   */
+  async runResolved(
+    kind: string,
+    name: string,
+    instance: ResourceInstance,
+    ctx?: InvokeContext,
+  ): Promise<void> {
+    if (typeof instance.run !== "function") {
+      throw new RuntimeError(
+        "ERR_RESOURCE_NOT_RUNNABLE",
+        `Resource ${kind}.${name} does not have a run method`,
+      );
+    }
+    return this.runInstance(kind, name, instance, ctx);
+  }
+
+  /**
+   * Open a trace span for an inbound boundary (an HTTP request). Mints a span
+   * that roots a fresh trace (or continues `opts.inbound`), emits its `start`,
+   * and returns a child context to thread into `invokeResolved` so the handler
+   * nests under it. A no-op pass-through when tracing is off.
+   */
+  async openSpan(base: InvokeContext | undefined, opts: OpenSpanOptions): Promise<OpenSpan> {
+    const ctx = base ?? UNCANCELLABLE_CONTEXT;
+    if (this.tracer?.enabled !== true) {
+      return { context: ctx, settle: async () => {} };
+    }
+    const spanId = this.tracer.next();
+    const traceId = opts.inbound?.traceId ?? this.tracer.newTraceId();
+    const parentSpanId = opts.inbound?.parentSpanId;
+    // A root request span (not continuing an upstream trace) carries the root scope.
+    const rootScope = parentSpanId === undefined ? this.traceRootScope() : undefined;
+    const detail = {
+      ...(opts.label !== undefined ? { label: opts.label } : {}),
+      ...(opts.attributes !== undefined ? { attributes: opts.attributes } : {}),
+    };
+    const payload = (
+      phase: "start" | "end",
+      outcome: "ok" | "failed" | "rejected" | "cancelled" | undefined,
+      extra: Record<string, unknown> = {},
+    ) =>
+      this.tracePayload(
+        opts.ref.kind,
+        opts.ref.name,
+        spanId,
+        parentSpanId,
+        traceId,
+        "request",
+        phase,
+        outcome,
+        { ...detail, ...extra },
+      );
+
+    await this.emit(`${opts.ref.name}.Requesting`, payload("start", undefined));
+    const context: InvokeContext = {
+      cancellation: ctx.cancellation,
+      invocationId: spanId,
+      parentInvocationId: parentSpanId,
+      traceId,
+    };
+    let settled = false;
+    return {
+      context,
+      settle: async (outcome, extra) => {
+        if (settled) return;
+        settled = true;
+        await this.emit(
+          `${opts.ref.name}.Request`,
+          payload("end", outcome, rootScope ? { ...extra, context: rootScope } : extra),
         );
+      },
+    };
+  }
+
+  private async runInstance(
+    kind: string,
+    name: string,
+    instance: ResourceInstance,
+    ctx?: InvokeContext,
+  ): Promise<void> {
+    const ambient = cancellationStore.getStore();
+    const baseCtx = ctx ?? ambient ?? UNCANCELLABLE_CONTEXT;
+    const token = baseCtx.cancellation;
+
+    // A long-lived Service's `run()` is not a one-shot dispatch: it stays pending
+    // for the process lifetime, so wrapping it in the cancellation/trace ALS scope
+    // would leak that scope onto every async resource the service creates (e.g. an
+    // HTTP server's listening socket → every inbound request callback). Such a
+    // service must NOT establish an ambient: its token reaches it via the explicit
+    // `run(invokeCtx)` argument (how it observes shutdown), and its externally
+    // triggered work then starts with a clean ambient — separate traces, no
+    // inherited cancellation. Runnables (one-shot, e.g. `Run.Sequence`) keep the
+    // ALS scope so their steps nest and inherit cancellation.
+    const isService = this.capabilityOf(kind) === "Telo.Service";
+
+    // Span instrumentation mirrors `runInvoke` — minting an id here makes
+    // Runnables (a `Run.Sequence` boot target) appear in the trace and re-parents
+    // their nested invokes. A long-lived Service emits only the `start` span (its
+    // `run()` resolves at teardown), the "running" signal a debug consumer wants.
+    const tracing = this.tracer?.enabled === true;
+    const invocationId = tracing ? this.tracer!.next() : undefined;
+    const parentInvocationId = ctx?.invocationId ?? ambient?.invocationId;
+    const traceId = tracing
+      ? (ctx?.traceId ?? ambient?.traceId ?? this.tracer!.newTraceId())
+      : undefined;
+    const rootScope = tracing && parentInvocationId === undefined ? this.traceRootScope() : undefined;
+    const span = (
+      phase: "start" | "end",
+      outcome: "ok" | "failed" | "cancelled" | undefined,
+      detail: Record<string, unknown>,
+    ) =>
+      this.tracePayload(
+        kind,
+        name,
+        invocationId,
+        parentInvocationId,
+        traceId,
+        "run",
+        phase,
+        outcome,
+        phase === "end" && rootScope ? { ...detail, context: rootScope } : detail,
+      );
+    const invokeCtx: InvokeContext = tracing
+      ? { cancellation: token, invocationId, parentInvocationId, traceId }
+      : baseCtx;
+
+    // Refuse a target reached after the boot run was cancelled.
+    if (token.isCancelled) {
+      await this.emit(`${name}.RunCancelled`, span("end", "cancelled", { reason: token.reason }));
+      throw new RuntimeError(
+        "ERR_INVOKE_CANCELLED",
+        `Run ${kind}.${name} was cancelled${token.reason ? `: ${token.reason}` : ""}`,
+      );
+    }
+
+    if (tracing) await this.emit(`${name}.Running`, span("start", undefined, {}));
+
+    try {
+      // Runnable: run inside the ALS scope so nested invokes inherit the token and
+      // trace id (skip the redundant `run` when the token is already ambient).
+      // Service: call directly with the explicit context and NO ambient scope, so
+      // its long-lived async work does not capture this scope.
+      const call = () => (instance.run as (c?: InvokeContext) => Promise<void>)(invokeCtx);
+      await (isService || invokeCtx === ambient ? call() : cancellationStore.run(invokeCtx, call));
+      await this.emit(`${name}.Run`, span("end", "ok", {}));
+    } catch (err) {
+      if (isCancellationError(err)) {
+        const reason = err instanceof Error ? err.message : String(err);
+        await this.emit(`${name}.RunCancelled`, span("end", "cancelled", { reason }));
+        throw err;
       }
-      // Run inside the scope so the runnable's nested invokes inherit the token,
-      // and pass it explicitly so long-lived targets can observe cancellation.
-      // Skip the redundant `run` when the token is already the ambient one.
-      const call = () => (entry.instance.run as (c?: InvokeContext) => Promise<void>)(invokeCtx);
-      return invokeCtx === ambient ? call() : cancellationStore.run(invokeCtx, call);
+      const detail =
+        err instanceof Error
+          ? { name: err.name, message: err.message }
+          : { name: "UnknownError", message: String(err) };
+      await this.emit(`${name}.RunFailed`, span("end", "failed", detail));
+      throw err;
     }
-    throw new RuntimeError(
-      "ERR_RESOURCE_NOT_RUNNABLE",
-      `Resource ${name} is not runnable or not found. Available resources: ${[...this.resourceInstances.keys()].join(", ")}`,
-    );
   }
 
   /**

package/src/events.ts

@@ -70,6 +70,11 @@ export class EventBus {
   }
 
   async emit(event: string, payload?: any, metadata?: any): Promise<void> {
+    // O(1) idle short-circuit: with no subscriber at all — the common case when
+    // no debug consumer is attached — emitting costs a single integer compare,
+    // no map walk and no allocation. This is what keeps routing every dispatch
+    // through the instrumented chokepoint effectively free when nobody listens.
+    if (this.handlers.size === 0) return;
     const handlers: EventHandler[] = [];
     for (const [pattern, set] of this.handlers.entries()) {
       if (!this.matchesPattern(pattern, event)) {

package/src/kernel.ts

@@ -30,6 +30,7 @@ import {
 import { parseArgs } from "util";
 import { ControllerRegistry } from "./controller-registry.js";
 import { EventBus } from "./events.js";
+import { KernelTracer } from "./tracing.js";
 import { ModuleContext } from "./module-context.js";
 import { ResourceContextImpl } from "./resource-context.js";
 import { nodeCelHandlers } from "./cel-handlers.js";
@@ -104,6 +105,7 @@ export class Kernel implements IKernel {
   private readonly registry = new AnalysisRegistry();
   private controllers: ControllerRegistry = new ControllerRegistry();
   private eventBus: EventBus = new EventBus();
+  private readonly tracer = new KernelTracer();
 
   private holdCount = 0;
   private idleResolvers: Array<() => void> = [];
@@ -130,6 +132,9 @@ export class Kernel implements IKernel {
   // SIGINT (before runTargets) still has a source to cancel, which the run then
   // observes via the pre-dispatch gate.
   private _bootCancellation?: CancellationSource;
+  // Root application name — labels the boot `targets` trace span so the app
+  // appears as the trace root with its targets nested beneath.
+  private _appName?: string;
 
   readonly stdin: NodeJS.ReadableStream;
   readonly stdout: NodeJS.WritableStream;
@@ -317,9 +322,10 @@ export class Kernel implements IKernel {
       {},
       [],
       this._createInstance.bind(this),
-      (event, payload) => this.eventBus.emit(event, payload),
+      (event, payload, metadata) => this.eventBus.emit(event, payload, metadata),
       this.env,
     );
+    this.rootContext.tracer = this.tracer;
     // Initialize built-in Runtime definitions first
     await this.loadBuiltinDefinitions();
 
@@ -508,6 +514,7 @@ export class Kernel implements IKernel {
         this.rootContext.setTargets(rawTargets as BootTarget[]);
         if (manifest.kind === "Telo.Application") {
           rootApplicationManifest = manifest;
+          this._appName = (manifest.metadata as { name?: string } | undefined)?.name;
         }
       }
       this.rootContext.registerManifest(manifest);
@@ -635,7 +642,7 @@ export class Kernel implements IKernel {
     this._targetsRan = true;
 
     await this.eventBus.emit("Kernel.Starting", {});
-    await this.rootContext.runTargets(this.bootCancellation.context);
+    await this.rootContext.runTargets(this.bootCancellation.context, this._appName);
     await this.eventBus.emit("Kernel.Started", {});
   }
 
@@ -817,6 +824,16 @@ export class Kernel implements IKernel {
     return this.eventBus.hasHandlers(event);
   }
 
+  /**
+   * Turn invocation tracing on/off. A debug consumer (the CLI debug server) flips
+   * it on while attached: invocations then mint monotonic ids and emit
+   * `invocationId` / `parentInvocationId` in event metadata, so the consumer can
+   * rebuild the call tree. Off by default — zero overhead when nobody is watching.
+   */
+  setTracing(enabled: boolean): void {
+    this.tracer.enabled = enabled;
+  }
+
   on(event: string, handler: (event: RuntimeEvent) => void | Promise<void>): void {
     this.eventBus.on(event, handler);
   }