@telorun/sdk 0.2.7 → 0.3.0

package/README.md

@@ -16,6 +16,60 @@ Early prototype. APIs and contracts are still evolving. The API surface - includ
 
 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.
 
+## Errors
+
+Telo distinguishes two kinds of failure from an `Invocable` / `Runnable`:
+
+- **Operational failures** — plain `Error` or `RuntimeError` throws. Propagate to the kernel's infrastructure layer (HTTP → Fastify 5xx, sequence → bubbles up). These represent bugs or environment failure.
+- **Domain failures** — `InvokeError` throws. Part of the invocable's public contract. Route handlers match on `error.code` via `catches:` entries; sequences handle them in `try`/`catch`.
+
+```ts
+import { InvokeError, isInvokeError } from "@telorun/sdk";
+
+// In a controller:
+throw new InvokeError("UNAUTHORIZED", "Token missing or invalid", {
+  reason: "expired",
+});
+
+// Anywhere a thrown value crosses a boundary:
+if (isInvokeError(err)) {
+  // err.code, err.message, err.data
+}
+```
+
+Use `isInvokeError(err)` for recognition — it's dual-realm-safe (survives pnpm hoist splits, registry-loaded modules with their own SDK copy, and future sandbox isolation). `instanceof InvokeError` is not reliable across package boundaries.
+
+Controllers that throw `InvokeError` **must** declare their codes in their `Telo.Definition`:
+
+```yaml
+kind: Telo.Definition
+metadata: { name: VerifyToken }
+capability: Telo.Invocable
+throws:
+  codes:
+    UNAUTHORIZED: { description: Missing or invalid token. }
+    EXPIRED:
+      description: Token is past its expires_at.
+      data:
+        type: object
+        properties:
+          expiredAt: { type: string, format: date-time }
+        required: [expiredAt]
+```
+
+Undeclared codes emit an `${kind}.${name}.InvokeRejected.Undeclared` observability event — the analyzer catches these statically.
+
+Composers that propagate rather than originate codes can declare:
+
+```yaml
+throws:
+  inherit: true   # union of everything I call (requires x-telo-step-context)
+  # or
+  passthrough: true   # union is whatever my inputs.code resolves to (Run.Throw-style)
+```
+
+`inherit` is driven by the analyzer's dataflow pass over `x-telo-step-context` arrays; future composers opt in by declaring both the annotation and `inherit: true`. See [modules/run/docs/structured-errors.md](../../modules/run/docs/structured-errors.md) for the end-to-end flow.
+
 ## Related Docs
 
 - Kernel overview: [kernel/README.md](../../kernel/README.md)

package/dist/compiled-value.d.ts

@@ -3,6 +3,8 @@
  *  The SDK has no knowledge of CEL — it only calls .call(). */
 export interface CompiledValue {
     readonly __compiled: true;
+    /** Original expression source text (e.g. "env.PORT"), if available. */
+    readonly source?: string;
     call(ctx: Record<string, unknown>): unknown;
 }
 export declare function isCompiledValue(v: unknown): v is CompiledValue;

package/dist/compiled-value.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"compiled-value.d.ts","sourceRoot":"","sources":["../src/compiled-value.ts"],"names":[],"mappings":"AAAA;;+DAE+D;AAC/D,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,UAAU,EAAE,IAAI,CAAC;IAC1B,IAAI,CAAC,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,OAAO,CAAC;CAC7C;AAED,wBAAgB,eAAe,CAAC,CAAC,EAAE,OAAO,GAAG,CAAC,IAAI,aAAa,CAE9D"}
+{"version":3,"file":"compiled-value.d.ts","sourceRoot":"","sources":["../src/compiled-value.ts"],"names":[],"mappings":"AAAA;;+DAE+D;AAC/D,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,UAAU,EAAE,IAAI,CAAC;IAC1B,uEAAuE;IACvE,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IACzB,IAAI,CAAC,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,OAAO,CAAC;CAC7C;AAED,wBAAgB,eAAe,CAAC,CAAC,EAAE,OAAO,GAAG,CAAC,IAAI,aAAa,CAE9D"}

package/dist/evaluation-context.d.ts

@@ -1,7 +1,7 @@
-import type { ModuleContext } from "./module-context.js";
 import type { ScopeHandle } from "./ref.js";
-import { ResourceInstance } from "./resource-instance.js";
-import { ResourceManifest } from "./resource-manifest.js";
+import type { ResourceInstance } from "./resource-instance.js";
+import type { ResourceManifest } from "./resource-manifest.js";
+import type { ResourceDefinition } from "./types.js";
 export type EmitEvent = (event: string, payload?: any) => void | Promise<void>;
 /** Four-stage resource lifecycle defined in resource-lifecycle.md */
 export type LifecycleState = "Pending" | "Validated" | "Initialized" | "Draining" | "Teardown";
@@ -20,7 +20,7 @@ export type CreatedResource = {
  * Returns a CreatedResource (instance + ctx) so initializeResources can run
  * init() separately in a second phase.
  */
-export type InstanceFactory = (moduleContext: ModuleContext, resource: ResourceManifest) => Promise<CreatedResource | null>;
+export type InstanceFactory = (context: EvaluationContext, resource: ResourceManifest) => Promise<CreatedResource | null>;
 /**
  * Hook called after controller.create() and before controller.init() for each resource.
  * Implementations (e.g. the kernel) use this to inject live instances into reference
@@ -34,129 +34,43 @@ export type PreInitHook = (resource: ResourceManifest, getInstance: (name: strin
 /** Canonical key for a resource instance: "<module>.<kind>.<name>" */
 export declare function resourceKey(r: ResourceManifest): string;
 /**
- * Base class for all evaluation contexts. Owns template
- * expansion, secrets redaction, and the generic resource lifecycle tree.
+ * Public contract for the base evaluation context.
  *
- * Every EvaluationContext node can:
- *   - Hold its own resource instances (resourceInstances)
- *   - Queue resources for initialization (pendingResources)
- *   - Spawn child contexts (spawnChild) forming a lifecycle tree
- *   - Run a multi-pass initialization loop (initializeResources)
- *   - Cascade teardown depth-first through the tree (teardownResources)
+ * Owns template expansion, secrets redaction, and the generic resource lifecycle tree.
+ * The class implementation lives in `@telorun/kernel`.
  */
-export declare class EvaluationContext {
-    readonly source: string;
+export interface EvaluationContext {
     readonly id: string;
-    protected _context: Record<string, unknown>;
-    protected _secretValues: Set<string>;
-    protected _createInstance: InstanceFactory;
+    readonly source: string;
     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 that have been created but not yet initialized (between phases). */
-    protected readonly createdInstances: Map<string, {
-        resource: ResourceManifest;
-        instance: ResourceInstance;
-        ctx: any;
-    }>;
-    /** Resources queued for initialization on this context node. */
-    private pendingResources;
-    /**
-     * Optional hook called between create() and init() for each resource.
-     * Set by the kernel to inject live instances into reference fields.
-     */
     preInitHook?: PreInitHook;
-    constructor(source: string, context: Record<string, unknown>, createInstance: InstanceFactory | undefined, secretValues: Set<string>, emit: EmitEvent);
-    get createInstance(): InstanceFactory;
-    /** Called after init() when a resource snapshot is available. Overridden by ModuleContext. */
-    protected onResourceSnapshotted(_name: string, _snap: Record<string, unknown>): void;
-    get context(): Record<string, unknown>;
-    get secretValues(): Set<string>;
-    /**
-     * 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.
-     */
+    /** Looks up a registered resource definition by fully-qualified kind.
+     *  Set by the kernel; used for declared-throw-union checks. */
+    getDefinition?: (kind: string) => ResourceDefinition | undefined;
+    readonly createInstance: InstanceFactory;
+    readonly context: Record<string, unknown>;
+    readonly secretValues: Set<string>;
     setInitOrder(names: string[]): void;
-    /**
-     * Queue a resource manifest for initialization on this context.
-     */
     hasManifest(name: string): boolean;
     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;
-    /**
-     * Interleaved create/init loop.
-     *
-     * Each pass has two sub-phases run back-to-back:
-     *   1. Create sub-phase: call controller.create() for each pending resource that
-     *      hasn't been created yet. Successful results go into createdInstances.
-     *   2. Init sub-phase: call instance.init(ctx) for each created-but-not-inited
-     *      resource. Successful results go into resourceInstances.
-     *
-     * Interleaving is necessary because some resources' create() depends on effects
-     * produced by other resources' init() (e.g. Kernel.Import.init() runs
-     * child.initializeResources() which registers controllers needed by sibling
-     * resources' create()). Running both sub-phases each pass lets those effects
-     * propagate before the next create attempt.
-     *
-     * Each resource is created at most once and inited at most once.
-     * ERR_VISIBILITY_DENIED is fatal and re-thrown immediately.
-     * All other errors are tracked and retried until no progress is made.
-     */
     initializeResources(): Promise<void>;
     withManifests<T>(manifests: any[], fn: () => T): T;
-    /**
-     * Returns a ScopeHandle that initializes `manifests` in a fresh child context each time
-     * `run()` is called, executes the callback with a ScopeContext, and tears down when done.
-     *
-     * The child inherits the parent's preInitHook (if any), extended so that `getInstance`
-     * also checks the parent's already-initialized singleton instances. This lets scoped
-     * resources hold x-telo-ref slots pointing to outer resources — those deps are already
-     * live when the scope opens.
-     */
     createScopeHandle(manifests: ResourceManifest[]): ScopeHandle;
-    /**
-     * Cascade teardown depth-first through the tree:
-     *   1. Tear down child contexts in reverse registration order.
-     *   2. Tear down own resource instances in reverse registration order,
-     *      emitting a Teardown event for each via the injected emit callback.
-     */
     teardownResources(): Promise<void>;
     transientChild(context: Record<string, any>): EvaluationContext;
-    /**
-     * 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<TInputs>(kind: string, name: string, inputs: TInputs): Promise<any>;
+    invokeResolved<TInputs>(kind: string, name: string, instance: ResourceInstance, inputs: TInputs): Promise<any>;
     run(name: string): Promise<void>;
-    /**
-     * Expand a value that may contain precompiled ${{ }} templates.
-     * Works recursively over CompiledValues, arrays, and objects.
-     */
     expand(value: unknown): unknown;
-    /**
-     * Expand a value using this context merged with additional properties.
-     * Equivalent to merge(extraContext).expand(value) without allocating a context object.
-     */
     expandWith(value: unknown, extraContext: Record<string, unknown>): unknown;
-    /**
-       * 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: Record<string, unknown>, paths: string[], excludePaths?: string[]): Record<string, unknown>;
 }
 //# sourceMappingURL=evaluation-context.d.ts.map

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

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

package/dist/evaluation-context.js

@@ -1,394 +1,4 @@
-import { isCompiledValue } from "./compiled-value.js";
-import { RuntimeError } from "./types.js";
 /** Canonical key for a resource instance: "<module>.<kind>.<name>" */
 export function resourceKey(r) {
     return `${r.kind}.${r.metadata.name}`;
 }
-/**
- * Base class for all evaluation contexts. Owns 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 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;
-        this._createInstance = createInstance;
-        this._secretValues = secretValues ?? new Set();
-        this.emit = emit;
-    }
-    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);
-    }
-    /**
-     * 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);
-        // Propagate injection hook so all child contexts (module imports, scopes) participate
-        // in Phase 5 injection. createScopeHandle overrides this with an extended version.
-        if (this.preInitHook && !child.preInitHook) {
-            child.preInitHook = this.preInitHook;
-        }
-        return child;
-    }
-    /**
-     * Interleaved create/init loop.
-     *
-     * Each pass has two sub-phases run back-to-back:
-     *   1. Create sub-phase: call controller.create() for each pending resource that
-     *      hasn't been created yet. Successful results go into createdInstances.
-     *   2. Init sub-phase: call instance.init(ctx) for each created-but-not-inited
-     *      resource. Successful results go into resourceInstances.
-     *
-     * Interleaving is necessary because some resources' create() depends on effects
-     * produced by other resources' init() (e.g. Kernel.Import.init() runs
-     * child.initializeResources() which registers controllers needed by sibling
-     * resources' create()). Running both sub-phases each pass lets those effects
-     * propagate before the next create attempt.
-     *
-     * Each resource is created at most once and inited at most once.
-     * ERR_VISIBILITY_DENIED is fatal and re-thrown immediately.
-     * All other errors are tracked and retried until no progress is made.
-     */
-    async initializeResources() {
-        const MAX_PASSES = 10;
-        const errors = new Map();
-        let pass = 1;
-        do {
-            let progress = false;
-            // Create sub-phase
-            for (const resource of [...this.pendingResources]) {
-                const name = resource.metadata.name;
-                if (this.createdInstances.has(name))
-                    continue;
-                try {
-                    // const expanded = this.expand(resource) as ResourceManifest;
-                    // FIXME: Cannot expand it for all resources, needs to be selective
-                    const created = await this._createInstance(this, resource);
-                    if (created) {
-                        this.createdInstances.set(name, {
-                            resource,
-                            instance: created.instance,
-                            ctx: created.ctx,
-                        });
-                        const idx = this.pendingResources.findIndex((m) => m.metadata.name === name);
-                        if (idx >= 0)
-                            this.pendingResources.splice(idx, 1);
-                        errors.delete(name);
-                        progress = true;
-                    }
-                }
-                catch (error) {
-                    if (error instanceof RuntimeError && error.code === "ERR_VISIBILITY_DENIED")
-                        throw error;
-                    errors.set(name, error instanceof Error ? error.message : String(error));
-                }
-            }
-            // Init sub-phase
-            for (const [name, { resource, instance, ctx }] of [...this.createdInstances]) {
-                if (this.resourceInstances.has(name))
-                    continue;
-                try {
-                    if (this.preInitHook) {
-                        this.preInitHook(resource, (n) => this.resourceInstances.get(n)?.instance);
-                    }
-                    if (instance.init)
-                        await instance.init(ctx);
-                    if (instance.snapshot) {
-                        const snap = await Promise.resolve(instance.snapshot()).catch(() => ({}));
-                        this.onResourceSnapshotted(name, snap ?? {});
-                    }
-                    this.resourceInstances.set(name, { resource, instance });
-                    this.createdInstances.delete(name);
-                    errors.delete(name);
-                    progress = true;
-                }
-                catch (error) {
-                    if (error instanceof RuntimeError && error.code === "ERR_VISIBILITY_DENIED")
-                        throw error;
-                    errors.set(name, error instanceof Error ? error.message : String(error));
-                }
-            }
-            pass++;
-            if (!progress)
-                break;
-        } while (pass <= MAX_PASSES);
-        if (this.pendingResources.length > 0 || this.createdInstances.size > 0) {
-            const diagnostics = [
-                ...this.pendingResources.map((r) => ({
-                    resource: r.metadata.name,
-                    message: errors.get(r.metadata.name) ?? "Unknown error",
-                })),
-                ...[...this.createdInstances.keys()].map((name) => ({
-                    resource: name,
-                    message: errors.get(name) ?? "Unknown error",
-                })),
-            ];
-            throw new RuntimeError("ERR_RESOURCE_INITIALIZATION_FAILED", "Unable to process resources", diagnostics);
-        }
-        this.state = "Initialized";
-    }
-    withManifests(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();
-        }
-    }
-    /**
-     * 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,
-     *      emitting a Teardown event for each via the injected emit callback.
-     */
-    async teardownResources() {
-        this.state = "Draining";
-        for (const child of [...this.children].reverse()) {
-            await child.teardownResources();
-        }
-        const entries = [...this.resourceInstances.entries()].reverse();
-        for (const [key, { resource, instance }] of entries) {
-            if (instance.teardown)
-                await instance.teardown();
-            await this.emit(`${resource.kind}.${resource.metadata.name}.Teardown`, {
-                resource: { kind: resource.kind, name: resource.metadata.name },
-            });
-            this.resourceInstances.delete(key);
-        }
-        this.state = "Teardown";
-    }
-    transientChild(context) {
-        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, 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(inputs);
-            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(", ")}`);
-    }
-    /**
-     * Expand a value that may contain precompiled ${{ }} templates.
-     * Works recursively over CompiledValues, arrays, and objects.
-     */
-    expand(value) {
-        if (isCompiledValue(value)) {
-            return value.call(this._context);
-        }
-        if (Array.isArray(value)) {
-            return value.map((entry) => this.expand(entry));
-        }
-        if (value !== null && typeof value === "object") {
-            const resolved = {};
-            for (const [key, entry] of Object.entries(value)) {
-                resolved[key] = this.expand(entry);
-            }
-            return resolved;
-        }
-        return value;
-    }
-    /**
-     * Expand a value using this context merged with additional properties.
-     * Equivalent to merge(extraContext).expand(value) without allocating a context object.
-     */
-    expandWith(value, extraContext) {
-        const saved = this._context;
-        this._context = Object.assign(Object.create(null), saved, extraContext);
-        try {
-            return this.expand(value);
-        }
-        finally {
-            this._context = saved;
-        }
-    }
-    /**
-       * Expand specific dot-paths within an object. '**' expands the entire object.
-       * Paths listed in excludePaths are left untouched (runtime takes precedence).
-       * Always throws if an expression cannot be resolved.
-       */
-    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 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

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

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"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"}
+{"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,mBAAmB,CAAC;AAClC,cAAc,oBAAoB,CAAC;AACnC,cAAc,oBAAoB,CAAC;AACnC,cAAc,uBAAuB,CAAC;AACtC,cAAc,YAAY,CAAC"}