@telorun/kernel 0.31.0 → 0.33.0

package/dist/dependency-injection.d.ts

@@ -6,5 +6,5 @@ import { ResourceInstance, ResourceManifest } from "@telorun/sdk";
  * returned live ResourceInstance. Values where getInstance returns undefined are
  * left unchanged.
  */
-export declare function injectAtPath(resource: ResourceManifest, fieldPath: string, getInstance: (name: string, alias?: string) => ResourceInstance | undefined): void;
+export declare function injectAtPath(resource: ResourceManifest, fieldPath: string, getInstance: (name: string, alias?: string) => ResourceInstance | undefined, isPending?: (name: string) => boolean): void;
 //# sourceMappingURL=dependency-injection.d.ts.map

package/dist/dependency-injection.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"dependency-injection.d.ts","sourceRoot":"","sources":["../src/dependency-injection.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,gBAAgB,EAAE,gBAAgB,EAAgB,MAAM,cAAc,CAAC;AAEhF;;;;;;GAMG;AACH,wBAAgB,YAAY,CAC1B,QAAQ,EAAE,gBAAgB,EAC1B,SAAS,EAAE,MAAM,EACjB,WAAW,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,MAAM,KAAK,gBAAgB,GAAG,SAAS,GAC1E,IAAI,CAkFN"}
+{"version":3,"file":"dependency-injection.d.ts","sourceRoot":"","sources":["../src/dependency-injection.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,gBAAgB,EAAE,gBAAgB,EAAkC,MAAM,cAAc,CAAC;AAElG;;;;;;GAMG;AACH,wBAAgB,YAAY,CAC1B,QAAQ,EAAE,gBAAgB,EAC1B,SAAS,EAAE,MAAM,EACjB,WAAW,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,MAAM,KAAK,gBAAgB,GAAG,SAAS,EAC3E,SAAS,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,GACpC,IAAI,CAmGN"}

package/dist/dependency-injection.js

@@ -1,4 +1,4 @@
-import { RuntimeError } from "@telorun/sdk";
+import { RuntimeError, stampRefIdentity } from "@telorun/sdk";
 /**
  * Walks `resource` following `fieldPath` (dot notation, `[]` = array traversal,
  * `{}` = map traversal). For each leaf value that looks like a {kind, name}
@@ -6,20 +6,34 @@ import { RuntimeError } from "@telorun/sdk";
  * returned live ResourceInstance. Values where getInstance returns undefined are
  * left unchanged.
  */
-export function injectAtPath(resource, fieldPath, getInstance) {
+export function injectAtPath(resource, fieldPath, getInstance, isPending) {
     const parts = fieldPath.split(".");
     // Resolve a {kind, name, alias?} reference to its live instance. A non-`Self` alias is a
     // cross-module reference into an import's published exports; if that import hasn't
     // finished init() yet the instance is absent, so we throw to defer this resource to a
     // later pass of the multi-pass init loop (which catches and retries) rather than leaving
-    // the ref unresolved. Local refs (no alias) that miss are left for topo ordering / later
-    // diagnostics, matching prior behaviour.
+    // the ref unresolved. A LOCAL ref (no alias) that names a resource registered in this
+    // context but not yet initialized is deferred the same way — create-success order does
+    // not always match init order (e.g. a globally-registered controller lets a dependent
+    // create before its dependency's controller has loaded), so injection can run before the
+    // dependency inits. Without this defer the slot would be left unresolved and surface as a
+    // runtime ERR_RESOURCE_NOT_INVOKABLE. A local ref that names nothing pending is left as-is
+    // (topo ordering / later diagnostics), matching prior behaviour.
     function resolveInto(ref) {
         const alias = typeof ref.alias === "string" ? ref.alias : undefined;
         const instance = getInstance(ref.name, alias);
         if (!instance && alias && alias !== "Self") {
             throw new RuntimeError("ERR_CROSS_MODULE_REF_PENDING", `Cross-module reference '${alias}.${String(ref.name)}' is not available yet (import not initialized)`);
         }
+        if (!instance && (!alias || alias === "Self") && isPending?.(ref.name)) {
+            throw new RuntimeError("ERR_LOCAL_REF_PENDING", `Local reference '${String(ref.name)}' is registered but not initialized yet (deferring to a later init pass)`);
+        }
+        // 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;
     }
     function traverse(obj, partsLeft) {

package/dist/dependency-injection.js.map

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

package/dist/evaluation-context.d.ts

@@ -1,4 +1,4 @@
-import { resourceKey, type EvaluationContext as IEvaluationContext, type EmitEvent, type InstanceFactory, type InvokeContext, type LifecycleState, type PreInitHook, type ResourceDefinition, type ResourceInstance, type ResourceManifest, type ScopeHandle, type Tracer } from "@telorun/sdk";
+import { resourceKey, type EvaluationContext as IEvaluationContext, type EmitEvent, type InstanceFactory, type InvokeContext, type LifecycleState, type OpenSpan, type OpenSpanOptions, type PreInitHook, type ResourceDefinition, type ResourceInstance, type ResourceManifest, type ScopeHandle, type Tracer } from "@telorun/sdk";
 export { resourceKey };
 /**
  * Base class for all evaluation contexts. Owns template
@@ -135,9 +135,66 @@ export declare class EvaluationContext implements IEvaluationContext {
      * regardless of which path reached the instance.
      */
     invokeResolved<TInputs>(kind: string, name: string, instance: ResourceInstance, inputs: TInputs, ctx?: InvokeContext): Promise<any>;
+    /**
+     * 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;
+    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>;
     private runInvoke;
+    /**
+     * 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;
+    private capabilityOf;
     private getDeclaredThrowCodes;
     run(name: string, ctx?: InvokeContext): Promise<void>;
+    /**
+     * 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.
+     */
+    runResolved(kind: string, name: string, instance: ResourceInstance, ctx?: InvokeContext): Promise<void>;
+    /**
+     * 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.
+     */
+    openSpan(base: InvokeContext | undefined, opts: OpenSpanOptions): Promise<OpenSpan>;
+    private runInstance;
+    /**
+     * Run `fn` detached from the caller's cancellation/trace scope. The current
+     * ambient `InvokeContext` (a request's token + span) is replaced with the
+     * uncancellable root, so request-scope teardown cannot abort the work and it
+     * does not nest under the request's trace. This is the bare scope primitive —
+     * tracking/draining a detached task is the owning resource's concern (the
+     * per-resource `ResourceContext` records the task and drains it in the
+     * resource's teardown).
+     */
+    runDetached<T>(fn: () => Promise<T>): Promise<T>;
     /**
      * Expand a value that may contain precompiled ${{ }} templates.
      *

package/dist/evaluation-context.d.ts.map

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

package/dist/evaluation-context.js

@@ -279,7 +279,7 @@ export class EvaluationContext {
                     if (this.preInitHook) {
                         this.preInitHook(resource, (n, alias) => alias && alias !== "Self"
                             ? this.resolveImportedInstance(alias, n)
-                            : this.resourceInstances.get(n)?.instance);
+                            : this.resourceInstances.get(n)?.instance, (n) => this.hasManifest(n) && !this.resourceInstances.has(n));
                     }
                     if (instance.init)
                         await instance.init(ctx);
@@ -371,10 +371,14 @@ export class EvaluationContext {
                 // Propagate injection hook: extend getInstance to also resolve parent singleton instances.
                 if (parent.preInitHook) {
                     const parentHook = parent.preInitHook;
-                    child.preInitHook = (resource, childGetInstance) => {
+                    child.preInitHook = (resource, childGetInstance, childIsPending) => {
                         parentHook(resource, (name, alias) => alias && alias !== "Self"
                             ? parent.resolveImportedInstance(alias, name)
-                            : childGetInstance(name) ?? parent.resourceInstances.get(name)?.instance);
+                            : childGetInstance(name) ?? parent.resourceInstances.get(name)?.instance, 
+                        // A scoped ref resolves against the scope's own resources or an already-inited
+                        // outer one; only a scope-local dependency can still be pending. The outer is
+                        // live by the time a scope opens, so the child's own predicate suffices.
+                        childIsPending);
                     };
                 }
                 try {
@@ -471,6 +475,38 @@ export class EvaluationContext {
         }
         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).
+     */
+    traceRootScope() {
+        return undefined;
+    }
+    tracePayload(kind, name, spanId, parentSpanId, traceId, capability, phase, outcome, detail) {
+        return {
+            traceId,
+            spanId,
+            parentSpanId,
+            capability,
+            phase,
+            ...(outcome !== undefined ? { outcome } : {}),
+            ref: { kind, name },
+            ...detail,
+        };
+    }
     async runInvoke(kind, name, instance, inputs, ctx) {
         // Explicit seed (trigger / embedder) wins; otherwise inherit the ambient
         // tree token; otherwise open a fresh, never-cancellable scope. The token
@@ -479,28 +515,40 @@ export class EvaluationContext {
         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 on every event's
-        // `metadata` so the consumer can rebuild the call tree. Off by default —
-        // `tracedCtx` stays `baseCtx` and the fast `=== ambient` skip is preserved.
+        // 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;
-        const meta = tracing ? { invocationId, parentInvocationId } : undefined;
+        // 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, outcome, detail) => 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 = tracing
-            ? { cancellation: token, invocationId, parentInvocationId }
+            ? { 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`, { inputs, reason: token.reason }, meta);
+            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`.
@@ -515,7 +563,7 @@ export class EvaluationContext {
             const outputs = await (invokeCtx === ambient
                 ? call()
                 : cancellationStore.run(invokeCtx, call));
-            await this.emit(`${kind}.${name}.Invoked`, { inputs, outputs }, meta);
+            await this.emit(`${name}.Invoked`, span("end", "ok", { inputs, outputs }));
             return outputs;
         }
         catch (err) {
@@ -523,23 +571,23 @@ export class EvaluationContext {
             // 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`, { inputs, reason }, meta);
+                await this.emit(`${name}.InvokeCancelled`, span("end", "cancelled", { inputs, reason }));
                 throw err;
             }
             if (isInvokeError(err)) {
-                const payload = { inputs, code: err.code, message: err.message, data: err.data };
-                await this.emit(`${kind}.${name}.InvokeRejected`, payload, meta);
+                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, meta);
+                    await this.emit(`${name}.InvokeRejected.Undeclared`, span("end", "rejected", detail));
                 }
                 throw err;
             }
             if (err instanceof Error) {
-                await this.emit(`${kind}.${name}.InvokeFailed`, { inputs, name: err.name, message: err.message }, meta);
+                await this.emit(`${name}.InvokeFailed`, span("end", "failed", { inputs, name: err.name, message: err.message }));
             }
             else {
-                await this.emit(`${kind}.${name}.InvokeFailed`, { inputs, name: "UnknownError", message: String(err) }, meta);
+                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.
@@ -560,6 +608,24 @@ export class EvaluationContext {
             throw wrapped;
         }
     }
+    /**
+     * 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. */
+    resolveKindSafe(kind) {
+        return kind;
+    }
+    capabilityOf(kind) {
+        const resolved = this.resolveKindSafe(kind);
+        return this.getDefinition?.(resolved)?.capability ?? this.getDefinition?.(kind)?.capability;
+    }
     getDeclaredThrowCodes(kind) {
         if (!this.getDefinition)
             return null;
@@ -582,22 +648,131 @@ export class EvaluationContext {
     }
     async run(name, ctx) {
         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, 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, name, instance, ctx) {
+        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, opts) {
+        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, outcome, extra = {}) => 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 = {
+            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));
+            },
+        };
+    }
+    async runInstance(kind, name, instance, ctx) {
+        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, outcome, detail) => this.tracePayload(kind, name, invocationId, parentInvocationId, traceId, "run", phase, outcome, phase === "end" && rootScope ? { ...detail, context: rootScope } : detail);
+        const invokeCtx = 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(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(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(", ")}`);
+    }
+    /**
+     * Run `fn` detached from the caller's cancellation/trace scope. The current
+     * ambient `InvokeContext` (a request's token + span) is replaced with the
+     * uncancellable root, so request-scope teardown cannot abort the work and it
+     * does not nest under the request's trace. This is the bare scope primitive —
+     * tracking/draining a detached task is the owning resource's concern (the
+     * per-resource `ResourceContext` records the task and drains it in the
+     * resource's teardown).
+     */
+    runDetached(fn) {
+        return cancellationStore.run(UNCANCELLABLE_CONTEXT, fn);
     }
     /**
      * Expand a value that may contain precompiled ${{ }} templates.