@telorun/sdk 0.2.4 → 0.2.6

package/src/module-context.ts

@@ -0,0 +1,215 @@
+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;
+}
+
+/**
+ * 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).
+ *
+ * Imported modules are surfaced under resources.<alias> alongside local
+ * resources — no separate imports namespace needed.
+ */
+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();
+  }
+
+  setTargets(vars: string[]): void {
+    this.targets = vars;
+  }
+
+  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;
+  }
+
+  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);
+    }
+  }
+}

package/src/ref.ts

@@ -0,0 +1,61 @@
+import type { ResourceInstance } from "./resource-instance.js";
+
+/** Marker type for x-telo-ref fields. Carries the live instance type at the TypeScript level;
+ *  at runtime this field holds `{ kind, name }` until Phase 5 injection replaces it.
+ *  T is a phantom type — any capability interface (Invocable, Runnable, …) or ResourceInstance. */
+export interface KindRef<T = ResourceInstance> {
+  readonly kind: string;
+  readonly name: string;
+  readonly __type?: T;
+}
+
+/** Marker type for x-telo-scope fields. Has no runtime value — used only as a discriminant
+ *  for Injected<T> to transform the field to ScopeHandle. */
+export interface ScopeRef {
+  readonly __scope: true;
+}
+
+/** Gives a controller access to the resources initialized within a scope. */
+export interface ScopeContext {
+  /** Returns the initialized instance for the given name.
+   *  Throws synchronously if the name was not declared in the scope —
+   *  this is always a programming error; all scope members are statically
+   *  validated in Phase 3 before the kernel ever reaches runtime. */
+  getInstance(name: string): ResourceInstance;
+}
+
+/** Returned by Phase 5 injection in place of an x-telo-scope manifest array.
+ *  The controller calls run() to open the scope, execute work, and tear it down. */
+export interface ScopeHandle {
+  run<T>(fn: (scope: ScopeContext) => Promise<T>): Promise<T>;
+}
+
+/** Transforms the raw config shape into the controller's view:
+ *  - KindRef<U>   → U        (live instance, injected by Phase 5)
+ *  - KindRef<U>[] → U[]      (live instances, injected by Phase 5)
+ *  - ScopeRef     → ScopeHandle
+ *  - everything else is unchanged */
+export type Injected<T> = {
+  [K in keyof T]: T[K] extends KindRef<infer U>
+    ? U
+    : T[K] extends KindRef<infer U>[]
+      ? U[]
+      : NonNullable<T[K]> extends ScopeRef
+        ? ScopeHandle | Exclude<T[K], ScopeRef>
+        : T[K];
+};
+
+/** 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" */
+export const Ref = <T = ResourceInstance>(ref: string): KindRef<T> =>
+  ({ "x-telo-ref": ref } as unknown as KindRef<T>);
+
+/** Returns a schema node that emits `x-telo-scope` for buildReferenceFieldMap and carries
+ *  ScopeRef as its TypeScript type. For TypeBox schemas use Type.Unsafe<ScopeRef>(Scope(...)).
+ *
+ *  @param visibilityPath JSON Pointer(s) (RFC 6901) declaring where x-telo-ref slots within
+ *                        this field can resolve to scoped resources. */
+export const Scope = (visibilityPath: string | string[]): ScopeRef =>
+  ({ "x-telo-scope": visibilityPath } as unknown as ScopeRef);

package/src/resource-context.ts

@@ -1,4 +1,6 @@
 import { ControllerContext } from "./controller-context.js";
+import { EvaluationContext } from "./evaluation-context.js";
+import { ModuleContext } from "./module-context.js";
 import { RuntimeResource } from "./runtime-resource.js";
 
 export interface DataValidator {
@@ -19,23 +21,25 @@ export class NoopValidator implements DataValidator {
 export interface ResourceContext extends ControllerContext {
   acquireHold(reason?: string): () => void;
   emitEvent(event: string, payload?: any): Promise<void>;
-  invoke(kind: string, name: string, ...args: any[]): Promise<any>;
+  invoke<TInputs>(kind: string, name: string, inputs: TInputs, options?: any): Promise<any>;
+  run(kind: string, name: string): Promise<void>;
   getResources(kind: string): RuntimeResource[];
   getResourcesByName(kind: string, name: string): RuntimeResource | null;
   registerManifest(resource: any): void;
+  spawnChildContext(): EvaluationContext;
+  transientChild(context: Record<string, any>): EvaluationContext;
+  withManifests<T>(manifests: any[], fn: () => T): T;
   resolveChildren(resource: any, resourceName?: string): { kind: string; name: string };
   validateSchema(value: any, schema: any): void;
   createSchemaValidator(schema: any): DataValidator;
   registerSchema(name: string, schema: object): void;
   lookupSchema(name: string): object | undefined;
-  registerController(
-    moduleName: string,
-    kindName: string,
-    controllerInstance: any,
-  ): Promise<void>;
+  registerController(moduleName: string, kindName: string, controllerInstance: any): Promise<void>;
   registerDefinition(definition: any): void;
-  registerCapability(name: string, schema?: Record<string, any>): void;
-  isCapabilityRegistered(name: string): boolean;
-  getCapabilitySchema(name: string): Record<string, any> | null | undefined;
+  registerModuleImport(alias: string, targetModule: string, kinds: string[]): void;
   teardownResource(kind: string, name: string): Promise<void>;
+  moduleContext: ModuleContext;
+  stdin: NodeJS.ReadableStream;
+  stdout: NodeJS.WritableStream;
+  stderr: NodeJS.WritableStream;
 }

package/src/resource-instance.ts

@@ -1,15 +1,12 @@
-import { ResourceContext } from "./resource-context.js";
+import type { Invocable } from "./capabilities/invokable.js";
+import type { Runnable } from "./capabilities/runnable.js";
+import type { ResourceContext } from "./resource-context.js";
 
-export type ResourceInstance = {
-  init?(ctx?: ResourceContext): Promise<void>;
-  run?(): void | Promise<void>;
-  invoke?(input: any): any | Promise<any>;
-  teardown?(): void | Promise<void>;
-
-  /**
-   * Optional method for debugging/snapshots
-   * Called when taking runtime state snapshots
-   * Should return serializable state data specific to this resource
-   */
-  snapshot?(): Record<string, any> | Promise<Record<string, any>>;
-};
+export type ResourceInstance<TInput = Record<string, any>, TOutput = any> = Partial<
+  Invocable<TInput, TOutput>
+> &
+  Partial<Runnable> & {
+    init?(ctx?: ResourceContext): Promise<void>;
+    teardown?(): void | Promise<void>;
+    snapshot?(): Record<string, any> | Promise<Record<string, any>>;
+  };

package/src/resource-manifest.ts

@@ -5,7 +5,7 @@ export interface ResourceManifest {
   kind: string;
   metadata: {
     name: string;
-    module: string;
+    module?: string;
     [key: string]: any;
   };
   [key: string]: any;

package/src/runtime-error.ts

@@ -1,9 +1,22 @@
+export interface RuntimeDiagnostic {
+  severity?: "error" | "warning";
+  message: string;
+  resource?: string;
+  code?: string;
+}
+
 export type RuntimeErrorCode =
-  | 'ERR_RESOURCE_NOT_FOUND'
-  | 'ERR_CONTROLLER_NOT_FOUND'
-  | 'ERR_CONTROLLER_INVALID'
-  | 'ERR_RESOURCE_NOT_INVOKABLE'
-  | 'ERR_DUPLICATE_RESOURCE'
-  | 'ERR_EXECUTION_FAILED'
-  | 'ERR_INVALID_VALUE'
-  | 'ERR_VISIBILITY_DENIED';
+  | "ERR_RESOURCE_NOT_FOUND"
+  | "ERR_RESOURCE_NOT_RUNNABLE"
+  | "ERR_CONTROLLER_NOT_FOUND"
+  | "ERR_CONTROLLER_INVALID"
+  | "ERR_RESOURCE_INITIALIZATION_FAILED"
+  | "ERR_RESOURCE_NOT_INVOKABLE"
+  | "ERR_RESOURCE_SCHEMA_VALIDATION_FAILED"
+  | "ERR_DUPLICATE_RESOURCE"
+  | "ERR_EXECUTION_FAILED"
+  | "ERR_INVALID_VALUE"
+  | "ERR_VISIBILITY_DENIED"
+  | "ERR_MANIFEST_VALIDATION_FAILED"
+  | "ERR_CIRCULAR_DEPENDENCY"
+  | "ERR_SCOPE_RESOURCE_NOT_FOUND";

package/src/types.ts

@@ -0,0 +1,91 @@
+import { ControllerContext } from "./controller-context.js";
+import { ResourceContext } from "./resource-context.js";
+import { ResourceInstance } from "./resource-instance.js";
+import { ResourceManifest } from "./resource-manifest.js";
+import { RuntimeDiagnostic, RuntimeErrorCode } from "./runtime-error.js";
+import { RuntimeResource } from "./runtime-resource.js";
+
+export interface KernelContext {
+  kernel: Kernel;
+}
+
+export interface ExecContext {
+  execute(urn: string, input: any): Promise<any>;
+  [key: string]: any;
+}
+
+export interface ResourceDefinition {
+  kind: string;
+  metadata: {
+    name: string;
+    module: string;
+  };
+  /** JSON Schema for the resource's compile-time configuration fields. */
+  schema?: Record<string, any>;
+  capability?: 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; // Fully-qualified kind (e.g., "Http.Route")
+  runtime: string; // Runtime selector (e.g., "node@>=20")
+  entry: string; // Path to controller implementation
+  controller?: any; // Lazy-loaded controller code
+}
+
+/**
+ * Controller instance - runtime representation of a controller that handles resource instances.
+ *
+ * TResource - the typed shape of the resource manifest (compile-time config)
+ * TInput    - the typed shape of invoke() inputs (runtime)
+ * TOutput   - the typed shape of invoke() outputs (runtime)
+ */
+export interface ControllerInstance<
+  TResource extends ResourceManifest = ResourceManifest,
+  TInput = Record<string, any>,
+  TOutput = any,
+> {
+  execute?(name: string, inputs: any, ctx: ExecContext): Promise<any>;
+  compile?(resource: TResource, ctx: ResourceContext): RuntimeResource | Promise<RuntimeResource>;
+  register?(ctx: ControllerContext): void | Promise<void>;
+  create?(
+    resource: TResource,
+    ctx: ResourceContext,
+  ): ResourceInstance<TInput, TOutput> | null | Promise<ResourceInstance<TInput, TOutput> | null>;
+  schema?: any;
+  /** JSON Schema for invoke() inputs — used for runtime validation and static analysis. */
+  inputSchema?: Record<string, any>;
+  /** JSON Schema for invoke() outputs — used for documentation and static analysis. */
+  outputSchema?: Record<string, 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>;
+  // getSourceFiles(): string[];
+  // reloadSource(sourcePath: string): Promise<void>;
+  shutdown(): void;
+}
+
+export class RuntimeError extends Error {
+  constructor(
+    public code: RuntimeErrorCode,
+    message: string,
+    public diagnostics?: RuntimeDiagnostic[],
+  ) {
+    super(message);
+    this.name = "RuntimeError";
+  }
+}