@telorun/sdk 0.2.7 → 0.3.0

package/src/evaluation-context.ts

@@ -1,10 +1,7 @@
-import { isCompiledValue } from "./compiled-value.js";
-import type { ModuleContext } from "./module-context.js";
-import type { ScopeContext, ScopeHandle } from "./ref.js";
-import { ResourceInstance } from "./resource-instance.js";
-import { ResourceManifest } from "./resource-manifest.js";
-import { RuntimeDiagnostic } from "./runtime-error.js";
-import { RuntimeError } from "./types.js";
+import type { ScopeHandle } from "./ref.js";
+import type { ResourceInstance } from "./resource-instance.js";
+import type { ResourceManifest } from "./resource-manifest.js";
+import type { ResourceDefinition } from "./types.js";
 
 export type EmitEvent = (event: string, payload?: any) => void | Promise<void>;
 
@@ -25,7 +22,7 @@ export type CreatedResource = { instance: ResourceInstance; ctx: any };
  * init() separately in a second phase.
  */
 export type InstanceFactory = (
-  moduleContext: ModuleContext,
+  context: EvaluationContext,
   resource: ResourceManifest,
 ) => Promise<CreatedResource | null>;
 
@@ -49,471 +46,58 @@ export function resourceKey(r: ResourceManifest): string {
 }
 
 /**
- * Base class for all evaluation contexts. Owns template
- * expansion, secrets redaction, and the generic resource lifecycle tree.
+ * Public contract for the base evaluation context.
  *
- * Every EvaluationContext node can:
- *   - Hold its own resource instances (resourceInstances)
- *   - Queue resources for initialization (pendingResources)
- *   - Spawn child contexts (spawnChild) forming a lifecycle tree
- *   - Run a multi-pass initialization loop (initializeResources)
- *   - Cascade teardown depth-first through the tree (teardownResources)
+ * Owns template expansion, secrets redaction, and the generic resource lifecycle tree.
+ * The class implementation lives in `@telorun/kernel`.
  */
-export class EvaluationContext {
-  readonly id = Math.random().toString(16).slice(2, 8);
-  protected _context: Record<string, unknown>;
-  protected _secretValues: Set<string>;
-  protected _createInstance: InstanceFactory;
+export interface EvaluationContext {
+  readonly id: string;
+  readonly source: string;
   readonly emit: EmitEvent;
 
-  /** Position in the lifecycle tree. */
-  parent: EvaluationContext | undefined = undefined;
-  readonly children: EvaluationContext[] = [];
+  parent: EvaluationContext | undefined;
+  readonly children: EvaluationContext[];
 
-  /** Current lifecycle state of this context node. */
-  state: LifecycleState = "Pending";
+  state: LifecycleState;
 
-  /** Resource instances owned by this context node, keyed by resourceKey(). */
-  readonly resourceInstances = new Map<
+  readonly resourceInstances: Map<
     string,
     { resource: ResourceManifest; instance: ResourceInstance }
-  >();
+  >;
 
-  /** Resources that have been created but not yet initialized (between phases). */
-  protected readonly createdInstances = new Map<
-    string,
-    { resource: ResourceManifest; instance: ResourceInstance; ctx: any }
-  >();
-
-  /** Resources queued for initialization on this context node. */
-  private pendingResources: ResourceManifest[] = [];
-
-  /**
-   * Optional hook called between create() and init() for each resource.
-   * Set by the kernel to inject live instances into reference fields.
-   */
   preInitHook?: PreInitHook;
 
-  constructor(
-    readonly source: string,
-    context: Record<string, unknown>,
-    createInstance: InstanceFactory = async () => null,
-    secretValues: Set<string>,
-    emit: EmitEvent,
-  ) {
-    this._context = context;
-    this._createInstance = createInstance;
-    this._secretValues = secretValues ?? new Set();
-    this.emit = emit;
-  }
-
-  get createInstance(): InstanceFactory {
-    return this._createInstance;
-  }
-
-  /** Called after init() when a resource snapshot is available. Overridden by ModuleContext. */
-  protected onResourceSnapshotted(_name: string, _snap: Record<string, unknown>): void {}
-
-  get context(): Record<string, unknown> {
-    return this._context;
-  }
-
-  get secretValues(): Set<string> {
-    return this._secretValues;
-  }
-
-  /**
-   * Reorder pending resources to match the given name sequence (topo order from Phase 4).
-   * Resources not present in `names` are left at the end in their original order.
-   * Call before initializeResources() so the create/init sub-phases run in dependency order,
-   * guaranteeing that Phase 5 injection always finds initialized dependencies.
-   */
-  setInitOrder(names: string[]): void {
-    const rank = new Map(names.map((n, i) => [n, i]));
-    this.pendingResources.sort((a, b) => {
-      const ra = rank.get(a.metadata.name as string) ?? Infinity;
-      const rb = rank.get(b.metadata.name as string) ?? Infinity;
-      return ra - rb;
-    });
-  }
-
-  /**
-   * Queue a resource manifest for initialization on this context.
-   */
-  hasManifest(name: string): boolean {
-    return (
-      this.resourceInstances.has(name) ||
-      this.createdInstances.has(name) ||
-      this.pendingResources.some((r) => r.metadata.name === name)
-    );
-  }
-
-  registerManifest(resource: ResourceManifest): void {
-    if (!resource.metadata) {
-      resource.metadata = { name: `__unnamed_${Math.random().toString(16).slice(2, 8)}` };
-    }
-    const name = resource.metadata.name;
-    if (this.hasManifest(name)) {
-      throw new RuntimeError("ERR_DUPLICATE_RESOURCE", `Resource '${name}' is already registered`);
-    }
-    this.pendingResources.push(resource);
-  }
-
-  /**
-   * Attach a child context to this node. The child's parent is set to this
-   * context and the child is registered under the given name.
-   */
-  spawnChild<T extends EvaluationContext>(child: T): T {
-    child.parent = this;
-    this.children.push(child);
-    // Propagate injection hook so all child contexts (module imports, scopes) participate
-    // in Phase 5 injection. createScopeHandle overrides this with an extended version.
-    if (this.preInitHook && !child.preInitHook) {
-      child.preInitHook = this.preInitHook;
-    }
-    return child;
-  }
-
-  /**
-   * Interleaved create/init loop.
-   *
-   * Each pass has two sub-phases run back-to-back:
-   *   1. Create sub-phase: call controller.create() for each pending resource that
-   *      hasn't been created yet. Successful results go into createdInstances.
-   *   2. Init sub-phase: call instance.init(ctx) for each created-but-not-inited
-   *      resource. Successful results go into resourceInstances.
-   *
-   * Interleaving is necessary because some resources' create() depends on effects
-   * produced by other resources' init() (e.g. Kernel.Import.init() runs
-   * child.initializeResources() which registers controllers needed by sibling
-   * resources' create()). Running both sub-phases each pass lets those effects
-   * propagate before the next create attempt.
-   *
-   * Each resource is created at most once and inited at most once.
-   * ERR_VISIBILITY_DENIED is fatal and re-thrown immediately.
-   * All other errors are tracked and retried until no progress is made.
-   */
-  async initializeResources(): Promise<void> {
-    const MAX_PASSES = 10;
-    const errors = new Map<string, string>();
-
-    let pass = 1;
-    do {
-      let progress = false;
-
-      // Create sub-phase
-      for (const resource of [...this.pendingResources]) {
-        const name = resource.metadata.name;
-        if (this.createdInstances.has(name)) continue;
-        try {
-          // const expanded = this.expand(resource) as ResourceManifest;
-          // FIXME: Cannot expand it for all resources, needs to be selective
-          const created = await this._createInstance(this as any, resource);
-          if (created) {
-            this.createdInstances.set(name, {
-              resource,
-              instance: created.instance,
-              ctx: created.ctx,
-            });
-            const idx = this.pendingResources.findIndex((m) => m.metadata.name === name);
-            if (idx >= 0) this.pendingResources.splice(idx, 1);
-            errors.delete(name);
-            progress = true;
-          }
-        } catch (error) {
-          if (error instanceof RuntimeError && error.code === "ERR_VISIBILITY_DENIED") throw error;
-          errors.set(name, error instanceof Error ? error.message : String(error));
-        }
-      }
-
-      // Init sub-phase
-      for (const [name, { resource, instance, ctx }] of [...this.createdInstances]) {
-        if (this.resourceInstances.has(name)) continue;
-        try {
-          if (this.preInitHook) {
-            this.preInitHook(resource, (n) => this.resourceInstances.get(n)?.instance);
-          }
-          if (instance.init) await instance.init(ctx);
-          if (instance.snapshot) {
-            const snap = await Promise.resolve(instance.snapshot()).catch(() => ({}));
-            this.onResourceSnapshotted(name, (snap as Record<string, unknown>) ?? {});
-          }
-          this.resourceInstances.set(name, { resource, instance });
-          this.createdInstances.delete(name);
-          errors.delete(name);
-          progress = true;
-        } catch (error) {
-          if (error instanceof RuntimeError && error.code === "ERR_VISIBILITY_DENIED") throw error;
-          errors.set(name, error instanceof Error ? error.message : String(error));
-        }
-      }
-
-      pass++;
-      if (!progress) break;
-    } while (pass <= MAX_PASSES);
-
-    if (this.pendingResources.length > 0 || this.createdInstances.size > 0) {
-      const diagnostics: RuntimeDiagnostic[] = [
-        ...this.pendingResources.map((r) => ({
-          resource: r.metadata.name,
-          message: errors.get(r.metadata.name) ?? "Unknown error",
-        })),
-        ...[...this.createdInstances.keys()].map((name) => ({
-          resource: name,
-          message: errors.get(name) ?? "Unknown error",
-        })),
-      ];
-      throw new RuntimeError(
-        "ERR_RESOURCE_INITIALIZATION_FAILED",
-        "Unable to process resources",
-        diagnostics,
-      );
-    }
-
-    this.state = "Initialized";
-  }
-
-  withManifests<T>(manifests: any[], fn: () => T): T {
-    const child = this.spawnChild(
-      new EvaluationContext(
-        this.source,
-        this._context,
-        this._createInstance,
-        this._secretValues,
-        this.emit,
-      ),
-    );
-    try {
-      for (const manifest of manifests) {
-        child.registerManifest(manifest);
-      }
-      return fn();
-    } finally {
-      // Tear down child context and its resources immediately after fn() completes.
-      // Note that this does NOT emit Kernel-level events (e.g. Teardown events) —
-      // they remain the Kernel's responsibility.
-      child.teardownResources();
-    }
-  }
-
-  /**
-   * Returns a ScopeHandle that initializes `manifests` in a fresh child context each time
-   * `run()` is called, executes the callback with a ScopeContext, and tears down when done.
-   *
-   * The child inherits the parent's preInitHook (if any), extended so that `getInstance`
-   * also checks the parent's already-initialized singleton instances. This lets scoped
-   * resources hold x-telo-ref slots pointing to outer resources — those deps are already
-   * live when the scope opens.
-   */
-  createScopeHandle(manifests: ResourceManifest[]): ScopeHandle {
-    const parent = this;
-    return {
-      async run<T>(fn: (scope: ScopeContext) => Promise<T>): Promise<T> {
-        const child = parent.spawnChild(
-          new EvaluationContext(
-            parent.source,
-            parent._context,
-            parent._createInstance,
-            parent._secretValues,
-            parent.emit,
-          ),
-        );
-
-        // Propagate injection hook: extend getInstance to also resolve parent singleton instances.
-        if (parent.preInitHook) {
-          const parentHook = parent.preInitHook;
-          child.preInitHook = (resource, childGetInstance) => {
-            parentHook(
-              resource,
-              (name) => childGetInstance(name) ?? parent.resourceInstances.get(name)?.instance,
-            );
-          };
-        }
-
-        try {
-          for (const manifest of manifests) {
-            child.registerManifest(manifest);
-          }
-          await child.initializeResources();
-          const scope: ScopeContext = {
-            getInstance(name: string): ResourceInstance {
-              const childEntry = child.resourceInstances.get(name);
-              if (childEntry) return childEntry.instance;
-              const parentEntry = parent.resourceInstances.get(name);
-              if (parentEntry) return parentEntry.instance;
-              throw new RuntimeError(
-                "ERR_SCOPE_RESOURCE_NOT_FOUND",
-                `Resource '${name}' not found in scope or outer context. Available scoped: ${[...child.resourceInstances.keys()].join(", ")}`,
-              );
-            },
-          };
-          return await fn(scope);
-        } finally {
-          await child.teardownResources();
-          const idx = parent.children.indexOf(child);
-          if (idx >= 0) parent.children.splice(idx, 1);
-        }
-      },
-    };
-  }
-
-  /**
-   * Cascade teardown depth-first through the tree:
-   *   1. Tear down child contexts in reverse registration order.
-   *   2. Tear down own resource instances in reverse registration order,
-   *      emitting a Teardown event for each via the injected emit callback.
-   */
-  async teardownResources(): Promise<void> {
-    this.state = "Draining";
-    for (const child of [...this.children].reverse()) {
-      await child.teardownResources();
-    }
-    const entries = [...this.resourceInstances.entries()].reverse();
-    for (const [key, { resource, instance }] of entries) {
-      if (instance.teardown) await instance.teardown();
-      await this.emit(`${resource.kind}.${resource.metadata.name}.Teardown`, {
-        resource: { kind: resource.kind, name: resource.metadata.name },
-      });
-      this.resourceInstances.delete(key);
-    }
-    this.state = "Teardown";
-  }
-
-  transientChild(context: Record<string, any>): EvaluationContext {
-    return new EvaluationContext(
-      this.source,
-      { ...this.context, ...context },
-      this._createInstance,
-      this._secretValues,
-      this.emit,
-    );
-  }
-
-  /**
-   * Invoke a resource by kind and name within this context's resourceInstances.
-   * Emits a scoped Invoked event via the injected emit callback after invocation.
-   */
-  async invoke<TInputs>(kind: string, name: string, inputs: TInputs): Promise<any> {
-    const entry = this.resourceInstances.get(name);
-
-    if (entry) {
-      if (typeof entry.instance.invoke !== "function") {
-        throw new RuntimeError(
-          "ERR_RESOURCE_NOT_INVOKABLE",
-          `Resource ${kind}.${name} does not have an invoke method`,
-        );
-      }
-      const outputs = await entry.instance.invoke(inputs as any);
-      await this.emit(`${kind}.${name}.Invoked`, { outputs });
-      return outputs;
-    }
-
-    throw new RuntimeError(
-      "ERR_RESOURCE_NOT_FOUND",
-      `Resource not found for invocation: ${kind}.${name}. Available resources: ${[...this.resourceInstances.keys()].join(", ")}`,
-    );
-  }
-
-  async run(name: string): Promise<void> {
-    const entry = this.resourceInstances.get(name);
-    if (entry && typeof entry.instance.run === "function") {
-      return entry.instance.run();
-    }
-    throw new RuntimeError(
-      "ERR_RESOURCE_NOT_RUNNABLE",
-      `Resource ${name} is not runnable or not found. Available resources: ${[...this.resourceInstances.keys()].join(", ")}`,
-    );
-  }
-
-  /**
-   * Expand a value that may contain precompiled ${{ }} templates.
-   * Works recursively over CompiledValues, arrays, and objects.
-   */
-  expand(value: unknown): unknown {
-    if (isCompiledValue(value)) {
-      return value.call(this._context);
-    }
-    if (Array.isArray(value)) {
-      return value.map((entry) => this.expand(entry));
-    }
-    if (value !== null && typeof value === "object") {
-      const resolved: Record<string, unknown> = {};
-      for (const [key, entry] of Object.entries(value as Record<string, unknown>)) {
-        resolved[key] = this.expand(entry);
-      }
-      return resolved;
-    }
-    return value;
-  }
-
-  /**
-   * Expand a value using this context merged with additional properties.
-   * Equivalent to merge(extraContext).expand(value) without allocating a context object.
-   */
-  expandWith(value: unknown, extraContext: Record<string, unknown>): unknown {
-    const saved = this._context;
-    this._context = Object.assign(Object.create(null), saved, extraContext) as Record<
-      string,
-      unknown
-    >;
-    try {
-      return this.expand(value);
-    } finally {
-      this._context = saved;
-    }
-  }
-
-/**
-   * Expand specific dot-paths within an object. '**' expands the entire object.
-   * Paths listed in excludePaths are left untouched (runtime takes precedence).
-   * Always throws if an expression cannot be resolved.
-   */
+  /** Looks up a registered resource definition by fully-qualified kind.
+   *  Set by the kernel; used for declared-throw-union checks. */
+  getDefinition?: (kind: string) => ResourceDefinition | undefined;
+
+  readonly createInstance: InstanceFactory;
+  readonly context: Record<string, unknown>;
+  readonly secretValues: Set<string>;
+
+  setInitOrder(names: string[]): void;
+  hasManifest(name: string): boolean;
+  registerManifest(resource: ResourceManifest): void;
+  spawnChild<T extends EvaluationContext>(child: T): T;
+  initializeResources(): Promise<void>;
+  withManifests<T>(manifests: any[], fn: () => T): T;
+  createScopeHandle(manifests: ResourceManifest[]): ScopeHandle;
+  teardownResources(): Promise<void>;
+  transientChild(context: Record<string, any>): EvaluationContext;
+  invoke<TInputs>(kind: string, name: string, inputs: TInputs): Promise<any>;
+  invokeResolved<TInputs>(
+    kind: string,
+    name: string,
+    instance: ResourceInstance,
+    inputs: TInputs,
+  ): Promise<any>;
+  run(name: string): Promise<void>;
+  expand(value: unknown): unknown;
+  expandWith(value: unknown, extraContext: Record<string, unknown>): unknown;
   expandPaths(
     value: Record<string, unknown>,
     paths: string[],
-    excludePaths: string[] = [],
-  ): Record<string, unknown> {
-    if (paths.includes("**")) {
-      const result: Record<string, unknown> = {};
-      for (const [key, v] of Object.entries(value)) {
-        result[key] = isExcluded(key, excludePaths) ? v : this.expand(v);
-      }
-      return result;
-    }
-    const result = { ...value };
-    for (const path of paths) {
-      if (isExcluded(path, excludePaths)) continue;
-      const parts = path.split(".");
-      const current = getNestedValue(result, parts);
-      if (current !== undefined) {
-        setNestedValue(result, parts, this.expand(current));
-      }
-    }
-    return result;
-  }
-}
-
-function isExcluded(path: string, excludePaths: string[]): boolean {
-  return excludePaths.some(
-    (ep) => ep === path || ep === "**" || path.startsWith(ep + ".") || ep.startsWith(path + "."),
-  );
-}
-
-function getNestedValue(obj: Record<string, unknown>, parts: string[]): unknown {
-  let current: unknown = obj;
-  for (const part of parts) {
-    if (current === null || typeof current !== "object") return undefined;
-    current = (current as Record<string, unknown>)[part];
-  }
-  return current;
-}
-
-function setNestedValue(obj: Record<string, unknown>, parts: string[], value: unknown): void {
-  let current: Record<string, unknown> = obj;
-  for (let i = 0; i < parts.length - 1; i++) {
-    const next = current[parts[i]];
-    if (next === null || typeof next !== "object") return;
-    current = next as Record<string, unknown>;
-  }
-  current[parts[parts.length - 1]] = value;
+    excludePaths?: string[],
+  ): Record<string, unknown>;
 }

package/src/index.ts

@@ -10,6 +10,7 @@ export * from "./module-context.js";
 export * from "./resource-context.js";
 export * from "./resource-instance.js";
 export * from "./resource-manifest.js";
+export * from "./invoke-error.js";
 export * from "./runtime-error.js";
 export * from "./runtime-event.js";
 export * from "./runtime-resource.js";

package/src/invoke-error.ts

@@ -0,0 +1,39 @@
+const INVOKE_ERROR = Symbol.for("telo.InvokeError");
+
+/**
+ * Structured, catchable error for invocables and runnables. Route handlers and
+ * Run.Sequence try/catch match on `code`; downstream renderers consume `data`.
+ *
+ * Use `isInvokeError` for recognition, not `instanceof` — dual-realm safe
+ * across pnpm hoist splits, registry modules, and future sandbox isolation.
+ */
+export class InvokeError extends Error {
+  readonly code: string;
+  readonly data?: unknown;
+
+  constructor(code: string, message: string, data?: unknown) {
+    super(message);
+    this.name = "InvokeError";
+    this.code = code;
+    this.data = data;
+    // Set via defineProperty (not a class field initializer) so the marker is
+    // always present regardless of TS/runtime class-field semantics
+    // (useDefineForClassFields, Error-subclass quirks, etc.) and stays
+    // non-enumerable so JSON serialisation / CEL property access don't trip
+    // over it.
+    Object.defineProperty(this, INVOKE_ERROR, {
+      value: true,
+      enumerable: false,
+      writable: false,
+      configurable: false,
+    });
+  }
+}
+
+export function isInvokeError(err: unknown): err is InvokeError {
+  return (
+    typeof err === "object" &&
+    err !== null &&
+    (err as Record<PropertyKey, unknown>)[INVOKE_ERROR] === true
+  );
+}