@telorun/kernel 0.2.5 → 0.2.6

package/src/loader.ts

@@ -1,30 +1,17 @@
+import { Loader as BaseLoader } from "@telorun/analyzer";
 import { ResourceManifest, RuntimeResource } from "@telorun/sdk";
-import { compile } from "@telorun/yaml-cel-templating";
 import * as path from "path";
-import { HttpAdapter } from "./manifest-adapters/http-adapter.js";
 import { LocalFileAdapter } from "./manifest-adapters/local-file-adapter.js";
-import type { ManifestAdapter, ManifestSourceData } from "./manifest-adapters/manifest-adapter.js";
-import { RegistryAdapter } from "./manifest-adapters/registry-adapter.js";
 import { formatAjvErrors, validateRuntimeResource } from "./manifest-schemas.js";
 
-/**
- * Loader: Ingests resolved YAML manifests from disk or remote URLs into memory
- */
-export class Loader {
+export class Loader extends BaseLoader {
   private static projectRoot: string | null = null;
+  private readonly localAdapter: LocalFileAdapter;
 
-  private readonly adapters: ManifestAdapter[] = [
-    new HttpAdapter(),
-    new RegistryAdapter(),
-    new LocalFileAdapter(),
-  ];
-
-  private getAdapter(pathOrUrl: string): ManifestAdapter {
-    const adapter = this.adapters.find((a) => a.supports(pathOrUrl));
-    if (!adapter) {
-      throw new Error(`No manifest adapter found for: ${pathOrUrl}`);
-    }
-    return adapter;
+  constructor() {
+    super();
+    this.localAdapter = new LocalFileAdapter();
+    this.register(this.localAdapter);
   }
 
   private static ensureProjectRoot(baseDir: string): void {
@@ -34,15 +21,39 @@ export class Loader {
   }
 
   resolvePath(base: string, relative: string): string {
-    return this.getAdapter(base).resolveRelative(base, relative);
+    return this.localAdapter.resolveRelative(base, relative);
+  }
+
+  /**
+   * Resolve a path-or-URL to its canonical file source URL.
+   * If the path refers to a directory, returns the URL of module.yaml inside it.
+   */
+  async resolveEntryPoint(pathOrUrl: string): Promise<string> {
+    const { source } = await this.localAdapter.read(pathOrUrl);
+    return source;
   }
 
   async loadDirectory(pathOrUrl: string): Promise<ResourceManifest[]> {
-    const files = await this.getAdapter(pathOrUrl).readAll(pathOrUrl);
-    Loader.ensureProjectRoot(files[0]?.baseDir ?? process.cwd());
+    const sources = await this.localAdapter.readAll(pathOrUrl);
+    const firstPath = sources[0] ? new URL(sources[0]).pathname : process.cwd();
+    Loader.ensureProjectRoot(path.dirname(firstPath));
     const resources: RuntimeResource[] = [];
-    for (const file of files) {
-      await this.processFile(file, resources, { env: process.env });
+    for (const source of sources) {
+      const manifests = await this.loadModule(source);
+      for (const m of manifests) {
+        if (!m.metadata?.name) continue;
+        const resource = m as RuntimeResource;
+        if (!validateRuntimeResource(resource)) {
+          throw new Error(
+            `Resource validation failed for ${m.kind}.${m.metadata.name}: ${formatAjvErrors(validateRuntimeResource.errors)}`,
+          );
+        }
+        const filePath = new URL(m.metadata.source as string).pathname;
+        const uriBase = `file://localhost${filePath.replace(/\\/g, "/")}`;
+        resource.metadata.uri = `${uriBase}#${m.kind}.${m.metadata.name as string}`;
+        resource.metadata.generationDepth = 0;
+        resources.push(resource);
+      }
     }
     return this.orderResourcesByKindDependencies(resources);
   }
@@ -56,146 +67,35 @@ export class Loader {
       throw new Error("Base URL is required to load target manifest");
     }
     const url = new URL(pathOrUrl, baseUrl).toString();
-    const file = await this.getAdapter(url).read(url);
     if (!Loader.projectRoot) {
-      Loader.ensureProjectRoot(file.baseDir);
+      Loader.ensureProjectRoot(path.dirname(new URL(url).pathname));
     }
-
-    const resolved: ResourceManifest[] = [];
-    for (const rawDoc of file.documents) {
-      let compiled: any;
-      try {
-        compiled = compile(rawDoc, { context: compileContext });
-      } catch (error) {
-        throw new Error(
-          `Failed to compile manifest in ${file.source}: ${error instanceof Error ? error.message : String(error)}`,
-        );
-      }
-      const compiledDocs = Array.isArray(compiled) ? compiled : [compiled];
-      for (const manifest of compiledDocs) {
-        if (manifest === null) {
-          // Ignore empty documents
-          continue;
-        }
-        const resource: ResourceManifest = {
-          ...manifest,
-          metadata: {
-            ...manifest.metadata,
-            source: file.source,
-          },
-        };
-        resolved.push(resource);
-      }
-    }
-
-    // Auto-assign metadata.module from the file's Kernel.Module declaration to
-    // any resource that doesn't explicitly declare one. This matches the implicit
-    // convention that resources in the same file belong to the declared module.
-    const moduleName = resolved.find((m) => m.kind === "Kernel.Module")?.metadata?.name;
-    if (moduleName) {
-      for (const manifest of resolved) {
-        if (manifest.kind !== "Kernel.Module" && !manifest.metadata?.module) {
-          manifest.metadata = { ...manifest.metadata, module: moduleName };
-        }
-      }
-    }
-
-    return resolved;
+    return this.loadModule(url, { compile: true });
   }
 
-  private async processFile(
-    file: ManifestSourceData,
-    resources: RuntimeResource[],
-    compileContext: Record<string, unknown> = {},
-  ): Promise<void> {
-    const documents = file.documents;
-
-    for (const rawDoc of documents) {
-      let compiled: any;
-      try {
-        compiled = compile(rawDoc, { context: compileContext });
-      } catch (error) {
-        throw new Error(
-          `Failed to compile manifest in ${file.source}: ${error instanceof Error ? error.message : String(error)}`,
-        );
-      }
-      const compiledDocs = Array.isArray(compiled) ? compiled : [compiled];
-      for (const doc of compiledDocs) {
-        const resource = this.normalizeResource(doc);
-        if (!resource) {
-          continue;
-        }
-        if (!validateRuntimeResource(resource)) {
-          const kind = (resource as any).kind;
-          const name = (resource as any).metadata?.name;
-          throw new Error(
-            `Resource validation failed for ${kind}.${name}: ${formatAjvErrors(validateRuntimeResource.errors)}`,
-          );
-        }
-
-        const { kind, name } = resource.metadata;
-        resource.metadata.source = file.source;
-        resource.metadata.uri = `${file.uriBase}#${kind}.${name}`;
-        resource.metadata.generationDepth = 0;
-
-        resources.push(resource);
-      }
-    }
-  }
-
-  private normalizeResource(doc: any): RuntimeResource | null {
-    if (!doc || typeof doc !== "object" || typeof doc.kind !== "string") {
-      return null;
-    }
-
-    // Already in correct format
-    if (doc.metadata && typeof doc.metadata === "object" && typeof doc.metadata.name === "string") {
-      return doc as RuntimeResource;
-    }
-
-    return null;
-  }
-
-  // Validation handled by TypeBox + Ajv schemas.
-
   private orderResourcesByKindDependencies(resources: RuntimeResource[]): RuntimeResource[] {
-    if (resources.length <= 1) {
-      return resources;
-    }
+    if (resources.length <= 1) return resources;
 
     const indicesByName = new Map<string, number[]>();
-    for (let i = 0; i < resources.length; i += 1) {
+    for (let i = 0; i < resources.length; i++) {
       const name = resources[i]?.metadata?.name;
-      if (!name) {
-        continue;
-      }
+      if (!name) continue;
       const list = indicesByName.get(name);
-      if (list) {
-        list.push(i);
-      } else {
-        indicesByName.set(name, [i]);
-      }
+      if (list) list.push(i);
+      else indicesByName.set(name, [i]);
     }
 
     const edges = new Map<number, Set<number>>();
     const indegree = new Map<number, number>();
-    for (let i = 0; i < resources.length; i += 1) {
-      indegree.set(i, 0);
-    }
+    for (let i = 0; i < resources.length; i++) indegree.set(i, 0);
 
-    for (let i = 0; i < resources.length; i += 1) {
+    for (let i = 0; i < resources.length; i++) {
       const kind = resources[i]?.kind;
-      if (!kind) {
-        continue;
-      }
+      if (!kind) continue;
       const definers = indicesByName.get(kind);
-      if (!definers) {
-        continue;
-      }
+      if (!definers) continue;
       for (const definerIndex of definers) {
-        if (definerIndex === i) {
-          continue;
-        }
+        if (definerIndex === i) continue;
         let set = edges.get(definerIndex);
         if (!set) {
           set = new Set();
@@ -209,10 +109,8 @@ export class Loader {
     }
 
     const ready: number[] = [];
-    for (let i = 0; i < resources.length; i += 1) {
-      if ((indegree.get(i) || 0) === 0) {
-        ready.push(i);
-      }
+    for (let i = 0; i < resources.length; i++) {
+      if ((indegree.get(i) || 0) === 0) ready.push(i);
     }
     ready.sort((a, b) => a - b);
 
@@ -221,25 +119,16 @@ export class Loader {
       const index = ready.shift() as number;
       ordered.push(resources[index]);
       const next = edges.get(index);
-      if (!next) {
-        continue;
-      }
+      if (!next) continue;
       for (const dependent of next) {
         const count = (indegree.get(dependent) || 0) - 1;
         indegree.set(dependent, count);
-        if (count === 0) {
-          ready.push(dependent);
-        }
+        if (count === 0) ready.push(dependent);
       }
-      if (ready.length > 1) {
-        ready.sort((a, b) => a - b);
-      }
-    }
-
-    if (ordered.length !== resources.length) {
-      throw new Error("Resource dependency cycle detected");
+      if (ready.length > 1) ready.sort((a, b) => a - b);
     }
 
+    if (ordered.length !== resources.length) throw new Error("Resource dependency cycle detected");
     return ordered;
   }
 }

package/src/manifest-adapters/local-file-adapter.ts

@@ -1,7 +1,6 @@
+import type { ManifestAdapter } from "@telorun/analyzer";
 import * as fs from "fs/promises";
-import * as yaml from "js-yaml";
 import * as path from "path";
-import type { ManifestAdapter, ManifestSourceData } from "./manifest-adapter.js";
 
 export class LocalFileAdapter implements ManifestAdapter {
   supports(pathOrUrl: string): boolean {
@@ -9,58 +8,52 @@ export class LocalFileAdapter implements ManifestAdapter {
       pathOrUrl.startsWith("file://") ||
       pathOrUrl.startsWith("/") ||
       pathOrUrl.startsWith("./") ||
-      pathOrUrl.startsWith("../")
+      pathOrUrl.startsWith("../") ||
+      (!pathOrUrl.includes("://") && !pathOrUrl.includes("@"))
     );
   }
 
-  async read(pathOrUrl: string): Promise<ManifestSourceData> {
+  async read(pathOrUrl: string): Promise<{ text: string; source: string }> {
     const normalizedPath = pathOrUrl.startsWith("file://")
-      ? pathOrUrl.replace("file://", "")
+      ? new URL(pathOrUrl).pathname
       : pathOrUrl;
-    const stat = await fs.stat(normalizedPath);
-    const filePath = stat.isDirectory() ? path.join(normalizedPath, "module.yaml") : normalizedPath;
-    return this.readFile(filePath);
+    const resolvedPath = path.resolve(normalizedPath);
+    const stat = await fs.stat(resolvedPath);
+    const filePath = stat.isDirectory() ? path.join(resolvedPath, "module.yaml") : resolvedPath;
+    const text = await fs.readFile(filePath, "utf-8");
+    return { text, source: `file://${filePath}` };
   }
 
-  async readAll(pathOrUrl: string): Promise<ManifestSourceData[]> {
+  async readAll(pathOrUrl: string): Promise<string[]> {
     const normalizedPath = pathOrUrl.startsWith("file://")
-      ? pathOrUrl.replace("file://", "")
+      ? new URL(pathOrUrl).pathname
       : pathOrUrl;
-    const stat = await fs.stat(normalizedPath);
+    const resolvedPath = path.resolve(normalizedPath);
+    const stat = await fs.stat(resolvedPath);
     if (stat.isDirectory()) {
-      const results: ManifestSourceData[] = [];
-      await this.collectYamlFiles(normalizedPath, results);
-      return results;
+      return this.collectYamlSources(resolvedPath);
     }
-    return [await this.readFile(normalizedPath)];
+    return [`file://${resolvedPath}`];
   }
 
   resolveRelative(base: string, relative: string): string {
-    const basePath = base.startsWith("file://") ? base.slice("file://".length) : base;
-    return `file://${path.resolve(basePath, relative)}`;
+    const basePath = base.startsWith("file://") ? new URL(base).pathname : base;
+    const baseDir = basePath.endsWith("/") ? basePath : path.dirname(basePath);
+    return `file://${path.resolve(baseDir, relative)}`;
   }
 
-  private async readFile(filePath: string): Promise<ManifestSourceData> {
-    const content = await fs.readFile(filePath, "utf-8");
-
-    return {
-      documents: yaml.loadAll(content),
-      source: `file://${filePath}`,
-      baseDir: path.dirname(filePath),
-      uriBase: `file://localhost${filePath.replace(/\\/g, "/")}`,
-    };
-  }
-
-  private async collectYamlFiles(dirPath: string, results: ManifestSourceData[]): Promise<void> {
+  private async collectYamlSources(dirPath: string): Promise<string[]> {
+    const sources: string[] = [];
     const entries = await fs.readdir(dirPath, { withFileTypes: true });
     for (const entry of entries) {
       const fullPath = path.join(dirPath, entry.name);
       if (entry.isDirectory()) {
-        await this.collectYamlFiles(fullPath, results);
+        sources.push(...(await this.collectYamlSources(fullPath)));
       } else if (entry.isFile() && this.isYamlFile(entry.name)) {
-        results.push(await this.readFile(fullPath));
+        sources.push(`file://${fullPath}`);
       }
     }
+    return sources;
   }
 
   private isYamlFile(filename: string): boolean {

package/src/manifest-adapters/manifest-adapter.ts

@@ -1,4 +1,6 @@
 export interface ManifestSourceData {
+  /** Raw YAML text */
+  text: string;
   /** Parsed YAML documents (result of yaml.loadAll) */
   documents: any[];
   /** Stored as metadata.source (file path or URL) */

package/src/manifest-schemas.ts

@@ -1,5 +1,5 @@
 import { Type } from "@sinclair/typebox";
-import AjvModule, { ErrorObject } from "ajv";
+import AjvModule from "ajv";
 import addFormats from "ajv-formats";
 const Ajv = AjvModule.default ?? AjvModule;
 
@@ -11,23 +11,62 @@ export const RuntimeResourceSchema = Type.Object(
   { additionalProperties: true },
 );
 
-export const ResourceDefinitionSchema = Type.Object(
-  {
-    kind: Type.Literal("Kernel.Definition"),
-    metadata: Type.Object(
-      {
-        name: Type.String(),
-        module: Type.Optional(Type.String()),
-      },
-      { additionalProperties: true },
-    ),
-    schema: Type.Object({}, { additionalProperties: true }),
-    capabilities: Type.Array(Type.String(), { minItems: 1 }),
-    events: Type.Optional(Type.Array(Type.String())),
-    controllers: Type.Optional(Type.Array(Type.String())),
+const metadataSchema = {
+  type: "object",
+  required: ["name"],
+  properties: {
+    name: { type: "string" },
+    module: { type: "string" },
   },
-  { additionalProperties: true },
-);
+  additionalProperties: true,
+};
+
+const baseDefinition = {
+  type: "object",
+  required: ["kind", "metadata"],
+  properties: {
+    kind: { const: "Kernel.Definition" },
+    metadata: metadataSchema,
+    capability: { type: "string" },
+    schema: { type: "object", additionalProperties: true },
+    controllers: { type: "array", items: { type: "string" } },
+  },
+  unevaluatedProperties: false,
+};
+
+const KNOWN_CAPABILITIES = [
+  "Kernel.Service",
+  "Kernel.Runnable",
+  "Kernel.Invocable",
+  "Kernel.Provider",
+  "Kernel.Type",
+  "Kernel.Mount",
+] as const;
+
+export const ResourceDefinitionSchema = {
+  ...baseDefinition,
+  oneOf: [
+    { required: ["capability"], properties: { capability: { const: "Kernel.Service" } } },
+    { required: ["capability"], properties: { capability: { const: "Kernel.Runnable" } } },
+    { required: ["capability"], properties: { capability: { const: "Kernel.Invocable" } } },
+    { required: ["capability"], properties: { capability: { const: "Kernel.Provider" } } },
+    { required: ["capability"], properties: { capability: { const: "Kernel.Type" } } },
+    {
+      required: ["capability"],
+      properties: {
+        capability: { const: "Kernel.Mount" },
+      },
+    },
+    // Unknown/absent capability: open schema for third-party extensibility
+    {
+      not: {
+        required: ["capability"],
+        properties: { capability: { enum: KNOWN_CAPABILITIES } },
+      },
+      unevaluatedProperties: true,
+    },
+  ],
+};
 
 const ajv = new Ajv({ allErrors: true, strict: false });
 addFormats.default(ajv);
@@ -35,15 +74,12 @@ addFormats.default(ajv);
 export const validateRuntimeResource = ajv.compile(RuntimeResourceSchema);
 export const validateResourceDefinition = ajv.compile(ResourceDefinitionSchema);
 
-export function formatAjvErrors(errors: ErrorObject[] | null | undefined): string {
-  if (!errors || errors.length === 0) {
-    return "Unknown schema error";
-  }
+export function formatAjvErrors(errors: any[] | null | undefined): string {
+  if (!errors || errors.length === 0) return "Unknown schema error";
   return errors
     .map((err) => {
-      const path = err.instancePath && err.instancePath.length > 0 ? err.instancePath : "/";
-      const message = err.message || "is invalid";
-      return `${path} ${message}`;
+      const p = err.instancePath || "/";
+      return `${p} ${err.message ?? "is invalid"}`;
     })
     .join("; ");
 }

package/src/resource-context.ts

@@ -5,6 +5,7 @@ import {
   ResourceContext,
   RuntimeError,
   RuntimeResource,
+  isCompiledValue,
 } from "@telorun/sdk";
 import AjvModule from "ajv";
 import addFormats from "ajv-formats";
@@ -42,8 +43,13 @@ export class ResourceContextImpl implements ResourceContext {
   }
 
   validateSchema(value: any, schema: any) {
-    const ajv = new Ajv();
+    const ajv = new Ajv({
+      removeAdditional: true,
+    });
     addFormats.default(ajv);
+    for (const kw of ["x-telo-ref", "x-telo-scope", "x-telo-context", "x-telo-schema-from"]) {
+      ajv.addKeyword(kw);
+    }
     const validate = ajv.compile(
       "type" in schema && typeof schema.type === "string"
         ? schema
@@ -54,17 +60,17 @@ export class ResourceContextImpl implements ResourceContext {
             additionalProperties: false,
           },
     );
-    const isValid = validate(value);
+    const isValid = validate(stripCompiledValues(value));
     if (!isValid) {
       throw new RuntimeError(
         "ERR_INVALID_VALUE",
-        `[${this.metadata.name}] Invalid value passed: ${JSON.stringify(value)}. Error: ${formatAjvErrors(validate.errors)}`,
+        `[${this.metadata.name}] Invalid value. Error: ${formatAjvErrors(validate.errors)}`,
       );
     }
   }
 
-  invoke(kind: string, name: string, ...args: any[]): Promise<any> {
-    return this.moduleContext.invoke(kind, name, ...args);
+  invoke<TInputs>(kind: string, name: string, inputs: TInputs): Promise<any> {
+    return this.moduleContext.invoke(kind, name, inputs);
   }
 
   async run(name: string) {
@@ -112,7 +118,7 @@ export class ResourceContextImpl implements ResourceContext {
       (k) => k !== "kind" && k !== "name" && k !== "metadata",
     );
 
-    if (definitionKeys.length > 0) {
+    if (definitionKeys.length > 0 && !this.moduleContext.hasManifest(name)) {
       this.registerManifest({
         ...resource,
         metadata: {
@@ -157,18 +163,6 @@ export class ResourceContextImpl implements ResourceContext {
     this.kernel.registerResourceDefinition(def);
   }
 
-  registerCapability(name: string, schema?: Record<string, any>): void {
-    this.kernel.registerCapability(name, schema);
-  }
-
-  isCapabilityRegistered(name: string): boolean {
-    return this.kernel.isCapabilityRegistered(name);
-  }
-
-  getCapabilitySchema(name: string): Record<string, any> | null | undefined {
-    return this.kernel.getCapabilitySchema(name);
-  }
-
   on(event: string, handler: (payload?: any) => void | Promise<void>): void {
     this.kernel.on(event, handler);
   }
@@ -193,18 +187,8 @@ export class ResourceContextImpl implements ResourceContext {
     this.kernel.requestExit(code);
   }
 
-  evaluateCel(expression: string, context: Record<string, any>): unknown {
-    return new EvaluationContext(
-      this.moduleContext.source,
-      context,
-      undefined,
-      new Set(),
-      this.emit,
-    ).evaluate(expression);
-  }
-
   expandValue(value: any, context: Record<string, any>) {
-    return this.moduleContext.merge(context).expand(value);
+    return this.moduleContext.expandWith(value, context);
   }
 
   async emitEvent(event: string, payload?: any) {
@@ -240,6 +224,10 @@ export class ResourceContextImpl implements ResourceContext {
     return this.moduleContext.spawnChild(child);
   }
 
+  transientChild(context: Record<string, any>): EvaluationContext {
+    return this.moduleContext.transientChild(context);
+  }
+
   /**
    * Create a temporary child context, queue manifests on it, run a function,
    * then tear down the child context and its resources.
@@ -259,8 +247,21 @@ export class ResourceContextImpl implements ResourceContext {
         await child.initializeResources();
         return await Promise.resolve(fn() as any);
       } finally {
-        await this.kernel.teardownContext(child);
+        await child.teardownResources();
       }
     })() as unknown as T;
   }
 }
+
+function stripCompiledValues(v: unknown): unknown {
+  if (isCompiledValue(v)) return "";
+  if (Array.isArray(v)) return v.map(stripCompiledValues);
+  if (v !== null && typeof v === "object") {
+    const out: Record<string, unknown> = {};
+    for (const [k, val] of Object.entries(v as Record<string, unknown>)) {
+      out[k] = stripCompiledValues(val);
+    }
+    return out;
+  }
+  return v;
+}

package/src/schema-valiator.ts

@@ -28,7 +28,7 @@ export class SchemaValidator {
   }
 
   compile(schema: any): DataValidator {
-    const validate = this.ajv.compile(
+    const normalized =
       "type" in schema && typeof schema.type === "string"
         ? schema
         : {
@@ -36,8 +36,19 @@ export class SchemaValidator {
             properties: schema,
             required: Object.keys(schema),
             additionalProperties: false,
-          },
-    );
+          };
+    const injected =
+      normalized.additionalProperties === false
+        ? {
+            ...normalized,
+            properties: {
+              kind: { type: "string" },
+              metadata: { type: "object" },
+              ...normalized.properties,
+            },
+          }
+        : normalized;
+    const validate = this.ajv.compile(injected);
 
     return {
       validate: (data: any) => {

package/src/capabilities/component.yaml

@@ -1,4 +0,0 @@
-kind: Kernel.Capability
-metadata:
-  module: Kernel
-  name: component

package/src/capabilities/executable.yaml

@@ -1,8 +0,0 @@
-kind: Kernel.Capability
-metadata:
-  module: Kernel
-  name: executable
-schema:
-  type: object
-  properties:
-    foo: { type: string }

package/src/capabilities/handler.yaml

@@ -1,4 +0,0 @@
-kind: Kernel.Capability
-metadata:
-  module: Kernel
-  name: handler

package/src/capabilities/listener.yaml

@@ -1,4 +0,0 @@
-kind: Kernel.Capability
-metadata:
-  module: Kernel
-  name: listener

package/src/capabilities/provider.yaml

@@ -1,4 +0,0 @@
-kind: Kernel.Capability
-metadata:
-  module: Kernel
-  name: provider

package/src/capabilities/template.yaml

@@ -1,4 +0,0 @@
-kind: Kernel.Capability
-metadata:
-  module: Kernel
-  name: template