@telorun/sdk 0.2.7 → 0.3.0

package/src/module-context.ts

@@ -1,215 +1,34 @@
-import { Invocable } from "./capabilities/invokable.js";
-import { EmitEvent, EvaluationContext, InstanceFactory } from "./evaluation-context.js";
-
-/** Wraps process.env so that missing keys return null instead of throwing in CEL.
- * cel-js uses Object.hasOwn(obj, key) before accessing obj[key], so we must
- * intercept getOwnPropertyDescriptor to report every string key as "own". */
-function lenientEnv(env: Record<string, string | undefined>): Record<string, string | null> {
-  return new Proxy(env as Record<string, string | null>, {
-    get(target, key) {
-      if (typeof key !== "string") return (target as any)[key];
-      return key in target ? (target[key] ?? null) : null;
-    },
-    has() {
-      return true;
-    },
-    getOwnPropertyDescriptor(target, key) {
-      if (typeof key !== "string") return Object.getOwnPropertyDescriptor(target, key);
-      const value = key in target ? (target[key] ?? null) : null;
-      return { configurable: true, enumerable: true, writable: true, value };
-    },
-  });
-}
-
-function collectSecretValues(secrets: Record<string, unknown>): Set<string> {
-  const values = new Set<string>();
-  for (const value of Object.values(secrets)) {
-    if (typeof value === "string" && value.length > 0) {
-      values.add(value);
-    }
-  }
-  return values;
-}
+import type { Invocable } from "./capabilities/invokable.js";
+import type { EvaluationContext } from "./evaluation-context.js";
 
 /**
- * Persistent, module-scoped context. Three reserved CEL namespaces:
- * variables, secrets, resources.
+ * Public contract for a persistent, module-scoped context.
  *
+ * Three reserved CEL namespaces: variables, secrets, resources.
  * Unlike the base EvaluationContext, ModuleContext is stateful and mutable:
- * variables/secrets/resources accumulate during multi-pass initialization and
- * the context record is rebuilt on each mutation. Import aliases are tracked
- * here for alias-prefixed kind resolution (e.g. MyImport.Http.Route).
+ * variables/secrets/resources accumulate during multi-pass initialization.
+ * Import aliases are tracked here for alias-prefixed kind resolution.
  *
- * Imported modules are surfaced under resources.<alias> alongside local
- * resources — no separate imports namespace needed.
+ * The class implementation lives in `@telorun/kernel`.
  */
-export class ModuleContext extends EvaluationContext {
-  private _variables: Record<string, unknown>;
-  private _secrets: Record<string, unknown>;
-  private _resources: Record<string, unknown>;
-
-  /** Maps import alias → real module name for kind resolution. */
-  readonly importAliases = new Map<string, string>();
-
-  /** Maps import alias → allowed kind names. Absent entry = unrestricted (e.g. Kernel). */
-  private readonly importedKinds = new Map<string, Set<string>>();
-
-  constructor(
-    source: string,
-    variables: Record<string, unknown> = {},
-    secrets: Record<string, unknown> = {},
-    resources: Record<string, unknown> = {},
-    private targets: string[] = [],
-    createInstance: InstanceFactory = async () => null,
-    emit: EmitEvent,
-    private readonly _hostEnv?: Record<string, string | undefined>,
-  ) {
-    super(source, {}, createInstance, new Set(), emit);
-    this._variables = variables;
-    this._secrets = secrets;
-    this._resources = resources;
-    this._rebuildContext();
-  }
-
-  get variables(): Record<string, unknown> {
-    return this._variables;
-  }
-
-  get secrets(): Record<string, unknown> {
-    return this._secrets;
-  }
-
-  get resources(): Record<string, unknown> {
-    return this._resources;
-  }
-
-  setVariables(vars: Record<string, unknown>): void {
-    this._variables = vars;
-    this._rebuildContext();
-  }
+export interface ModuleContext extends EvaluationContext {
+  readonly variables: Record<string, unknown>;
+  readonly secrets: Record<string, unknown>;
+  readonly resources: Record<string, unknown>;
 
-  setTargets(vars: string[]): void {
-    this.targets = vars;
-  }
+  /** Maps import alias -> real module name for kind resolution. */
+  readonly importAliases: Map<string, string>;
 
-  setSecrets(secrets: Record<string, unknown>): void {
-    this._secrets = secrets;
-    this._rebuildContext();
-  }
-
-  setResource(name: string, props: Record<string, unknown>): void {
-    this._resources = { ...this._resources, [name]: props };
-    this._rebuildContext();
-  }
-
-  protected override onResourceSnapshotted(name: string, snap: Record<string, unknown>): void {
-    this.setResource(name, snap);
-  }
-
-  /**
-   * Register an imported module under the given alias, with the list of kind names
-   * it exports. An empty kinds array means no restriction (used for built-ins like Kernel).
-   */
-  registerImport(alias: string, targetModule: string, kinds: string[]): void {
-    this.importAliases.set(alias, targetModule);
-    if (kinds.length > 0) {
-      this.importedKinds.set(alias, new Set(kinds));
-    }
-  }
-
-  getInstance(name: string): unknown {
-    const entry = this.resourceInstances.get(name);
-    if (!entry) {
-      throw new Error(
-        `Resource '${name}' not found in module context. Available resources: ${[...this.resourceInstances.keys()].join(", ")}`,
-      );
-    }
-    return entry?.instance;
-  }
+  setVariables(vars: Record<string, unknown>): void;
+  setTargets(vars: string[]): void;
+  setSecrets(secrets: Record<string, unknown>): void;
+  setResource(name: string, props: Record<string, unknown>): void;
 
+  registerImport(alias: string, targetModule: string, kinds: string[]): void;
+  getInstance(name: string): unknown;
   getInvocable<TInput = Record<string, any>, TOutput = any>(
     name: string,
-  ): Invocable<TInput, TOutput> {
-    const instance = this.getInstance(name);
-
-    if (
-      instance &&
-      typeof instance === "object" &&
-      "invoke" in instance &&
-      typeof instance.invoke !== "function"
-    ) {
-      throw new Error(`Resource '${name}' does not have an invoke() method.`);
-    }
-    return instance as Invocable<TInput, TOutput>;
-  }
-
-  /**
-   * Resolve a fully-qualified kind like "Http.Server" to its real kind "http-server.Server".
-   * Splits on the first dot, looks up the prefix in importAliases, validates against
-   * importedKinds (if set), and reconstructs the resolved kind.
-   * Throws with a clear message if the alias is unknown or the kind is not exported.
-   */
-  resolveKind(kind: string): string {
-    const dot = kind.indexOf(".");
-    if (dot === -1) {
-      throw new Error(`Kind '${kind}' must be fully qualified (e.g. 'Module.KindName')`);
-    }
-    const prefix = kind.slice(0, dot);
-    const suffix = kind.slice(dot + 1);
-    const realModule = this.importAliases.get(prefix);
-    if (!realModule) {
-      const known = [...this.importAliases.keys()].join(", ") || "(none)";
-      throw new Error(
-        `Kind '${kind}': no module imported with alias '${prefix}'. Known aliases: ${known}`,
-      );
-    }
-    const allowed = this.importedKinds.get(prefix);
-    if (allowed !== undefined && !allowed.has(suffix)) {
-      throw new Error(
-        `Kind '${suffix}' is not exported by module '${realModule}' (imported as '${prefix}'). ` +
-          `Exported kinds: ${[...allowed].join(", ")}`,
-      );
-    }
-    return `${realModule}.${suffix}`;
-  }
-
-  private _rebuildContext(): void {
-    this._context = {
-      variables: this._variables,
-      secrets: this._secrets,
-      resources: this._resources,
-      ...(this._hostEnv ? { env: lenientEnv(this._hostEnv) } : {}),
-    };
-    this._secretValues = collectSecretValues(this._secrets);
-  }
-
-  override async invoke<TInputs>(kind: string, name: string, inputs: TInputs): Promise<any> {
-    const result = await super.invoke(kind, name, inputs);
-    const entry = this.resourceInstances.get(name);
-    if (entry && typeof (entry.instance as any).snapshot === "function") {
-      const snap = await Promise.resolve((entry.instance as any).snapshot());
-      this.setResource(name, snap as Record<string, unknown>);
-    }
-    return result;
-  }
-
-  async run(name: string) {
-    const resource = this.resourceInstances.get(name);
-    if (!resource) {
-      throw new Error(
-        `Target resource ${name} not found in module context. Available resources: ${[...this.resourceInstances.keys()].join(", ")}`,
-      );
-    }
-    if (typeof resource.instance.run === "function") {
-      await resource.instance.run();
-    } else {
-      throw new Error(`Target resource ${name} does not have a run() method.`);
-    }
-  }
-
-  async runTargets() {
-    for (const target of this.targets) {
-      await this.run(target);
-    }
-  }
+  ): Invocable<TInput, TOutput>;
+  resolveKind(kind: string): string;
+  runTargets(): Promise<void>;
 }

package/src/ref.ts

@@ -48,7 +48,7 @@ export type Injected<T> = {
 /** Returns a schema node that emits `x-telo-ref` for buildReferenceFieldMap and carries
  *  KindRef<T> as its TypeScript type. For TypeBox schemas use Type.Unsafe<KindRef<T>>(Ref(...)).
  *
- *  @param ref Canonical ref string: "namespace/module-name#TypeName" or "kernel#TypeName" */
+ *  @param ref Canonical ref string: "namespace/module-name#TypeName" or "telo#TypeName" */
 export const Ref = <T = ResourceInstance>(ref: string): KindRef<T> =>
   ({ "x-telo-ref": ref } as unknown as KindRef<T>);
 

package/src/resource-context.ts

@@ -1,8 +1,16 @@
 import { ControllerContext } from "./controller-context.js";
 import { EvaluationContext } from "./evaluation-context.js";
 import { ModuleContext } from "./module-context.js";
+import { ResourceInstance } from "./resource-instance.js";
+import { ResourceManifest } from "./resource-manifest.js";
 import { RuntimeResource } from "./runtime-resource.js";
 
+export interface LoadOptions {
+  /** When true, `${{ }}` templates are replaced with CompiledValue wrappers
+   *  so they can be evaluated at runtime. Leave unset for static analysis. */
+  compile?: boolean;
+}
+
 export interface DataValidator {
   validate(data: any): void;
   isValid(data: any): boolean;
@@ -31,6 +39,12 @@ export interface ResourceContext extends ControllerContext {
   acquireHold(reason?: string): () => void;
   emitEvent(event: string, payload?: any): Promise<void>;
   invoke<TInputs>(kind: string, name: string, inputs: TInputs, options?: any): Promise<any>;
+  invokeResolved<TInputs>(
+    kind: string,
+    name: string,
+    instance: ResourceInstance,
+    inputs: TInputs,
+  ): Promise<any>;
   run(kind: string, name: string): Promise<void>;
   getResources(kind: string): RuntimeResource[];
   getResourcesByName(kind: string, name: string): RuntimeResource | null;
@@ -51,7 +65,16 @@ export interface ResourceContext extends ControllerContext {
   registerDefinition(definition: any): void;
   registerModuleImport(alias: string, targetModule: string, kinds: string[]): void;
   teardownResource(kind: string, name: string): Promise<void>;
+  /** Load a single module (its own file + `include`d partials). Use this when
+   *  you need just the declaring file's manifests. */
+  loadModule(url: string, options?: LoadOptions): Promise<ResourceManifest[]>;
+  /** Load a module and follow its Telo.Import chain, returning the union of
+   *  the module's manifests plus all transitively-imported Telo.Definition
+   *  manifests. Use this when you need the full kind surface area visible from
+   *  the module. */
+  loadManifests(url: string): Promise<ResourceManifest[]>;
   readonly moduleContext: ModuleContext;
+  readonly env: Record<string, string | undefined>;
   readonly stdin: NodeJS.ReadableStream;
   readonly stdout: NodeJS.WritableStream;
   readonly stderr: NodeJS.WritableStream;

package/src/types.ts

@@ -14,6 +14,22 @@ export interface ExecContext {
   [key: string]: any;
 }
 
+export interface ThrowCodeSpec {
+  description: string;
+  data?: Record<string, any>;
+}
+
+/**
+ * Declared throw contract for a Telo.Invocable or Telo.Runnable definition.
+ * Codes-only (explicit contract) in Phase 1; `inherit` and `passthrough` land
+ * in Phase 2 together with the analyzer dataflow pass.
+ */
+export interface ThrowsSpec {
+  codes?: Record<string, ThrowCodeSpec>;
+  inherit?: boolean;
+  passthrough?: boolean;
+}
+
 export interface ResourceDefinition {
   kind: string;
   metadata: {
@@ -27,6 +43,8 @@ export interface ResourceDefinition {
     runtime: string;
     entry: string;
   }>;
+  /** Declared throw contract — only valid on Telo.Invocable / Telo.Runnable. */
+  throws?: ThrowsSpec;
 }
 
 /**

package/dist/capability-definition.d.ts

@@ -1,8 +0,0 @@
-import type { CapabilityDefinition } from "./types.js";
-/**
- * Factory that wires the declarative `expand` config on a CapabilityDefinition
- * into the `onManifest` and `onInvoke` lifecycle hooks. The kernel only ever
- * calls these hooks — it has no knowledge of the `expand` config.
- */
-export declare function createCapability(def: CapabilityDefinition): CapabilityDefinition;
-//# sourceMappingURL=capability-definition.d.ts.map

package/dist/capability-definition.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"capability-definition.d.ts","sourceRoot":"","sources":["../src/capability-definition.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,YAAY,CAAC;AAGvD;;;;GAIG;AACH,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,oBAAoB,GAAG,oBAAoB,CAwBhF"}

package/dist/capability-definition.js

@@ -1,21 +0,0 @@
-/**
- * Factory that wires the declarative `expand` config on a CapabilityDefinition
- * into the `onManifest` and `onInvoke` lifecycle hooks. The kernel only ever
- * calls these hooks — it has no knowledge of the `expand` config.
- */
-export function createCapability(def) {
-    const compile = def.expand?.compile ?? [];
-    const runtime = def.expand?.runtime ?? [];
-    return {
-        ...def,
-        onManifest: compile.length
-            ? (manifest, ctx) => ctx.expandPaths(manifest, compile, runtime)
-            : def.onManifest,
-        onInvoke: runtime.length
-            ? async (instance, inputs, ctx) => {
-                const expanded = ctx.moduleContext.expandPaths(inputs, runtime);
-                return instance.invoke(expanded);
-            }
-            : def.onInvoke,
-    };
-}

package/dist/cel-environment.d.ts

@@ -1,3 +0,0 @@
-import { Environment } from "@marcbachmann/cel-js";
-export declare const celEnvironment: Environment;
-//# sourceMappingURL=cel-environment.d.ts.map

package/dist/cel-environment.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"cel-environment.d.ts","sourceRoot":"","sources":["../src/cel-environment.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,MAAM,sBAAsB,CAAC;AAEnD,eAAO,MAAM,cAAc,aAWvB,CAAC"}

package/dist/cel-environment.js

@@ -1,13 +0,0 @@
-import { Environment } from "@marcbachmann/cel-js";
-export const celEnvironment = new Environment({ unlistedVariablesAreDyn: true })
-    .registerFunction("join(list, string): string", (list, sep) => list.map(String).join(sep))
-    .registerFunction("keys(map): list", (map) => {
-    if (map instanceof Map)
-        return [...map.keys()];
-    return Object.keys(map);
-})
-    .registerFunction("values(map): list", (map) => {
-    if (map instanceof Map)
-        return [...map.values()];
-    return Object.values(map);
-});

package/dist/execution-context.d.ts

@@ -1,13 +0,0 @@
-import { EvaluationContext } from "./evaluation-context.js";
-import { ModuleContext } from "./module-context.js";
-/**
- * The ephemeral, per-trigger context layer. Merges a ModuleContext with
- * arbitrary execution-time properties (e.g. { request, inputs } for HTTP;
- * any shape is valid — determined by the trigger type).
- *
- * Execution props overlay the module namespaces on key conflict.
- */
-export declare class ExecutionContext extends EvaluationContext {
-    constructor(moduleCtx: ModuleContext, execProps: Record<string, unknown>);
-}
-//# sourceMappingURL=execution-context.d.ts.map

package/dist/execution-context.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"execution-context.d.ts","sourceRoot":"","sources":["../src/execution-context.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,iBAAiB,EAAE,MAAM,yBAAyB,CAAC;AAC5D,OAAO,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AAEpD;;;;;;GAMG;AACH,qBAAa,gBAAiB,SAAQ,iBAAiB;gBACzC,SAAS,EAAE,aAAa,EAAE,SAAS,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;CASzE"}

package/dist/execution-context.js

@@ -1,13 +0,0 @@
-import { EvaluationContext } from "./evaluation-context.js";
-/**
- * The ephemeral, per-trigger context layer. Merges a ModuleContext with
- * arbitrary execution-time properties (e.g. { request, inputs } for HTTP;
- * any shape is valid — determined by the trigger type).
- *
- * Execution props overlay the module namespaces on key conflict.
- */
-export class ExecutionContext extends EvaluationContext {
-    constructor(moduleCtx, execProps) {
-        super(moduleCtx.source, Object.assign(Object.create(null), moduleCtx.context, execProps), moduleCtx.createInstance, moduleCtx.secretValues, moduleCtx.emit);
-    }
-}

package/src/execution-context.ts

@@ -1,21 +0,0 @@
-import { EvaluationContext } from "./evaluation-context.js";
-import { ModuleContext } from "./module-context.js";
-
-/**
- * The ephemeral, per-trigger context layer. Merges a ModuleContext with
- * arbitrary execution-time properties (e.g. { request, inputs } for HTTP;
- * any shape is valid — determined by the trigger type).
- *
- * Execution props overlay the module namespaces on key conflict.
- */
-export class ExecutionContext extends EvaluationContext {
-  constructor(moduleCtx: ModuleContext, execProps: Record<string, unknown>) {
-    super(
-      moduleCtx.source,
-      Object.assign(Object.create(null), moduleCtx.context, execProps) as Record<string, unknown>,
-      moduleCtx.createInstance,
-      moduleCtx.secretValues,
-      moduleCtx.emit,
-    );
-  }
-}