@telorun/kernel 0.11.1 → 1.1.0

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

@@ -150,7 +150,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 };
   }
@@ -195,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 = {
@@ -221,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");
@@ -299,6 +300,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 +311,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 +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.
@@ -618,6 +599,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
@@ -914,7 +913,7 @@ export const __testing__ = {
   resolvePackageExportTarget,
   resolveExportTargetValue,
   tryResolveFile,
-  walkUpToPackageRoot,
   EXPORTS_MAX_DEPTH,
   DEFAULT_RESOLVER_CONDITIONS,
+  REALM_COLLAPSE_NAMES,
 };

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();
         },

package/src/kernel.ts

@@ -30,6 +30,7 @@ import { EventStream } from "./event-stream.js";
 import { EventBus } from "./events.js";
 import { ModuleContext } from "./module-context.js";
 import { ResourceContextImpl } from "./resource-context.js";
+import { resolveApplicationEnv } from "./application-env.js";
 import { policyFingerprint } from "./runtime-registry.js";
 import { SchemaValidator } from "./schema-validator.js";
 
@@ -304,15 +305,35 @@ export class Kernel implements IKernel {
     const normalizedManifests = this.analyzer.normalize(allManifests, this.registry);
     this.staticManifests = normalizedManifests;
 
+    let rootApplicationManifest: ResourceManifest | undefined;
     for (const manifest of normalizedManifests) {
       if (isModuleKind(manifest.kind)) {
-        // Root is always Telo.Application (Library root rejected above). Applications
-        // have no variables/secrets fields — those are a Library-only contract, populated
-        // by importers, not by the root manifest itself.
+        // Root is always Telo.Application (Library root rejected above).
+        // Application-level `variables` / `secrets` declarations carry an `env:`
+        // mapping per field; the kernel populates the root scope from
+        // `process.env` after the manifest loop so imports can read
+        // `${{ variables.X }}` during their own init.
         this.rootContext.setTargets(manifest.targets ?? []);
+        if (manifest.kind === "Telo.Application") {
+          rootApplicationManifest = manifest;
+        }
       }
       this.rootContext.registerManifest(manifest);
     }
+
+    if (rootApplicationManifest) {
+      const { variables, secrets } = resolveApplicationEnv(
+        rootApplicationManifest as Record<string, any>,
+        this.env,
+        this.sharedSchemaValidator,
+      );
+      if (Object.keys(variables).length > 0) {
+        this.rootContext.setVariables(variables);
+      }
+      if (Object.keys(secrets).length > 0) {
+        this.rootContext.setSecrets(secrets);
+      }
+    }
   }
 
   /**

package/dist/generated/runtime-deps.json

@@ -1,6 +0,0 @@
-{
-  "generated": "scripts/generate-runtime-deps.mjs",
-  "names": [
-    "@telorun/sdk"
-  ]
-}