@telorun/kernel 0.11.1 → 0.13.0

package/src/controller-loaders/npm-loader.ts

@@ -81,10 +81,13 @@ export interface NpmControllerLoaderOptions {
 }
 
 /**
- * The npm-loader maintains a single install root per kernel process at
- * `<entry-manifest-dir>/.telo/npm/`. Every controller — registry tag or
- * `local_path` — is installed via `npm install <spec>` into this root, then
- * imported from `<root>/node_modules/<pkg>`. This collapses two parallel
+ * The npm-loader maintains a single install root per kernel process. For a
+ * local entry manifest (`file://` URL or bare path) the root lives at
+ * `<entry-manifest-dir>/.telo/npm/`; for an HTTP(S) entry URL it lives in a
+ * user-level cache keyed by `sha256(entryUrl)` (see `computeInstallRoot`).
+ * Every controller — registry tag or `local_path` — is installed via
+ * `npm install <spec>` into this root, then imported from
+ * `<root>/node_modules/<pkg>`. This collapses two parallel
  * module realms (kernel-side @telorun/sdk vs. controller-side @telorun/sdk)
  * into one: the kernel's own SDK is wired in as a `file:` dep, npm/pnpm
  * symlink it, and Node's ESM resolver follows the symlink to the same
@@ -150,7 +153,13 @@ export class NpmControllerLoader {
 
     const installRoot = await this.ensureInstallRoot();
     const resolved = await resolveInstallSpec(parsed, packageName, baseUri);
-    const source = await this.installPackage(installRoot, packageName, resolved.spec, resolved.kind);
+    const source = await this.installPackage(
+      installRoot,
+      packageName,
+      resolved.spec,
+      resolved.kind,
+      parsed.version ?? null,
+    );
     const instance = await loadFromInstall(installRoot, packageName, parsed.subpath ?? null, purl);
     return { instance, source };
   }
@@ -184,36 +193,24 @@ export class NpmControllerLoader {
       );
     }
     const entryUrlStr = this.entryUrl;
-    // The install root is anchored next to the entry manifest on disk. For an
-    // http(s):// entry URL there is no such anchor — `path.resolve` would
-    // silently turn `http://host/x.yaml` into something like
-    // `<cwd>/http:/host/x.yaml`, materializing a `.telo/npm` tree in an
-    // unrelated directory. Reject the case loudly until we ship an explicit
-    // strategy (e.g. a hash-keyed cache under `~/.cache/telo`) for HTTP-sourced
-    // manifests; today nothing in the workspace exercises this path.
-    const entryPath = parseFileUrlOrThrow(entryUrlStr);
-    const entryDir = path.dirname(path.resolve(entryPath));
-    const installRoot = path.join(entryDir, ".telo", "npm");
-
-    // Build the install-root package.json: kernel-runtime deps as `file:` refs,
-    // `overrides` + `pnpm.overrides` pinning every name to `$<name>`. This is
-    // the realm-collapse mechanism — npm's `file:` symlinks the kernel's own
-    // package locations, the resolver follows symlinks to the realpath, and
-    // every controller transitively resolving these names lands on the
-    // identical module instance the kernel itself is using.
-    const runtimeDeps = await loadRuntimeDeps();
+    const installRoot = computeInstallRoot(entryUrlStr);
+
+    // Build the install-root package.json: kernel-runtime deps as `file:` refs
+    // pointing at the kernel-side realpath. Modules declare these names as
+    // `peerDependencies`, so npm/pnpm resolve each controller's `import` to the
+    // single copy provided here — the realm-collapse mechanism that gives
+    // class-identity-sensitive types (today: `Stream`) one constructor across
+    // the kernel/controller boundary.
     const dependencies: Record<string, string> = {};
-    const overrides: Record<string, string> = {};
-    for (const name of runtimeDeps) {
+    for (const name of REALM_COLLAPSE_NAMES) {
       const resolvedPkgRoot = await resolveKernelPackageRoot(name);
       if (!resolvedPkgRoot) {
         // A kernel runtime dep that can't be resolved at boot is unusual but
-        // not fatal — the realm-collapse story degrades to "rely on registry
-        // resolution + overrides" for that name. Don't crash the loader.
+        // not fatal — the realm-collapse story degrades to "rely on whatever
+        // the package manager picks" for that name. Don't crash the loader.
         continue;
       }
       dependencies[name] = `file:${resolvedPkgRoot}`;
-      overrides[name] = `$${name}`;
     }
 
     const packageJson = {
@@ -221,8 +218,6 @@ export class NpmControllerLoader {
       private: true,
       version: "0.0.0",
       dependencies,
-      overrides,
-      pnpm: { overrides },
     };
     const packageJsonPath = path.join(installRoot, "package.json");
     const stateFile = path.join(installRoot, ".telo-state.json");
@@ -299,6 +294,7 @@ export class NpmControllerLoader {
     packageName: string,
     spec: string,
     kind: SpecKind,
+    requestedVersion: string | null,
   ): Promise<NpmResolveSource> {
     const cacheKey = `${packageName}@${spec}`;
     if (this.installedSpecs.has(cacheKey)) return "cache";
@@ -309,22 +305,37 @@ export class NpmControllerLoader {
       return "cache";
     }
 
-    // Lock-free fast path: consult the in-process snapshot of the install
-    // root's `dependencies` map (seeded by `materializeInstallRoot`). If the
-    // spec matches what's already wired in and the package directory exists,
-    // there's nothing to do — no lock, no fork, no per-load file read. This
-    // is the dominant case for warm test suites: every Kernel touches the
-    // same controllers and a fresh-on-disk read per (Kernel × controller)
-    // dominates wall time even when the actual installs are already done.
-    //
-    // Normalize specs before comparing because npm rewrites absolute `file:`
-    // deps to relative paths inside the install root's `package.json`. The
-    // loader passes absolute paths (resolved against the declaring library's
-    // baseUri); the on-disk record is `file:../../foo`. Without normalization
-    // every fast-path read is a string-mismatch and the loader would fall
-    // through to a real `npm install` per controller per Kernel — turning a
-    // 1ms hit into a 150–200ms one.
     const targetPath = path.join(installRoot, "node_modules", ...packageName.split("/"));
+
+    // Registry fast path: compare against the installed package's own
+    // `package.json` version field. `rootDeps[packageName]` can't be used
+    // here because npm rewrites registry specs on `--save` — we pass
+    // `@scope/pkg@0.3.4`, npm writes `^0.3.4` — so a string comparison
+    // never matches and every fresh `NpmControllerLoader` (one per
+    // `Telo.Definition.init`) would fall through to a no-op but ~200ms
+    // `npm install`. Reading the installed package.json sidesteps that
+    // entirely: if the requested PURL version equals what's on disk, we
+    // already have the right thing.
+    //
+    // Ranges (`^1.0.0`, `~2.3.0`) fall through to a real `npm install` —
+    // they're rare in PURLs (which typically pin) and a proper range check
+    // would need a semver dep here.
+    if (kind === "registry") {
+      const installedVersion = await readInstalledVersion(targetPath);
+      if (
+        installedVersion !== null &&
+        (requestedVersion === null || requestedVersion === installedVersion)
+      ) {
+        this.installedSpecs.add(cacheKey);
+        return "cache";
+      }
+    }
+
+    // Local (`file:`) spec fast path: consult the in-process snapshot of the
+    // install root's `dependencies` map (seeded by `materializeInstallRoot`).
+    // Normalize because npm rewrites absolute `file:` deps to relative paths
+    // inside the install root's `package.json` — the loader passes the
+    // absolute path, the on-disk record is `file:../../foo`.
     const cachedSpec = this.rootDeps[packageName];
     if (
       cachedSpec !== undefined &&
@@ -383,54 +394,18 @@ export class NpmControllerLoader {
 }
 
 /**
- * Read the realm-collapse name list shipped with the kernel under
- * `dist/generated/runtime-deps.json`. The list is small and stable (today:
- * `@telorun/sdk`); see `scripts/generate-runtime-deps.mjs` for the rationale
- * about which packages belong here. Returns an empty array if the file is
- * unreadable — the npm-loader then degrades to "no realm collapse," which is
- * still a working install path; only `Stream`-flavoured class-identity bugs
- * resurface.
+ * Names of packages whose realpath must be shared between the kernel and every
+ * loaded controller. Each name here becomes a `file:` dep in the install-root
+ * `package.json`, pinned at the kernel's own resolution; controllers declare
+ * these names as `peerDependencies` so npm/pnpm resolves them to that single
+ * copy instead of nesting their own.
+ *
+ * Add a name here if you ship another shared runtime symbol whose `instanceof`
+ * or constructor identity matters across module boundaries. Today the only
+ * such name is `@telorun/sdk` (carries the `Stream` class registered with
+ * `@marcbachmann/cel-js`).
  */
-async function loadRuntimeDeps(): Promise<string[]> {
-  const here = fileURLToPath(import.meta.url);
-  // Walk up from this file's location to the kernel-package root (the dir
-  // that contains package.json). In dev: `kernel/nodejs/`. In published:
-  // the installed package root inside `node_modules/@telorun/kernel/`.
-  // Walk-until-root rather than a fixed depth — the directory tree depth
-  // depends on whether we're in a workspace or installed tree.
-  const pkgDir = await walkUpToPackageRoot(path.dirname(here));
-  if (!pkgDir) return [];
-
-  const generated = path.join(pkgDir, "dist", "generated", "runtime-deps.json");
-  if (!(await pathExists(generated))) return [];
-  // The file is generated by `scripts/generate-runtime-deps.mjs`; if it
-  // exists but is malformed, that's a kernel-build bug. Don't swallow —
-  // surface so the cause is debuggable. Realm collapse is the whole point
-  // of this code path; quietly degrading to "no realm collapse" would
-  // silently re-introduce the very bug the file fixes.
-  const data = JSON.parse(await fs.readFile(generated, "utf8"));
-  if (!Array.isArray(data?.names)) {
-    throw new Error(
-      `[telo] ${generated} is malformed: expected { names: string[] } at top level. ` +
-        `Re-run \`node scripts/generate-runtime-deps.mjs <pkg-dir>\` to regenerate.`,
-    );
-  }
-  return data.names as string[];
-}
-
-/**
- * Walk up from `from` until the directory contains a `package.json`.
- * Returns null at filesystem root if none found.
- */
-async function walkUpToPackageRoot(from: string): Promise<string | null> {
-  let dir = from;
-  while (true) {
-    if (await pathExists(path.join(dir, "package.json"))) return dir;
-    const parent = path.dirname(dir);
-    if (parent === dir) return null;
-    dir = parent;
-  }
-}
+const REALM_COLLAPSE_NAMES: ReadonlyArray<string> = ["@telorun/sdk"];
 
 /**
  * Resolve a kernel-runtime dep name to the realpath of its package directory.
@@ -618,6 +593,24 @@ async function readJsonField(filePath: string, field: string): Promise<unknown>
   }
 }
 
+/**
+ * Read the `version` field from `<packageRoot>/package.json`, or null if the
+ * file is missing/unreadable/malformed or carries a non-string version. Used
+ * by the registry fast path to decide whether an existing install already
+ * satisfies the requested PURL version — the install-root's own
+ * `dependencies` map can't answer that because npm rewrites registry specs
+ * on `--save`.
+ */
+async function readInstalledVersion(packageRoot: string): Promise<string | null> {
+  try {
+    const text = await fs.readFile(path.join(packageRoot, "package.json"), "utf8");
+    const pkg = JSON.parse(text);
+    return typeof pkg?.version === "string" ? pkg.version : null;
+  } catch {
+    return null;
+  }
+}
+
 /**
  * Read the install root's `dependencies[<packageName>]` value, or undefined
  * if package.json is missing/unreadable or the dep isn't listed. Used by the
@@ -635,35 +628,56 @@ async function readDepSpec(installRoot: string, packageName: string): Promise<st
 }
 
 /**
- * Convert an entry-manifest URL to its on-disk path, throwing a descriptive
- * error for any URL scheme that doesn't map to a local filesystem location.
- * The install-root anchoring story requires a real directory next to the
- * manifest; non-file schemes (e.g. `http://`, `https://`) have no such
- * anchor and would otherwise silently produce a junk path via
- * `path.resolve("http://host/x")`.
+ * Decide where the per-kernel install root lives for a given entry URL.
+ *
+ * - `file://` URL or bare filesystem path: anchored next to the manifest at
+ *   `<entry-dir>/.telo/npm/`. Same as before — keeps the "install lives with
+ *   the project" story for local development and Docker builds where the
+ *   tree is `COPY`-d into the image.
+ * - `http(s)://` URL: there is no on-disk anchor next to the manifest, so
+ *   the install root lives in a user-level cache keyed by the SHA-256 of
+ *   the entry URL: `<cacheDir>/<hash>/npm/`. Repeat runs of the same URL
+ *   hit the same cache; distinct URLs get isolated trees so two unrelated
+ *   remote apps don't share `node_modules` (different controller versions,
+ *   different realm-collapse pins).
  *
- * Bare paths without a scheme are accepted as-is — callers that hand the
- * loader an absolute filesystem path are common and there's no ambiguity
- * to surface.
+ *   Cache location, in priority order:
+ *     1. `$TELO_NPM_CACHE_DIR` (explicit override — tests use this to avoid
+ *        polluting the developer's `~/.cache`).
+ *     2. `$XDG_CACHE_HOME/telo/remote` (standard XDG path on Linux).
+ *     3. `<os.homedir()>/.cache/telo/remote` (POSIX fallback / macOS).
+ *
+ * Unrecognised schemes (anything that isn't `file://`, `http://`, or
+ * `https://`) still throw `ControllerEnvMissingError` so the dispatcher can
+ * advance to a non-npm candidate.
  */
-function parseFileUrlOrThrow(entryUrl: string): string {
-  if (entryUrl.startsWith("file://")) return fileURLToPath(entryUrl);
-  // A scheme is anything before the first `://` — distinguish a URL from a
-  // bare filesystem path (which has no `://`).
+function computeInstallRoot(entryUrl: string): string {
+  if (entryUrl.startsWith("file://")) {
+    const entryPath = fileURLToPath(entryUrl);
+    return path.join(path.dirname(path.resolve(entryPath)), ".telo", "npm");
+  }
   const schemeMatch = entryUrl.match(/^([a-zA-Z][a-zA-Z0-9+.-]*):\/\//);
-  if (schemeMatch) {
-    // Env-missing rather than a hard error: the dispatcher should advance
-    // to the next candidate when an HTTP-sourced manifest is paired with a
-    // `pkg:cargo` (or other non-npm) fallback. Hard-failing would lock the
-    // whole resolve chain to this branch.
-    throw new ControllerEnvMissingError(
-      `[telo] entry URL scheme '${schemeMatch[1]}' is not supported by the npm controller ` +
-        `loader. The install root must live next to a local manifest; HTTP-sourced manifests ` +
-        `have no such anchor. Resolve the manifest to disk first, or use file:// directly. ` +
-        `(entryUrl: ${entryUrl})`,
-    );
+  if (!schemeMatch) {
+    // Bare filesystem path: same anchor as `file://`.
+    return path.join(path.dirname(path.resolve(entryUrl)), ".telo", "npm");
+  }
+  const scheme = schemeMatch[1].toLowerCase();
+  if (scheme === "http" || scheme === "https") {
+    const cacheBase =
+      process.env.TELO_NPM_CACHE_DIR ||
+      (process.env.XDG_CACHE_HOME
+        ? path.join(process.env.XDG_CACHE_HOME, "telo", "remote")
+        : path.join(os.homedir(), ".cache", "telo", "remote"));
+    return path.join(cacheBase, sha256(entryUrl), "npm");
   }
-  return entryUrl;
+  // Env-missing rather than a hard error: the dispatcher should advance to
+  // the next candidate when a non-npm scheme is paired with a `pkg:cargo`
+  // (or other) fallback.
+  throw new ControllerEnvMissingError(
+    `[telo] entry URL scheme '${schemeMatch[1]}' is not supported by the npm controller ` +
+      `loader. Supported schemes: file://, http://, https://, or a bare filesystem path. ` +
+      `(entryUrl: ${entryUrl})`,
+  );
 }
 
 /**
@@ -914,7 +928,8 @@ export const __testing__ = {
   resolvePackageExportTarget,
   resolveExportTargetValue,
   tryResolveFile,
-  walkUpToPackageRoot,
+  computeInstallRoot,
   EXPORTS_MAX_DEPTH,
   DEFAULT_RESOLVER_CONDITIONS,
+  REALM_COLLAPSE_NAMES,
 };

package/src/controllers/module/import-controller.ts

@@ -1,26 +1,14 @@
 import { DiagnosticSeverity, StaticAnalyzer } from "@telorun/analyzer";
-import type { ResourceContext, ResourceInstance } from "@telorun/sdk";
+import type { ResourceInstance } from "@telorun/sdk";
 import { RuntimeError } from "@telorun/sdk";
+import type { BuiltinControllerContext } from "../../internal-context.js";
 import { ModuleContext } from "../../module-context.js";
 import { isDefaultPolicy, normalizeRuntime } from "../../runtime-registry.js";
 
-const importAnalysisCache = new Map<
-  string,
-  { signature: string; errors: string[] }
->();
-
-// Only resolve relative/absolute-path sources against the importer's URL. Registry refs
-// (std/foo@1.2.3) and absolute URLs (https://, file://) must pass through unchanged so the
-// loader's source chain can dispatch them — otherwise `new URL("std/foo@1", "file:///srv/telo.yaml")`
-// turns a registry ref into a bogus file path and LocalFileSource ENOENTs on it.
-function resolveImportSource(source: string, baseSource: string): string {
-  if (source.startsWith(".") || source.startsWith("/")) {
-    return new URL(source, baseSource).toString();
-  }
-  return source;
-}
-
-export async function create(resource: any, ctx: ResourceContext): Promise<ResourceInstance> {
+export async function create(
+  resource: any,
+  ctx: BuiltinControllerContext,
+): Promise<ResourceInstance> {
   const alias = resource.metadata.name as string;
 
   const moduleSource: string = resource.module ?? resource.source;
@@ -36,27 +24,36 @@ export async function create(resource: any, ctx: ResourceContext): Promise<Resou
   // Validate the imported module and all its transitive imports before loading for runtime.
   // loadManifests() follows Telo.Import chains so definitions from sub-imports are present,
   // preventing false UNDEFINED_KIND errors for kinds that come from the module's own imports.
-  const resolvedUrl = resolveImportSource(moduleSource, base);
-  const analysisManifests = await ctx.loadManifests(resolvedUrl);
-  const signature = JSON.stringify(analysisManifests);
-  const cached = importAnalysisCache.get(resolvedUrl);
-  let errors: string[];
-
-  if (cached && cached.signature === signature) {
-    errors = cached.errors;
-  } else {
+  //
+  // Route URL resolution through the kernel/loader's own helper rather than
+  // a hand-rolled `new URL(...).toString()`. For LocalFileSource the
+  // outputs match; for any custom `ManifestSource` with a non-trivial
+  // `resolveRelative`, only this path produces the canonical URL the
+  // loader keyed its caches under — without which fast paths like
+  // `isImportValidatedAtLoad` silently miss.
+  const resolvedUrl = ctx.resolveImportUrl(base, moduleSource);
+
+  // Fast path: when the kernel's load-time `analyzeErrors` already covered
+  // this import's subtree (the common case — every Telo.Import declared in
+  // the entry graph is walked by `loadGraph` and validated by
+  // `kernel.load`), skip the redundant per-import StaticAnalyzer pass.
+  // Falls through to the full analysis for URLs that arrived
+  // programmatically after `load()` (e.g. dynamically constructed imports
+  // in tests). Two Telo.Imports with the same source but distinct
+  // metadata.name would each re-run analysis here — a memoisation hook
+  // can be reintroduced if that turns into a measurable cost.
+  if (!ctx.isImportValidatedAtLoad(resolvedUrl)) {
+    const analysisManifests = await ctx.loadManifests(resolvedUrl);
     const diagnostics = new StaticAnalyzer().analyze(analysisManifests);
-    errors = diagnostics
+    const errors = diagnostics
       .filter((d) => d.severity === DiagnosticSeverity.Error)
       .map((d) => d.message);
-    importAnalysisCache.set(resolvedUrl, { signature, errors });
-  }
-
-  if (errors.length > 0) {
-    throw new RuntimeError(
-      "ERR_MANIFEST_VALIDATION_FAILED",
-      errors.join("\n"),
-    );
+    if (errors.length > 0) {
+      throw new RuntimeError(
+        "ERR_MANIFEST_VALIDATION_FAILED",
+        errors.join("\n"),
+      );
+    }
   }
 
   // Load target module manifests for runtime. Inject variables/secrets as compile context so

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

@@ -18,6 +18,7 @@ type ResourceDefinitionResource = RuntimeResource & {
   schema: Record<string, any>;
   capability?: string;
   controllers?: Array<string>;
+  provide?: unknown;
 };
 
 /**
@@ -31,6 +32,11 @@ class ResourceDefinition implements ResourceInstance {
 
   async init(ctx: ResourceContext) {
     if (!this.resource.controllers?.length) {
+      if (this.resource.capability === "Telo.Provider" && this.resource.provide == null) {
+        throw new Error(
+          `Telo.Definition '${this.resource.metadata.name}': 'capability: Telo.Provider' requires either 'controllers:' (TS-backed) or 'provide:' (template-backed).`,
+        );
+      }
       const controllerInstance = createTemplateController(this.resource as any);
       ctx.registerDefinition(this.resource);
       await ctx.registerController(

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

@@ -1,11 +1,32 @@
 import type { ControllerInstance, ResourceContext, ResourceInstance } from "@telorun/sdk";
 import { isCompiledValue } from "@telorun/sdk";
 
+/** Reports the resources: entries available to dispatch against, by expanded
+ *  name and kind. Used in error messages to guide the developer back to the
+ *  template's `resources:` array when a dispatch target doesn't match. */
+function describeAvailableTargets(
+  ctx: ResourceContext,
+  resources: any[] | undefined,
+  self: Record<string, unknown>,
+): string {
+  if (!resources || resources.length === 0) return "<none>";
+  return resources
+    .map((r) => {
+      const expanded = ctx.moduleContext.expandWith(r?.metadata?.name ?? "", { self }) as string;
+      const kind = typeof r?.kind === "string" ? r.kind : "<unknown-kind>";
+      return `'${expanded || "<unnamed>"}' (${kind})`;
+    })
+    .join(", ");
+}
+
 export function createTemplateController(definition: {
   schema: Record<string, any>;
   resources?: any[];
-  invoke?: string | { kind?: string; name: string; inputs?: Record<string, any> };
+  invoke?: string | { kind?: string; name: string };
+  inputs?: Record<string, any>;
   run?: string;
+  provide?: { kind: string; name: string };
+  result?: Record<string, any>;
 }): ControllerInstance {
   return {
     schema: definition.schema ?? { type: "object", additionalProperties: true },
@@ -13,13 +34,16 @@ export function createTemplateController(definition: {
     create: async (resource: any, ctx: ResourceContext): Promise<ResourceInstance> => {
       const self = { ...resource, name: resource.metadata.name };
 
-      // Old string form: invoke is a plain string or a CompiledValue (after precompile).
-      // New object form: invoke is a plain object (non-CompiledValue) with at least `name`.
+      // `invoke` describes the dispatch target: a string name template (legacy
+      // shorthand) or an object `{ kind?, name }` for explicit kind-typed
+      // dispatch. `inputs:` lives as a sibling on the definition (same shape
+      // as Run.Sequence steps) — the values passed to the dispatch target's
+      // invoke() after CEL expansion.
       const objectInvoke =
         definition.invoke !== null &&
         typeof definition.invoke === "object" &&
         !isCompiledValue(definition.invoke)
-          ? (definition.invoke as { kind?: string; name: string; inputs?: Record<string, any> })
+          ? (definition.invoke as { kind?: string; name: string })
           : null;
       const invokeNameTemplate = objectInvoke ? objectInvoke.name : (definition.invoke ?? null);
       const invokeTarget = invokeNameTemplate
@@ -28,6 +52,9 @@ export function createTemplateController(definition: {
       const runTarget = definition.run
         ? (ctx.moduleContext.expandWith(definition.run, { self }) as string)
         : null;
+      const provideTarget = definition.provide?.name
+        ? (ctx.moduleContext.expandWith(definition.provide.name, { self }) as string)
+        : null;
 
       const persistentManifests: any[] = [];
       let ephemeralTemplate: any = null;
@@ -36,7 +63,10 @@ export function createTemplateController(definition: {
         const expandedName = ctx.moduleContext.expandWith(template.metadata?.name ?? "", {
           self,
         }) as string;
-        const isTarget = expandedName === invokeTarget || expandedName === runTarget;
+        const isTarget =
+          expandedName === invokeTarget ||
+          expandedName === runTarget ||
+          expandedName === provideTarget;
         if (isTarget) {
           ephemeralTemplate = template;
         } else {
@@ -80,7 +110,8 @@ export function createTemplateController(definition: {
           invoke: async (inputs: any) => {
             if (!ephemeralTemplate) {
               throw new Error(
-                `Template '${resource.metadata.name}': no ephemeral resource for invoke target '${invokeTarget}'`,
+                `Template '${resource.metadata.name}': 'invoke:' targets '${invokeTarget}' ` +
+                  `but no entry in 'resources:' has that metadata.name. Available: ${describeAvailableTargets(ctx, definition.resources, self)}.`,
               );
             }
             const extraContext = { self, inputs };
@@ -91,18 +122,32 @@ export function createTemplateController(definition: {
             return withEphemeral(expanded, async (name) => {
               const entry = ctx.moduleContext.resourceInstances.get(name);
               if (!entry?.instance?.invoke) {
-                throw new Error(`Ephemeral resource '${name}' is not invocable`);
+                const targetKind = (entry?.resource?.kind ?? expanded?.kind ?? "<unknown-kind>") as string;
+                const targetDef = ctx.moduleContext.getDefinition?.(targetKind);
+                const actualCap = typeof targetDef?.capability === "string" ? targetDef.capability : "<unknown>";
+                throw new Error(
+                  `Template '${resource.metadata.name}': 'invoke:' target '${targetKind}/${invokeTarget}' ` +
+                    `has capability '${actualCap}', not Telo.Invocable. Update 'invoke:' to a Telo.Invocable kind, or change the target's kind in 'resources:'.`,
+                );
               }
-              // New object form: expand objectInvoke.inputs with invoke context and pass as arg.
-              // Old string form: the manifest inputs were computed during template expansion;
-              // pass expanded.inputs so Sql.Exec/Query controllers receive { sql, bindings }.
-              const invokeInputs = objectInvoke?.inputs != null
+              // Top-level `inputs:` (sibling of `invoke:`) carries the values passed
+              // to the dispatch target's invoke(). When absent, fall back to the
+              // expanded resource entry's own `inputs` field (legacy string-form
+              // shape where the inputs live on the resource declaration), then
+              // finally to the caller's `inputs` arg.
+              const invokeInputs = definition.inputs != null
                 ? ctx.moduleContext.expandWith(
-                    ctx.moduleContext.expandWith(objectInvoke.inputs, extraContext),
+                    ctx.moduleContext.expandWith(definition.inputs, extraContext),
                     extraContext,
                   )
                 : expanded.inputs ?? inputs;
-              return entry.instance.invoke(invokeInputs);
+              const raw = await entry.instance.invoke(invokeInputs);
+              if (definition.result == null) return raw;
+              const resultContext = { self, result: raw };
+              return ctx.moduleContext.expandWith(
+                ctx.moduleContext.expandWith(definition.result, resultContext),
+                resultContext,
+              );
             });
           },
         }),
@@ -111,24 +156,73 @@ export function createTemplateController(definition: {
           run: async () => {
             if (!ephemeralTemplate) {
               throw new Error(
-                `Template '${resource.metadata.name}': no ephemeral resource for run target '${runTarget}'`,
+                `Template '${resource.metadata.name}': 'run:' targets '${runTarget}' ` +
+                  `but no entry in 'resources:' has that metadata.name. Available: ${describeAvailableTargets(ctx, definition.resources, self)}.`,
               );
             }
             const extraContext = { self };
             const expanded = ctx.moduleContext.expandWith(
               ctx.moduleContext.expandWith(ephemeralTemplate, extraContext),
               extraContext,
-            );
+            ) as any;
             return withEphemeral(expanded, async (name) => {
               const entry = ctx.moduleContext.resourceInstances.get(name);
               if (!entry?.instance?.run) {
-                throw new Error(`Ephemeral resource '${name}' is not runnable`);
+                const targetKind = (entry?.resource?.kind ?? expanded?.kind ?? "<unknown-kind>") as string;
+                const targetDef = ctx.moduleContext.getDefinition?.(targetKind);
+                const actualCap = typeof targetDef?.capability === "string" ? targetDef.capability : "<unknown>";
+                throw new Error(
+                  `Template '${resource.metadata.name}': 'run:' target '${targetKind}/${runTarget}' ` +
+                    `has capability '${actualCap}', not Telo.Runnable. Update 'run:' to a Telo.Runnable kind, or change the target's kind in 'resources:'.`,
+                );
               }
               return entry.instance.run();
             });
           },
         }),
 
+        ...(provideTarget && {
+          provide: async () => {
+            if (!ephemeralTemplate) {
+              throw new Error(
+                `Template '${resource.metadata.name}': 'provide:' targets '${provideTarget}' ` +
+                  `but no entry in 'resources:' has that metadata.name. Available: ${describeAvailableTargets(ctx, definition.resources, self)}.`,
+              );
+            }
+            const extraContext = { self };
+            const expanded = ctx.moduleContext.expandWith(
+              ctx.moduleContext.expandWith(ephemeralTemplate, extraContext),
+              extraContext,
+            ) as any;
+            return withEphemeral(expanded, async (name) => {
+              const entry = ctx.moduleContext.resourceInstances.get(name);
+              if (!entry?.instance?.invoke) {
+                const targetKind = (entry?.resource?.kind ?? expanded?.kind ?? "<unknown-kind>") as string;
+                const targetDef = ctx.moduleContext.getDefinition?.(targetKind);
+                const actualCap = typeof targetDef?.capability === "string" ? targetDef.capability : "<unknown>";
+                throw new Error(
+                  `Template '${resource.metadata.name}': 'provide:' target '${targetKind}/${provideTarget}' ` +
+                    `has capability '${actualCap}', not Telo.Invocable. Update 'provide:' to a Telo.Invocable kind, or change the target's kind in 'resources:'.`,
+                );
+              }
+              const provideInputs: any =
+                definition.inputs != null
+                  ? ctx.moduleContext.expandWith(
+                      ctx.moduleContext.expandWith(definition.inputs, extraContext),
+                      extraContext,
+                    )
+                  : {};
+              const raw = await entry.instance.invoke(provideInputs);
+              if (definition.result == null) return raw;
+              const resultContext = { self, result: raw };
+              return ctx.moduleContext.expandWith(
+                ctx.moduleContext.expandWith(definition.result, resultContext),
+                resultContext,
+              );
+            });
+          },
+        }),
+
         teardown: async () => {
           await childContext.teardownResources();
         },