@telorun/kernel 0.4.1 → 0.5.0

package/src/kernel.ts

@@ -1,6 +1,7 @@
 import { AnalysisRegistry, DEFAULT_MANIFEST_FILENAME, isModuleKind, Loader, StaticAnalyzer } from "@telorun/analyzer";
 import {
   ControllerContext,
+  ControllerPolicy,
   Kernel as IKernel,
   type LoadOptions,
   ResourceContext,
@@ -23,8 +24,22 @@ import { EventStream } from "./event-stream.js";
 import { EventBus } from "./events.js";
 import { LocalFileAdapter } from "./manifest-adapters/local-file-adapter.js";
 import { ResourceContextImpl } from "./resource-context.js";
+import { policyFingerprint } from "./runtime-registry.js";
 import { SchemaValidator } from "./schema-validator.js";
 
+/** Walks up the EvaluationContext parent chain to the nearest enclosing
+ *  ModuleContext and returns its controller policy (or undefined). Used to
+ *  pick the right cache entry when a kind has been loaded under multiple
+ *  runtime selections. */
+function findEnclosingPolicy(ctx: IEvaluationContext): ControllerPolicy | undefined {
+  let cur: IEvaluationContext | undefined = ctx;
+  while (cur) {
+    if (cur instanceof ModuleContext) return cur.getControllerPolicy();
+    cur = cur.parent;
+  }
+  return undefined;
+}
+
 export interface KernelOptions {
   stdin?: NodeJS.ReadableStream;
   stdout?: NodeJS.WritableStream;
@@ -83,8 +98,13 @@ export class Kernel implements IKernel {
     moduleName: string,
     kindName: string,
     controllerInstance: any,
+    fingerprint?: string,
   ): Promise<void> {
-    this.controllers.registerController(`${moduleName}.${kindName}`, controllerInstance);
+    this.controllers.registerController(
+      `${moduleName}.${kindName}`,
+      controllerInstance,
+      fingerprint,
+    );
     await controllerInstance.register?.(this.createControllerContext(`${moduleName}.${kindName}`));
   }
 
@@ -148,6 +168,10 @@ export class Kernel implements IKernel {
       "Telo.Definition",
       await import("./controllers/resource-definition/resource-definition-controller.js"),
     );
+    this.controllers.registerController(
+      "Telo.Abstract",
+      await import("./controllers/resource-definition/abstract-controller.js"),
+    );
     const moduleController = await import("./controllers/module/module-controller.js");
     this.controllers.registerController("Telo.Application", moduleController);
     this.controllers.registerController("Telo.Library", moduleController);
@@ -260,10 +284,12 @@ export class Kernel implements IKernel {
    * Phase 2: Start - Initialize resources
    */
   async start(): Promise<void> {
-    // Call controller register hooks first (before any initialization)
-    for (const kind of this.controllers.getKinds()) {
+    // Call register hooks for controllers actually loaded at this point (built-ins).
+    // User-module kinds load their controllers during Phase 3 (Telo.Definition.init),
+    // and registerController() fires their register hook there.
+    for (const kind of this.controllers.getControllerKinds()) {
       const controller = this.controllers.getController(kind);
-      if (controller?.register) {
+      if (controller.register) {
         await controller.register(this.createControllerContext(`controller:${kind}`));
       }
     }
@@ -475,12 +501,13 @@ export class Kernel implements IKernel {
     // resolveKind() throws with a clear message if the alias or kind is not found.
     const resolvedKind = this.rootContext.resolveKind(kind);
 
-    const controller = this.controllers.getControllerOrUndefined(resolvedKind);
+    const fingerprint = policyFingerprint(findEnclosingPolicy(evalContext));
+    const controller = this.controllers.getControllerOrUndefined(resolvedKind, fingerprint);
     if (!controller) {
       const kindInfo =
         resolvedKind !== kind ? `'${kind}' (resolved to '${resolvedKind}')` : `'${kind}'`;
       throw new Error(
-        `No controller registered for kind ${kindInfo}, known controllers are: ${this.controllers.getKinds().join(", ")}`,
+        `No controller registered for kind ${kindInfo} (runtime fingerprint "${fingerprint}"), known controllers are: ${this.controllers.getKinds().join(", ")}`,
       );
     }
 
@@ -539,14 +566,17 @@ export class Kernel implements IKernel {
 
     if (!runtime.length) return { instance, ctx };
 
-    const wrapped: ResourceInstance = {
-      ...instance,
-      invoke: async (inputs: any) => {
-        const expanded = evalContext.expandPaths(inputs as Record<string, unknown>, runtime);
-        return instance.invoke!(expanded);
-      },
+    // Override invoke in-place so all lifecycle methods (init/invoke/teardown/snapshot)
+    // share the same `this`. A wrapper object would split identity: state mutated by
+    // init() on the wrapper would be invisible to the original invoke(), which still
+    // runs with `this === instance`. Mutating in place also preserves the prototype
+    // chain — class-declared methods remain reachable.
+    const originalInvoke = instance.invoke!.bind(instance);
+    instance.invoke = async (inputs: any) => {
+      const expanded = evalContext.expandPaths(inputs as Record<string, unknown>, runtime);
+      return originalInvoke(expanded);
     };
-    return { instance: wrapped, ctx };
+    return { instance, ctx };
   }
 
   /**

package/src/manifest-schemas.ts

@@ -49,6 +49,16 @@ const throwsSchema = {
   },
 };
 
+/** Alias-form pattern for `extends` values: "<Alias>.<AbstractName>".
+ *  Resolved against the declaring file's `Telo.Import` aliases — identical to how
+ *  kind prefixes work (e.g. `kind: Http.Api` resolves `Http` via the importer's
+ *  alias registration). Identity form (`std/mod#Name`) is intentionally not
+ *  accepted: aliases carry the module version via their `Telo.Import` source,
+ *  which canonical module names can't.
+ *  - Alias: PascalCase (first letter uppercase)
+ *  - Name: PascalCase */
+const EXTENDS_ALIAS_PATTERN = "^[A-Z][A-Za-z0-9_]*\\.[A-Z][A-Za-z0-9_]*$";
+
 const baseDefinition = {
   type: "object",
   required: ["kind", "metadata"],
@@ -56,6 +66,7 @@ const baseDefinition = {
     kind: { const: "Telo.Definition" },
     metadata: metadataSchema,
     capability: { type: "string" },
+    extends: { type: "string", pattern: EXTENDS_ALIAS_PATTERN },
     schema: { type: "object", additionalProperties: true },
     controllers: { type: "array", items: { type: "string" } },
     throws: throwsSchema,
@@ -114,11 +125,33 @@ export const ResourceDefinitionSchema = {
   ],
 };
 
+/** Schema for `kind: Telo.Abstract`. Library-declared abstracts are type blueprints —
+ *  they may carry an optional `capability` (lifecycle inherited by implementations)
+ *  and an optional `schema` (shared base for implementations). `controllers` and `throws`
+ *  are forbidden (no runtime implementation; throws lives on concrete definitions).
+ *  Other fields are permitted for forward compatibility with typed-abstracts work
+ *  (inputType, outputType, …) — Telo.Abstract is an extension point by design. */
+export const ResourceAbstractSchema = {
+  type: "object",
+  required: ["kind", "metadata"],
+  properties: {
+    kind: { const: "Telo.Abstract" },
+    metadata: metadataSchema,
+    capability: { type: "string" },
+    schema: { type: "object", additionalProperties: true },
+  },
+  not: {
+    anyOf: [{ required: ["controllers"] }, { required: ["throws"] }],
+  },
+  additionalProperties: true,
+};
+
 const ajv = new Ajv({ allErrors: true, strict: false });
 addFormats.default(ajv);
 
 export const validateRuntimeResource = ajv.compile(RuntimeResourceSchema);
 export const validateResourceDefinition = ajv.compile(ResourceDefinitionSchema);
+export const validateResourceAbstract = ajv.compile(ResourceAbstractSchema);
 
 export function formatAjvErrors(errors: any[] | null | undefined): string {
   if (!errors || errors.length === 0) return "Unknown schema error";

package/src/module-context.ts

@@ -1,4 +1,8 @@
-import type { Invocable, ModuleContext as IModuleContext } from "@telorun/sdk";
+import type {
+  ControllerPolicy,
+  Invocable,
+  ModuleContext as IModuleContext,
+} from "@telorun/sdk";
 import type { EmitEvent, InstanceFactory } from "@telorun/sdk";
 import { EvaluationContext } from "./evaluation-context.js";
 
@@ -55,6 +59,15 @@ export class ModuleContext extends EvaluationContext implements IModuleContext {
   /** Maps import alias → allowed kind names. Absent entry = unrestricted (e.g. Kernel). */
   private readonly importedKinds = new Map<string, Set<string>>();
 
+  /**
+   * Resolved controller-selection policy for this module's `Telo.Definition`s.
+   * Stamped by the parent `Telo.Import` controller from the import's `runtime:`
+   * field; read by `Telo.Definition.init` (via `ResourceContext.getControllerPolicy`)
+   * when invoking `ControllerLoader.load`. `undefined` means "no policy set" —
+   * loader treats it as `auto`.
+   */
+  private _controllerPolicy: ControllerPolicy | undefined;
+
   constructor(
     source: string,
     variables: Record<string, unknown> = {},
@@ -103,6 +116,14 @@ export class ModuleContext extends EvaluationContext implements IModuleContext {
     this._rebuildContext();
   }
 
+  setControllerPolicy(policy: ControllerPolicy | undefined): void {
+    this._controllerPolicy = policy;
+  }
+
+  getControllerPolicy(): ControllerPolicy | undefined {
+    return this._controllerPolicy;
+  }
+
   protected override onResourceSnapshotted(name: string, snap: Record<string, unknown>): void {
     this.setResource(name, snap);
   }

package/src/resource-context.ts

@@ -6,6 +6,7 @@ import {
   RuntimeError,
   RuntimeResource,
   isCompiledValue,
+  type ControllerPolicy,
   type EvaluationContext as IEvaluationContext,
   type LoadOptions,
   type ModuleContext,
@@ -17,6 +18,7 @@ import AjvModule from "ajv";
 import addFormats from "ajv-formats";
 import { Kernel } from "./kernel.js";
 import { formatAjvErrors } from "./manifest-schemas.js";
+import { policyFingerprint } from "./runtime-registry.js";
 import { SchemaValidator } from "./schema-validator.js";
 
 const Ajv = AjvModule.default ?? AjvModule;
@@ -261,13 +263,18 @@ export class ResourceContextImpl implements ResourceContext {
     kindName: string,
     controllerInstance: any,
   ): Promise<void> {
-    await this.kernel.registerController(moduleName, kindName, controllerInstance);
+    const fingerprint = policyFingerprint(this.moduleContext.getControllerPolicy());
+    await this.kernel.registerController(moduleName, kindName, controllerInstance, fingerprint);
   }
 
   registerDefinition(def: any) {
     this.kernel.registerResourceDefinition(def);
   }
 
+  getControllerPolicy(): ControllerPolicy | undefined {
+    return this.moduleContext.getControllerPolicy();
+  }
+
   on(event: string, handler: (payload?: any) => void | Promise<void>): void {
     this.kernel.on(event, handler);
   }

package/src/runtime-registry.ts

@@ -0,0 +1,170 @@
+import type { ControllerPolicy } from "@telorun/sdk";
+import { RuntimeError } from "@telorun/sdk";
+
+export type { ControllerPolicy } from "@telorun/sdk";
+
+/**
+ * The PURL-type prefix the kernel itself runs (i.e. "no FFI" controllers
+ * for this kernel). For the Node.js kernel, that's `pkg:npm`. A future
+ * Rust kernel reports `pkg:cargo` here.
+ */
+export const KERNEL_NATIVE_PURL_TYPE = "pkg:npm";
+
+/**
+ * Wildcard sentinel inside a resolved `ControllerPolicy.load`. Means
+ * "all remaining controllers in declaration order, minus PURL types
+ * already listed earlier in the same policy." May appear at most once.
+ */
+export const POLICY_WILDCARD = "*";
+
+/**
+ * Maps user-facing runtime labels to PURL-type prefixes. The user-facing
+ * label is the implementation directory name a contributor sees at
+ * `modules/<name>/<label>/`.
+ */
+const LABEL_TO_PURL_TYPE: Readonly<Record<string, string>> = {
+  nodejs: "pkg:npm",
+  rust: "pkg:cargo",
+};
+
+/**
+ * Labels that only make sense as a single value (`runtime: auto`,
+ * `runtime: native`) — they describe a whole policy, not one slot in a
+ * list. `any` is also reserved but is allowed as the final list entry,
+ * so it is handled separately in `normalizeRuntime`.
+ */
+const SINGLE_ONLY_LABELS = new Set(["auto", "native"]);
+
+/**
+ * Default policy for missing `runtime:` field — equivalent to `runtime: auto`.
+ * Tries kernel-native first, then any other declared controller in declaration order.
+ */
+export const DEFAULT_POLICY: ControllerPolicy = {
+  load: [KERNEL_NATIVE_PURL_TYPE, POLICY_WILDCARD],
+};
+
+/**
+ * Resolve a `runtime:` field value (string, array, or undefined) into a
+ * canonical `ControllerPolicy`. Throws `ERR_RUNTIME_INVALID` on:
+ *  - empty array
+ *  - unknown label
+ *  - `any` anywhere but the final list entry
+ *  - duplicate label
+ */
+export function normalizeRuntime(value: string | ReadonlyArray<string> | undefined): ControllerPolicy {
+  if (value === undefined) {
+    return DEFAULT_POLICY;
+  }
+  if (typeof value === "string") {
+    return resolveSingle(value);
+  }
+  if (!Array.isArray(value)) {
+    throw new RuntimeError(
+      "ERR_RUNTIME_INVALID",
+      `runtime must be a string or array of strings, got ${typeof value}`,
+    );
+  }
+  if (value.length === 0) {
+    throw new RuntimeError(
+      "ERR_RUNTIME_INVALID",
+      "runtime: [] has no useful meaning. Omit the field for `auto`, or list at least one runtime label.",
+    );
+  }
+  const load: string[] = [];
+  for (let i = 0; i < value.length; i++) {
+    const entry = value[i];
+    if (typeof entry !== "string") {
+      throw new RuntimeError(
+        "ERR_RUNTIME_INVALID",
+        `runtime list entries must be strings, got ${typeof entry}`,
+      );
+    }
+    if (entry === "any") {
+      if (i !== value.length - 1) {
+        throw new RuntimeError(
+          "ERR_RUNTIME_INVALID",
+          "runtime: 'any' may only appear as the last entry in the list",
+        );
+      }
+      load.push(POLICY_WILDCARD);
+      continue;
+    }
+    const purlType = labelToPurlType(entry);
+    if (load.includes(purlType)) {
+      throw new RuntimeError(
+        "ERR_RUNTIME_INVALID",
+        `runtime: '${entry}' listed twice (resolves to ${purlType})`,
+      );
+    }
+    load.push(purlType);
+  }
+  return { load };
+}
+
+function resolveSingle(label: string): ControllerPolicy {
+  if (label === "auto") {
+    return DEFAULT_POLICY;
+  }
+  if (label === "native") {
+    return { load: [KERNEL_NATIVE_PURL_TYPE] };
+  }
+  if (label === "any") {
+    return { load: [POLICY_WILDCARD] };
+  }
+  return { load: [labelToPurlType(label)] };
+}
+
+function labelToPurlType(label: string): string {
+  if (SINGLE_ONLY_LABELS.has(label)) {
+    throw new RuntimeError(
+      "ERR_RUNTIME_INVALID",
+      `runtime label '${label}' describes a whole policy and is only valid as a single value, not inside a list`,
+    );
+  }
+  const purlType = LABEL_TO_PURL_TYPE[label];
+  if (!purlType) {
+    const known = Object.keys(LABEL_TO_PURL_TYPE).concat(["auto", "native", "any"]).sort().join(", ");
+    throw new RuntimeError(
+      "ERR_RUNTIME_INVALID",
+      `Unknown runtime label '${label}'. Known: ${known}`,
+    );
+  }
+  return purlType;
+}
+
+/**
+ * Stable short hash of a resolved policy, for use as a registry cache key
+ * suffix. Two imports with the same resolved policy share a cached
+ * controller; divergent policies get separate entries.
+ *
+ * Both `undefined` (no policy stamped) and any policy structurally equal to
+ * `DEFAULT_POLICY` (`runtime: auto`, missing `runtime:`, or any list that
+ * normalizes to the auto shape) collapse to the `"default"` fingerprint —
+ * the plan's contract is that "missing" is sugar for "auto", so they must
+ * share a cache entry.
+ */
+export function policyFingerprint(policy: ControllerPolicy | undefined): string {
+  if (!policy || isDefaultPolicy(policy)) {
+    return "default";
+  }
+  return policy.load.join(",");
+}
+
+/**
+ * Structural equality check against `DEFAULT_POLICY`. Used at policy-stamp
+ * time (import-controller) to skip stamping when the resolved policy is the
+ * canonical default — `runtime: auto`, `runtime: [nodejs, any]`, etc. all
+ * normalize to the same shape and should be observationally identical to a
+ * plain omitted `runtime:` field, both at the fingerprint level (handled by
+ * `policyFingerprint`) and at the policy-presence level.
+ */
+export function isDefaultPolicy(policy: ControllerPolicy): boolean {
+  if (policy === DEFAULT_POLICY) return true;
+  const a = policy.load;
+  const b = DEFAULT_POLICY.load;
+  if (a.length !== b.length) return false;
+  for (let i = 0; i < a.length; i++) {
+    if (a[i] !== b[i]) return false;
+  }
+  return true;
+}