@telorun/kernel 0.37.0 → 0.39.0

package/src/evaluation-context.ts

@@ -1,5 +1,6 @@
 import { AsyncLocalStorage } from "node:async_hooks";
 import {
+  getRefIdentity,
   isCompiledValue,
   isInvokeError,
   isCancellationError,
@@ -16,12 +17,14 @@ import {
   type ResourceDefinition,
   type ResourceInstance,
   type ResourceManifest,
+  type ResourceOwner,
   type RuntimeDiagnostic,
   type ScopeContext,
   type ScopeHandle,
   type Tracer,
 } from "@telorun/sdk";
 import { RuntimeError } from "@telorun/sdk";
+import { evalPathCovers } from "@telorun/analyzer";
 
 export { resourceKey };
 
@@ -40,16 +43,28 @@ function isResolvedRef(value: unknown): value is ResourceRef {
   return Object.keys(v).every((k) => k === "kind" || k === "name" || k === "alias");
 }
 
+/** The system kinds whose top-level `schema:` is, by definition, a JSON Schema
+ *  document (with `examples` / `default` / `const`) rather than config — a
+ *  `{kind, name}` inside one is documentation data, not a `!ref`. For these the
+ *  `schema` field is skipped when walking for refs/properties; for every other
+ *  kind a `schema` field is ordinary config and is walked normally, so a real
+ *  `schema: !ref X` still resolves. Narrowly scoped (rather than skipping any
+ *  field named `schema` on every kind) so the heuristic can't misfire. */
+const SCHEMA_AS_CONTRACT_KINDS = new Set(["Telo.Definition", "Telo.Abstract", "Telo.Type"]);
+
 /**
  * Walk a resource manifest's config and collect every resolved `{kind, name,
  * alias?}` reference it points at — the outbound edges for the dependency graph.
  * Called at create time, before Phase-5 injection swaps refs for live instances,
  * so the targets are still inspectable plain objects (and there are no instance
- * cycles to guard against). `metadata` is skipped (it holds the resource's own
- * identity, never refs); ref leaves are not descended into. Deduped by alias+name.
+ * cycles to guard against). Deduped by alias+name. `metadata` is always skipped
+ * (the resource's own identity); `schema` is skipped only for the system kinds
+ * that carry a JSON-Schema contract there (see {@link SCHEMA_AS_CONTRACT_KINDS}).
+ * Ref leaves are not descended into.
  */
 function collectResourceRefs(resource: ResourceManifest): ResourceRef[] {
   const found = new Map<string, ResourceRef>();
+  const skipSchema = SCHEMA_AS_CONTRACT_KINDS.has(resource.kind as string);
   const visit = (value: unknown): void => {
     if (isResolvedRef(value)) {
       const key = `${value.alias ?? ""}::${value.name}`;
@@ -60,18 +75,86 @@ function collectResourceRefs(resource: ResourceManifest): ResourceRef[] {
       for (const item of value) visit(item);
     } else if (value && typeof value === "object") {
       for (const [k, v] of Object.entries(value as Record<string, unknown>)) {
-        if (k === "metadata") continue;
+        if (k === "metadata" || (skipSchema && k === "schema")) continue;
         visit(v);
       }
     }
   };
   for (const [k, v] of Object.entries(resource as Record<string, unknown>)) {
-    if (k === "kind" || k === "metadata") continue;
+    if (k === "kind" || k === "metadata" || (skipSchema && k === "schema")) continue;
     visit(v);
   }
   return [...found.values()];
 }
 
+/**
+ * Build a resource's resolved properties for the debug stream — its config "after
+ * templating", with `${{ }}` / `!cel` reduced to concrete values. The manifest is
+ * already compile-evaluated by the time it is created, so this just makes the
+ * remaining live forms wire-friendly:
+ *  - a resolved `!ref` (`{kind, name, alias?}`) → its `{kind, name}` target;
+ *  - a deferred runtime expression (a `CompiledValue` left for per-call eval, e.g.
+ *    an Http.Api route reading `request`) → its `${{ source }}` text — there is no
+ *    concrete value for it at the resource level;
+ *  - a string carrying a known secret value → `[secret]` (substring-scrubbed), so
+ *    a compile-time `${{ secrets.x }}` never lands in the stream verbatim.
+ * `metadata` / `schema` are omitted (identity and JSON-Schema, not config).
+ */
+/** Substring-scrubbing a secret shorter than this risks redacting unrelated
+ *  content (a short/common-word value matches everywhere), so below it only a
+ *  whole-value match is redacted. */
+const MIN_SUBSTRING_SCRUB_LEN = 5;
+
+export function buildResolvedProperties(
+  resource: ResourceManifest,
+  secretValues: Set<string>,
+): Record<string, unknown> {
+  const skipSchema = SCHEMA_AS_CONTRACT_KINDS.has(resource.kind as string);
+  const scrub = (s: string): string => {
+    let out = s;
+    for (const secret of secretValues) {
+      if (!secret) continue;
+      // Exact match is always a secret; substring-redact only longer values so a
+      // short secret can't garble unrelated text it happens to appear in.
+      if (out === secret) out = "[secret]";
+      else if (secret.length >= MIN_SUBSTRING_SCRUB_LEN && out.includes(secret)) {
+        out = out.split(secret).join("[secret]");
+      }
+    }
+    return out;
+  };
+  const visit = (value: unknown): unknown => {
+    if (isCompiledValue(value)) {
+      const src = (value as { source?: unknown }).source;
+      return typeof src === "string" ? `\${{ ${src} }}` : "[expression]";
+    }
+    if (isResolvedRef(value)) return { kind: value.kind, name: value.name };
+    if (typeof value === "string") return scrub(value);
+    if (Array.isArray(value)) return value.map(visit);
+    if (value && typeof value === "object") {
+      // A live instance injected into a ref slot (e.g. a template child whose
+      // `connection` was resolved to the real connection): show its identity, not
+      // its internals. Other class instances (streams, clients) get a marker.
+      const id = getRefIdentity(value);
+      if (id) return { kind: id.kind, name: id.name };
+      const proto = Object.getPrototypeOf(value);
+      if (proto !== Object.prototype && proto !== null) {
+        return `[${(value as { constructor?: { name?: string } }).constructor?.name ?? "Object"}]`;
+      }
+      const out: Record<string, unknown> = {};
+      for (const [k, v] of Object.entries(value as Record<string, unknown>)) out[k] = visit(v);
+      return out;
+    }
+    return value;
+  };
+  const out: Record<string, unknown> = {};
+  for (const [k, v] of Object.entries(resource as Record<string, unknown>)) {
+    if (k === "kind" || k === "metadata" || (skipSchema && k === "schema")) continue;
+    out[k] = visit(v);
+  }
+  return out;
+}
+
 /**
  * Kernel-internal propagation of the current invocation tree's cancellation
  * scope. NEVER the controller-facing contract — controllers always receive the
@@ -188,6 +271,38 @@ export class EvaluationContext implements IEvaluationContext {
    */
   tracer?: Tracer;
 
+  /**
+   * The resource that owns this context's resources — stamped by a template
+   * controller on the child context it registers its `resources:` into.
+   * Propagated through spawnChild() so scoped/nested children inherit it. Drives
+   * the hierarchical `id` and `owner` every lifecycle/dispatch event carries, so
+   * a debug consumer nests children under their parent and two instances of the
+   * same templated kind don't collide by name. Undefined ⇒ top-level resources.
+   */
+  owner?: ResourceOwner;
+
+  /** Id prefix for a resource created in this context: `owner.id + "/"`, or ""
+   *  at the top level. A resource's full id is `ownerPrefix + kind + "." + name`. */
+  get ownerPrefix(): string {
+    return this.owner ? `${this.owner.id}/` : "";
+  }
+
+  /** The full hierarchical id of a resource emitted from this context. */
+  private resourceId(kind: string, name: string): string {
+    return `${this.ownerPrefix}${kind}.${name}`;
+  }
+
+  /** Stamp each dependency ref with the target node's hierarchical id. A local
+   *  (no-alias) sibling lives in this same context, so it carries this prefix; a
+   *  cross-module (`alias`) target lives elsewhere, so it stays unqualified
+   *  (best-effort — the renderer drops an edge that finds no node). */
+  private qualifyDeps(refs: ResourceRef[]): (ResourceRef & { id: string })[] {
+    return refs.map((ref) => ({
+      ...ref,
+      id: ref.alias ? `${ref.kind}.${ref.name}` : this.resourceId(ref.kind, ref.name),
+    }));
+  }
+
   constructor(
     readonly source: string,
     context: Record<string, unknown>,
@@ -271,6 +386,12 @@ export class EvaluationContext implements IEvaluationContext {
     if (this.tracer && !child.tracer) {
       child.tracer = this.tracer;
     }
+    // Inherit ownership so a scope/import opened inside a template's child
+    // context keeps its resources nested under the same owner. A template
+    // controller overrides this on its own child context after spawning.
+    if (this.owner && !child.owner) {
+      child.owner = this.owner;
+    }
     return child;
   }
 
@@ -348,14 +469,29 @@ export class EvaluationContext implements IEvaluationContext {
             if (idx >= 0) this.pendingResources.splice(idx, 1);
             errors.delete(name);
             progress = true;
-            await this.emit(`${created.resource.kind}.${created.resource.metadata.name}.Created`, {
+            const createdRes = created.resource;
+            const payload: Record<string, unknown> = {
               resource: {
-                kind: created.resource.kind,
-                name: created.resource.metadata.name,
-                module: created.resource.metadata.module,
+                kind: createdRes.kind,
+                name: createdRes.metadata.name,
+                module: createdRes.metadata.module,
+                id: this.resourceId(createdRes.kind, createdRes.metadata.name),
               },
-              dependencies: collectResourceRefs(created.resource),
+              ...(this.owner ? { owner: this.owner } : {}),
+              dependencies: this.qualifyDeps(collectResourceRefs(createdRes)),
+            };
+            // `properties` (the resolved config) is a second full config walk plus
+            // a secret scrub. Build it lazily: the EventBus short-circuits when
+            // nothing is subscribed (the no-debug-consumer case), so this getter
+            // only runs when a consumer actually serializes the payload. Memoized
+            // so multiple sinks (JSONL + SSE) don't rebuild it.
+            let props: Record<string, unknown> | undefined;
+            Object.defineProperty(payload, "properties", {
+              enumerable: true,
+              configurable: true,
+              get: () => (props ??= buildResolvedProperties(createdRes, this.secretValues)),
             });
+            await this.emit(`${createdRes.kind}.${createdRes.metadata.name}.Created`, payload);
           }
         } catch (error) {
           if (error instanceof RuntimeError && (error.code === "ERR_VISIBILITY_DENIED" || error.code === "ERR_FATAL")) throw error;
@@ -387,7 +523,12 @@ export class EvaluationContext implements IEvaluationContext {
           errors.delete(name);
           progress = true;
           await this.emit(`${resource.kind}.${resource.metadata.name}.Initialized`, {
-            resource: { kind: resource.kind, name: resource.metadata.name },
+            resource: {
+              kind: resource.kind,
+              name: resource.metadata.name,
+              id: this.resourceId(resource.kind, resource.metadata.name),
+            },
+            ...(this.owner ? { owner: this.owner } : {}),
           });
         } catch (error) {
           if (error instanceof RuntimeError && (error.code === "ERR_VISIBILITY_DENIED" || error.code === "ERR_FATAL")) throw error;
@@ -555,7 +696,12 @@ export class EvaluationContext implements IEvaluationContext {
     for (const [key, { resource, instance }] of entries) {
       if (instance.teardown) await instance.teardown();
       await this.emit(`${resource.kind}.${resource.metadata.name}.Teardown`, {
-        resource: { kind: resource.kind, name: resource.metadata.name },
+        resource: {
+          kind: resource.kind,
+          name: resource.metadata.name,
+          id: this.resourceId(resource.kind, resource.metadata.name),
+        },
+        ...(this.owner ? { owner: this.owner } : {}),
       });
       this.resourceInstances.delete(key);
     }
@@ -673,7 +819,8 @@ export class EvaluationContext implements IEvaluationContext {
       capability,
       phase,
       ...(outcome !== undefined ? { outcome } : {}),
-      ref: { kind, name },
+      ref: { kind, name, id: this.resourceId(kind, name) },
+      ...(this.owner ? { owner: this.owner } : {}),
       ...detail,
     };
   }
@@ -1124,10 +1271,12 @@ export class EvaluationContext implements IEvaluationContext {
   }
 }
 
+/** A compile path is excluded from compile-time expansion when it overlaps a
+ *  runtime path in either direction — the runtime path is a descendant of it, or
+ *  vice versa. Both directions go through the shared {@link evalPathCovers}
+ *  containment rule so this stays in lockstep with the analyzer's coverage check. */
 function isExcluded(path: string, excludePaths: string[]): boolean {
-  return excludePaths.some(
-    (ep) => ep === path || ep === "**" || path.startsWith(ep + ".") || ep.startsWith(path + "."),
-  );
+  return excludePaths.some((ep) => evalPathCovers(ep, path) || evalPathCovers(path, ep));
 }
 
 function getNestedValue(obj: Record<string, unknown>, parts: string[]): unknown {

package/src/kernel.ts

@@ -1,5 +1,6 @@
 import {
   AnalysisRegistry,
+  buildEvalPaths,
   defaultSources,
   flattenForAnalyzer,
   flattenLoadedModule,
@@ -36,7 +37,6 @@ import { ModuleContext } from "./module-context.js";
 import { ResourceContextImpl } from "./resource-context.js";
 import { nodeCelHandlers } from "./cel-handlers.js";
 import { parseRef, seedInvokeSource } from "./invoke-dispatch.js";
-import { buildEvalPaths } from "./eval-paths.js";
 import { stripCompiledValues } from "./schema-compiled-values.js";
 import { injectAtPath } from "./dependency-injection.js";
 import {
@@ -895,6 +895,7 @@ export class Kernel implements IKernel {
     moduleContext: IModuleContext,
     resource: ResourceManifest,
     args?: ParsedArgs,
+    ownerPrefix = "",
   ): ResourceContext {
     return new ResourceContextImpl(
       this,
@@ -906,6 +907,7 @@ export class Kernel implements IKernel {
       this.stdout,
       this.stderr,
       args,
+      ownerPrefix,
     );
   }
 
@@ -1043,7 +1045,12 @@ export class Kernel implements IKernel {
 
     const parsedArgs = this.parseArgsForController(controller);
     const moduleCtx = this.findModuleContext(evalContext);
-    const ctx = this.createResourceContext(moduleCtx, processedResource, parsedArgs);
+    const ctx = this.createResourceContext(
+      moduleCtx,
+      processedResource,
+      parsedArgs,
+      evalContext.ownerPrefix,
+    );
     const instance = await controller.create(processedResource, ctx);
     if (!instance) return null;
 

package/src/manifest-sources/local-file-source.ts

@@ -1,8 +1,8 @@
 import { DEFAULT_MANIFEST_FILENAME, type ManifestSource } from "@telorun/analyzer";
+import { selectByPatterns } from "@telorun/glob";
 import * as fs from "fs/promises";
 import * as path from "path";
 import { fileURLToPath, pathToFileURL } from "url";
-import { minimatch } from "minimatch";
 
 function toFilePath(pathOrUrl: string): string {
   return pathOrUrl.startsWith("file://") ? fileURLToPath(pathOrUrl) : pathOrUrl;
@@ -49,17 +49,18 @@ export class LocalFileSource implements ManifestSource {
   async expandGlob(base: string, patterns: string[]): Promise<string[]> {
     const baseDir = path.dirname(path.resolve(toFilePath(base)));
     const entries = await fs.readdir(baseDir, { recursive: true, withFileTypes: true });
-    const normalizedPatterns = patterns.map((p) => p.replace(/\\/g, "/").replace(/^\.\//, ""));
-    const matched: string[] = [];
+    const rels: string[] = [];
     for (const entry of entries) {
       if (!entry.isFile()) continue;
-      const relative = path.relative(baseDir, path.join(entry.parentPath, entry.name));
-      const normalized = relative.replace(/\\/g, "/");
-      if (normalizedPatterns.some((p) => minimatch(normalized, p))) {
-        matched.push(toFileUrl(path.resolve(baseDir, relative)));
-      }
+      rels.push(path.relative(baseDir, path.join(entry.parentPath, entry.name)).replace(/\\/g, "/"));
     }
-    return matched.sort();
+    // `include:` resolution may reach any co-located partial, so it opts out of
+    // the soft default-ignore tier (parity with `telo publish`'s include path).
+    // The hard tier (`node_modules`/`.git`/`.telo`) is always denied, so a broad
+    // `**` include never recurses into the manifest cache.
+    return selectByPatterns(rels, patterns, { applyDefaultIgnore: false }).map((rel) =>
+      toFileUrl(path.resolve(baseDir, rel)),
+    );
   }
 
   async resolveOwnerOf(fileUrl: string): Promise<string | null> {

package/src/resource-context.ts

@@ -38,6 +38,10 @@ export class ResourceContextImpl implements ResourceContext {
   readonly stdout: NodeJS.WritableStream;
   readonly stderr: NodeJS.WritableStream;
   readonly args: ParsedArgs;
+  /** Id prefix of the context this resource was created in. A controller that
+   *  spawns sub-resources composes their ids as `ownerPrefix + kind + "." + name`
+   *  and stamps the owner on the child context it registers them into. */
+  readonly ownerPrefix: string;
 
   constructor(
     readonly kernel: Kernel,
@@ -49,12 +53,14 @@ export class ResourceContextImpl implements ResourceContext {
     stdout?: NodeJS.WritableStream,
     stderr?: NodeJS.WritableStream,
     args?: ParsedArgs,
+    ownerPrefix = "",
   ) {
     this.env = env ?? process.env;
     this.stdin = stdin ?? process.stdin;
     this.stdout = stdout ?? process.stdout;
     this.stderr = stderr ?? process.stderr;
     this.args = args ?? { _: [] };
+    this.ownerPrefix = ownerPrefix;
   }
 
   createSchemaValidator(schema: any) {

package/dist/eval-paths.d.ts

@@ -1,10 +0,0 @@
-/**
- * Traverses a definition schema and collects all paths annotated with `x-telo-eval`.
- * Root-level `x-telo-eval` produces the `"**"` wildcard (expand all fields).
- * Property-level annotations produce the dot-notation path to that property.
- */
-export declare function buildEvalPaths(schema: Record<string, any>): {
-    compile: string[];
-    runtime: string[];
-};
-//# sourceMappingURL=eval-paths.d.ts.map

package/dist/eval-paths.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"eval-paths.d.ts","sourceRoot":"","sources":["../src/eval-paths.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,wBAAgB,cAAc,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAAG;IAC3D,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,OAAO,EAAE,MAAM,EAAE,CAAC;CACnB,CAcA"}

package/dist/eval-paths.js

@@ -1,35 +0,0 @@
-/**
- * Traverses a definition schema and collects all paths annotated with `x-telo-eval`.
- * Root-level `x-telo-eval` produces the `"**"` wildcard (expand all fields).
- * Property-level annotations produce the dot-notation path to that property.
- */
-export function buildEvalPaths(schema) {
-    const compile = [];
-    const runtime = [];
-    if (schema["x-telo-eval"] === "compile")
-        compile.push("**");
-    else if (schema["x-telo-eval"] === "runtime")
-        runtime.push("**");
-    if (schema.properties) {
-        for (const [key, propSchema] of Object.entries(schema.properties)) {
-            collectEvalPathsNode(propSchema, key, compile, runtime);
-        }
-    }
-    return { compile, runtime };
-}
-function collectEvalPathsNode(node, path, compile, runtime) {
-    if (node["x-telo-eval"] === "compile") {
-        compile.push(path);
-        return;
-    }
-    if (node["x-telo-eval"] === "runtime") {
-        runtime.push(path);
-        return;
-    }
-    if (node.properties) {
-        for (const [key, propSchema] of Object.entries(node.properties)) {
-            collectEvalPathsNode(propSchema, `${path}.${key}`, compile, runtime);
-        }
-    }
-}
-//# sourceMappingURL=eval-paths.js.map

package/dist/eval-paths.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"eval-paths.js","sourceRoot":"","sources":["../src/eval-paths.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,MAAM,UAAU,cAAc,CAAC,MAA2B;IAIxD,MAAM,OAAO,GAAa,EAAE,CAAC;IAC7B,MAAM,OAAO,GAAa,EAAE,CAAC;IAE7B,IAAI,MAAM,CAAC,aAAa,CAAC,KAAK,SAAS;QAAE,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;SACvD,IAAI,MAAM,CAAC,aAAa,CAAC,KAAK,SAAS;QAAE,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IAEjE,IAAI,MAAM,CAAC,UAAU,EAAE,CAAC;QACtB,KAAK,MAAM,CAAC,GAAG,EAAE,UAAU,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,MAAM,CAAC,UAAiC,CAAC,EAAE,CAAC;YACzF,oBAAoB,CAAC,UAAU,EAAE,GAAG,EAAE,OAAO,EAAE,OAAO,CAAC,CAAC;QAC1D,CAAC;IACH,CAAC;IAED,OAAO,EAAE,OAAO,EAAE,OAAO,EAAE,CAAC;AAC9B,CAAC;AAED,SAAS,oBAAoB,CAC3B,IAAyB,EACzB,IAAY,EACZ,OAAiB,EACjB,OAAiB;IAEjB,IAAI,IAAI,CAAC,aAAa,CAAC,KAAK,SAAS,EAAE,CAAC;QACtC,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QACnB,OAAO;IACT,CAAC;IACD,IAAI,IAAI,CAAC,aAAa,CAAC,KAAK,SAAS,EAAE,CAAC;QACtC,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QACnB,OAAO;IACT,CAAC;IACD,IAAI,IAAI,CAAC,UAAU,EAAE,CAAC;QACpB,KAAK,MAAM,CAAC,GAAG,EAAE,UAAU,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,IAAI,CAAC,UAAiC,CAAC,EAAE,CAAC;YACvF,oBAAoB,CAAC,UAAU,EAAE,GAAG,IAAI,IAAI,GAAG,EAAE,EAAE,OAAO,EAAE,OAAO,CAAC,CAAC;QACvE,CAAC;IACH,CAAC;AACH,CAAC"}

package/src/eval-paths.ts

@@ -1,44 +0,0 @@
-/**
- * Traverses a definition schema and collects all paths annotated with `x-telo-eval`.
- * Root-level `x-telo-eval` produces the `"**"` wildcard (expand all fields).
- * Property-level annotations produce the dot-notation path to that property.
- */
-export function buildEvalPaths(schema: Record<string, any>): {
-  compile: string[];
-  runtime: string[];
-} {
-  const compile: string[] = [];
-  const runtime: string[] = [];
-
-  if (schema["x-telo-eval"] === "compile") compile.push("**");
-  else if (schema["x-telo-eval"] === "runtime") runtime.push("**");
-
-  if (schema.properties) {
-    for (const [key, propSchema] of Object.entries(schema.properties as Record<string, any>)) {
-      collectEvalPathsNode(propSchema, key, compile, runtime);
-    }
-  }
-
-  return { compile, runtime };
-}
-
-function collectEvalPathsNode(
-  node: Record<string, any>,
-  path: string,
-  compile: string[],
-  runtime: string[],
-): void {
-  if (node["x-telo-eval"] === "compile") {
-    compile.push(path);
-    return;
-  }
-  if (node["x-telo-eval"] === "runtime") {
-    runtime.push(path);
-    return;
-  }
-  if (node.properties) {
-    for (const [key, propSchema] of Object.entries(node.properties as Record<string, any>)) {
-      collectEvalPathsNode(propSchema, `${path}.${key}`, compile, runtime);
-    }
-  }
-}