@telorun/kernel 0.12.0 → 1.1.0

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

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"
-  ]
-}