@telorun/kernel 0.12.0 → 1.2.0

package/package.json

@@ -1,9 +1,9 @@
 {
   "name": "@telorun/kernel",
-  "version": "0.12.0",
+  "version": "1.2.0",
   "description": "Telo Runtime - A lightweight, polyglot execution host.",
   "keywords": [
-    "digly",
+    "telo",
     "runtime",
     "execution",
     "manifest"
@@ -47,8 +47,7 @@
   "dependencies": {
     "@marcbachmann/cel-js": "^7.5.3",
     "@sinclair/typebox": "^0.34.48",
-    "@telorun/analyzer": "0.11.0",
-    "@telorun/sdk": "0.11.1",
+    "@telorun/analyzer": "1.2.0",
     "ajv": "^8.17.1",
     "ajv-formats": "^3.0.1",
     "minimatch": "^10.2.5",
@@ -60,11 +59,13 @@
     "typescript": "^5.0.0",
     "vitest": "^2.1.8"
   },
+  "peerDependencies": {
+    "@telorun/sdk": "1.0.0"
+  },
   "overrides": {
     "@marcbachmann/cel-js": "$@marcbachmann/cel-js",
     "@sinclair/typebox": "$@sinclair/typebox",
     "@telorun/analyzer": "$@telorun/analyzer",
-    "@telorun/sdk": "$@telorun/sdk",
     "ajv": "$ajv",
     "ajv-formats": "$ajv-formats",
     "minimatch": "$minimatch",
@@ -72,7 +73,7 @@
     "yaml": "$yaml"
   },
   "scripts": {
-    "build": "tsc && node ../../scripts/generate-runtime-deps.mjs .",
+    "build": "tsc",
     "dev": "tsc --watch",
     "test": "vitest run",
     "test:watch": "vitest"

package/src/application-env.ts

@@ -0,0 +1,216 @@
+import { residualEntrySchema } from "@telorun/analyzer";
+import { RuntimeError } from "@telorun/sdk";
+import { SchemaValidator } from "./schema-validator.js";
+
+type EntryType = "string" | "integer" | "number" | "boolean" | "object" | "array";
+
+interface EnvEntry {
+  env: string;
+  type: EntryType;
+  default?: unknown;
+  [key: string]: unknown;
+}
+
+export interface EnvResolutionResult {
+  variables: Record<string, unknown>;
+  secrets: Record<string, unknown>;
+}
+
+/**
+ * Populate the root Application's `variables` / `secrets` namespaces from
+ * host environment variables, per the per-field `env:` mapping declared on
+ * each entry.
+ *
+ * Implements the polyglot env-resolution spec from
+ * kernel/nodejs/plans/application-env-variables.md: read the env var, coerce
+ * per `entry.type`, validate the coerced value (or the declared default, when
+ * the env var is unset) against the entry's residual schema, and aggregate
+ * every failure into a single `ERR_MANIFEST_VALIDATION_FAILED` error so all
+ * problems surface before any controller initializes.
+ *
+ * This must run BEFORE any Telo.Import controller initializes — imports may
+ * pass `${{ variables.X }}` as their `variables:` inputs, so the root scope
+ * has to be populated by the time the import controller evaluates those
+ * expressions.
+ */
+export function resolveApplicationEnv(
+  manifest: Record<string, any>,
+  env: Record<string, string | undefined>,
+  validator: SchemaValidator,
+): EnvResolutionResult {
+  const errors: string[] = [];
+  const variables = resolveBlock(
+    manifest.variables ?? {},
+    env,
+    validator,
+    errors,
+    false,
+  );
+  const secrets = resolveBlock(
+    manifest.secrets ?? {},
+    env,
+    validator,
+    errors,
+    true,
+  );
+  if (errors.length > 0) {
+    throw new RuntimeError(
+      "ERR_MANIFEST_VALIDATION_FAILED",
+      `Application environment validation failed:\n` +
+        errors.map((e) => `  - ${e}`).join("\n"),
+    );
+  }
+  return { variables, secrets };
+}
+
+function resolveBlock(
+  block: Record<string, EnvEntry> | unknown,
+  env: Record<string, string | undefined>,
+  validator: SchemaValidator,
+  errors: string[],
+  isSecret: boolean,
+): Record<string, unknown> {
+  const out: Record<string, unknown> = {};
+  if (!block || typeof block !== "object" || Array.isArray(block)) {
+    return out;
+  }
+  for (const [name, entry] of Object.entries(block as Record<string, EnvEntry>)) {
+    if (!entry || typeof entry !== "object") continue;
+    const envKey = entry.env;
+    const raw = env[envKey];
+    const residual = residualEntrySchema(entry as Record<string, unknown>);
+
+    if (raw === undefined || raw === null) {
+      if (entry.default !== undefined) {
+        const validation = validateResidual(entry.default, residual, validator);
+        if (validation) {
+          errors.push(`${name}: ${validation}`);
+        } else {
+          out[name] = entry.default;
+        }
+        continue;
+      }
+      errors.push(`${name}: environment variable ${envKey} is not set (no default)`);
+      continue;
+    }
+
+    let coerced: unknown;
+    try {
+      coerced = coerce(raw, entry.type, envKey, isSecret);
+    } catch (e) {
+      errors.push(`${name}: ${(e as Error).message}`);
+      continue;
+    }
+
+    const validation = validateResidual(coerced, residual, validator);
+    if (validation) {
+      errors.push(`${name}: ${validation}`);
+      continue;
+    }
+
+    out[name] = coerced;
+  }
+  return out;
+}
+
+/** Render a raw env value for inclusion in an error message. Secret values
+ *  are masked so coercion / schema diagnostics don't leak secret material
+ *  into logs (the env-var name and the failure reason still surface). */
+function renderRawForError(raw: string, isSecret: boolean): string {
+  return isSecret ? "<redacted>" : `"${raw}"`;
+}
+
+function coerce(
+  raw: string,
+  type: EntryType,
+  envKey: string,
+  isSecret: boolean,
+): unknown {
+  switch (type) {
+    case "string":
+      return raw;
+    case "integer": {
+      const trimmed = raw.trim();
+      if (!/^-?\d+$/.test(trimmed)) {
+        throw new Error(
+          `environment variable ${envKey}: value ${renderRawForError(raw, isSecret)} is not a valid integer`,
+        );
+      }
+      return parseInt(trimmed, 10);
+    }
+    case "number": {
+      const n = parseFloat(raw);
+      if (Number.isNaN(n)) {
+        throw new Error(
+          `environment variable ${envKey}: value ${renderRawForError(raw, isSecret)} is not a valid number`,
+        );
+      }
+      return n;
+    }
+    case "boolean":
+      if (raw === "true") return true;
+      if (raw === "false") return false;
+      throw new Error(
+        `environment variable ${envKey}: value ${renderRawForError(raw, isSecret)} is not a valid boolean (expected "true" or "false")`,
+      );
+    case "object": {
+      const parsed = parseJson(raw, envKey, isSecret);
+      if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) {
+        throw new Error(
+          `environment variable ${envKey}: expected JSON object, got ${describeJsonType(parsed)}`,
+        );
+      }
+      return parsed;
+    }
+    case "array": {
+      const parsed = parseJson(raw, envKey, isSecret);
+      if (!Array.isArray(parsed)) {
+        throw new Error(
+          `environment variable ${envKey}: expected JSON array, got ${describeJsonType(parsed)}`,
+        );
+      }
+      return parsed;
+    }
+  }
+}
+
+function parseJson(raw: string, envKey: string, isSecret: boolean): unknown {
+  try {
+    return JSON.parse(raw);
+  } catch (e) {
+    // Node's JSON.parse error embeds the offending character / position; for
+    // secrets, swallow the parser detail and surface only the env var name.
+    const detail = isSecret ? "value is not valid JSON" : (e as Error).message;
+    throw new Error(`environment variable ${envKey}: ${isSecret ? detail : `value is not valid JSON: ${detail}`}`);
+  }
+}
+
+function describeJsonType(value: unknown): string {
+  if (value === null) return "null";
+  if (Array.isArray(value)) return "array";
+  return typeof value;
+}
+
+function validateResidual(
+  value: unknown,
+  residual: Record<string, unknown>,
+  validator: SchemaValidator,
+): string | null {
+  try {
+    validator.compile(residual as any).validate(value);
+    return null;
+  } catch (e) {
+    const msg = e instanceof Error ? e.message : String(e);
+    // Strip SchemaValidator's "Invalid value passed: <JSON>. Error: " prefix
+    // so the JSON-stringified value (which can be secret material for entries
+    // under `secrets:`) never reaches the caller. The split is anchored on
+    // the literal ". Error: " delimiter — a `[^.]*` regex would have leaked
+    // any value containing a dot (URLs, versions, paths).
+    const sentinel = ". Error: ";
+    const idx = msg.indexOf(sentinel);
+    if (msg.startsWith("Invalid value passed:") && idx !== -1) {
+      return msg.slice(idx + sentinel.length);
+    }
+    return msg;
+  }
+}

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

@@ -201,25 +201,22 @@ export class NpmControllerLoader {
     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();
+    // 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 = {
@@ -227,8 +224,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");
@@ -405,54 +400,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.
- */
-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.
+ * 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 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.
@@ -954,7 +913,7 @@ export const __testing__ = {
   resolvePackageExportTarget,
   resolveExportTargetValue,
   tryResolveFile,
-  walkUpToPackageRoot,
   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,12 +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>;
   run?: string;
+  provide?: { kind: string; name: string };
+  result?: Record<string, any>;
 }): ControllerInstance {
   return {
     schema: definition.schema ?? { type: "object", additionalProperties: true },
@@ -32,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;
@@ -40,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 {
@@ -84,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 };
@@ -95,7 +122,13 @@ 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:'.`,
+                );
               }
               // Top-level `inputs:` (sibling of `invoke:`) carries the values passed
               // to the dispatch target's invoke(). When absent, fall back to the
@@ -108,7 +141,13 @@ export function createTemplateController(definition: {
                     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,
+              );
             });
           },
         }),
@@ -117,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();
         },