@telorun/sdk 0.2.3 → 0.2.5

package/README.md

@@ -1,6 +1,6 @@
 # Telo SDK (Node.js)
 
-The Node.js SDK provides the authoring surface for Telo modules. It defines the shared contracts (types and lifecycle interfaces) that modules use to plug into the runtime, so module code stays consistent across implementations.
+The Node.js SDK provides the authoring surface for Telo modules. It defines the shared contracts (types and lifecycle interfaces) that modules use to plug into the kernel, so module code stays consistent across implementations.
 
 ## What It Provides
 
@@ -14,10 +14,10 @@ Early prototype. APIs and contracts are still evolving. The API surface - includ
 
 ## When to Use It
 
-Use the SDK when building or extending Telo modules. It is not the runtime itself; it is the contract layer that keeps module behavior consistent and predictable.
+Use the SDK when building or extending Telo modules. It is not the kernel itself; it is the contract layer that keeps module behavior consistent and predictable.
 
 ## Related Docs
 
-- Runtime overview: `runtime/README.md`
-- Built‑in modules: `modiles/`
-- SDKs index: `sdk/README.md`
+- Kernel overview: [kernel/README.md](../../kernel/README.md)
+- Built‑in modules: [modules/](../../modules/)
+- SDKs index: [sdk/README.md](../README.md)

package/dist/capabilities/invokable.d.ts

@@ -0,0 +1,4 @@
+export interface Invokable {
+    invoke(inputs: Record<string, any>): Promise<any>;
+}
+//# sourceMappingURL=invokable.d.ts.map

package/dist/capabilities/invokable.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"invokable.d.ts","sourceRoot":"","sources":["../../src/capabilities/invokable.ts"],"names":[],"mappings":"AAAA,MAAM,WAAW,SAAS;IACxB,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAAG,OAAO,CAAC,GAAG,CAAC,CAAC;CACnD"}

package/dist/capabilities/invokable.js

@@ -0,0 +1 @@
+export {};

package/dist/capabilities/provider.d.ts

@@ -0,0 +1,4 @@
+export interface Provider {
+    init(): Promise<void>;
+}
+//# sourceMappingURL=provider.d.ts.map

package/dist/capabilities/provider.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"provider.d.ts","sourceRoot":"","sources":["../../src/capabilities/provider.ts"],"names":[],"mappings":"AAAA,MAAM,WAAW,QAAQ;IACvB,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CACvB"}

package/dist/capabilities/provider.js

@@ -0,0 +1 @@
+export {};

package/dist/capabilities/runnable.d.ts

@@ -0,0 +1,4 @@
+export interface Runnable {
+    run(): Promise<void>;
+}
+//# sourceMappingURL=runnable.d.ts.map

package/dist/capabilities/runnable.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"runnable.d.ts","sourceRoot":"","sources":["../../src/capabilities/runnable.ts"],"names":[],"mappings":"AAAA,MAAM,WAAW,QAAQ;IACvB,GAAG,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CACtB"}

package/dist/capabilities/runnable.js

@@ -0,0 +1 @@
+export {};

package/dist/context-provider.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Optional interface that a ResourceInstance can implement to expose
+ * stable, boot-time key/value pairs into the shared CEL context.
+ *
+ * Values are captured once after init() completes and cached for the
+ * lifetime of the initialization phase. Do not return request-specific
+ * or mutable data — this is AOT (Ahead-of-Time) static context only.
+ */
+export interface ContextProvider {
+    provideContext(): Record<string, unknown>;
+}
+/**
+ * Duck-type guard: returns true when `instance` has a callable `provideContext` method.
+ * The kernel uses this to detect providers without coupling to any concrete class,
+ * keeping the Core 100% generic.
+ */
+export declare function isContextProvider(instance: unknown): instance is ContextProvider;
+//# sourceMappingURL=context-provider.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"context-provider.d.ts","sourceRoot":"","sources":["../src/context-provider.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,MAAM,WAAW,eAAe;IAC9B,cAAc,IAAI,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAC3C;AAED;;;;GAIG;AACH,wBAAgB,iBAAiB,CAAC,QAAQ,EAAE,OAAO,GAAG,QAAQ,IAAI,eAAe,CAOhF"}

package/dist/context-provider.js

@@ -0,0 +1,11 @@
+/**
+ * Duck-type guard: returns true when `instance` has a callable `provideContext` method.
+ * The kernel uses this to detect providers without coupling to any concrete class,
+ * keeping the Core 100% generic.
+ */
+export function isContextProvider(instance) {
+    return (typeof instance === 'object' &&
+        instance !== null &&
+        'provideContext' in instance &&
+        typeof instance['provideContext'] === 'function');
+}

package/dist/controller-context.d.ts

@@ -1,4 +1,4 @@
-import { RuntimeEvent } from './runtime-event.js';
+import { RuntimeEvent } from "./runtime-event.js";
 export interface ControllerContext {
     on(event: string, handler: (event: RuntimeEvent) => void | Promise<void>): void;
     once(event: string, handler: (event: RuntimeEvent) => void | Promise<void>): void;
@@ -6,6 +6,6 @@ export interface ControllerContext {
     emit(event: string, payload?: any, metadata?: Record<string, any>): void;
     acquireHold(reason?: string): () => void;
     requestExit(code: number): void;
-    evaluateCel(expression: string, context: Record<string, any>): unknown;
     expandValue(value: any, context: Record<string, any>): any;
 }
+//# sourceMappingURL=controller-context.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"controller-context.d.ts","sourceRoot":"","sources":["../src/controller-context.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAElD,MAAM,WAAW,iBAAiB;IAChC,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,CAAC,KAAK,EAAE,YAAY,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC;IAChF,IAAI,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,CAAC,KAAK,EAAE,YAAY,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC;IAClF,GAAG,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,CAAC,KAAK,EAAE,YAAY,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC;IACjF,IAAI,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,GAAG,EAAE,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAAG,IAAI,CAAC;IACzE,WAAW,CAAC,MAAM,CAAC,EAAE,MAAM,GAAG,MAAM,IAAI,CAAC;IACzC,WAAW,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IAChC,WAAW,CAAC,KAAK,EAAE,GAAG,EAAE,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAAG,GAAG,CAAC;CAC5D"}

package/dist/evaluation-context.d.ts

@@ -0,0 +1,103 @@
+import { ModuleContext } from "./module-context.js";
+import { ResourceInstance } from "./resource-instance.js";
+import { ResourceManifest } from "./resource-manifest.js";
+export type EmitEvent = (event: string, payload?: any) => void | Promise<void>;
+/** Four-stage resource lifecycle defined in resource-lifecycle.md */
+export type LifecycleState = "Pending" | "Validated" | "Initialized" | "Draining" | "Teardown";
+/**
+ * Creates a ResourceInstance for the given manifest, or returns null if not yet
+ * ready (e.g. a dependency is still initializing). Injected at construction so
+ * every EvaluationContext node owns its full resource lifecycle.
+ */
+export type InstanceFactory = (moduleContext: ModuleContext, resource: ResourceManifest) => Promise<ResourceInstance | null>;
+/** Canonical key for a resource instance: "<module>.<kind>.<name>" */
+export declare function resourceKey(r: ResourceManifest): string;
+/**
+ * Base class for all evaluation contexts. Owns CEL evaluation, template
+ * expansion, secrets redaction, and the generic resource lifecycle tree.
+ *
+ * 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)
+ */
+export declare class EvaluationContext {
+    readonly source: string;
+    readonly id: string;
+    protected _context: Record<string, unknown>;
+    protected _secretValues: Set<string>;
+    protected _createInstance: InstanceFactory;
+    readonly emit: EmitEvent;
+    /** Position in the lifecycle tree. */
+    parent: EvaluationContext | undefined;
+    readonly children: EvaluationContext[];
+    /** Current lifecycle state of this context node. */
+    state: LifecycleState;
+    /** Resource instances owned by this context node, keyed by resourceKey(). */
+    readonly resourceInstances: Map<string, {
+        resource: ResourceManifest;
+        instance: ResourceInstance;
+    }>;
+    /** Resources queued for initialization on this context node. */
+    private pendingResources;
+    constructor(source: string, context: Record<string, unknown>, createInstance: InstanceFactory | undefined, secretValues: Set<string>, emit: EmitEvent);
+    get createInstance(): InstanceFactory;
+    get context(): Record<string, unknown>;
+    get secretValues(): Set<string>;
+    /**
+     * Queue a resource manifest for initialization on this context.
+     */
+    registerManifest(resource: ResourceManifest): void;
+    /**
+     * 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;
+    /**
+     * Multi-pass initialization loop. Processes pendingResources by calling the
+     * supplied instantiator for each resource, retrying failures across up to 10
+     * passes (handles dependency ordering without explicit topological sort).
+     *
+     * ERR_VISIBILITY_DENIED errors are fatal and re-thrown immediately.
+     * All other errors are tracked and retried until no progress is made.
+     */
+    initializeResources(): Promise<void>;
+    withManifests<T>(manifests: any[], fn: () => T): T;
+    /**
+     * 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.
+     *
+     * Note: Kernel-level events (e.g. Teardown events) are NOT emitted here —
+     * they remain the Kernel's responsibility.
+     */
+    teardownResources(): Promise<void>;
+    /**
+     * Invoke a resource by kind and name within this context's resourceInstances.
+     * Emits a scoped Invoked event via the injected emit callback after invocation.
+     */
+    invoke(kind: string, name: string, ...args: any[]): Promise<any>;
+    run(name: string): Promise<void>;
+    /**
+     * Evaluate a single CEL expression string against the context.
+     * Secret values are redacted from any thrown error message.
+     */
+    evaluate(expression: string): unknown;
+    /**
+     * Expand a value that may contain ${{ }} templates.
+     * Works recursively over strings, arrays, and objects.
+     * Templates whose identifiers are not present in the context are left
+     * unchanged (deferred) — they will be resolved at execution time when a
+     * richer ExecutionContext is available. All other CEL errors are propagated.
+     */
+    expand(value: unknown): unknown;
+    /**
+     * Merge another context on top of this one.
+     * Returns a new base EvaluationContext — 'other' wins on key conflict.
+     */
+    merge(other: EvaluationContext | Record<string, unknown>): EvaluationContext;
+    private expandString;
+}
+//# sourceMappingURL=evaluation-context.d.ts.map

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

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

package/dist/evaluation-context.js

@@ -0,0 +1,256 @@
+import { evaluate } from "cel-js";
+import { RuntimeError } from "./types.js";
+const TEMPLATE_REGEX = /\$\{\{\s*([^}]+?)\s*\}\}/g;
+const EXACT_TEMPLATE_REGEX = /^\s*\$\{\{\s*([^}]+?)\s*\}\}\s*$/;
+/** Canonical key for a resource instance: "<module>.<kind>.<name>" */
+export function resourceKey(r) {
+    return `${r.kind}.${r.metadata.name}`;
+}
+function redactSecrets(message, secretValues) {
+    if (secretValues.size === 0)
+        return message;
+    const sorted = Array.from(secretValues).sort((a, b) => b.length - a.length);
+    let result = message;
+    for (const secret of sorted) {
+        result = result.split(secret).join("[REDACTED]");
+    }
+    return result;
+}
+/**
+ * Base class for all evaluation contexts. Owns CEL evaluation, template
+ * expansion, secrets redaction, and the generic resource lifecycle tree.
+ *
+ * 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)
+ */
+export class EvaluationContext {
+    source;
+    id = Math.random().toString(16).slice(2, 8);
+    _context;
+    _secretValues;
+    _createInstance;
+    emit;
+    /** Position in the lifecycle tree. */
+    parent = undefined;
+    children = [];
+    /** Current lifecycle state of this context node. */
+    state = "Pending";
+    /** Resource instances owned by this context node, keyed by resourceKey(). */
+    resourceInstances = new Map();
+    /** Resources queued for initialization on this context node. */
+    pendingResources = [];
+    constructor(source, context, createInstance = async () => null, secretValues, emit) {
+        this.source = source;
+        this._context = context;
+        this._createInstance = createInstance;
+        this._secretValues = secretValues ?? new Set();
+        this.emit = emit;
+    }
+    get createInstance() {
+        return this._createInstance;
+    }
+    get context() {
+        return this._context;
+    }
+    get secretValues() {
+        return this._secretValues;
+    }
+    /**
+     * Queue a resource manifest for initialization on this context.
+     */
+    registerManifest(resource) {
+        if (!resource.metadata) {
+            resource.metadata = { name: `__unnamed_${Math.random().toString(16).slice(2, 8)}` };
+        }
+        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(child) {
+        child.parent = this;
+        this.children.push(child);
+        return child;
+    }
+    /**
+     * Multi-pass initialization loop. Processes pendingResources by calling the
+     * supplied instantiator for each resource, retrying failures across up to 10
+     * passes (handles dependency ordering without explicit topological sort).
+     *
+     * ERR_VISIBILITY_DENIED errors are fatal and re-thrown immediately.
+     * All other errors are tracked and retried until no progress is made.
+     */
+    async initializeResources() {
+        const MAX_PASSES = 10;
+        let pass = 1;
+        const errors = new Map();
+        do {
+            const handled = [];
+            for (const resource of [...this.pendingResources]) {
+                // const rkey = resourceKey(resource);
+                // const displayKey = rkey;
+                const name = resource.metadata.name;
+                if (this.resourceInstances.has(name))
+                    continue;
+                try {
+                    const instance = await this._createInstance(this, resource);
+                    if (instance) {
+                        this.resourceInstances.set(name, { resource, instance });
+                        handled.push(name);
+                        errors.delete(name);
+                    }
+                }
+                catch (error) {
+                    if (error instanceof RuntimeError && error.code === "ERR_VISIBILITY_DENIED")
+                        throw error;
+                    errors.set(name, error instanceof Error ? (error.stack ?? error.message) : String(error));
+                }
+            }
+            for (const name of handled) {
+                const resource = this.pendingResources.find((m) => m.metadata.name === name);
+                const idx = this.pendingResources.indexOf(resource);
+                if (idx >= 0)
+                    this.pendingResources.splice(idx, 1);
+            }
+            pass++;
+            if (handled.length === 0)
+                break;
+        } while (pass <= MAX_PASSES);
+        if (this.pendingResources.length > 0) {
+            const unhandledList = this.pendingResources
+                .reverse()
+                .map((r) => `- ${r.metadata.name}: ${errors.get(r.metadata.name) ?? "Unknown error"}`)
+                .join("\n");
+            throw new RuntimeError("ERR_RESOURCE_INITIALIZATION_FAILED", `Unable to process resources:\n\n${unhandledList}`);
+        }
+        this.state = "Initialized";
+    }
+    withManifests(manifests, fn) {
+        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();
+        }
+    }
+    /**
+     * 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.
+     *
+     * Note: Kernel-level events (e.g. Teardown events) are NOT emitted here —
+     * they remain the Kernel's responsibility.
+     */
+    async teardownResources() {
+        this.state = "Draining";
+        for (const child of [...this.children].reverse()) {
+            await child.teardownResources();
+        }
+        const entries = [...this.resourceInstances.entries()].reverse();
+        for (const [key, { instance }] of entries) {
+            if (instance.teardown)
+                await instance.teardown();
+            this.resourceInstances.delete(key);
+        }
+        this.state = "Teardown";
+    }
+    /**
+     * 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(kind, name, ...args) {
+        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(args[0]);
+            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) {
+        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(", ")}`);
+    }
+    /**
+     * Evaluate a single CEL expression string against the context.
+     * Secret values are redacted from any thrown error message.
+     */
+    evaluate(expression) {
+        try {
+            return evaluate(expression, this._context);
+        }
+        catch (error) {
+            const raw = error instanceof Error ? error.message : String(error);
+            const safe = redactSecrets(raw, this._secretValues);
+            throw new Error(`CEL evaluation failed: "${expression}": ${safe}`);
+        }
+    }
+    /**
+     * Expand a value that may contain ${{ }} templates.
+     * Works recursively over strings, arrays, and objects.
+     * Templates whose identifiers are not present in the context are left
+     * unchanged (deferred) — they will be resolved at execution time when a
+     * richer ExecutionContext is available. All other CEL errors are propagated.
+     */
+    expand(value) {
+        if (typeof value === "string") {
+            return this.expandString(value);
+        }
+        if (Array.isArray(value)) {
+            return value.map((entry) => this.expand(entry));
+        }
+        if (value !== null && typeof value === "object") {
+            const resolved = {};
+            for (const [key, entry] of Object.entries(value)) {
+                resolved[key] = this.expand(entry);
+            }
+            return resolved;
+        }
+        return value;
+    }
+    /**
+     * Merge another context on top of this one.
+     * Returns a new base EvaluationContext — 'other' wins on key conflict.
+     */
+    merge(other) {
+        const otherCtx = other instanceof EvaluationContext ? other.context : other;
+        const otherSecrets = other instanceof EvaluationContext ? other.secretValues : new Set();
+        const merged = Object.assign(Object.create(null), this._context, otherCtx);
+        const mergedSecrets = new Set([...this._secretValues, ...otherSecrets]);
+        return new EvaluationContext(this.source, merged, this._createInstance, mergedSecrets, this.emit);
+    }
+    expandString(value) {
+        if (!value.includes("${{")) {
+            return value;
+        }
+        const exact = value.match(EXACT_TEMPLATE_REGEX);
+        if (exact) {
+            return this.evaluate(exact[1]);
+        }
+        return value.replace(TEMPLATE_REGEX, (_match, expr) => {
+            const resolved = this.evaluate(expr);
+            if (resolved === null || resolved === undefined) {
+                return "";
+            }
+            return String(resolved);
+        });
+    }
+}

package/dist/execution-context.d.ts

@@ -0,0 +1,13 @@
+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

@@ -0,0 +1 @@
+{"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

@@ -0,0 +1,13 @@
+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/dist/index.d.ts

@@ -1,7 +1,15 @@
-export * from './controller-context.js';
-export * from './resource-context.js';
-export * from './resource-instance.js';
-export * from './resource-manifest.js';
-export * from './runtime-error.js';
-export * from './runtime-event.js';
-export * from './runtime-resource.js';
+export * from "./capabilities/invokable.js";
+export * from "./capabilities/provider.js";
+export * from "./capabilities/runnable.js";
+export * from "./context-provider.js";
+export * from "./controller-context.js";
+export * from "./evaluation-context.js";
+export * from "./module-context.js";
+export * from "./resource-context.js";
+export * from "./resource-instance.js";
+export * from "./resource-manifest.js";
+export * from "./runtime-error.js";
+export * from "./runtime-event.js";
+export * from "./runtime-resource.js";
+export * from "./types.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,6BAA6B,CAAC;AAC5C,cAAc,4BAA4B,CAAC;AAC3C,cAAc,4BAA4B,CAAC;AAC3C,cAAc,uBAAuB,CAAC;AACtC,cAAc,yBAAyB,CAAC;AACxC,cAAc,yBAAyB,CAAC;AACxC,cAAc,qBAAqB,CAAC;AACpC,cAAc,uBAAuB,CAAC;AACtC,cAAc,wBAAwB,CAAC;AACvC,cAAc,wBAAwB,CAAC;AACvC,cAAc,oBAAoB,CAAC;AACnC,cAAc,oBAAoB,CAAC;AACnC,cAAc,uBAAuB,CAAC;AACtC,cAAc,YAAY,CAAC"}

package/dist/index.js

@@ -1,7 +1,14 @@
-export * from './controller-context.js';
-export * from './resource-context.js';
-export * from './resource-instance.js';
-export * from './resource-manifest.js';
-export * from './runtime-error.js';
-export * from './runtime-event.js';
-export * from './runtime-resource.js';
+export * from "./capabilities/invokable.js";
+export * from "./capabilities/provider.js";
+export * from "./capabilities/runnable.js";
+export * from "./context-provider.js";
+export * from "./controller-context.js";
+export * from "./evaluation-context.js";
+export * from "./module-context.js";
+export * from "./resource-context.js";
+export * from "./resource-instance.js";
+export * from "./resource-manifest.js";
+export * from "./runtime-error.js";
+export * from "./runtime-event.js";
+export * from "./runtime-resource.js";
+export * from "./types.js";

package/dist/module-context.d.ts

@@ -0,0 +1,51 @@
+import { Invokable } from "./capabilities/invokable.js";
+import { EmitEvent, EvaluationContext, InstanceFactory } from "./evaluation-context.js";
+/**
+ * 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 declare class ModuleContext extends EvaluationContext {
+    private targets;
+    private _variables;
+    private _secrets;
+    private _resources;
+    /** Maps import alias → real module name for kind resolution. */
+    readonly importAliases: Map<string, string>;
+    /** Maps import alias → allowed kind names. Absent entry = unrestricted (e.g. Kernel). */
+    private readonly importedKinds;
+    constructor(source: string, variables: Record<string, unknown> | undefined, secrets: Record<string, unknown> | undefined, resources: Record<string, unknown> | undefined, targets: string[] | undefined, createInstance: InstanceFactory | undefined, emit: EmitEvent);
+    get variables(): Record<string, unknown>;
+    get secrets(): Record<string, unknown>;
+    get resources(): Record<string, unknown>;
+    setVariables(vars: Record<string, unknown>): void;
+    setTargets(vars: string[]): void;
+    setSecrets(secrets: Record<string, unknown>): void;
+    setResource(name: string, props: Record<string, unknown>): void;
+    /**
+     * 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;
+    getInstance(name: string): unknown;
+    getInvokable(name: string): Invokable;
+    /**
+     * 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;
+    private _rebuildContext;
+    invoke(kind: string, name: string, ...args: any[]): Promise<any>;
+    run(name: string): Promise<void>;
+    runTargets(): Promise<void>;
+}
+//# sourceMappingURL=module-context.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"module-context.d.ts","sourceRoot":"","sources":["../src/module-context.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,6BAA6B,CAAC;AACxD,OAAO,EAAE,SAAS,EAAE,iBAAiB,EAAE,eAAe,EAAE,MAAM,yBAAyB,CAAC;AAYxF;;;;;;;;;;;GAWG;AACH,qBAAa,aAAc,SAAQ,iBAAiB;IAgBhD,OAAO,CAAC,OAAO;IAfjB,OAAO,CAAC,UAAU,CAA0B;IAC5C,OAAO,CAAC,QAAQ,CAA0B;IAC1C,OAAO,CAAC,UAAU,CAA0B;IAE5C,gEAAgE;IAChE,QAAQ,CAAC,aAAa,sBAA6B;IAEnD,yFAAyF;IACzF,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAkC;gBAG9D,MAAM,EAAE,MAAM,EACd,SAAS,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,YAAK,EACvC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,YAAK,EACrC,SAAS,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,YAAK,EAC/B,OAAO,EAAE,MAAM,EAAE,YAAK,EAC9B,cAAc,EAAE,eAAe,YAAmB,EAClD,IAAI,EAAE,SAAS;IASjB,IAAI,SAAS,IAAI,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAEvC;IAED,IAAI,OAAO,IAAI,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAErC;IAED,IAAI,SAAS,IAAI,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAEvC;IAED,YAAY,CAAC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI;IAKjD,UAAU,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,IAAI;IAIhC,UAAU,CAAC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI;IAKlD,WAAW,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI;IAK/D;;;OAGG;IACH,cAAc,CAAC,KAAK,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,GAAG,IAAI;IAO1E,WAAW,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO;IAUlC,YAAY,CAAC,IAAI,EAAE,MAAM,GAAG,SAAS;IAcrC;;;;;OAKG;IACH,WAAW,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM;IAwBjC,OAAO,CAAC,eAAe;IASR,MAAM,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,GAAG,IAAI,EAAE,GAAG,EAAE,GAAG,OAAO,CAAC,GAAG,CAAC;IAUzE,GAAG,CAAC,IAAI,EAAE,MAAM;IAchB,UAAU;CAKjB"}