@telorun/kernel 0.66.0 → 0.67.0

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.

package/src/kernel.ts

@@ -1,6 +1,7 @@
 import {
   AnalysisRegistry,
   buildEvalPaths,
+  collectZoneModuleDocuments,
   flattenForAnalyzer,
   flattenLoadedModule,
   isModuleKind,
@@ -45,6 +46,7 @@ import { formatSpanCounter } from "./logging/span-id.js";
 import { ambientInvokeContext } from "./evaluation-context.js";
 import { ModuleContext } from "./module-context.js";
 import { ResourceContextImpl } from "./resource-context.js";
+import { mintResourceHandle } from "./resource-handle.js";
 import { nodeCelHandlers } from "./cel-handlers.js";
 import { parseRef, seedInvokeSource } from "./invoke-dispatch.js";
 import { stripCompiledValues } from "./schema-compiled-values.js";
@@ -520,7 +522,10 @@ export class Kernel implements IKernel {
     const skipValidation = stamp?.signature === analysisSignature;
     const errors = this.analyzer.analyzeErrors(
       staticManifests,
-      { skipValidation },
+      // Imported libraries' full documents, for the zone stage's per-library
+      // export derivation: `flattenForAnalyzer` forwards only each library's
+      // export surface, never its internal dispatch chain.
+      { skipValidation, moduleDocuments: collectZoneModuleDocuments(analysisGraph) },
       this.registry,
     );
     if (errors.length > 0) {
@@ -1286,6 +1291,17 @@ export class Kernel implements IKernel {
     const instance = await controller.create(processedResource, ctx);
     if (!instance) return null;
 
+    // Mint the instance's identity here, at the single instance-production site,
+    // so an instance is never observable without a handle — the same argument
+    // that put contract binding here. First mint wins: a `base:` child IS the
+    // parent instance returned verbatim and must not be re-identified.
+    const handle = mintResourceHandle(
+      instance,
+      resolvedKind,
+      (processedResource.metadata?.name as string | undefined) ?? "<unnamed>",
+    );
+    (ctx as ResourceContextImpl).bindResourceIdentity(handle, resolvedKind, processedResource);
+
     // Bind the resolved invocation contract to the instance, here at the kernel's
     // single instance-production site — so every consumer holds an already
     // enforcing instance, including the majority that read a Phase-5-injected ref

package/src/manifest-schemas.ts

@@ -96,6 +96,12 @@ const KNOWN_CAPABILITIES = [
   // path, and dispatch emits trace events, so routing logs through it would
   // generate telemetry from inside the telemetry path. See kernel/specs/logging.md §10.
   "Telo.Sink",
+  // `Telo.Executable` is deliberately declarable NOWHERE: it is the slot-
+  // constraint parent of Invocable and Runnable ("control can be transferred to
+  // this"), naming no lifecycle role. Listing it here keeps the open third-party
+  // fallback branch below from accepting it — and since no branch above admits
+  // it either, `capability: Telo.Executable` fails validation outright.
+  "Telo.Executable",
 ] as const;
 
 /** Rule 8: `throws:` is only meaningful on Telo.Invocable or Telo.Runnable.

package/src/module-context.ts

@@ -1,4 +1,4 @@
-import { executeInvokeStep, getRefIdentity, RuntimeError } from "@telorun/sdk";
+import { deriveContext, executeInvokeStep, getRefIdentity, RuntimeError } from "@telorun/sdk";
 import type { ScopeConfig } from "./logging/scope-config.js";
 import type {
   BootTarget,
@@ -585,12 +585,11 @@ export class ModuleContext extends EvaluationContext implements IModuleContext {
       );
     const targetCtx: InvokeContext | undefined =
       tracing && ctx
-        ? {
-            cancellation: ctx.cancellation,
+        ? deriveContext(ctx, {
             invocationId: appSpanId,
             parentInvocationId: undefined,
             traceId: appTraceId,
-          }
+          })
         : ctx;
 
     const steps: Record<string, unknown> = {};

package/src/resource-context.ts

@@ -1,15 +1,20 @@
 import {
+  InvokeError,
   NoopValidator,
   ResourceContext,
   ResourceInstance,
   ResourceManifest,
   RuntimeError,
   RuntimeResource,
+  UNCANCELLABLE_CONTEXT,
   createCancellationSource,
+  deriveContext,
+  getRefIdentity,
   resolveRefInstance,
   type CancellationSource,
   type ControllerPolicy,
   type EvaluationContext as IEvaluationContext,
+  type InvokeByNameOptions,
   type InvokeContext,
   type LoadOptions,
   type ModuleContext,
@@ -17,10 +22,14 @@ import {
   type OpenSpan,
   type OpenSpanOptions,
   type ParsedArgs,
+  type ResourceDefinition,
+  type ResourceHandle,
   type RuntimeSeam,
   type TypeRule,
+  type ZoneEntry,
 } from "@telorun/sdk";
 import { isRefSentinel } from "@telorun/templating";
+import { ZoneContext } from "./zone-context.js";
 import * as path from "path";
 import { pathToFileURL } from "url";
 import type { ModuleArtifact } from "./bundle/module-artifact.js";
@@ -350,6 +359,88 @@ export class ResourceContextImpl implements ResourceContext {
     return createCancellationSource();
   }
 
+  // ── Execution zones (kernel/specs/execution-zones.md) ─────────────────────
+  //
+  // Identity is held here (it is the resource's, not the zone subsystem's);
+  // everything else delegates to `ZoneContext`, which owns the annotation
+  // resolution, correlation walk and stack matching — and memoizes them, since
+  // this sits on the dispatch path.
+
+  #self: ResourceHandle | undefined;
+  #zones: ZoneContext | undefined;
+
+  /** Kernel-internal: stamped at `create()`, the moment the instance exists. */
+  bindResourceIdentity(
+    handle: ResourceHandle,
+    resolvedKind: string,
+    manifest: Record<string, unknown>,
+  ): void {
+    this.#self = handle;
+    this.#zones = new ZoneContext({
+      resourceName: (this.metadata?.name as string) ?? "<unnamed>",
+      resolvedKind,
+      self: handle,
+      // The SAME object Phase-5 injection later mutates, so a correlation
+      // pointer read at invoke time sees live instances in ref slots.
+      manifest,
+      resolveDefinition: (kind) => this.kernel.getAnalysisRegistry().resolveDefinition(kind),
+      resolveDefinitionIn: (kind, module) =>
+        this.kernel.getAnalysisRegistry().resolveDefinitionIn(kind, module),
+      resolveLocalInstance: (name) => this.resolveLocalInstance(name),
+      resolveLocalManifest: (name) =>
+        this.contextForName(name).resourceInstances.get(name)?.resource as
+          | Record<string, unknown>
+          | undefined,
+    });
+  }
+
+  get self(): ResourceHandle {
+    if (!this.#self) {
+      throw new RuntimeError(
+        "ERR_RESOURCE_IDENTITY_UNBOUND",
+        `[${this.metadata.name}] ctx.self is unavailable inside create() — the handle is minted when create() returns`,
+      );
+    }
+    return this.#self;
+  }
+
+  /** The zone subsystem, available once `create()` has returned. */
+  private zoneContext(): ZoneContext {
+    if (!this.#zones) {
+      throw new RuntimeError(
+        "ERR_RESOURCE_IDENTITY_UNBOUND",
+        `[${this.metadata.name}] zones are unavailable inside create() — the handle is minted when create() returns`,
+      );
+    }
+    return this.#zones;
+  }
+
+  withZone<T>(
+    slot: string,
+    fn: (ctx: InvokeContext, entry: ZoneEntry) => Promise<T>,
+    base?: InvokeContext,
+  ): Promise<T> {
+    return this.zoneContext().withZone(slot, fn, base);
+  }
+
+  requireZone(field: string, ctx?: InvokeContext): ZoneEntry {
+    return this.zoneContext().requireZone(field, ctx);
+  }
+
+  findZone(field: string, ctx?: InvokeContext): ZoneEntry | undefined {
+    return this.zoneContext().findZone(field, ctx);
+  }
+
+  zonesFor(instance: ResourceInstance, ctx?: InvokeContext): readonly ZoneEntry[] {
+    return this.zoneContext().zonesFor(instance, ctx);
+  }
+
+  /** The root context for runtime-driven inbound work — inherits nothing from
+   *  whatever ambient happens to be live at the registration site. */
+  rootContext(opts?: { cancellation?: CancellationSource }): InvokeContext {
+    return opts?.cancellation?.context ?? UNCANCELLABLE_CONTEXT;
+  }
+
   /** In-flight fire-and-forget tasks this resource spawned. Owned here, not by
    *  the kernel: the resource drains them in its own teardown (see
    *  `drainDetached`), so background work is bounded by the resource's lifetime. */
@@ -401,8 +492,13 @@ export class ResourceContextImpl implements ResourceContext {
     return this.owningContext.openSpan(base, opts);
   }
 
-  invoke<TInputs>(kind: string, name: string, inputs: TInputs): Promise<any> {
-    return this.contextForName(name).invoke(kind, name, inputs);
+  invoke<TInputs>(
+    kind: string,
+    name: string,
+    inputs: TInputs,
+    options?: InvokeByNameOptions,
+  ): Promise<any> {
+    return this.contextForName(name).invoke(kind, name, inputs, options?.ctx);
   }
 
   invokeResolved<TInputs>(

package/src/resource-handle.ts

@@ -0,0 +1,35 @@
+import type { ResourceHandle, ResourceInstanceId } from "@telorun/sdk";
+
+/**
+ * Instance → handle, minted at `create()` — the kernel's single
+ * instance-production site, where the invocation contract already binds — so an
+ * instance is never observable without one. The reverse direction deliberately
+ * does not exist: nothing turns a handle back into someone else's live
+ * instance, which is what keeps the ambient zone stack from leaking instances
+ * across module boundaries.
+ */
+const handles = new WeakMap<object, ResourceHandle>();
+
+let counter = 0;
+
+/**
+ * Mint (or return) the handle for a live instance. Idempotent, first mint wins
+ * — a `base:` child IS its parent's instance returned verbatim, so the nested
+ * parent create stamps first and the child create must not re-identify it; one
+ * live instance, one id, exactly like `stampRefIdentity`.
+ */
+export function mintResourceHandle(instance: object, kind: string, name: string): ResourceHandle {
+  const existing = handles.get(instance);
+  if (existing) return existing;
+  const handle: ResourceHandle = Object.freeze({
+    id: `ri-${++counter}` as ResourceInstanceId,
+    ref: Object.freeze({ kind, name }),
+  });
+  handles.set(instance, handle);
+  return handle;
+}
+
+/** The handle minted for a live instance, if any. */
+export function handleOfInstance(instance: object): ResourceHandle | undefined {
+  return handles.get(instance);
+}

package/src/runtime-seam.ts

@@ -1,9 +1,11 @@
 import {
   Loader,
   StaticAnalyzer,
+  collectZoneModuleDocuments,
   flattenForAnalyzer,
   type AnalysisDiagnostic,
   type ManifestSource,
+  type ZoneModuleDocuments,
 } from "@telorun/analyzer";
 import {
   Stream,
@@ -211,6 +213,7 @@ export class KernelRuntimeSeam implements RuntimeSeam {
     // `analyze()`'s — carried out of the try so the checks below can see them.
     let parseDiagnostics: AnalysisDiagnostic[] = [];
     let versionDiagnostics: AnalysisDiagnostic[] = [];
+    let moduleDocuments: ZoneModuleDocuments[] = [];
     try {
       const graph = await loader.loadGraph(source, {
         desugarImports: options?.desugarImports ?? true,
@@ -219,6 +222,9 @@ export class KernelRuntimeSeam implements RuntimeSeam {
       parseDiagnostics = graph.parseDiagnostics;
       versionDiagnostics = graph.versionDiagnostics;
       manifests = flattenForAnalyzer(graph);
+      // The zone stage derives each imported library's export contracts from
+      // its own full documents, which the flattened list drops.
+      moduleDocuments = collectZoneModuleDocuments(graph);
     } catch (err) {
       // A graph that would not load is an answer, not a failure of the call —
       // "this manifest does not load, and here is the reason" is precisely what
@@ -243,7 +249,9 @@ export class KernelRuntimeSeam implements RuntimeSeam {
 
     // `analyze()` never sees version skew, so without merging these a major
     // mismatch — which `load()` refuses to boot on — would check clean.
-    const diagnostics = new StaticAnalyzer({ celHandlers: nodeCelHandlers }).analyze(manifests);
+    const diagnostics = new StaticAnalyzer({ celHandlers: nodeCelHandlers }).analyze(manifests, {
+      moduleDocuments,
+    });
     return {
       diagnostics: [...versionDiagnostics, ...diagnostics].map(toCheckDiagnostic),
     };