@telorun/sdk 0.2.5 → 0.2.7

package/dist/evaluation-context.js

@@ -1,23 +1,11 @@
-import { evaluate } from "cel-js";
+import { isCompiledValue } from "./compiled-value.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
+ * Base class for all evaluation contexts. Owns template
  * expansion, secrets redaction, and the generic resource lifecycle tree.
  *
  * Every EvaluationContext node can:
@@ -41,8 +29,15 @@ export class EvaluationContext {
     state = "Pending";
     /** Resource instances owned by this context node, keyed by resourceKey(). */
     resourceInstances = new Map();
+    /** Resources that have been created but not yet initialized (between phases). */
+    createdInstances = new Map();
     /** Resources queued for initialization on this context node. */
     pendingResources = [];
+    /**
+     * Optional hook called between create() and init() for each resource.
+     * Set by the kernel to inject live instances into reference fields.
+     */
+    preInitHook;
     constructor(source, context, createInstance = async () => null, secretValues, emit) {
         this.source = source;
         this._context = context;
@@ -53,19 +48,44 @@ export class EvaluationContext {
     get createInstance() {
         return this._createInstance;
     }
+    /** Called after init() when a resource snapshot is available. Overridden by ModuleContext. */
+    onResourceSnapshotted(_name, _snap) { }
     get context() {
         return this._context;
     }
     get secretValues() {
         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) {
+        const rank = new Map(names.map((n, i) => [n, i]));
+        this.pendingResources.sort((a, b) => {
+            const ra = rank.get(a.metadata.name) ?? Infinity;
+            const rb = rank.get(b.metadata.name) ?? Infinity;
+            return ra - rb;
+        });
+    }
     /**
      * Queue a resource manifest for initialization on this context.
      */
+    hasManifest(name) {
+        return (this.resourceInstances.has(name) ||
+            this.createdInstances.has(name) ||
+            this.pendingResources.some((r) => r.metadata.name === name));
+    }
     registerManifest(resource) {
         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);
     }
     /**
@@ -75,58 +95,107 @@ export class EvaluationContext {
     spawnChild(child) {
         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;
     }
     /**
-     * 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).
+     * 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.
      *
-     * ERR_VISIBILITY_DENIED errors are fatal and re-thrown immediately.
+     * 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() {
         const MAX_PASSES = 10;
-        let pass = 1;
         const errors = new Map();
+        let pass = 1;
         do {
-            const handled = [];
+            let progress = false;
+            // Create sub-phase
             for (const resource of [...this.pendingResources]) {
-                // const rkey = resourceKey(resource);
-                // const displayKey = rkey;
                 const name = resource.metadata.name;
-                if (this.resourceInstances.has(name))
+                if (this.createdInstances.has(name))
                     continue;
                 try {
-                    const instance = await this._createInstance(this, resource);
-                    if (instance) {
-                        this.resourceInstances.set(name, { resource, instance });
-                        handled.push(name);
+                    // const expanded = this.expand(resource) as ResourceManifest;
+                    // FIXME: Cannot expand it for all resources, needs to be selective
+                    const created = await this._createInstance(this, 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.stack ?? error.message) : String(error));
+                    errors.set(name, error instanceof Error ? 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);
+            // 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 ?? {});
+                    }
+                    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 (handled.length === 0)
+            if (!progress)
                 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}`);
+        if (this.pendingResources.length > 0 || this.createdInstances.size > 0) {
+            const diagnostics = [
+                ...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";
     }
@@ -145,13 +214,59 @@ export class EvaluationContext {
             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) {
+        const parent = this;
+        return {
+            async run(fn) {
+                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 = {
+                        getInstance(name) {
+                            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.
-     *
-     * Note: Kernel-level events (e.g. Teardown events) are NOT emitted here —
-     * they remain the Kernel's responsibility.
+     *   2. Tear down own resource instances in reverse registration order,
+     *      emitting a Teardown event for each via the injected emit callback.
      */
     async teardownResources() {
         this.state = "Draining";
@@ -159,24 +274,30 @@ export class EvaluationContext {
             await child.teardownResources();
         }
         const entries = [...this.resourceInstances.entries()].reverse();
-        for (const [key, { instance }] of entries) {
+        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) {
+        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(kind, name, ...args) {
+    async invoke(kind, name, inputs) {
         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]);
+            const outputs = await entry.instance.invoke(inputs);
             await this.emit(`${kind}.${name}.Invoked`, { outputs });
             return outputs;
         }
@@ -190,29 +311,12 @@ export class EvaluationContext {
         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 a value that may contain precompiled ${{ }} templates.
+     * Works recursively over CompiledValues, arrays, and objects.
      */
     expand(value) {
-        if (typeof value === "string") {
-            return this.expandString(value);
+        if (isCompiledValue(value)) {
+            return value.call(this._context);
         }
         if (Array.isArray(value)) {
             return value.map((entry) => this.expand(entry));
@@ -227,30 +331,64 @@ export class EvaluationContext {
         return value;
     }
     /**
-     * Merge another context on top of this one.
-     * Returns a new base EvaluationContext — 'other' wins on key conflict.
+     * Expand a value using this context merged with additional properties.
+     * Equivalent to merge(extraContext).expand(value) without allocating a context object.
      */
-    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;
+    expandWith(value, extraContext) {
+        const saved = this._context;
+        this._context = Object.assign(Object.create(null), saved, extraContext);
+        try {
+            return this.expand(value);
         }
-        const exact = value.match(EXACT_TEMPLATE_REGEX);
-        if (exact) {
-            return this.evaluate(exact[1]);
+        finally {
+            this._context = saved;
         }
-        return value.replace(TEMPLATE_REGEX, (_match, expr) => {
-            const resolved = this.evaluate(expr);
-            if (resolved === null || resolved === undefined) {
-                return "";
+    }
+    /**
+       * 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.
+       */
+    expandPaths(value, paths, excludePaths = []) {
+        if (paths.includes("**")) {
+            const result = {};
+            for (const [key, v] of Object.entries(value)) {
+                result[key] = isExcluded(key, excludePaths) ? v : this.expand(v);
             }
-            return String(resolved);
-        });
+            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, excludePaths) {
+    return excludePaths.some((ep) => ep === path || ep === "**" || path.startsWith(ep + ".") || ep.startsWith(path + "."));
+}
+function getNestedValue(obj, parts) {
+    let current = obj;
+    for (const part of parts) {
+        if (current === null || typeof current !== "object")
+            return undefined;
+        current = current[part];
+    }
+    return current;
+}
+function setNestedValue(obj, parts, value) {
+    let current = obj;
+    for (let i = 0; i < parts.length - 1; i++) {
+        const next = current[parts[i]];
+        if (next === null || typeof next !== "object")
+            return;
+        current = next;
     }
+    current[parts[parts.length - 1]] = value;
 }

package/dist/index.d.ts

@@ -1,4 +1,6 @@
+export * from "./compiled-value.js";
 export * from "./capabilities/invokable.js";
+export * from "./ref.js";
 export * from "./capabilities/provider.js";
 export * from "./capabilities/runnable.js";
 export * from "./context-provider.js";

package/dist/index.d.ts.map

@@ -1 +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"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,qBAAqB,CAAC;AACpC,cAAc,6BAA6B,CAAC;AAC5C,cAAc,UAAU,CAAC;AACzB,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,4 +1,6 @@
+export * from "./compiled-value.js";
 export * from "./capabilities/invokable.js";
+export * from "./ref.js";
 export * from "./capabilities/provider.js";
 export * from "./capabilities/runnable.js";
 export * from "./context-provider.js";

package/dist/module-context.d.ts

@@ -1,4 +1,4 @@
-import { Invokable } from "./capabilities/invokable.js";
+import { Invocable } from "./capabilities/invokable.js";
 import { EmitEvent, EvaluationContext, InstanceFactory } from "./evaluation-context.js";
 /**
  * Persistent, module-scoped context. Three reserved CEL namespaces:
@@ -14,6 +14,7 @@ import { EmitEvent, EvaluationContext, InstanceFactory } from "./evaluation-cont
  */
 export declare class ModuleContext extends EvaluationContext {
     private targets;
+    private readonly _hostEnv?;
     private _variables;
     private _secrets;
     private _resources;
@@ -21,7 +22,7 @@ export declare class ModuleContext extends EvaluationContext {
     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);
+    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, _hostEnv?: Record<string, string | undefined> | undefined);
     get variables(): Record<string, unknown>;
     get secrets(): Record<string, unknown>;
     get resources(): Record<string, unknown>;
@@ -29,13 +30,14 @@ export declare class ModuleContext extends EvaluationContext {
     setTargets(vars: string[]): void;
     setSecrets(secrets: Record<string, unknown>): void;
     setResource(name: string, props: Record<string, unknown>): void;
+    protected onResourceSnapshotted(name: string, snap: 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;
+    getInvocable<TInput = Record<string, any>, TOutput = any>(name: string): 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
@@ -44,7 +46,7 @@ export declare class ModuleContext extends EvaluationContext {
      */
     resolveKind(kind: string): string;
     private _rebuildContext;
-    invoke(kind: string, name: string, ...args: any[]): Promise<any>;
+    invoke<TInputs>(kind: string, name: string, inputs: TInputs): Promise<any>;
     run(name: string): Promise<void>;
     runTargets(): Promise<void>;
 }

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

@@ -1 +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"}
+{"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;AAgCxF;;;;;;;;;;;GAWG;AACH,qBAAa,aAAc,SAAQ,iBAAiB;IAgBhD,OAAO,CAAC,OAAO;IAGf,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAC;IAlB5B,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,EACE,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,YAAA;IAShE,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;cAK5C,qBAAqB,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI;IAI3F;;;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,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,EAAE,OAAO,GAAG,GAAG,EACtD,IAAI,EAAE,MAAM,GACX,SAAS,CAAC,MAAM,EAAE,OAAO,CAAC;IAc7B;;;;;OAKG;IACH,WAAW,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM;IAwBjC,OAAO,CAAC,eAAe;IAUR,MAAM,CAAC,OAAO,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,GAAG,OAAO,CAAC,GAAG,CAAC;IAUnF,GAAG,CAAC,IAAI,EAAE,MAAM;IAchB,UAAU;CAKjB"}

package/dist/module-context.js

@@ -1,4 +1,25 @@
 import { EvaluationContext } 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) {
+    return new Proxy(env, {
+        get(target, key) {
+            if (typeof key !== "string")
+                return target[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) {
     const values = new Set();
     for (const value of Object.values(secrets)) {
@@ -22,6 +43,7 @@ function collectSecretValues(secrets) {
  */
 export class ModuleContext extends EvaluationContext {
     targets;
+    _hostEnv;
     _variables;
     _secrets;
     _resources;
@@ -29,9 +51,10 @@ export class ModuleContext extends EvaluationContext {
     importAliases = new Map();
     /** Maps import alias → allowed kind names. Absent entry = unrestricted (e.g. Kernel). */
     importedKinds = new Map();
-    constructor(source, variables = {}, secrets = {}, resources = {}, targets = [], createInstance = async () => null, emit) {
+    constructor(source, variables = {}, secrets = {}, resources = {}, targets = [], createInstance = async () => null, emit, _hostEnv) {
         super(source, {}, createInstance, new Set(), emit);
         this.targets = targets;
+        this._hostEnv = _hostEnv;
         this._variables = variables;
         this._secrets = secrets;
         this._resources = resources;
@@ -61,6 +84,9 @@ export class ModuleContext extends EvaluationContext {
         this._resources = { ...this._resources, [name]: props };
         this._rebuildContext();
     }
+    onResourceSnapshotted(name, snap) {
+        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).
@@ -78,7 +104,7 @@ export class ModuleContext extends EvaluationContext {
         }
         return entry?.instance;
     }
-    getInvokable(name) {
+    getInvocable(name) {
         const instance = this.getInstance(name);
         if (instance &&
             typeof instance === "object" &&
@@ -118,11 +144,12 @@ export class ModuleContext extends EvaluationContext {
             variables: this._variables,
             secrets: this._secrets,
             resources: this._resources,
+            ...(this._hostEnv ? { env: lenientEnv(this._hostEnv) } : {}),
         };
         this._secretValues = collectSecretValues(this._secrets);
     }
-    async invoke(kind, name, ...args) {
-        const result = await super.invoke(kind, name, ...args);
+    async invoke(kind, name, inputs) {
+        const result = await super.invoke(kind, name, inputs);
         const entry = this.resourceInstances.get(name);
         if (entry && typeof entry.instance.snapshot === "function") {
             const snap = await Promise.resolve(entry.instance.snapshot());

package/dist/ref.d.ts

@@ -0,0 +1,47 @@
+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 declare const Ref: <T = ResourceInstance>(ref: string) => 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 declare const Scope: (visibilityPath: string | string[]) => ScopeRef;
+//# sourceMappingURL=ref.d.ts.map

package/dist/ref.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ref.d.ts","sourceRoot":"","sources":["../src/ref.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAC;AAE/D;;mGAEmG;AACnG,MAAM,WAAW,OAAO,CAAC,CAAC,GAAG,gBAAgB;IAC3C,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC;CACrB;AAED;6DAC6D;AAC7D,MAAM,WAAW,QAAQ;IACvB,QAAQ,CAAC,OAAO,EAAE,IAAI,CAAC;CACxB;AAED,6EAA6E;AAC7E,MAAM,WAAW,YAAY;IAC3B;;;uEAGmE;IACnE,WAAW,CAAC,IAAI,EAAE,MAAM,GAAG,gBAAgB,CAAC;CAC7C;AAED;oFACoF;AACpF,MAAM,WAAW,WAAW;IAC1B,GAAG,CAAC,CAAC,EAAE,EAAE,EAAE,CAAC,KAAK,EAAE,YAAY,KAAK,OAAO,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,CAAC;CAC7D;AAED;;;;qCAIqC;AACrC,MAAM,MAAM,QAAQ,CAAC,CAAC,IAAI;KACvB,CAAC,IAAI,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,SAAS,OAAO,CAAC,MAAM,CAAC,CAAC,GACzC,CAAC,GACD,CAAC,CAAC,CAAC,CAAC,SAAS,OAAO,CAAC,MAAM,CAAC,CAAC,EAAE,GAC7B,CAAC,EAAE,GACH,WAAW,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,SAAS,QAAQ,GAChC,WAAW,GAAG,OAAO,CAAC,CAAC,CAAC,CAAC,CAAC,EAAE,QAAQ,CAAC,GACrC,CAAC,CAAC,CAAC,CAAC;CACb,CAAC;AAEF;;;6FAG6F;AAC7F,eAAO,MAAM,GAAG,GAAI,CAAC,GAAG,gBAAgB,EAAE,KAAK,MAAM,KAAG,OAAO,CAAC,CAAC,CACf,CAAC;AAEnD;;;;wEAIwE;AACxE,eAAO,MAAM,KAAK,GAAI,gBAAgB,MAAM,GAAG,MAAM,EAAE,KAAG,QACG,CAAC"}