@telorun/kernel 0.2.5 → 0.2.7

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@telorun/kernel",
-  "version": "0.2.5",
+  "version": "0.2.7",
   "description": "Telo Runtime - A lightweight, polyglot execution host.",
   "type": "module",
   "main": "./dist/index.js",
@@ -27,19 +27,18 @@
     "@sinclair/typebox": "^0.34.48",
     "ajv": "^8.17.1",
     "ajv-formats": "^3.0.1",
-    "cel-js": "^0.8.2",
-    "js-yaml": "^4.1.0",
+    "@marcbachmann/cel-js": "^7.5.3",
     "packageurl-js": "^2.0.1",
-    "@telorun/sdk": "0.2.5",
-    "@telorun/yaml-cel-templating": "1.0.2"
+    "@telorun/analyzer": "0.1.2",
+    "@telorun/sdk": "0.2.7",
+    "@telorun/yaml-cel-templating": "1.0.3"
   },
   "devDependencies": {
-    "@types/js-yaml": "^4.0.5",
     "@types/node": "^20.0.0",
     "typescript": "^5.0.0"
   },
   "scripts": {
-    "build": "tsc && cp -r src/capabilities dist/capabilities",
+    "build": "tsc",
     "dev": "tsc --watch"
   }
 }

package/src/controller-loader.ts

@@ -39,7 +39,8 @@ export class ControllerLoader {
     const isLocalManifest =
       baseUri && !baseUri.startsWith("http://") && !baseUri.startsWith("https://");
     if (localPath && isLocalManifest) {
-      const manifestDir = path.dirname(baseUri);
+      const baseUriPath = baseUri.startsWith("file://") ? baseUri.slice("file://".length) : baseUri;
+      const manifestDir = path.dirname(baseUriPath);
       const resolvedLocalPath = path.resolve(manifestDir, localPath);
       if (await this.pathExists(resolvedLocalPath)) {
         packageRoot = resolvedLocalPath;

package/src/controller-registry.ts

@@ -9,20 +9,6 @@ export class ControllerRegistry {
   private controllersByKind: Map<string, ControllerInstance> = new Map();
   private definitionsByKind: Map<string, ResourceDefinition> = new Map();
   private controllerLoaders: Map<string, () => Promise<ControllerInstance>> = new Map();
-  private capabilitySchemas: Map<string, Record<string, any> | null> = new Map();
-
-  registerCapability(name: string, schema?: Record<string, any>): void {
-    this.capabilitySchemas.set(name, schema ?? null);
-  }
-
-  isCapabilityRegistered(name: string): boolean {
-    return this.capabilitySchemas.has(name);
-  }
-
-  getCapabilitySchema(name: string): Record<string, any> | null | undefined {
-    return this.capabilitySchemas.get(name);
-  }
-
   /**
    * Register a controller definition
    */
@@ -64,8 +50,10 @@ export class ControllerRegistry {
     //   this.controllersByKind.set(kind, controller);
     //   return controller;
     // }
-
-    throw new Error(`No controller registered for kind: ${kind}`);
+    return {
+      schema: { type: "object", additionalProperties: false },
+    };
+    // throw new Error(`No controller registered for kind: ${kind}`);
   }
 
   /**
@@ -124,16 +112,13 @@ export class ControllerRegistry {
     }
     // Ensure controller has schema from definition
     const definition = this.definitionsByKind.get(kind);
-    if (definition?.schema && !controller.schema) {
-      // Wrap controller to add schema without mutating the original
-      const wrappedController: ControllerInstance = {
-        ...controller,
-        schema: definition.schema,
-      };
-      this.controllersByKind.set(kind, wrappedController);
-    } else {
-      this.controllersByKind.set(kind, controller);
-    }
+    const wrappedController: ControllerInstance = {
+      ...controller,
+      schema: controller.schema ?? definition?.schema,
+      inputType: controller.inputType,
+      outputType: controller.outputType,
+    };
+    this.controllersByKind.set(kind, wrappedController);
   }
 
   /**

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

@@ -1,20 +1,37 @@
+import { DiagnosticSeverity, Loader, StaticAnalyzer } from "@telorun/analyzer";
 import type { ResourceContext, ResourceInstance } from "@telorun/sdk";
-import { EvaluationContext } from "@telorun/sdk";
-import { Loader } from "../../loader.js";
+import { EvaluationContext, RuntimeError } from "@telorun/sdk";
+import { LocalFileAdapter } from "../../manifest-adapters/local-file-adapter.js";
 
 export async function create(resource: any, ctx: ResourceContext): Promise<ResourceInstance> {
   const alias = resource.metadata.name as string;
-  const declaringModule: string = resource.metadata.module ?? "default";
-  const loader = new Loader();
+  const loader = new Loader([new LocalFileAdapter()]);
 
-  // Load target module manifests. Inject variables/secrets as compile context so that
-  // ${{ variables.x }} / ${{ secrets.y }} templates in the child module resolve correctly.
+  const moduleSource: string = resource.module ?? resource.source;
+
+  // Validate the imported module and all its transitive imports before loading for runtime.
+  // loadManifests() follows Kernel.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 = new URL(moduleSource, ctx.moduleContext.source).toString();
+  const analysisManifests = await loader.loadManifests(resolvedUrl);
+  const diagnostics = new StaticAnalyzer().analyze(analysisManifests);
+  const errors = diagnostics.filter((d) => d.severity === DiagnosticSeverity.Error);
+  if (errors.length > 0) {
+    throw new RuntimeError(
+      "ERR_MANIFEST_VALIDATION_FAILED",
+      errors.map((d) => d.message).join("\n"),
+    );
+  }
+
+  // Load target module manifests for runtime. Inject variables/secrets as compile context so
+  // that ${{ variables.x }} / ${{ secrets.y }} templates in the child module resolve correctly.
   // No env — child modules are isolated from host environment.
-  const manifests = await loader.loadManifest(resource.source as string, ctx.moduleContext.source, {
-    // Potentially not needed
-    variables: (resource.variables as Record<string, unknown>) ?? {},
-    secrets: (resource.secrets as Record<string, unknown>) ?? {},
-  });
+  const manifests = await loader.loadModule(
+    new URL(moduleSource, ctx.moduleContext.source).toString(),
+    {
+      compile: true,
+    },
+  );
   // Find the kind: Module manifest to learn the target module name and contract.
   const moduleManifest = manifests.find((m: any) => m.kind === "Kernel.Module");
   if (!moduleManifest) {
@@ -22,22 +39,6 @@ export async function create(resource: any, ctx: ResourceContext): Promise<Resou
   }
   const targetModule: string = moduleManifest.metadata.name;
 
-  // Validate that every non-module manifest's metadata.module (when explicitly set)
-  // matches the target module name.  A mismatch means the author put the wrong module
-  // name in a resource's metadata, which would silently give it an empty context and
-  // produce a confusing CEL "Identifier not found" error at runtime.
-  for (const manifest of manifests) {
-    if (manifest.kind === "Kernel.Module") continue;
-    const declaredModule: string | undefined = manifest.metadata?.module;
-    if (declaredModule && declaredModule !== targetModule) {
-      throw new Error(
-        `Resource '${manifest.metadata?.name ?? "(unnamed)"}' (kind: ${manifest.kind}) inside module '${targetModule}' ` +
-          `has metadata.module: '${declaredModule}', but the module is named '${targetModule}'. ` +
-          `Update metadata.module to '${targetModule}'.`,
-      );
-    }
-  }
-
   // Validate required inputs before injecting.
   validateRequiredInputs(moduleManifest.variables ?? {}, resource.variables ?? {}, "variables");
   validateRequiredInputs(moduleManifest.secrets ?? {}, resource.secrets ?? {}, "secrets");
@@ -82,8 +83,8 @@ export async function create(resource: any, ctx: ResourceContext): Promise<Resou
   // in the declaring module's evaluation context — no separate imports namespace needed.
   return {
     snapshot: () => ({
-      variables: (resource.variables as Record<string, unknown>) ?? {},
-      secrets: (resource.secrets as Record<string, unknown>) ?? {},
+      variables: ctx.expandValue(resource.variables, {}) ?? {},
+      secrets: ctx.expandValue(resource.secrets, {}) ?? {},
     }),
     run: async () => {
       // Proxy run to target module
@@ -128,7 +129,6 @@ export const schema = {
       type: "object",
       properties: {
         name: { type: "string" },
-        source: { type: "string" },
         module: { type: "string" },
       },
       required: ["name"],

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

@@ -1,27 +1,6 @@
 import type { ResourceContext, ResourceInstance } from "@telorun/sdk";
-import { Loader } from "../../loader.js";
 
 export async function create(resource: any, ctx: ResourceContext): Promise<ResourceInstance> {
-  const moduleName = resource.metadata.name as string;
-  const loader = new Loader();
-
-  for (const includePath of (resource.include as string[]) ?? []) {
-    const manifests = await loader.loadManifest(
-      includePath,
-      resource.metadata.source as string,
-      {},
-    );
-    for (const manifest of manifests) {
-      if (manifest.kind === "Kernel.Module") {
-        throw new Error(`Included file "${includePath}" must not declare kind: Module`);
-      }
-      if (!manifest.metadata.module) {
-        manifest.metadata.module = moduleName;
-      }
-      ctx.registerManifest(manifest);
-    }
-  }
-
   return {
     run: async () => {
       for (const target of (resource.targets as string[]) ?? []) {
@@ -35,33 +14,3 @@ export async function create(resource: any, ctx: ResourceContext): Promise<Resou
   };
 }
 
-export const schema = {
-  type: "object",
-  properties: {
-    kind: { type: "string" },
-    metadata: {
-      type: "object",
-      properties: {
-        name: { type: "string" },
-        version: { type: "string" },
-        source: { type: "string" },
-        module: { type: "string" },
-      },
-      required: ["name"],
-      additionalProperties: true,
-    },
-    include: { type: "array", items: { type: "string" } },
-    variables: { type: "object" },
-    secrets: { type: "object" },
-    targets: { type: "array", items: { type: "string" } },
-    exports: {
-      type: "object",
-      properties: {
-        kinds: { type: "array", items: { type: "string" } },
-      },
-      additionalProperties: true,
-    },
-  },
-  required: ["metadata"],
-  additionalProperties: false,
-};

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

@@ -6,18 +6,18 @@ import type {
 } from "@telorun/sdk";
 import { ControllerLoader } from "../../controller-loader.js";
 import { formatAjvErrors, validateResourceDefinition } from "../../manifest-schemas.js";
+import { createTemplateController } from "./resource-template-controller.js";
 
 type ResourceDefinitionResource = RuntimeResource & {
-  kind: "Definition";
+  kind: "Kernel.Definition";
   metadata: {
     [key: string]: any;
     name: string;
     module?: string;
   };
   schema: Record<string, any>;
-  capabilities: string[];
-  events?: string[];
-  controllers: Array<string>;
+  capability?: string;
+  controllers?: Array<string>;
 };
 
 /**
@@ -33,16 +33,15 @@ class ResourceDefinition implements ResourceInstance {
   ) {}
 
   async init(ctx: ResourceContext) {
-    for (const cap of this.resource.capabilities) {
-      if (!ctx.isCapabilityRegistered(cap)) {
-        throw new Error(
-          `Capability "${cap}" is not registered. Declare it as a Kernel.Capability resource.`,
-        );
-      }
-      const capSchema = ctx.getCapabilitySchema(cap);
-      if (capSchema) {
-        ctx.validateSchema(this.resource, capSchema);
-      }
+    if (!this.resource.controllers?.length) {
+      const controllerInstance = createTemplateController(this.resource as any);
+      ctx.registerDefinition(this.resource);
+      await ctx.registerController(
+        this.resource.metadata.module,
+        this.resource.metadata.name,
+        controllerInstance,
+      );
+      return;
     }
     ctx.emit("ControllerLoading", { controllers: this.resource.controllers });
     try {
@@ -77,7 +76,7 @@ export async function create(resource: any, ctx: ResourceContext): Promise<Resou
   }
 
   // Return a fully-formed ResourceDefinition instance
-  const definition = resource as ResourceDefinitionResource;
+  const definition = resource as unknown as ResourceDefinitionResource;
   return new ResourceDefinition(definition, new ControllerLoader());
 }
 

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

@@ -0,0 +1,138 @@
+import type { ControllerInstance, ResourceContext, ResourceInstance } from "@telorun/sdk";
+import { isCompiledValue } from "@telorun/sdk";
+
+export function createTemplateController(definition: {
+  schema: Record<string, any>;
+  resources?: any[];
+  invoke?: string | { kind?: string; name: string; inputs?: Record<string, any> };
+  run?: string;
+}): ControllerInstance {
+  return {
+    schema: definition.schema ?? { type: "object", additionalProperties: true },
+
+    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`.
+      const objectInvoke =
+        definition.invoke !== null &&
+        typeof definition.invoke === "object" &&
+        !isCompiledValue(definition.invoke)
+          ? (definition.invoke as { kind?: string; name: string; inputs?: Record<string, any> })
+          : null;
+      const invokeNameTemplate = objectInvoke ? objectInvoke.name : (definition.invoke ?? null);
+      const invokeTarget = invokeNameTemplate
+        ? (ctx.moduleContext.expandWith(invokeNameTemplate, { self }) as string)
+        : null;
+      const runTarget = definition.run
+        ? (ctx.moduleContext.expandWith(definition.run, { self }) as string)
+        : null;
+
+      const persistentManifests: any[] = [];
+      let ephemeralTemplate: any = null;
+
+      for (const template of definition.resources ?? []) {
+        const expandedName = ctx.moduleContext.expandWith(template.metadata?.name ?? "", {
+          self,
+        }) as string;
+        const isTarget = expandedName === invokeTarget || expandedName === runTarget;
+        if (isTarget) {
+          ephemeralTemplate = template;
+        } else {
+          persistentManifests.push(ctx.moduleContext.expandWith(template, { self }));
+        }
+      }
+
+      const childContext = ctx.spawnChildContext();
+
+      // Registers an ephemeral manifest on ctx.moduleContext so it shares the same
+      // resource scope (and can access connections, etc. via getInstance).
+      // Tears down and removes the resource after fn() completes.
+      const withEphemeral = async (expandedManifest: any, fn: (name: string) => Promise<any>) => {
+        const uniqueName = `${expandedManifest.metadata?.name ?? "eph"}__${Math.random().toString(16).slice(2, 8)}`;
+        const manifest = {
+          ...expandedManifest,
+          metadata: {
+            ...expandedManifest.metadata,
+            name: uniqueName,
+            module: resource.metadata.module,
+          },
+        };
+        ctx.moduleContext.registerManifest(manifest);
+        await ctx.moduleContext.initializeResources();
+        const entry = ctx.moduleContext.resourceInstances.get(uniqueName);
+        try {
+          return await fn(uniqueName);
+        } finally {
+          if (entry?.instance?.teardown) await entry.instance.teardown();
+          ctx.moduleContext.resourceInstances.delete(uniqueName);
+        }
+      };
+
+      return {
+        init: async () => {
+          for (const m of persistentManifests) childContext.registerManifest(m);
+          await childContext.initializeResources();
+        },
+
+        ...(invokeTarget && {
+          invoke: async (inputs: any) => {
+            if (!ephemeralTemplate) {
+              throw new Error(
+                `Template '${resource.metadata.name}': no ephemeral resource for invoke target '${invokeTarget}'`,
+              );
+            }
+            const extraContext = { self, inputs };
+            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) {
+                throw new Error(`Ephemeral resource '${name}' is not invocable`);
+              }
+              // 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
+                ? ctx.moduleContext.expandWith(
+                    ctx.moduleContext.expandWith(objectInvoke.inputs, extraContext),
+                    extraContext,
+                  )
+                : expanded.inputs ?? inputs;
+              return entry.instance.invoke(invokeInputs);
+            });
+          },
+        }),
+
+        ...(runTarget && {
+          run: async () => {
+            if (!ephemeralTemplate) {
+              throw new Error(
+                `Template '${resource.metadata.name}': no ephemeral resource for run target '${runTarget}'`,
+              );
+            }
+            const extraContext = { self };
+            const expanded = ctx.moduleContext.expandWith(
+              ctx.moduleContext.expandWith(ephemeralTemplate, extraContext),
+              extraContext,
+            );
+            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`);
+              }
+              return entry.instance.run();
+            });
+          },
+        }),
+
+        teardown: async () => {
+          await childContext.teardownResources();
+        },
+      };
+    },
+  };
+}

package/src/index.ts

@@ -1,7 +1,7 @@
 export { ControllerRegistry } from "./controller-registry.js";
 export { EventStream } from "./event-stream.js";
-export { Kernel } from "./kernel.js";
-export { Loader } from "./loader.js";
+export { Kernel, type KernelOptions } from "./kernel.js";
 export { ManifestRegistry as Registry } from "./registry.js";
 export { ResourceURI } from "./resource-uri.js";
+export type { RuntimeDiagnostic } from "@telorun/sdk";