@telorun/kernel 0.13.2 → 0.15.0

package/dist/snapshot-serializer.d.ts

@@ -0,0 +1,62 @@
+import { ResourceInstance, RuntimeResource } from "@telorun/sdk";
+export interface SnapshotData {
+    timestamp: string;
+    resources: Array<{
+        kind: string;
+        name: string;
+        metadata: Record<string, any>;
+        data: Record<string, any>;
+        snapshot?: Record<string, any>;
+    }>;
+}
+/**
+ * Serializes runtime state into YAML snapshots
+ * Captures resource definitions, instances, and custom state
+ * Recursively includes nested resources based on generationDepth
+ */
+export declare class SnapshotSerializer {
+    /**
+     * Take a snapshot of runtime state
+     * @param resources Map of resources organized by kind
+     * @param resourceInstances Map of resource instances to include custom snapshots
+     * @param filePath Optional file path to write snapshot to
+     * @returns Snapshot data object
+     */
+    takeSnapshot(resources: Map<string, Map<string, RuntimeResource>>, resourceInstances?: Map<string, {
+        resource: RuntimeResource;
+        instance: ResourceInstance;
+    }>, filePath?: string): Promise<SnapshotData>;
+    /**
+     * Serialize a single resource
+     */
+    private serializeResource;
+    /**
+     * Get snapshot from resource instance if it implements snapshot() method
+     */
+    private getInstanceSnapshot;
+    /**
+     * Serialize metadata, filtering out circular references and functions
+     */
+    private serializeMetadata;
+    /**
+     * Serialize resource data, filtering out circular references and functions
+     */
+    private serializeData;
+    /**
+     * Group resources by generation depth for hierarchical ordering
+     */
+    private groupByGenerationDepth;
+    /**
+     * Write snapshot to YAML file
+     */
+    private writeSnapshotToFile;
+    /**
+     * Generate resource key for instance lookup
+     */
+    private getResourceKey;
+    /**
+     * Load snapshot from YAML file
+     */
+    loadSnapshotFromFile(filePath: string): Promise<SnapshotData>;
+}
+//# sourceMappingURL=snapshot-serializer.d.ts.map

package/dist/snapshot-serializer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"snapshot-serializer.d.ts","sourceRoot":"","sources":["../src/snapshot-serializer.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,gBAAgB,EAAE,eAAe,EAAE,MAAM,cAAc,CAAC;AAKjE,MAAM,WAAW,YAAY;IAC3B,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,KAAK,CAAC;QACf,IAAI,EAAE,MAAM,CAAC;QACb,IAAI,EAAE,MAAM,CAAC;QACb,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;QAC9B,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;QAC1B,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;KAChC,CAAC,CAAC;CACJ;AAED;;;;GAIG;AACH,qBAAa,kBAAkB;IAC7B;;;;;;OAMG;IACG,YAAY,CAChB,SAAS,EAAE,GAAG,CAAC,MAAM,EAAE,GAAG,CAAC,MAAM,EAAE,eAAe,CAAC,CAAC,EACpD,iBAAiB,CAAC,EAAE,GAAG,CAAC,MAAM,EAAE;QAAE,QAAQ,EAAE,eAAe,CAAC;QAAC,QAAQ,EAAE,gBAAgB,CAAA;KAAE,CAAC,EAC1F,QAAQ,CAAC,EAAE,MAAM,GAChB,OAAO,CAAC,YAAY,CAAC;IA4BxB;;OAEG;YACW,iBAAiB;IAoC/B;;OAEG;YACW,mBAAmB;IAmBjC;;OAEG;IACH,OAAO,CAAC,iBAAiB;IAiBzB;;OAEG;IACH,OAAO,CAAC,aAAa;IAiBrB;;OAEG;IACH,OAAO,CAAC,sBAAsB;IAoB9B;;OAEG;YACW,mBAAmB;IAgBjC;;OAEG;IACH,OAAO,CAAC,cAAc;IAItB;;OAEG;IACG,oBAAoB,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,CAAC;CAIpE"}

package/dist/snapshot-serializer.js

@@ -0,0 +1,164 @@
+import * as fs from "fs/promises";
+import * as YAML from "js-yaml";
+import * as path from "path";
+/**
+ * Serializes runtime state into YAML snapshots
+ * Captures resource definitions, instances, and custom state
+ * Recursively includes nested resources based on generationDepth
+ */
+export class SnapshotSerializer {
+    /**
+     * Take a snapshot of runtime state
+     * @param resources Map of resources organized by kind
+     * @param resourceInstances Map of resource instances to include custom snapshots
+     * @param filePath Optional file path to write snapshot to
+     * @returns Snapshot data object
+     */
+    async takeSnapshot(resources, resourceInstances, filePath) {
+        const snapshot = {
+            timestamp: new Date().toISOString(),
+            resources: [],
+        };
+        // Get all resources organized by generation depth (0 = first level)
+        // Start with depth 0 (directly loaded resources) and recursively include nested ones
+        const resourcesByDepth = this.groupByGenerationDepth(resources);
+        // Process resources starting from depth 0
+        for (const depth of Array.from(resourcesByDepth.keys()).sort((a, b) => a - b)) {
+            const resourcesAtDepth = resourcesByDepth.get(depth) || [];
+            for (const resource of resourcesAtDepth) {
+                const resourceEntry = await this.serializeResource(resource, resourceInstances);
+                snapshot.resources.push(resourceEntry);
+            }
+        }
+        // Write to file if path provided
+        if (filePath) {
+            await this.writeSnapshotToFile(snapshot, filePath);
+        }
+        return snapshot;
+    }
+    /**
+     * Serialize a single resource
+     */
+    async serializeResource(resource, resourceInstances) {
+        const { kind, metadata, ...data } = resource;
+        const { name } = metadata;
+        const resourceEntry = {
+            kind,
+            name,
+            metadata: this.serializeMetadata(metadata),
+            data: this.serializeData(data),
+        };
+        // Include custom snapshot if resource instance has snapshot() method
+        if (resourceInstances) {
+            const key = this.getResourceKey(kind, name);
+            const instanceData = resourceInstances.get(key);
+            if (instanceData && instanceData.instance) {
+                const snapshotData = await this.getInstanceSnapshot(instanceData.instance);
+                if (snapshotData) {
+                    resourceEntry.snapshot = snapshotData;
+                }
+            }
+        }
+        return resourceEntry;
+    }
+    /**
+     * Get snapshot from resource instance if it implements snapshot() method
+     */
+    async getInstanceSnapshot(instance) {
+        const instanceAny = instance;
+        // Check if snapshot method exists
+        if (typeof instanceAny.snapshot === "function") {
+            try {
+                const result = await Promise.resolve(instanceAny.snapshot(instance));
+                return result;
+            }
+            catch (error) {
+                console.error("Error calling snapshot() on resource instance:", error);
+                return null;
+            }
+        }
+        return null;
+    }
+    /**
+     * Serialize metadata, filtering out circular references and functions
+     */
+    serializeMetadata(metadata) {
+        const serialized = {};
+        for (const [key, value] of Object.entries(metadata)) {
+            if (typeof value === "function") {
+                continue;
+            }
+            try {
+                serialized[key] = JSON.parse(JSON.stringify(value));
+            }
+            catch {
+                // Skip non-serializable values
+            }
+        }
+        return serialized;
+    }
+    /**
+     * Serialize resource data, filtering out circular references and functions
+     */
+    serializeData(data) {
+        const serialized = {};
+        for (const [key, value] of Object.entries(data)) {
+            if (typeof value === "function") {
+                continue;
+            }
+            try {
+                serialized[key] = JSON.parse(JSON.stringify(value));
+            }
+            catch {
+                // Skip non-serializable values
+            }
+        }
+        return serialized;
+    }
+    /**
+     * Group resources by generation depth for hierarchical ordering
+     */
+    groupByGenerationDepth(resources) {
+        const grouped = new Map();
+        for (const kindMap of resources.values()) {
+            for (const resource of kindMap.values()) {
+                const depth = resource.metadata.generationDepth ?? 0;
+                if (!grouped.has(depth)) {
+                    grouped.set(depth, []);
+                }
+                grouped.get(depth).push(resource);
+            }
+        }
+        return grouped;
+    }
+    /**
+     * Write snapshot to YAML file
+     */
+    async writeSnapshotToFile(snapshot, filePath) {
+        // Ensure directory exists
+        const dir = path.dirname(filePath);
+        if (dir !== "." && dir !== "") {
+            await fs.mkdir(dir, { recursive: true });
+        }
+        // Convert to YAML
+        const yaml = YAML.dump(snapshot, {
+            indent: 2,
+            lineWidth: 0,
+        });
+        await fs.writeFile(filePath, yaml, "utf-8");
+    }
+    /**
+     * Generate resource key for instance lookup
+     */
+    getResourceKey(kind, name) {
+        return `${kind}:${name}`;
+    }
+    /**
+     * Load snapshot from YAML file
+     */
+    async loadSnapshotFromFile(filePath) {
+        const content = await fs.readFile(filePath, "utf-8");
+        return YAML.load(content);
+    }
+}
+//# sourceMappingURL=snapshot-serializer.js.map

package/dist/snapshot-serializer.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"snapshot-serializer.js","sourceRoot":"","sources":["../src/snapshot-serializer.ts"],"names":[],"mappings":"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"}

package/dist/types.d.ts

@@ -0,0 +1,65 @@
+import type { ControllerContext, ResourceContext, ResourceInstance, ResourceManifest, RuntimeErrorCode, RuntimeResource } from "@telorun/sdk";
+import type { ModuleContext } from "./module-context.js";
+export type { ControllerContext, ResourceContext, ResourceInstance, ResourceManifest } from "@telorun/sdk";
+export interface KernelContext {
+    kernel: Kernel;
+}
+export interface ExecContext {
+    execute(urn: string, input: any): Promise<any>;
+    [key: string]: any;
+}
+export type ResourceCapability = string;
+export interface ResourceDefinition {
+    kind: string;
+    metadata: {
+        name: string;
+        module: string;
+    };
+    schema: Record<string, any>;
+    capabilities: ResourceCapability[];
+    events?: string[];
+    controllers?: Array<{
+        runtime: string;
+        entry: string;
+    }>;
+}
+/**
+ * Controller definition for a resource kind.
+ * Maps a fully-qualified resource kind to its controller implementation for a specific runtime.
+ */
+export interface ControllerDefinition {
+    kind: string;
+    runtime: string;
+    entry: string;
+    controller?: any;
+}
+/**
+ * Controller instance - runtime representation of a controller that handles resource instances.
+ */
+export interface ControllerInstance {
+    execute?(name: string, inputs: any, ctx: ExecContext): Promise<any>;
+    compile?(resource: ResourceManifest, ctx: ResourceContext): RuntimeResource | Promise<RuntimeResource>;
+    register?(ctx: ControllerContext): void | Promise<void>;
+    create?(resource: ResourceManifest, ctx: ResourceContext): ResourceInstance | null | Promise<ResourceInstance | null>;
+    schema: any;
+}
+export interface Kernel {
+    loadFromConfig(runtimeYamlPath: string): Promise<void>;
+    start(): Promise<void>;
+    acquireHold(reason?: string): () => void;
+    waitForIdle(): Promise<void>;
+    requestExit(code: number): void;
+    readonly exitCode: number;
+    teardownResource(module: string, kind: string, name: string): Promise<void>;
+    registerChildManifest(parentKey: string, resource: ResourceManifest): void;
+    getSourceFiles(): string[];
+    reloadSource(sourcePath: string): Promise<void>;
+    shutdown(): void;
+    registerModuleContext(moduleName: string, variables: Record<string, unknown>, secrets: Record<string, unknown>): void;
+    getModuleContext(moduleName: string): ModuleContext;
+}
+export declare class RuntimeError extends Error {
+    code: RuntimeErrorCode;
+    constructor(code: RuntimeErrorCode, message: string);
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"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"}

package/dist/types.js

@@ -0,0 +1,8 @@
+export class RuntimeError extends Error {
+    constructor(code, message) {
+        super(message);
+        this.code = code;
+        this.name = "RuntimeError";
+    }
+}
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AA0FA,MAAM,OAAO,YAAa,SAAQ,KAAK;IACrC,YACS,IAAsB,EAC7B,OAAe;QAEf,KAAK,CAAC,OAAO,CAAC,CAAC;QAHR,SAAI,GAAJ,IAAI,CAAkB;QAI7B,IAAI,CAAC,IAAI,GAAG,cAAc,CAAC;IAC7B,CAAC;CACF"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@telorun/kernel",
-  "version": "0.13.2",
+  "version": "0.15.0",
   "description": "Telo Runtime - A lightweight, polyglot execution host.",
   "keywords": [
     "telo",
@@ -47,8 +47,8 @@
   "dependencies": {
     "@marcbachmann/cel-js": "^7.5.3",
     "@sinclair/typebox": "^0.34.48",
-    "@telorun/analyzer": "0.12.1",
-    "@telorun/templating": "0.3.0",
+    "@telorun/analyzer": "0.14.0",
+    "@telorun/templating": "0.4.0",
     "ajv": "^8.17.1",
     "ajv-formats": "^3.0.1",
     "minimatch": "^10.2.5",
@@ -61,7 +61,7 @@
     "vitest": "^2.1.8"
   },
   "peerDependencies": {
-    "@telorun/sdk": "0.12.0"
+    "@telorun/sdk": "0.13.0"
   },
   "overrides": {
     "@marcbachmann/cel-js": "$@marcbachmann/cel-js",

package/src/application-env.ts

@@ -11,11 +11,27 @@ interface EnvEntry {
   [key: string]: unknown;
 }
 
+interface PortEntry {
+  env: string;
+  protocol?: "tcp" | "udp";
+  default?: number;
+}
+
 export interface EnvResolutionResult {
   variables: Record<string, unknown>;
   secrets: Record<string, unknown>;
+  ports: Record<string, number>;
 }
 
+/** Residual schema every resolved port value is validated against. Ports are
+ *  implicitly integers in the IANA range; `protocol` selects transport and
+ *  carries no validation. */
+const PORT_RESIDUAL_SCHEMA: Record<string, unknown> = {
+  type: "integer",
+  minimum: 1,
+  maximum: 65535,
+};
+
 /**
  * Populate the root Application's `variables` / `secrets` namespaces from
  * host environment variables, per the per-field `env:` mapping declared on
@@ -53,6 +69,7 @@ export function resolveApplicationEnv(
     errors,
     true,
   );
+  const ports = resolvePorts(manifest.ports ?? {}, env, validator, errors);
   if (errors.length > 0) {
     throw new RuntimeError(
       "ERR_MANIFEST_VALIDATION_FAILED",
@@ -60,7 +77,63 @@ export function resolveApplicationEnv(
         errors.map((e) => `  - ${e}`).join("\n"),
     );
   }
-  return { variables, secrets };
+  return { variables, secrets, ports };
+}
+
+/**
+ * Populate the root Application's `ports` namespace from host environment
+ * variables. Mirrors `resolveBlock` but fixes the value type to a port integer
+ * (1–65535): read `entry.env`, coerce the raw value as an integer, validate it
+ * against `PORT_RESIDUAL_SCHEMA`, and fall back to `entry.default` when the env
+ * var is unset. Failures aggregate into the shared `errors` list so they
+ * surface alongside variable/secret problems.
+ */
+function resolvePorts(
+  block: Record<string, PortEntry> | unknown,
+  env: Record<string, string | undefined>,
+  validator: SchemaValidator,
+  errors: string[],
+): Record<string, number> {
+  const out: Record<string, number> = {};
+  if (!block || typeof block !== "object" || Array.isArray(block)) {
+    return out;
+  }
+  for (const [name, entry] of Object.entries(block as Record<string, PortEntry>)) {
+    if (!entry || typeof entry !== "object") continue;
+    const envKey = entry.env;
+    const raw = env[envKey];
+
+    if (raw === undefined || raw === null) {
+      if (entry.default !== undefined) {
+        const validation = validateResidual(entry.default, PORT_RESIDUAL_SCHEMA, validator);
+        if (validation) {
+          errors.push(`${name}: ${validation}`);
+        } else {
+          out[name] = entry.default;
+        }
+        continue;
+      }
+      errors.push(`${name}: environment variable ${envKey} is not set (no default)`);
+      continue;
+    }
+
+    let coerced: unknown;
+    try {
+      coerced = coerce(raw, "integer", envKey, false);
+    } catch (e) {
+      errors.push(`${name}: ${(e as Error).message}`);
+      continue;
+    }
+
+    const validation = validateResidual(coerced, PORT_RESIDUAL_SCHEMA, validator);
+    if (validation) {
+      errors.push(`${name}: ${validation}`);
+      continue;
+    }
+
+    out[name] = coerced as number;
+  }
+  return out;
 }
 
 function resolveBlock(

package/src/kernel.ts

@@ -19,6 +19,7 @@ import {
   ResourceManifest,
   RuntimeError,
   RuntimeEvent,
+  type BootTarget,
   type EvaluationContext as IEvaluationContext,
   type ModuleContext as IModuleContext,
   type LoadOptions,
@@ -392,25 +393,32 @@ export class Kernel implements IKernel {
         // `process.env` after the manifest loop so imports can read
         // `${{ variables.X }}` during their own init.
         //
-        // Targets normalize down to bare names regardless of source surface.
-        // The analyzer's `resolveRefSentinels` pass already substituted any
-        // `!ref <name>` to `{kind, name}`; bare-string forms pass through.
-        // Anything else (e.g. an unresolved sentinel because the analyzer
-        // couldn't see it, or a malformed manifest) is a hard error —
-        // silently dropping the entry would leave the user staring at a
-        // "no targets ran" outcome with no signal where it went wrong.
+        // Targets are preserved as their full shape so the boot runner can
+        // evaluate `when` guards and inline invoke steps. The analyzer's
+        // `resolveRefSentinels` pass already substituted any `!ref <name>` to
+        // `{kind, name}` (including inside an inline target's `invoke`).
+        // Recognized shapes: bare string ref, resolved `{kind, name}`, gated
+        // `{ ref, when? }`, and inline `{ name?, invoke, inputs?, when?, retry? }`.
+        // Anything else (e.g. an unresolved sentinel, or a malformed manifest)
+        // is a hard error — silently dropping the entry would leave the user
+        // staring at a "no targets ran" outcome with no signal.
         const rawTargets = (manifest.targets ?? []) as unknown[];
-        const targetNames = rawTargets.map((t, index) => {
-          if (typeof t === "string") return t;
-          if (t && typeof t === "object" && typeof (t as { name?: unknown }).name === "string") {
-            return (t as { name: string }).name;
+        rawTargets.forEach((t, index) => {
+          const ok =
+            typeof t === "string" ||
+            (!!t &&
+              typeof t === "object" &&
+              (typeof (t as { name?: unknown }).name === "string" ||
+                (t as { ref?: unknown }).ref != null ||
+                (t as { invoke?: unknown }).invoke !== undefined));
+          if (!ok) {
+            throw new RuntimeError(
+              "ERR_INVALID_VALUE",
+              `Telo.Application '${(manifest.metadata as { name?: string } | undefined)?.name ?? "(unnamed)"}' targets[${index}] is not a recognized target shape. Got: ${JSON.stringify(t)}`,
+            );
           }
-          throw new RuntimeError(
-            "ERR_INVALID_VALUE",
-            `Telo.Application '${(manifest.metadata as { name?: string } | undefined)?.name ?? "(unnamed)"}' targets[${index}] could not be normalized to a resource name. Got: ${JSON.stringify(t)}`,
-          );
         });
-        this.rootContext.setTargets(targetNames);
+        this.rootContext.setTargets(rawTargets as BootTarget[]);
         if (manifest.kind === "Telo.Application") {
           rootApplicationManifest = manifest;
         }
@@ -419,7 +427,7 @@ export class Kernel implements IKernel {
     }
 
     if (rootApplicationManifest) {
-      const { variables, secrets } = resolveApplicationEnv(
+      const { variables, secrets, ports } = resolveApplicationEnv(
         rootApplicationManifest as Record<string, any>,
         this.env,
         this.sharedSchemaValidator,
@@ -430,6 +438,9 @@ export class Kernel implements IKernel {
       if (Object.keys(secrets).length > 0) {
         this.rootContext.setSecrets(secrets);
       }
+      if (Object.keys(ports).length > 0) {
+        this.rootContext.setPorts(ports);
+      }
     }
   }
 

package/src/module-context.ts

@@ -1,6 +1,10 @@
+import { executeInvokeStep } from "@telorun/sdk";
 import type {
+  BootTarget,
   ControllerPolicy,
   Invocable,
+  InvokeStep,
+  InvokeStepContext,
   ModuleContext as IModuleContext,
 } from "@telorun/sdk";
 import type { EmitEvent, InstanceFactory } from "@telorun/sdk";
@@ -42,8 +46,8 @@ function collectSecretValues(secrets: Record<string, unknown>): Set<string> {
 }
 
 /**
- * Persistent, module-scoped context. Three reserved CEL namespaces:
- * variables, secrets, resources.
+ * Persistent, module-scoped context. Reserved CEL namespaces:
+ * variables, secrets, resources, ports (Application-only).
  *
  * Unlike the base EvaluationContext, ModuleContext is stateful and mutable:
  * variables/secrets/resources accumulate during multi-pass initialization and
@@ -57,6 +61,10 @@ export class ModuleContext extends EvaluationContext implements IModuleContext {
   private _variables: Record<string, unknown>;
   private _secrets: Record<string, unknown>;
   private _resources: Record<string, unknown>;
+  /** Resolved inbound ports (`ports.<name>` → integer). Application-only:
+   *  populated on the root context from the Application's `ports` block;
+   *  imported child modules keep this empty. */
+  private _ports: Record<string, unknown> = {};
 
   /** Maps import alias → real module name for kind resolution. */
   private readonly importAliases = new Map<string, string>();
@@ -78,7 +86,7 @@ export class ModuleContext extends EvaluationContext implements IModuleContext {
     variables: Record<string, unknown> = {},
     secrets: Record<string, unknown> = {},
     resources: Record<string, unknown> = {},
-    private targets: string[] = [],
+    private targets: BootTarget[] = [],
     createInstance: InstanceFactory = async () => null,
     emit: EmitEvent,
     private readonly _hostEnv?: Record<string, string | undefined>,
@@ -102,12 +110,21 @@ export class ModuleContext extends EvaluationContext implements IModuleContext {
     return this._resources;
   }
 
+  get ports(): Record<string, unknown> {
+    return this._ports;
+  }
+
   setVariables(vars: Record<string, unknown>): void {
     this._variables = vars;
     this._rebuildContext();
   }
 
-  setTargets(vars: string[]): void {
+  setPorts(ports: Record<string, unknown>): void {
+    this._ports = ports;
+    this._rebuildContext();
+  }
+
+  setTargets(vars: BootTarget[]): void {
     this.targets = vars;
   }
 
@@ -212,6 +229,7 @@ export class ModuleContext extends EvaluationContext implements IModuleContext {
       variables: this._variables,
       secrets: this._secrets,
       resources: this._resources,
+      ports: this._ports,
       ...(this._hostEnv ? { env: lenientEnv(this._hostEnv) } : {}),
     };
     this._secretValues = collectSecretValues(this._secrets);
@@ -242,8 +260,41 @@ export class ModuleContext extends EvaluationContext implements IModuleContext {
   }
 
   async runTargets() {
-    for (const target of this.targets) {
-      await this.run(target);
+    const steps: Record<string, unknown> = {};
+    const stepCtx: InvokeStepContext = {
+      expandValue: (value, context) => this.expandWith(value, context),
+      invoke: (kind, name, inputs) => this.invoke(kind, name, inputs),
+      invokeResolved: (kind, name, instance, inputs) =>
+        this.invokeResolved(kind, name, instance, inputs),
+    };
+    for (let i = 0; i < this.targets.length; i++) {
+      const target = this.targets[i]!;
+      if (typeof target === "string") {
+        await this.run(target);
+        continue;
+      }
+      if ("invoke" in target && target.invoke !== undefined) {
+        const step: InvokeStep = {
+          name: target.name ?? `Target${i}`,
+          when: target.when,
+          invoke: target.invoke,
+          inputs: target.inputs,
+        };
+        await executeInvokeStep(step, stepCtx, { steps });
+        continue;
+      }
+      if ("ref" in target && target.ref != null) {
+        const refName = typeof target.ref === "string" ? target.ref : target.ref.name;
+        if (target.when === undefined || this.expandWith(target.when, { steps })) {
+          await this.run(refName);
+        }
+        continue;
+      }
+      if ("name" in target && typeof target.name === "string") {
+        await this.run(target.name);
+        continue;
+      }
+      throw new Error(`Unrecognized target shape at index ${i}: ${JSON.stringify(target)}`);
     }
   }
 }

package/src/schema-validator.ts

@@ -112,6 +112,7 @@ export class SchemaValidator {
       "x-telo-topology-role",
       "x-telo-step-context",
       "x-telo-widget",
+      "x-telo-type",
     ]) {
       this.ajv.addKeyword(kw);
     }