@telorun/kernel 0.82.1 → 0.83.0

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

@@ -5,28 +5,65 @@ import type {
   ResourceContext,
   ResourceInstance,
 } from "@telorun/sdk";
-import { isCompiledValue } from "@telorun/sdk";
+import {
+  celEvalSites,
+  effectiveAuthorSchema,
+  evalPathCovers,
+  mergeCelEvalSites,
+  NO_CEL_EVAL_SITES,
+  pathMatchesScope,
+  type CelEvalSites,
+} from "@telorun/analyzer";
+import { isCompiledValue, type ResourceDefinition } from "@telorun/sdk";
 import { isRefSentinel } from "@telorun/templating";
 import { celSelfView } from "../../evaluation-context.js";
 
-/** CEL variables that are only bound at call time (request handling, step
- *  chaining, error branches) — never at a template's init(). A persistent
- *  child's body is expanded against `self` only, so a `${{ }}` node referencing
- *  any of these must survive untouched for the consuming controller (e.g. an
- *  Http.Api evaluating route CEL per request) to evaluate later. A node mixing
- *  `self` with a deferred variable in one expression is unsupported by design —
- *  keep `self`-derived literals and request-derived values in separate fields
- *  (e.g. a `self`-built SQL string vs. request-built `bindings`). */
-const DEFERRED_VARS = new Set(["request", "result", "steps", "error"]);
-const DEFERRED_RE = new RegExp(`(?<![.\\w])(?:${[...DEFERRED_VARS].join("|")})(?![\\w])`);
+/**
+ * WHICH NODES OF A TEMPLATE BODY SURVIVE init() UNEXPANDED.
+ *
+ * A `resources:` entry is a DECLARATION of another kind, and that kind decides
+ * when each of its fields is evaluated: an `x-telo-eval: runtime` field, or any
+ * field under a CEL-bearing region (an `x-telo-context`, an error branch, a step
+ * body), is evaluated by the child's OWN controller against a scope only it can
+ * build. Those nodes must reach the child compiled.
+ *
+ * Read off the nested kind's schema through the containment matcher both halves
+ * already share (`celEvalSites` / `evalPathCovers`), never off a list of
+ * variable names. The name list — `request`, `result`, `steps`, `error` — was
+ * the reason a body could not read the call's own arguments (`inputs`) or an
+ * iteration's element (`item`): those two names were simply absent from it, so
+ * such a node was expanded at init() against a scope where they do not exist and
+ * failed with `Unknown variable: inputs`. A list has to be extended for every
+ * name any kind ever binds; the annotations already say where evaluation
+ * happens.
+ */
+/** True when a node at `path` inside a body is evaluated by the child's own
+ *  controller rather than at the template's init(). `runtime` paths are
+ *  property-only and match by containment; a region scope is a JSONPath
+ *  (`$.routes[*].returns`) whose wildcards a plain prefix test cannot resolve. */
+function isDeferredPath(sites: CelEvalSites, path: string): boolean {
+  return (
+    sites.runtime.some((p) => evalPathCovers(p, path)) ||
+    sites.regions.some((scope) => pathMatchesScope(path, scope))
+  );
+}
 
-/** True when an expression reads a call-time-only variable. Prefers the AST-
- *  derived root identifiers stamped on the CompiledValue at compile time (exact —
- *  ignores string literals and substrings); falls back to a source-text scan for
- *  values produced by engines that surface no AST. */
-function referencesDeferred(value: CompiledValue): boolean {
-  if (value.refs) return value.refs.some((r) => DEFERRED_VARS.has(r));
-  return typeof value.source === "string" && DEFERRED_RE.test(value.source);
+/**
+ * True when an expression reads anything other than `self`. A deferred node that
+ * names only `self` is still resolved at `init()`: `self` is fixed for the life
+ * of the instance, so expanding it there costs nothing and keeps a `self`-built
+ * literal (a SQL string, a route path) a literal.
+ *
+ * Read off the AST-derived roots the compile step stamps, never off the source
+ * text. A regex over the source both over- and under-matches — it fires on a
+ * word inside a string literal and misses a bare `${{ item }}` with no member
+ * access — and there is nothing to fall back FOR: every built-in engine carries
+ * `refs` through. An engine that surfaces none is treated as reading nothing but
+ * `self`, which resolves it at `init()` and fails loudly there rather than
+ * silently deferring a node the child cannot evaluate.
+ */
+function referencesBeyondSelf(value: CompiledValue): boolean {
+  return (value.refs ?? []).some((r) => r !== "self");
 }
 
 /** Matches a CEL source that is exactly a `self.<path>` member access (capturing
@@ -75,8 +112,18 @@ export function createTemplateController(definition: {
       // `inputs:` sibling (same factoring as Run.Sequence steps), never in the
       // target's resource body — the body is `self`-only so every child can be
       // created once at init and reused across calls.
-      const targetName = (field: string | { kind?: string; name: string } | undefined): string | null => {
+      const targetName = (
+        field: string | { kind?: string; name: string } | undefined,
+      ): string | null => {
         if (field == null) return null;
+        // `invoke: !ref body` names a sibling `resources:` entry — the same
+        // spelling every other reference uses. Phase 2.5 does not descend into a
+        // `Telo.Definition`, so the sentinel arrives raw; `Self.` is the
+        // explicit self-qualifier and names the same local entry.
+        if (isRefSentinel(field)) {
+          const source = field.source;
+          return source.startsWith("Self.") ? source.slice("Self.".length) : source;
+        }
         const nameTemplate =
           typeof field === "object" && !isCompiledValue(field) ? field.name : field;
         return nameTemplate
@@ -146,16 +193,16 @@ export function createTemplateController(definition: {
       }
 
       // Expand a persistent child's body against `self`. Self-only CEL resolves
-      // to literals now; CEL bound only at call time (DEFERRED_VARS) passes
-      // through compiled for the child's own controller. `!ref` sentinels are
+      // to literals now; a node the NESTED KIND evaluates later (see
+      // `deferredPaths`) passes through compiled for the child's own controller. `!ref` sentinels are
       // rewritten to the `{kind, name, alias?}` injection shape here — Phase 2.5
       // (`resolveRefSentinels`) does not descend into template bodies, so the
       // child context's Phase 5 injection would otherwise see an unrecognized
       // sentinel and leave the slot unresolved. Kind is left empty: injection
       // dispatches by name and recovers the kind from the resolved instance.
-      const expandSelf = (value: any): any => {
+      const expandSelf = (value: any, path: string, deferred: CelEvalSites): any => {
         if (isCompiledValue(value)) {
-          if (referencesDeferred(value)) return value;
+          if (isDeferredPath(deferred, path) && referencesBeyondSelf(value)) return value;
           // A pure `self.<path>` access (e.g. a `connection: !ref` passed down) is
           // resolved by navigating the resource directly. Going through CEL would
           // re-emit the value through CEL's output type-checker, which rejects live
@@ -163,10 +210,11 @@ export function createTemplateController(definition: {
           // a consumer wired in could never reach a child's slot. Complex self
           // expressions (string building) still evaluate via CEL, where they yield
           // CEL-safe scalars.
-          const path = typeof value.source === "string" ? value.source.trim().match(SELF_PATH) : null;
-          if (path) {
+          const selfPath =
+            typeof value.source === "string" ? value.source.trim().match(SELF_PATH) : null;
+          if (selfPath) {
             let cur: any = getSelf();
-            for (const key of path[1].split(".").slice(1)) cur = cur?.[key];
+            for (const key of selfPath[1]!.split(".").slice(1)) cur = cur?.[key];
             return cur;
           }
           // CEL cannot read a member off a live instance, and a ref slot holds
@@ -188,15 +236,54 @@ export function createTemplateController(definition: {
           const name = alias === "Self" ? source.slice(dot + 1) : source;
           return { kind: siblingKinds.get(name) ?? "", name };
         }
-        if (Array.isArray(value)) return value.map(expandSelf);
+        if (Array.isArray(value)) {
+          return value.map((item, i) => expandSelf(item, `${path}[${i}]`, deferred));
+        }
         if (value !== null && typeof value === "object") {
           const out: Record<string, unknown> = {};
-          for (const [k, v] of Object.entries(value)) out[k] = expandSelf(v);
+          for (const [k, v] of Object.entries(value)) {
+            out[k] = expandSelf(v, path ? `${path}.${k}` : k, deferred);
+          }
           return out;
         }
         return value;
       };
 
+      /**
+       * The nested kind's own CEL evaluation sites, resolved once per body. The
+       * kind is written in the DEFINING library's alias scope, so it is
+       * resolved there — the consumer has never heard of the alias.
+       *
+       * The INHERITANCE-RESOLVED schema, merged with the capability abstract's,
+       * exactly as the analyzer half reads it (`effectiveSchemaOf` in
+       * `cel-scope.ts`). A nested kind that inherits a CEL region from an
+       * `extends` parent — or gets one implicitly from `Telo.Provider` — would
+       * otherwise be covered on the static side and not here, which is the two
+       * halves disagreeing about when a node is evaluated.
+       */
+      const deferredPathsFor = (kind: unknown): CelEvalSites => {
+        if (typeof kind !== "string") return NO_CEL_EVAL_SITES;
+        const cached = deferredByKind.get(kind);
+        if (cached) return cached;
+        const resolveDef = (k: string): ResourceDefinition | undefined =>
+          definingContext.getDefinition?.(definingContext.kindResolver?.(k) ?? k) ??
+          definingContext.getDefinition?.(k);
+        const def = resolveDef(kind);
+        const capability = def?.capability;
+        const sites = def
+          ? mergeCelEvalSites(
+              celEvalSites(effectiveAuthorSchema(def, resolveDef) as Record<string, any>),
+              celEvalSites(
+                (capability ? resolveDef(capability)?.schema : undefined) as
+                  | Record<string, any>
+                  | undefined,
+              ),
+            )
+          : NO_CEL_EVAL_SITES;
+        deferredByKind.set(kind, sites);
+        return sites;
+      };
+
       // init() may run more than once: when a child's local ref names a sibling
       // not yet initialized, child init defers with ERR_LOCAL_REF_PENDING and the
       // outer multi-pass loop retries this resource. Registration must happen
@@ -204,6 +291,10 @@ export function createTemplateController(definition: {
       // children are skipped, still-pending ones advance).
       let registered = false;
 
+      /** Memo per nested kind — a body is expanded once, but a template kind is
+       *  instantiated many times across an application. */
+      const deferredByKind = new Map<string, CelEvalSites>();
+
       return {
         // The template's own resources are its allocation, and tearing the child
         // context down is the inverse. `init()` still resumes rather than
@@ -212,8 +303,17 @@ export function createTemplateController(definition: {
         init: (templateCtx) =>
           templateCtx.effect("template resources", async () => {
             if (!registered) {
+              // `self` is in scope for the whole body, not only for what init()
+              // resolves: a node the nested kind evaluates later (a step's
+              // `inputs`, a route's `returns`) may read `self` beside the
+              // call-time names its own controller binds. Bound as the
+              // published-reading view, so `self.<ref>.<field>` answers exactly
+              // as `resources.<name>.<field>` does.
+              childContext.bindContextValue?.("self", celSelfView(getSelf()));
               for (const template of definition.resources ?? []) {
-                childContext.registerManifest(expandSelf(template));
+                childContext.registerManifest(
+                  expandSelf(template, "", deferredPathsFor(template?.kind)),
+                );
               }
               registered = true;
             }

package/src/evaluation-context.ts

@@ -82,6 +82,12 @@ const SCHEMA_AS_CONTRACT_KINDS = new Set(["Telo.Definition", "Telo.Abstract", "T
 function collectResourceRefs(resource: ResourceManifest): ResourceRef[] {
   const found = new Map<string, ResourceRef>();
   const skipSchema = SCHEMA_AS_CONTRACT_KINDS.has(resource.kind as string);
+  // A re-created resource is rebuilt from the manifest as REGISTERED, but
+  // Phase-5 injection mutated that object in place on the previous pass — so a
+  // ref slot may already hold a live instance, whose object graph is cyclic.
+  // The walk is a best-effort edge collection for failure attribution, so it
+  // stops at anything it has already seen rather than recursing forever.
+  const seen = new WeakSet<object>();
   const visit = (value: unknown): void => {
     if (isResolvedRef(value)) {
       const key = `${value.alias ?? ""}::${value.name}`;
@@ -89,8 +95,12 @@ function collectResourceRefs(resource: ResourceManifest): ResourceRef[] {
       return;
     }
     if (Array.isArray(value)) {
+      if (seen.has(value)) return;
+      seen.add(value);
       for (const item of value) visit(item);
     } else if (value && typeof value === "object") {
+      if (seen.has(value)) return;
+      seen.add(value);
       for (const [k, v] of Object.entries(value as Record<string, unknown>)) {
         if (k === "metadata" || (skipSchema && k === "schema")) continue;
         visit(v);
@@ -484,6 +494,10 @@ export class EvaluationContext implements IEvaluationContext {
   parent: IEvaluationContext | undefined = undefined;
   readonly children: IEvaluationContext[] = [];
 
+  /** Where this node sits in its parent's teardown cascade — ascending, default
+   *  0, reverse-registration within a tier. See `childTeardownOrder`. */
+  teardownPriority: number | undefined = undefined;
+
   /** Current lifecycle state of this context node. */
   state: LifecycleState = "Pending";
 
@@ -515,6 +529,84 @@ export class EvaluationContext implements IEvaluationContext {
    *  Their re-creation is not progress — see the create sub-phase. */
   private readonly recreatedResources = new Set<string>();
 
+  /**
+   * Instances this context can reach by name but does NOT own — a library's
+   * declared `resources:` inputs, bound here by the import that handed them
+   * down.
+   *
+   * **Borrowed, not owned.** The instance's effect frame belongs to the scope
+   * that DECLARED it, so this context must never include it in its own
+   * teardown: a library tearing one down would close the application's
+   * connection out from under everything else still using it.
+   */
+  protected readonly borrowedResources = new Set<string>();
+
+  /**
+   * Bind an instance this context does not own under `name`, and mirror its
+   * published reading into this context's `resources` scope so
+   * `resources.<name>.<field>` reads here exactly as it does where the resource
+   * is declared.
+   *
+   * The mirror is a subscription rather than a copy because a published value is
+   * a READING: the owner republishes after `run()`, after every `invoke()` and
+   * on every `setStatus()`, and a snapshot taken once at binding would go stale
+   * at the first of those — silently, since nothing downstream can tell a stale
+   * reading from a current one.
+   */
+  adoptBorrowedResource(
+    name: string,
+    resource: ResourceManifest,
+    instance: ResourceInstance,
+    owner: EvaluationContext,
+  ): void | (() => void) {
+    this.resourceInstances.set(name, { resource, instance });
+    this.borrowedResources.add(name);
+    this.declaredManifests.set(name, resource);
+    const unmirror = owner.mirrorPublications(resource.metadata.name as string, (props) =>
+      this.onResourceSnapshotted(name, props),
+    );
+    // The INVERSE, returned rather than performed: an import whose `init()`
+    // fails is discarded and re-created on the next pass, so a subscription left
+    // behind would be appended again on every pass — unbounded — and would keep
+    // a dead child context reachable from the live owner. The binding is not on
+    // this context's teardown path either (`teardownOrder` filters a borrowed
+    // name out, and that is also the only place an entry is deleted), so
+    // undoing it has to be stated here.
+    return () => {
+      unmirror();
+      this.borrowedResources.delete(name);
+      this.resourceInstances.delete(name);
+      this.declaredManifests.delete(name);
+    };
+  }
+
+  /** Publication mirrors registered by {@link adoptBorrowedResource}, by the
+   *  OWNER's name for the resource. */
+  private readonly publicationMirrors = new Map<
+    string,
+    Array<(props: Record<string, unknown>) => void>
+  >();
+
+  /** Register a mirror and replay the current reading, so a borrower that binds
+   *  after the owner has already published does not wait for the next one.
+   *  Returns the unsubscribe — a subscription with no way to end it outlives
+   *  whatever registered it. */
+  mirrorPublications(name: string, sink: (props: Record<string, unknown>) => void): () => void {
+    const bucket = this.publicationMirrors.get(name);
+    if (bucket) bucket.push(sink);
+    else this.publicationMirrors.set(name, [sink]);
+    const entry = this.resourceInstances.get(name) ?? this.createdInstances.get(name);
+    const current = entry ? publishedByInstance.get(entry.instance) : undefined;
+    if (current) sink(current);
+    return () => {
+      const sinks = this.publicationMirrors.get(name);
+      if (!sinks) return;
+      const at = sinks.indexOf(sink);
+      if (at >= 0) sinks.splice(at, 1);
+      if (sinks.length === 0) this.publicationMirrors.delete(name);
+    };
+  }
+
   /** Resources queued for initialization on this context node. */
   private pendingResources: ResourceManifest[] = [];
 
@@ -684,6 +776,7 @@ export class EvaluationContext implements IEvaluationContext {
     });
     publishedByInstance.set(entry.instance, props);
     this.onResourceSnapshotted(name, props);
+    for (const sink of this.publicationMirrors.get(name) ?? []) sink(props);
   }
 
   get context(): Record<string, unknown> {
@@ -801,6 +894,21 @@ export class EvaluationContext implements IEvaluationContext {
     return child;
   }
 
+  /**
+   * Bind a name into this context's own CEL scope.
+   *
+   * A copy is written rather than a mutation: `spawnChildContext` hands the
+   * child the PARENT's context object by reference, so mutating it in place
+   * would put the binding in the parent's scope as well.
+   *
+   * Used by a template to put `self` in scope for the body it creates, so a node
+   * the nested kind evaluates later can read the enclosing resource's
+   * configuration beside the call-time names that kind binds.
+   */
+  bindContextValue(name: string, value: unknown): void {
+    this._context = { ...this._context, [name]: value };
+  }
+
   /** Spawn a fresh child context attached to this node — the isolated scope a
    *  templated definition registers its `resources:` into. Rooting it on the
    *  context that DEFINED the template (not the consumer that instantiated the
@@ -1216,7 +1324,7 @@ export class EvaluationContext implements IEvaluationContext {
     this.state = "Draining";
     const failures: Array<{ resource: string; error: unknown }> = [];
 
-    for (const child of [...this.children].reverse()) {
+    for (const child of this.childTeardownOrder()) {
       try {
         await child.teardownResources();
       } catch (err) {
@@ -1294,6 +1402,28 @@ export class EvaluationContext implements IEvaluationContext {
     }
   }
 
+  /**
+   * Child contexts in teardown order: ascending `teardownPriority` (default 0),
+   * with the base reverse-registration order preserved within each tier.
+   *
+   * The same rule `teardownOrder` applies to resource instances, and for the
+   * same reason: reverse registration is reverse init order in the happy path,
+   * but a node that must reliably outlive the rest has to say so rather than
+   * depend on when it happened to be created. A `lifecycle: shared` library is
+   * registered when the FIRST import reaches it — which, for an import declared
+   * inside another library, is after that library's own context — so reverse
+   * registration would tear the singleton down while a borrower still holds it.
+   */
+  private childTeardownOrder(): IEvaluationContext[] {
+    return [...this.children]
+      .reverse()
+      .sort(
+        (a, b) =>
+          ((a as { teardownPriority?: number }).teardownPriority ?? 0) -
+          ((b as { teardownPriority?: number }).teardownPriority ?? 0),
+      );
+  }
+
   /**
    * Resource instances in teardown order: ascending `teardownPriority`, with the
    * base reverse-insertion order preserved within each priority tier.
@@ -1308,7 +1438,11 @@ export class EvaluationContext implements IEvaluationContext {
    * instance shape.
    */
   private teardownOrder(): Array<[string, { resource: any; instance: any }]> {
-    const entries = [...this.resourceInstances.entries()].reverse();
+    // A borrowed instance is torn down by the scope that declared it, never
+    // here — see `borrowedResources`.
+    const entries = [...this.resourceInstances.entries()]
+      .filter(([name]) => !this.borrowedResources.has(name))
+      .reverse();
     // Stable sort by priority (default 0); Array.prototype.sort is stable, so
     // the reverse-insertion order survives within each tier.
     return entries.sort(

package/src/module-context.ts

@@ -552,6 +552,12 @@ export class ModuleContext extends EvaluationContext implements IModuleContext {
     return `${realModule}.${suffix}`;
   }
 
+  /** A module context IS the alias table, so it answers the resolver seam
+   *  directly rather than inheriting one from a parent it does not have. Public
+   *  because a template body's nested kind is written in the DEFINING library's
+   *  scope and its controller has to resolve it there. */
+  override kindResolver = (kind: string): string => this.resolveKindSafe(kind);
+
   protected override resolveKindSafe(kind: string): string {
     // `resolveKind` throws for unqualified / ungated kinds — an expected signal,
     // not a failure: a capability probe that can't resolve falls back to the raw