@cadenza.io/core 3.27.0 → 3.28.0

package/dist/index.mjs

@@ -1241,6 +1241,7 @@ var SignalBroker = class _SignalBroker {
     this.signalObservers = /* @__PURE__ */ new Map();
     this.emittedSignalsRegistry = /* @__PURE__ */ new Set();
     this.signalMetadataRegistry = /* @__PURE__ */ new Map();
+    this.passiveSignalListeners = /* @__PURE__ */ new Map();
     // ── Flush Strategy Management ───────────────────────────────────────
     this.flushStrategies = /* @__PURE__ */ new Map();
     this.strategyData = /* @__PURE__ */ new Map();
@@ -1321,6 +1322,20 @@ var SignalBroker = class _SignalBroker {
     console.log(
       `  \u2022 emittedSignalsRegistry size: ${this.emittedSignalsRegistry.size}`
     );
+    const exactSignalEntries = Array.from(this.signalObservers.entries()).filter(([signal]) => signal.includes(":")).sort((left, right) => {
+      const taskDelta = right[1].tasks.size - left[1].tasks.size;
+      if (taskDelta !== 0) {
+        return taskDelta;
+      }
+      return left[0].localeCompare(right[0]);
+    });
+    console.log(`  \u2022 exact signal observer entries: ${exactSignalEntries.length}`);
+    for (const [signal, observer] of exactSignalEntries.slice(0, 8)) {
+      const sampleTaskNames = Array.from(observer.tasks).slice(0, 3).map((task) => task.name);
+      console.log(
+        `    - ${signal} (${observer.tasks.size} tasks) sample=${sampleTaskNames.join(", ")}`
+      );
+    }
     let totalSquashContexts = 0;
     let totalSquashGroups = 0;
     for (const groups of this.strategyData.values()) {
@@ -1734,7 +1749,7 @@ var SignalBroker = class _SignalBroker {
       this.schedule(signal, context, options);
       return;
     }
-    this.addSignal(signal);
+    this.validateSignalName(signal);
     this.execute(signal, context);
   }
   /**
@@ -1813,6 +1828,7 @@ var SignalBroker = class _SignalBroker {
       ...context.__metadata,
       __executionTraceId: executionTraceId
     };
+    this.notifyPassiveSignalListeners(signal, context);
     if (this.debug && (!isMetric && !isSubMeta || this.verbose)) {
       console.log(
         `EMITTING ${signal} to listeners ${this.signalObservers.get(signal)?.tasks.size ?? 0} with context ${this.verbose ? JSON.stringify(context) : JSON.stringify(context).slice(0, 100)}`
@@ -1910,11 +1926,37 @@ var SignalBroker = class _SignalBroker {
     this.addSignal(signal, metadata);
     this.signalObservers.get(signal).tasks.add(routineOrTask);
   }
+  addPassiveSignalListener(listener) {
+    const listenerId = uuid();
+    this.passiveSignalListeners.set(listenerId, listener);
+    return () => {
+      this.passiveSignalListeners.delete(listenerId);
+    };
+  }
+  notifyPassiveSignalListeners(signal, context) {
+    if (this.passiveSignalListeners.size === 0) {
+      return;
+    }
+    const metadata = this.getSignalMetadata(signal) ?? null;
+    for (const listener of this.passiveSignalListeners.values()) {
+      try {
+        listener(signal, context, metadata);
+      } catch (error) {
+        if (this.debug) {
+          console.error("Passive signal listener failed", error);
+        }
+      }
+    }
+  }
   registerEmittedSignal(signal, metadata) {
+    const signalKey = this.resolveSignalMetadataKey(signal);
+    if (!signalKey) {
+      return;
+    }
     if (metadata) {
-      this.setSignalMetadata(signal, metadata);
+      this.setSignalMetadata(signalKey, metadata);
     }
-    this.emittedSignalsRegistry.add(signal);
+    this.emittedSignalsRegistry.add(signalKey);
   }
   /**
    * Unsubscribes a routine/task from a signal.
@@ -2974,16 +3016,17 @@ var GraphNode = class _GraphNode extends SignalEmitter {
    * @return {void} Does not return a value.
    */
   finalize() {
+    const context = this.context?.getFullContext?.() ?? {};
     if (this.nextNodes.length === 0) {
       this.completeSubgraph();
     }
     if (this.errored || this.failed) {
       this.task.mapOnFailSignals(
-        (signal) => this.emitWithMetadata(signal, this.context.getFullContext())
+        (signal) => this.emitWithMetadata(signal, { ...context })
       );
     } else if (this.result !== void 0 && this.result !== false) {
       this.task.mapSignals(
-        (signal) => this.emitWithMetadata(signal, this.context.getFullContext())
+        (signal) => this.emitWithMetadata(signal, { ...context })
       );
     }
     this.end();
@@ -2997,8 +3040,9 @@ var GraphNode = class _GraphNode extends SignalEmitter {
    */
   onError(error, errorData = {}) {
     const normalizedError = normalizeGraphErrorMessage(error);
+    const context = this.context?.getFullContext?.() ?? {};
     this.result = {
-      ...this.context.getFullContext(),
+      ...context,
       __error: `Node error: ${normalizedError}`,
       __retries: this.retries,
       error: `Node error: ${normalizedError}`,
@@ -3882,7 +3926,13 @@ var Actor = class {
   task(handler, bindingOptions = {}) {
     const mode = bindingOptions.mode ?? "read";
     const taskBindingId = `${this.spec.name}:${++this.nextTaskBindingIndex}`;
-    const wrapped = (context, emit, inquire, progressCallback) => {
+    const wrapped = (context, emit, inquire, tools, progressCallback) => {
+      const resolvedTools = tools && typeof tools === "object" && !Array.isArray(tools) && "helpers" in tools && "globals" in tools ? tools : {
+        helpers: {},
+        globals: {}
+      };
+      const resolvedProgressCallback = typeof progressCallback === "function" ? progressCallback : typeof tools === "function" ? tools : () => {
+      };
       const normalizedInput = this.normalizeInputContext(context);
       const invocationOptions = this.resolveInvocationOptions(
         context,
@@ -4002,7 +4052,8 @@ var Actor = class {
           patchRuntimeState,
           reduceRuntimeState,
           emit: (signal, payload = {}) => emit(signal, payload),
-          inquire: (inquiryName, inquiryContext = {}, options = {}) => inquire(inquiryName, inquiryContext, options)
+          inquire: (inquiryName, inquiryContext = {}, options = {}) => inquire(inquiryName, inquiryContext, options),
+          tools: resolvedTools
         };
         const handlerResult = await handler(actorContext);
         if (invocationOptions.writeContract === "reducer" && typeof handlerResult === "function") {
@@ -4029,7 +4080,7 @@ var Actor = class {
           stateRecord.lastRuntimeWriteAt = writeTimestamp;
         }
         this.touchSession(actorKey, invocationOptions.touchSession, Date.now());
-        progressCallback(100);
+        resolvedProgressCallback(100);
         if (invocationOptions.writeContract === "reducer" && typeof handlerResult === "function") {
           return cloneForDurableState(stateRecord.durableState);
         }
@@ -4073,6 +4124,13 @@ var Actor = class {
     this.pruneExpiredActorKeys(Date.now());
     return this.ensureStateRecord(key).runtimeState;
   }
+  /**
+   * Lists all currently materialized actor keys.
+   */
+  listActorKeys() {
+    this.pruneExpiredActorKeys(Date.now());
+    return Array.from(this.stateByKey.keys()).sort();
+  }
   /**
    * Alias of `getDurableVersion`.
    */
@@ -4482,6 +4540,176 @@ var Actor = class {
   }
 };
 
+// src/tools/definitions.ts
+function validateAlias(alias) {
+  const normalized = String(alias ?? "").trim();
+  if (!normalized) {
+    throw new Error("Tool dependency alias must be a non-empty string");
+  }
+  return normalized;
+}
+function serializeGlobalValue(value) {
+  if (value === void 0 || typeof value === "function") {
+    throw new Error("Global values must be JSON-serializable");
+  }
+  try {
+    return JSON.parse(JSON.stringify(value));
+  } catch (error) {
+    throw new Error(
+      `Global values must be JSON-serializable: ${error instanceof Error ? error.message : String(error)}`
+    );
+  }
+}
+function deepFreeze(value) {
+  if (!value || typeof value !== "object") {
+    return value;
+  }
+  Object.freeze(value);
+  for (const nested of Object.values(value)) {
+    if (nested && typeof nested === "object" && !Object.isFrozen(nested)) {
+      deepFreeze(nested);
+    }
+  }
+  return value;
+}
+var GlobalDefinition = class {
+  constructor(name, value, description = "", isMeta = false) {
+    this.version = 1;
+    this.destroyed = false;
+    this.name = name;
+    this.description = description;
+    this.isMeta = isMeta;
+    this.value = deepFreeze(serializeGlobalValue(value));
+  }
+  destroy() {
+    this.destroyed = true;
+  }
+  export() {
+    return {
+      name: this.name,
+      description: this.description,
+      version: this.version,
+      isMeta: this.isMeta,
+      value: this.value
+    };
+  }
+};
+var HelperDefinition = class {
+  constructor(name, helperFunction, description = "", isMeta = false) {
+    this.version = 1;
+    this.helperAliases = /* @__PURE__ */ new Map();
+    this.globalAliases = /* @__PURE__ */ new Map();
+    this.destroyed = false;
+    this.name = name;
+    this.description = description;
+    this.isMeta = isMeta;
+    this.helperFunction = helperFunction;
+  }
+  usesHelpers(helpers) {
+    attachHelperDependency(
+      this,
+      this.name,
+      this.version,
+      helpers,
+      "meta.helper.helper_associated"
+    );
+    return this;
+  }
+  usesGlobals(globals) {
+    attachGlobalDependency(
+      this,
+      this.name,
+      this.version,
+      globals,
+      "meta.helper.global_associated"
+    );
+    return this;
+  }
+  execute(context, emit, inquire, progressCallback) {
+    return Cadenza.executeHelper(
+      this,
+      context,
+      emit,
+      inquire,
+      progressCallback
+    );
+  }
+  destroy() {
+    this.destroyed = true;
+  }
+  export() {
+    return {
+      name: this.name,
+      description: this.description,
+      version: this.version,
+      isMeta: this.isMeta,
+      functionString: this.helperFunction.toString(),
+      helperAliases: Object.fromEntries(this.helperAliases),
+      globalAliases: Object.fromEntries(this.globalAliases)
+    };
+  }
+};
+function attachHelperDependency(owner, ownerName, ownerVersion, helpers, signalName) {
+  for (const [alias, helper] of Object.entries(helpers)) {
+    const normalizedAlias = validateAlias(alias);
+    if (!helper) {
+      throw new Error(
+        `Helper dependency "${normalizedAlias}" must reference a helper definition`
+      );
+    }
+    if (helper.isMeta !== owner.isMeta) {
+      throw new Error(
+        `${ownerName} cannot use ${helper.isMeta ? "meta" : "business"} helper "${helper.name}" across layer boundaries`
+      );
+    }
+    owner.helperAliases.set(normalizedAlias, helper.name);
+    Cadenza.emit(signalName, {
+      data: {
+        alias: normalizedAlias,
+        ...signalName === "meta.task.helper_associated" ? {
+          taskName: ownerName,
+          taskVersion: ownerVersion
+        } : {
+          helperName: ownerName,
+          helperVersion: ownerVersion
+        },
+        dependencyHelperName: helper.name,
+        dependencyHelperVersion: helper.version
+      }
+    });
+  }
+}
+function attachGlobalDependency(owner, ownerName, ownerVersion, globals, signalName) {
+  for (const [alias, globalDefinition] of Object.entries(globals)) {
+    const normalizedAlias = validateAlias(alias);
+    if (!globalDefinition) {
+      throw new Error(
+        `Global dependency "${normalizedAlias}" must reference a global definition`
+      );
+    }
+    if (globalDefinition.isMeta !== owner.isMeta) {
+      throw new Error(
+        `${ownerName} cannot use ${globalDefinition.isMeta ? "meta" : "business"} global "${globalDefinition.name}" across layer boundaries`
+      );
+    }
+    owner.globalAliases.set(normalizedAlias, globalDefinition.name);
+    Cadenza.emit(signalName, {
+      data: {
+        alias: normalizedAlias,
+        ...signalName === "meta.task.global_associated" ? {
+          taskName: ownerName,
+          taskVersion: ownerVersion
+        } : {
+          helperName: ownerName,
+          helperVersion: ownerVersion
+        },
+        globalName: globalDefinition.name,
+        globalVersion: globalDefinition.version
+      }
+    });
+  }
+}
+
 // src/graph/definition/Task.ts
 function normalizeSignalDefinition(input) {
   if (typeof input === "string") {
@@ -4558,6 +4786,8 @@ var Task = class _Task extends SignalEmitter {
     this.observedSignals = /* @__PURE__ */ new Set();
     this.handlesIntents = /* @__PURE__ */ new Set();
     this.inquiresIntents = /* @__PURE__ */ new Set();
+    this.helperAliases = /* @__PURE__ */ new Map();
+    this.globalAliases = /* @__PURE__ */ new Map();
     this.name = name;
     this.taskFunction = task;
     this.description = description;
@@ -4593,6 +4823,8 @@ var Task = class _Task extends SignalEmitter {
       "meta.task.relationship_added",
       "meta.task.relationship_removed",
       "meta.task.intent_associated",
+      "meta.task.helper_associated",
+      "meta.task.global_associated",
       "meta.task.layer_index_changed",
       "meta.node.scheduled",
       "meta.node.mapped",
@@ -5106,10 +5338,18 @@ var Task = class _Task extends SignalEmitter {
    * @return {TaskResult} The result of the executed task.
    */
   execute(context, emit, inquire, progressCallback, nodeData) {
+    const executionContext = this.isMeta ? context.getClonedFullContext() : context.getClonedContext();
     return this.taskFunction(
-      this.isMeta ? context.getClonedFullContext() : context.getClonedContext(),
+      executionContext,
       emit,
       inquire,
+      Cadenza.resolveToolsForOwner(
+        this,
+        executionContext,
+        emit,
+        inquire,
+        progressCallback
+      ),
       progressCallback
     );
   }
@@ -5123,6 +5363,7 @@ var Task = class _Task extends SignalEmitter {
    * @throws {Error} Throws an error if adding a predecessor creates a cycle in the task structure.
    */
   doAfter(...tasks) {
+    Cadenza.assertGraphMutationAllowed("Task#doAfter");
     for (const pred of tasks) {
       if (!pred) continue;
       if (this.predecessorTasks.has(pred)) continue;
@@ -5154,6 +5395,7 @@ var Task = class _Task extends SignalEmitter {
    * @throws {Error} Throws an error if adding a task causes a cyclic dependency.
    */
   then(...tasks) {
+    Cadenza.assertGraphMutationAllowed("Task#then");
     for (const next of tasks) {
       if (!next) continue;
       if (this.nextTasks.has(next)) continue;
@@ -5317,6 +5559,7 @@ var Task = class _Task extends SignalEmitter {
    * @return {this} The current instance after adding the specified signals.
    */
   doOn(...signals) {
+    Cadenza.assertGraphMutationAllowed("Task#doOn");
     signals.forEach((input) => {
       const { name: signal, metadata } = normalizeSignalDefinition(input);
       if (this.observedSignals.has(signal)) return;
@@ -5341,6 +5584,7 @@ var Task = class _Task extends SignalEmitter {
    * @return {this} The current instance for method chaining.
    */
   emits(...signals) {
+    Cadenza.assertGraphMutationAllowed("Task#emits");
     signals.forEach((input) => {
       const { name: signal } = normalizeSignalDefinition(input);
       if (this.observedSignals.has(signal))
@@ -5360,6 +5604,7 @@ var Task = class _Task extends SignalEmitter {
    * @return {this} Returns the current instance for chaining.
    */
   emitsOnFail(...signals) {
+    Cadenza.assertGraphMutationAllowed("Task#emitsOnFail");
     signals.forEach((input) => {
       const { name: signal } = normalizeSignalDefinition(input);
       this.signalsToEmitOnFail.add(signal);
@@ -5374,6 +5619,7 @@ var Task = class _Task extends SignalEmitter {
    * @return {void} This method does not return a value.
    */
   attachSignal(...signals) {
+    Cadenza.assertGraphMutationAllowed("Task#attachSignal");
     signals.forEach((input) => {
       const { name: signal, metadata } = normalizeSignalDefinition(input);
       this.emitsSignals.add(signal);
@@ -5470,6 +5716,7 @@ var Task = class _Task extends SignalEmitter {
     return this;
   }
   respondsTo(...inquires) {
+    Cadenza.assertGraphMutationAllowed("Task#respondsTo");
     for (const intentName of inquires) {
       if (this.handlesIntents.has(intentName)) {
         continue;
@@ -5505,6 +5752,26 @@ var Task = class _Task extends SignalEmitter {
     }
     return this;
   }
+  usesHelpers(helpers) {
+    attachHelperDependency(
+      this,
+      this.name,
+      this.version,
+      helpers,
+      "meta.task.helper_associated"
+    );
+    return this;
+  }
+  usesGlobals(globals) {
+    attachGlobalDependency(
+      this,
+      this.name,
+      this.version,
+      globals,
+      "meta.task.global_associated"
+    );
+    return this;
+  }
   attachIntents(...intentNames) {
     for (const intent of intentNames) {
       this.inquiresIntents.add(intent);
@@ -5597,6 +5864,7 @@ var Task = class _Task extends SignalEmitter {
     this.nextTasks.clear();
     this.predecessorTasks.clear();
     this.destroyed = true;
+    Cadenza.forgetTask(this.name);
     if (this.register) {
       Cadenza.registry.tasks.delete(this.name);
       this.emitMetricsWithMetadata("meta.task.destroyed", {
@@ -5638,6 +5906,8 @@ var Task = class _Task extends SignalEmitter {
       __validateInputContext: this.validateInputContext,
       __outputSchema: this.outputContextSchema,
       __validateOutputContext: this.validateOutputContext,
+      __helperAliases: Object.fromEntries(this.helperAliases),
+      __globalAliases: Object.fromEntries(this.globalAliases),
       __nextTasks: Array.from(this.nextTasks).map((t) => t.name),
       __previousTasks: Array.from(this.predecessorTasks).map((t) => t.name)
     };
@@ -5884,6 +6154,13 @@ var DebounceTask = class extends Task {
         this.lastContext.getClonedContext(),
         this.lastEmitFunction,
         this.lastInquireFunction,
+        Cadenza.resolveToolsForOwner(
+          this,
+          this.lastContext.getClonedContext(),
+          this.lastEmitFunction,
+          this.lastInquireFunction,
+          this.lastProgressCallback
+        ),
         this.lastProgressCallback
       );
     } catch (error) {
@@ -6038,6 +6315,19 @@ var EphemeralTask = class extends Task {
       progressCallback,
       nodeData
     );
+    if (result instanceof Promise) {
+      return result.then((resolved) => {
+        if (this.once || this.condition(resolved)) {
+          this.destroy();
+        }
+        return resolved;
+      }).catch((error) => {
+        if (this.once || this.condition(error)) {
+          this.destroy();
+        }
+        throw error;
+      });
+    }
     if (this.once || this.condition(result)) {
       this.destroy();
     }
@@ -7028,6 +7318,386 @@ var InquiryBroker = class _InquiryBroker extends SignalEmitter {
   }
 };
 
+// src/runtime/RuntimeDefinitionRegistry.ts
+function createLinkKey(predecessorTaskName, successorTaskName) {
+  return `${predecessorTaskName}=>${successorTaskName}`;
+}
+function createTaskSignalKey(taskName, signalName) {
+  return `${taskName}=>${signalName}`;
+}
+function createTaskIntentKey(taskName, intentName) {
+  return `${taskName}=>${intentName}`;
+}
+function createRoutineSignalKey(routineName, signalName) {
+  return `${routineName}=>${signalName}`;
+}
+var RuntimeDefinitionRegistry = class {
+  constructor() {
+    this.taskDefinitions = /* @__PURE__ */ new Map();
+    this.helperDefinitions = /* @__PURE__ */ new Map();
+    this.globalDefinitions = /* @__PURE__ */ new Map();
+    this.routineDefinitions = /* @__PURE__ */ new Map();
+    this.intentDefinitions = /* @__PURE__ */ new Map();
+    this.actorDefinitions = /* @__PURE__ */ new Map();
+    this.actorTaskDefinitions = /* @__PURE__ */ new Map();
+    this.taskLinks = /* @__PURE__ */ new Map();
+    this.taskSignalObservations = /* @__PURE__ */ new Map();
+    this.taskSignalEmissions = /* @__PURE__ */ new Map();
+    this.taskIntentBindings = /* @__PURE__ */ new Map();
+    this.taskHelperBindings = /* @__PURE__ */ new Map();
+    this.taskGlobalBindings = /* @__PURE__ */ new Map();
+    this.helperHelperBindings = /* @__PURE__ */ new Map();
+    this.helperGlobalBindings = /* @__PURE__ */ new Map();
+    this.routineSignalObservations = /* @__PURE__ */ new Map();
+  }
+  reset() {
+    this.taskDefinitions.clear();
+    this.helperDefinitions.clear();
+    this.globalDefinitions.clear();
+    this.routineDefinitions.clear();
+    this.intentDefinitions.clear();
+    this.actorDefinitions.clear();
+    this.actorTaskDefinitions.clear();
+    this.taskLinks.clear();
+    this.taskSignalObservations.clear();
+    this.taskSignalEmissions.clear();
+    this.taskIntentBindings.clear();
+    this.taskHelperBindings.clear();
+    this.taskGlobalBindings.clear();
+    this.helperHelperBindings.clear();
+    this.helperGlobalBindings.clear();
+    this.routineSignalObservations.clear();
+  }
+  setTaskDefinition(definition) {
+    this.taskDefinitions.set(definition.name, {
+      ...definition,
+      kind: definition.kind ?? "task",
+      options: definition.options ? { ...definition.options } : void 0
+    });
+  }
+  setHelperDefinition(definition) {
+    this.helperDefinitions.set(definition.name, {
+      ...definition,
+      kind: definition.kind ?? "helper"
+    });
+  }
+  setGlobalDefinition(definition) {
+    this.globalDefinitions.set(definition.name, {
+      ...definition,
+      kind: definition.kind ?? "global",
+      value: definition.value
+    });
+  }
+  setRoutineDefinition(definition) {
+    this.routineDefinitions.set(definition.name, {
+      ...definition,
+      startTaskNames: [...definition.startTaskNames],
+      isMeta: definition.isMeta === true
+    });
+  }
+  setIntentDefinition(definition) {
+    this.intentDefinitions.set(definition.name, {
+      ...definition,
+      input: definition.input ? { ...definition.input } : void 0,
+      output: definition.output ? { ...definition.output } : void 0
+    });
+  }
+  setActorDefinition(definition) {
+    this.actorDefinitions.set(definition.name, {
+      ...definition,
+      state: definition.state ? {
+        ...definition.state,
+        durable: definition.state.durable ? { ...definition.state.durable } : void 0,
+        runtime: definition.state.runtime ? { ...definition.state.runtime } : void 0
+      } : void 0,
+      tasks: definition.tasks ? definition.tasks.map((task) => ({ ...task })) : void 0
+    });
+  }
+  setActorTaskDefinition(definition) {
+    this.actorTaskDefinitions.set(definition.taskName, {
+      ...definition,
+      mode: definition.mode ?? "read",
+      options: definition.options ? { ...definition.options } : void 0
+    });
+  }
+  setTaskLink(definition) {
+    this.taskLinks.set(
+      createLinkKey(
+        definition.predecessorTaskName,
+        definition.successorTaskName
+      ),
+      { ...definition }
+    );
+  }
+  setTaskSignalObservation(definition) {
+    const signalName = typeof definition.signal === "string" ? definition.signal : definition.signal.name;
+    this.taskSignalObservations.set(
+      createTaskSignalKey(definition.taskName, signalName),
+      {
+        taskName: definition.taskName,
+        signal: typeof definition.signal === "string" ? definition.signal : {
+          name: definition.signal.name,
+          deliveryMode: definition.signal.deliveryMode,
+          broadcastFilter: definition.signal.broadcastFilter ?? null
+        }
+      }
+    );
+  }
+  setTaskSignalEmission(definition) {
+    const signalName = typeof definition.signal === "string" ? definition.signal : definition.signal.name;
+    this.taskSignalEmissions.set(
+      `${definition.taskName}=>${definition.mode ?? "after"}=>${signalName}`,
+      {
+        taskName: definition.taskName,
+        mode: definition.mode ?? "after",
+        signal: typeof definition.signal === "string" ? definition.signal : {
+          name: definition.signal.name,
+          deliveryMode: definition.signal.deliveryMode,
+          broadcastFilter: definition.signal.broadcastFilter ?? null
+        }
+      }
+    );
+  }
+  setTaskIntentBinding(definition) {
+    this.taskIntentBindings.set(
+      createTaskIntentKey(definition.taskName, definition.intentName),
+      { ...definition }
+    );
+  }
+  setTaskHelperBinding(definition) {
+    this.taskHelperBindings.set(
+      `${definition.taskName}=>${definition.alias}`,
+      { ...definition }
+    );
+  }
+  setTaskGlobalBinding(definition) {
+    this.taskGlobalBindings.set(
+      `${definition.taskName}=>${definition.alias}`,
+      { ...definition }
+    );
+  }
+  setHelperHelperBinding(definition) {
+    this.helperHelperBindings.set(
+      `${definition.helperName}=>${definition.alias}`,
+      { ...definition }
+    );
+  }
+  setHelperGlobalBinding(definition) {
+    this.helperGlobalBindings.set(
+      `${definition.helperName}=>${definition.alias}`,
+      { ...definition }
+    );
+  }
+  setRoutineSignalObservation(definition) {
+    this.routineSignalObservations.set(
+      createRoutineSignalKey(definition.routineName, definition.signal),
+      { ...definition }
+    );
+  }
+  isRuntimeOwnedTask(taskName) {
+    return this.taskDefinitions.has(taskName) || this.actorTaskDefinitions.has(taskName);
+  }
+  isRuntimeOwnedHelper(helperName) {
+    return this.helperDefinitions.has(helperName);
+  }
+  isRuntimeOwnedGlobal(globalName) {
+    return this.globalDefinitions.has(globalName);
+  }
+  isRuntimeOwnedRoutine(routineName) {
+    return this.routineDefinitions.has(routineName);
+  }
+  isRuntimeOwnedActor(actorName) {
+    return this.actorDefinitions.has(actorName);
+  }
+};
+var runtimeDefinitionRegistry = new RuntimeDefinitionRegistry();
+
+// src/runtime/sandbox.ts
+import vm from "vm";
+import ts from "typescript";
+var FORBIDDEN_SOURCE_PATTERNS = [
+  {
+    pattern: /\bimport\b/,
+    message: "Runtime handler source must not contain import statements"
+  },
+  {
+    pattern: /\bexport\b/,
+    message: "Runtime handler source must not contain export statements"
+  },
+  {
+    pattern: /\brequire\s*\(/,
+    message: "Runtime handler source must not call require()"
+  },
+  {
+    pattern: /\bprocess\b/,
+    message: "Runtime handler source must not access process"
+  },
+  {
+    pattern: /\bFunction\s*\(/,
+    message: "Runtime handler source must not create dynamic functions"
+  },
+  {
+    pattern: /\beval\s*\(/,
+    message: "Runtime handler source must not call eval()"
+  }
+];
+function transpileIfNeeded(source, language, filename) {
+  if (language === "js") {
+    return source;
+  }
+  const result = ts.transpileModule(source, {
+    compilerOptions: {
+      target: ts.ScriptTarget.ES2020,
+      module: ts.ModuleKind.ESNext
+    },
+    fileName: filename,
+    reportDiagnostics: true
+  });
+  const diagnostics = result.diagnostics ?? [];
+  const blockingDiagnostics = diagnostics.filter(
+    (diagnostic) => diagnostic.category === ts.DiagnosticCategory.Error
+  );
+  if (blockingDiagnostics.length > 0) {
+    const message = blockingDiagnostics.map((diagnostic) => ts.flattenDiagnosticMessageText(diagnostic.messageText, "\n")).join("; ");
+    throw new Error(`TypeScript transpile failed: ${message}`);
+  }
+  return result.outputText;
+}
+function createSandbox() {
+  const sandbox = /* @__PURE__ */ Object.create(null);
+  sandbox.global = void 0;
+  sandbox.globalThis = sandbox;
+  sandbox.process = void 0;
+  sandbox.require = void 0;
+  sandbox.module = void 0;
+  sandbox.exports = void 0;
+  sandbox.Buffer = void 0;
+  sandbox.fetch = void 0;
+  sandbox.WebSocket = void 0;
+  sandbox.XMLHttpRequest = void 0;
+  sandbox.setTimeout = void 0;
+  sandbox.setInterval = void 0;
+  sandbox.clearTimeout = void 0;
+  sandbox.clearInterval = void 0;
+  sandbox.queueMicrotask = void 0;
+  return vm.createContext(sandbox);
+}
+function compileFunctionFromSource(source, language, filename, label) {
+  const normalizedSource = String(source ?? "").trim();
+  if (!normalizedSource) {
+    throw new Error(`${label} source must be a non-empty string`);
+  }
+  for (const rule of FORBIDDEN_SOURCE_PATTERNS) {
+    if (rule.pattern.test(normalizedSource)) {
+      throw new Error(rule.message);
+    }
+  }
+  const wrappedSource = `const __runtime_handler = ${normalizedSource};
+__runtime_handler;`;
+  const transpiledSource = transpileIfNeeded(
+    wrappedSource,
+    language,
+    filename
+  ).trim();
+  const sandbox = createSandbox();
+  const script = new vm.Script(transpiledSource, {
+    filename
+  });
+  const compiled = script.runInContext(sandbox, {
+    timeout: 1e3,
+    displayErrors: true,
+    contextCodeGeneration: {
+      strings: false,
+      wasm: false
+    }
+  });
+  if (typeof compiled !== "function") {
+    throw new Error(`${label} source must evaluate to a function`);
+  }
+  return compiled;
+}
+function compileRuntimeTaskFunction(definition) {
+  return compileFunctionFromSource(
+    definition.handlerSource,
+    definition.language,
+    `${definition.name}.runtime-task.${definition.language}`,
+    `Task "${definition.name}"`
+  );
+}
+function compileRuntimeHelperFunction(definition) {
+  return compileFunctionFromSource(
+    definition.handlerSource,
+    definition.language,
+    `${definition.name}.runtime-helper.${definition.language}`,
+    `Helper "${definition.name}"`
+  );
+}
+function compileRuntimeActorTaskHandler(definition) {
+  return compileFunctionFromSource(
+    definition.handlerSource,
+    definition.language,
+    `${definition.actorName}.${definition.taskName}.runtime-actor-task.${definition.language}`,
+    `Actor task "${definition.taskName}"`
+  );
+}
+
+// src/runtime/sanitize.ts
+function isPlainObject2(value) {
+  return typeof value === "object" && value !== null && Object.getPrototypeOf(value) === Object.prototype;
+}
+function sanitizeForJson(value, seen = /* @__PURE__ */ new WeakSet()) {
+  if (value === null || value === void 0 || typeof value === "string" || typeof value === "number" || typeof value === "boolean") {
+    return value ?? null;
+  }
+  if (typeof value === "bigint") {
+    return value.toString();
+  }
+  if (typeof value === "function") {
+    return `[Function ${value.name || "anonymous"}]`;
+  }
+  if (typeof value === "symbol") {
+    return value.toString();
+  }
+  if (value instanceof Date) {
+    return value.toISOString();
+  }
+  if (value instanceof Set) {
+    return Array.from(value).map((entry) => sanitizeForJson(entry, seen));
+  }
+  if (value instanceof Map) {
+    return Array.from(value.entries()).map(([key, entry]) => [
+      sanitizeForJson(key, seen),
+      sanitizeForJson(entry, seen)
+    ]);
+  }
+  if (Array.isArray(value)) {
+    return value.map((entry) => sanitizeForJson(entry, seen));
+  }
+  if (typeof value === "object") {
+    if (seen.has(value)) {
+      return "[Circular]";
+    }
+    seen.add(value);
+    if (!isPlainObject2(value)) {
+      const clone = {};
+      for (const key of Object.keys(value)) {
+        clone[key] = sanitizeForJson(
+          value[key],
+          seen
+        );
+      }
+      clone.__type = value.constructor?.name ?? "Object";
+      return clone;
+    }
+    const result = {};
+    for (const [key, entry] of Object.entries(value)) {
+      result[key] = sanitizeForJson(entry, seen);
+    }
+    return result;
+  }
+  return String(value);
+}
+
 // src/Cadenza.ts
 var Cadenza = class {
   /**
@@ -7110,6 +7780,73 @@ var Cadenza = class {
       throw new Error("Task or Routine name must be a non-empty string.");
     }
   }
+  static assertGraphMutationAllowed(operationName) {
+    if (this.helperExecutionDepth > 0) {
+      throw new Error(
+        `${operationName} is not allowed during helper execution`
+      );
+    }
+  }
+  static executeHelper(helper, context, emit, inquire, progressCallback) {
+    const helperContext = context && typeof context === "object" ? context : {};
+    const tools = this.resolveToolsForOwner(
+      helper,
+      helperContext,
+      emit,
+      inquire,
+      progressCallback
+    );
+    this.helperExecutionDepth += 1;
+    try {
+      return helper.helperFunction(
+        helperContext,
+        emit,
+        inquire,
+        tools,
+        progressCallback
+      );
+    } finally {
+      this.helperExecutionDepth = Math.max(0, this.helperExecutionDepth - 1);
+    }
+  }
+  static resolveToolsForOwner(owner, context, emit, inquire, progressCallback) {
+    const helpers = {};
+    const globals = {};
+    for (const [alias, helperName] of owner.helperAliases.entries()) {
+      const helper = this.getHelper(helperName);
+      if (!helper) {
+        continue;
+      }
+      if (helper.isMeta !== owner.isMeta) {
+        throw new Error(
+          `Tool alias "${alias}" resolves across layer boundaries`
+        );
+      }
+      helpers[alias] = (helperContext = context) => this.executeHelper(
+        helper,
+        helperContext,
+        emit,
+        inquire,
+        progressCallback
+      );
+    }
+    for (const [alias, globalName] of owner.globalAliases.entries()) {
+      const globalDefinition = this.getGlobal(globalName);
+      if (!globalDefinition) {
+        continue;
+      }
+      if (globalDefinition.isMeta !== owner.isMeta) {
+        throw new Error(
+          `Global alias "${alias}" resolves across layer boundaries`
+        );
+      }
+      globals[alias] = globalDefinition.value;
+    }
+    return {
+      helpers,
+      globals
+    };
+  }
   static resolveTaskOptionsForActorTask(func, options = {}) {
     const metadata = getActorTaskRuntimeMetadata(func);
     if (!metadata?.forceMeta) {
@@ -7126,6 +7863,22 @@ var Cadenza = class {
   static registerActor(actor) {
     this.actorCache.set(actor.spec.name, actor);
   }
+  static getHelper(name) {
+    return this.helperCache.get(name);
+  }
+  static getAllHelpers() {
+    return Array.from(this.helperCache.values()).filter(
+      (helper) => !helper.destroyed
+    );
+  }
+  static getGlobal(name) {
+    return this.globalCache.get(name);
+  }
+  static getAllGlobals() {
+    return Array.from(this.globalCache.values()).filter(
+      (globalDefinition) => !globalDefinition.destroyed
+    );
+  }
   /**
    * Executes the specified task or GraphRoutine with the given context using an internal runner.
    *
@@ -7188,6 +7941,9 @@ var Cadenza = class {
   static get(taskName) {
     return this.registry?.tasks.get(taskName) ?? this.taskCache.get(taskName);
   }
+  static forgetTask(taskName) {
+    this.taskCache.delete(taskName);
+  }
   static getActor(actorName) {
     return this.actorCache.get(actorName);
   }
@@ -7195,9 +7951,10 @@ var Cadenza = class {
     return Array.from(this.actorCache.values());
   }
   static getRoutine(routineName) {
-    return this.registry?.routines.get(routineName);
+    return this.registry?.routines.get(routineName) ?? this.routineCache.get(routineName);
   }
   static defineIntent(intent) {
+    this.assertGraphMutationAllowed("Cadenza.defineIntent");
     this.inquiryBroker?.addIntent(intent);
     return intent;
   }
@@ -7351,6 +8108,7 @@ var Cadenza = class {
    * participate in the graph like any other task.
    */
   static createActor(spec, options = {}) {
+    this.assertGraphMutationAllowed("Cadenza.createActor");
     this.bootstrap();
     const actor = new Actor(spec, options);
     this.registerActor(actor);
@@ -7466,6 +8224,7 @@ var Cadenza = class {
    * ```
    */
   static createTask(name, func, description, options = {}) {
+    this.assertGraphMutationAllowed("Cadenza.createTask");
     this.bootstrap();
     this.validateName(name);
     const actorResolvedOptions = this.resolveTaskOptionsForActorTask(
@@ -7515,14 +8274,172 @@ var Cadenza = class {
     this.taskCache.set(name, createdTask);
     return createdTask;
   }
-  /**
-   * Creates a meta task with the specified name, functionality, description, and options.
-   * This is used for creating tasks that lives on the meta layer.
-   * The meta layer is a special layer that is executed separately from the business logic layer and is used for extending Cadenzas core functionality.
-   * See {@link Task} or {@link createTask} for more information.
-   *
-   * @param {string} name - The name of the meta task.
-   * @param {TaskFunction} func - The function to be executed by the meta task.
+  static createTaskFromDefinition(definition) {
+    this.bootstrap();
+    this.validateName(definition.name);
+    const existing = this.get(definition.name);
+    if (existing) {
+      if (!runtimeDefinitionRegistry.isRuntimeOwnedTask(definition.name)) {
+        throw new Error(
+          `Task "${definition.name}" already exists and is not runtime-owned`
+        );
+      }
+      existing.destroy();
+    }
+    const taskFunction = compileRuntimeTaskFunction(definition);
+    const createdTask = definition.kind === "metaTask" ? this.createMetaTask(
+      definition.name,
+      taskFunction,
+      definition.description ?? "",
+      definition.options ?? {}
+    ) : this.createTask(
+      definition.name,
+      taskFunction,
+      definition.description ?? "",
+      definition.options ?? {}
+    );
+    runtimeDefinitionRegistry.setTaskDefinition(definition);
+    return createdTask;
+  }
+  static createHelper(name, func, description = "") {
+    this.bootstrap();
+    this.validateName(name);
+    this.assertGraphMutationAllowed("Cadenza.createHelper");
+    if (this.helperCache.has(name)) {
+      throw new Error(`Helper "${name}" already exists`);
+    }
+    const helper = new HelperDefinition(name, func, description, false);
+    this.helperCache.set(name, helper);
+    this.emit("meta.helper.created", {
+      data: {
+        name,
+        version: helper.version,
+        description,
+        functionString: func.toString(),
+        isMeta: false
+      }
+    });
+    return helper;
+  }
+  static createMetaHelper(name, func, description = "") {
+    this.bootstrap();
+    this.validateName(name);
+    this.assertGraphMutationAllowed("Cadenza.createMetaHelper");
+    if (this.helperCache.has(name)) {
+      throw new Error(`Helper "${name}" already exists`);
+    }
+    const helper = new HelperDefinition(name, func, description, true);
+    this.helperCache.set(name, helper);
+    this.emit("meta.helper.created", {
+      data: {
+        name,
+        version: helper.version,
+        description,
+        functionString: func.toString(),
+        isMeta: true
+      }
+    });
+    return helper;
+  }
+  static createHelperFromDefinition(definition) {
+    this.bootstrap();
+    this.validateName(definition.name);
+    const existing = this.getHelper(definition.name);
+    if (existing) {
+      if (!runtimeDefinitionRegistry.isRuntimeOwnedHelper(definition.name)) {
+        throw new Error(
+          `Helper "${definition.name}" already exists and is not runtime-owned`
+        );
+      }
+      existing.destroy();
+      this.helperCache.delete(definition.name);
+    }
+    const helperFunction = compileRuntimeHelperFunction(definition);
+    const helper = definition.kind === "metaHelper" ? this.createMetaHelper(
+      definition.name,
+      helperFunction,
+      definition.description ?? ""
+    ) : this.createHelper(
+      definition.name,
+      helperFunction,
+      definition.description ?? ""
+    );
+    runtimeDefinitionRegistry.setHelperDefinition(definition);
+    return helper;
+  }
+  static createGlobal(name, value, description = "") {
+    this.bootstrap();
+    this.validateName(name);
+    this.assertGraphMutationAllowed("Cadenza.createGlobal");
+    if (this.globalCache.has(name)) {
+      throw new Error(`Global "${name}" already exists`);
+    }
+    const globalDefinition = new GlobalDefinition(name, value, description, false);
+    this.globalCache.set(name, globalDefinition);
+    this.emit("meta.global.created", {
+      data: {
+        name,
+        version: globalDefinition.version,
+        description,
+        isMeta: false,
+        value: globalDefinition.value
+      }
+    });
+    return globalDefinition;
+  }
+  static createMetaGlobal(name, value, description = "") {
+    this.bootstrap();
+    this.validateName(name);
+    this.assertGraphMutationAllowed("Cadenza.createMetaGlobal");
+    if (this.globalCache.has(name)) {
+      throw new Error(`Global "${name}" already exists`);
+    }
+    const globalDefinition = new GlobalDefinition(name, value, description, true);
+    this.globalCache.set(name, globalDefinition);
+    this.emit("meta.global.created", {
+      data: {
+        name,
+        version: globalDefinition.version,
+        description,
+        isMeta: true,
+        value: globalDefinition.value
+      }
+    });
+    return globalDefinition;
+  }
+  static createGlobalFromDefinition(definition) {
+    this.bootstrap();
+    this.validateName(definition.name);
+    const existing = this.getGlobal(definition.name);
+    if (existing) {
+      if (!runtimeDefinitionRegistry.isRuntimeOwnedGlobal(definition.name)) {
+        throw new Error(
+          `Global "${definition.name}" already exists and is not runtime-owned`
+        );
+      }
+      existing.destroy();
+      this.globalCache.delete(definition.name);
+    }
+    const globalDefinition = definition.kind === "metaGlobal" ? this.createMetaGlobal(
+      definition.name,
+      definition.value,
+      definition.description ?? ""
+    ) : this.createGlobal(
+      definition.name,
+      definition.value,
+      definition.description ?? ""
+    );
+    runtimeDefinitionRegistry.setGlobalDefinition(definition);
+    return globalDefinition;
+  }
+  /**
+   * Creates a meta task with the specified name, functionality, description, and options.
+   * This is used for creating tasks that lives on the meta layer.
+   * The meta layer is a special layer that is executed separately from the business logic layer and is used for extending Cadenzas core functionality.
+   * See {@link Task} or {@link createTask} for more information.
+   *
+   * @param {string} name - The name of the meta task.
+   * @param {TaskFunction} func - The function to be executed by the meta task.
    * @param {string} [description] - An optional description of the meta task.
    * @param {TaskOptions} [options={}] - Additional optional task configuration. Automatically sets `isMeta` to true.
    * @return {Task} A task instance configured as a meta task.
@@ -7580,6 +8497,7 @@ var Cadenza = class {
    *
    */
   static createUniqueTask(name, func, description, options = {}) {
+    this.assertGraphMutationAllowed("Cadenza.createUniqueTask");
     options.isUnique = true;
     return this.createTask(name, func, description, options);
   }
@@ -7628,6 +8546,7 @@ var Cadenza = class {
    * ```
    */
   static createThrottledTask(name, func, throttledIdGetter = () => "default", description, options = {}) {
+    this.assertGraphMutationAllowed("Cadenza.createThrottledTask");
     options.concurrency = 1;
     options.getTagCallback = throttledIdGetter;
     return this.createTask(name, func, description, options);
@@ -7687,6 +8606,7 @@ var Cadenza = class {
    * ```
    */
   static createDebounceTask(name, func, description, debounceTime = 1e3, options = {}) {
+    this.assertGraphMutationAllowed("Cadenza.createDebounceTask");
     this.bootstrap();
     this.validateName(name);
     const actorResolvedOptions = this.resolveTaskOptionsForActorTask(
@@ -7815,6 +8735,7 @@ var Cadenza = class {
    * ```
    */
   static createEphemeralTask(name, func, description, options = {}) {
+    this.assertGraphMutationAllowed("Cadenza.createEphemeralTask");
     this.bootstrap();
     this.validateName(name);
     const actorResolvedOptions = this.resolveTaskOptionsForActorTask(
@@ -7911,12 +8832,46 @@ var Cadenza = class {
    * ```
    */
   static createRoutine(name, tasks, description = "") {
+    this.assertGraphMutationAllowed("Cadenza.createRoutine");
     this.bootstrap();
     this.validateName(name);
     if (tasks.length === 0) {
       throw new Error(`Routine '${name}' created with no starting tasks.`);
     }
-    return new GraphRoutine(name, tasks, description);
+    const createdRoutine = new GraphRoutine(name, tasks, description);
+    this.routineCache.set(name, createdRoutine);
+    return createdRoutine;
+  }
+  static createRoutineFromDefinition(definition) {
+    const existing = this.getRoutine(definition.name);
+    if (existing) {
+      if (!runtimeDefinitionRegistry.isRuntimeOwnedRoutine(definition.name)) {
+        throw new Error(
+          `Routine "${definition.name}" already exists and is not runtime-owned`
+        );
+      }
+      existing.destroy();
+    }
+    const startTasks = definition.startTaskNames.map((taskName) => {
+      const task = this.get(taskName);
+      if (!task) {
+        throw new Error(
+          `Routine "${definition.name}" references missing task "${taskName}"`
+        );
+      }
+      return task;
+    });
+    const routine = definition.isMeta === true ? this.createMetaRoutine(
+      definition.name,
+      startTasks,
+      definition.description ?? ""
+    ) : this.createRoutine(
+      definition.name,
+      startTasks,
+      definition.description ?? ""
+    );
+    runtimeDefinitionRegistry.setRoutineDefinition(definition);
+    return routine;
   }
   /**
    * Creates a meta routine with a given name, tasks, and optional description.
@@ -7931,47 +8886,1434 @@ var Cadenza = class {
    * @throws {Error} If no starting tasks are provided.
    */
   static createMetaRoutine(name, tasks, description = "") {
+    this.assertGraphMutationAllowed("Cadenza.createMetaRoutine");
     this.bootstrap();
     this.validateName(name);
     if (tasks.length === 0) {
       throw new Error(`Routine '${name}' created with no starting tasks.`);
     }
-    return new GraphRoutine(name, tasks, description, true);
+    const createdRoutine = new GraphRoutine(name, tasks, description, true);
+    this.routineCache.set(name, createdRoutine);
+    return createdRoutine;
+  }
+  static snapshotRuntime() {
+    const taskMap = /* @__PURE__ */ new Map();
+    for (const task of this.taskCache.values()) {
+      taskMap.set(task.name, task);
+    }
+    for (const task of this.registry?.tasks.values() ?? []) {
+      taskMap.set(task.name, task);
+    }
+    const tasks = Array.from(taskMap.values()).map((task) => {
+      const runtimeTaskDefinition = runtimeDefinitionRegistry.taskDefinitions.get(
+        task.name
+      );
+      const runtimeActorTaskDefinition = runtimeDefinitionRegistry.actorTaskDefinitions.get(task.name);
+      return {
+        name: task.name,
+        version: task.version,
+        description: task.description,
+        kind: runtimeActorTaskDefinition ? "actorTask" : task.isMeta ? "metaTask" : "task",
+        runtimeOwned: runtimeDefinitionRegistry.isRuntimeOwnedTask(task.name) === true,
+        language: runtimeTaskDefinition?.language ?? runtimeActorTaskDefinition?.language ?? null,
+        handlerSource: runtimeTaskDefinition?.handlerSource ?? runtimeActorTaskDefinition?.handlerSource ?? null,
+        concurrency: task.concurrency,
+        timeout: task.timeout,
+        retryCount: task.retryCount,
+        retryDelay: task.retryDelay,
+        retryDelayMax: task.retryDelayMax,
+        retryDelayFactor: task.retryDelayFactor,
+        validateInputContext: task.validateInputContext,
+        validateOutputContext: task.validateOutputContext,
+        inputContextSchema: sanitizeForJson(task.inputContextSchema),
+        outputContextSchema: sanitizeForJson(task.outputContextSchema),
+        nextTaskNames: Array.from(task.nextTasks).map((nextTask) => nextTask.name),
+        predecessorTaskNames: Array.from(task.predecessorTasks).map(
+          (predecessorTask) => predecessorTask.name
+        ),
+        signals: {
+          emits: Array.from(task.emitsSignals),
+          emitsAfter: Array.from(task.signalsToEmitAfter),
+          emitsOnFail: Array.from(task.signalsToEmitOnFail),
+          observed: Array.from(task.observedSignals)
+        },
+        intents: {
+          handles: Array.from(task.handlesIntents),
+          inquires: Array.from(task.inquiresIntents)
+        },
+        tools: {
+          helpers: Object.fromEntries(task.helperAliases),
+          globals: Object.fromEntries(task.globalAliases)
+        },
+        actorName: runtimeActorTaskDefinition?.actorName ?? null,
+        actorMode: runtimeActorTaskDefinition?.mode ?? null
+      };
+    });
+    const helpers = this.getAllHelpers().map((helper) => {
+      const runtimeHelperDefinition = runtimeDefinitionRegistry.helperDefinitions.get(helper.name);
+      return {
+        name: helper.name,
+        version: helper.version,
+        description: helper.description,
+        kind: helper.isMeta ? "metaHelper" : "helper",
+        runtimeOwned: runtimeDefinitionRegistry.isRuntimeOwnedHelper(helper.name),
+        language: runtimeHelperDefinition?.language ?? null,
+        handlerSource: runtimeHelperDefinition?.handlerSource ?? null,
+        tools: {
+          helpers: Object.fromEntries(helper.helperAliases),
+          globals: Object.fromEntries(helper.globalAliases)
+        }
+      };
+    });
+    const globals = this.getAllGlobals().map((globalDefinition) => ({
+      name: globalDefinition.name,
+      version: globalDefinition.version,
+      description: globalDefinition.description,
+      kind: globalDefinition.isMeta ? "metaGlobal" : "global",
+      runtimeOwned: runtimeDefinitionRegistry.isRuntimeOwnedGlobal(
+        globalDefinition.name
+      ),
+      value: sanitizeForJson(globalDefinition.value)
+    }));
+    const routineMap = /* @__PURE__ */ new Map();
+    for (const routine of this.routineCache.values()) {
+      routineMap.set(routine.name, routine);
+    }
+    for (const routine of this.registry?.routines.values() ?? []) {
+      routineMap.set(routine.name, routine);
+    }
+    const routines = Array.from(routineMap.values()).map(
+      (routine) => ({
+        name: routine.name,
+        version: routine.version,
+        description: routine.description,
+        isMeta: routine.isMeta,
+        runtimeOwned: runtimeDefinitionRegistry.isRuntimeOwnedRoutine(routine.name) === true,
+        startTaskNames: Array.from(routine.tasks).map((task) => task.name),
+        observedSignals: Array.from(routine.observedSignals)
+      })
+    );
+    const intents = Array.from(this.inquiryBroker?.intents.values() ?? []).map(
+      (intent) => {
+        const sanitizedIntent = sanitizeForJson(intent);
+        return {
+          ...sanitizedIntent,
+          runtimeOwned: runtimeDefinitionRegistry.intentDefinitions.has(
+            intent.name
+          )
+        };
+      }
+    );
+    const signals = Array.from(
+      this.signalBroker?.emittedSignalsRegistry.values() ?? []
+    ).map((signalName) => ({
+      name: signalName,
+      metadata: sanitizeForJson(
+        this.signalBroker?.signalMetadataRegistry.get(signalName) ?? null
+      ) ?? null
+    }));
+    const actors = this.getAllActors().map((actor) => {
+      const definition = actor.toDefinition();
+      const actorKeys = actor.listActorKeys().map((actorKey) => ({
+        actorKey,
+        durableState: sanitizeForJson(actor.getDurableState(actorKey)),
+        runtimeState: sanitizeForJson(actor.getRuntimeState(actorKey)),
+        durableVersion: actor.getDurableVersion(actorKey),
+        runtimeVersion: actor.getRuntimeVersion(actorKey)
+      }));
+      return {
+        name: actor.spec.name,
+        description: actor.spec.description ?? "",
+        runtimeOwned: runtimeDefinitionRegistry.isRuntimeOwnedActor(
+          actor.spec.name
+        ),
+        definition: sanitizeForJson(definition),
+        actorKeys
+      };
+    });
+    const actorTasks = Array.from(
+      runtimeDefinitionRegistry.actorTaskDefinitions.values()
+    ).map((definition) => ({
+      actorName: definition.actorName,
+      taskName: definition.taskName,
+      description: definition.description ?? "",
+      mode: definition.mode ?? "read",
+      language: definition.language,
+      handlerSource: definition.handlerSource,
+      runtimeOwned: true
+    }));
+    const links = Array.from(runtimeDefinitionRegistry.taskLinks.values()).map(
+      (link) => ({ ...link })
+    );
+    return {
+      runtimeMode: "core",
+      bootstrapped: this.isBootstrapped,
+      mode: this.mode,
+      tasks,
+      helpers,
+      globals,
+      routines,
+      intents,
+      signals,
+      actors,
+      actorTasks,
+      links
+    };
   }
   static reset() {
     this.signalBroker?.reset();
     this.inquiryBroker?.reset();
     this.registry?.reset();
     this.taskCache.clear();
+    this.routineCache.clear();
     this.actorCache.clear();
+    this.helperCache.clear();
+    this.globalCache.clear();
     this.runtimeInquiryDelegate = void 0;
     this.runtimeValidationPolicy = {};
     this.runtimeValidationScopes.clear();
     this.emittedMissingSchemaWarnings.clear();
+    this.helperExecutionDepth = 0;
+    runtimeDefinitionRegistry.reset();
     this.isBootstrapped = false;
   }
 };
 Cadenza.taskCache = /* @__PURE__ */ new Map();
+Cadenza.routineCache = /* @__PURE__ */ new Map();
 Cadenza.actorCache = /* @__PURE__ */ new Map();
+Cadenza.helperCache = /* @__PURE__ */ new Map();
+Cadenza.globalCache = /* @__PURE__ */ new Map();
 Cadenza.runtimeValidationPolicy = {};
 Cadenza.runtimeValidationScopes = /* @__PURE__ */ new Map();
 Cadenza.emittedMissingSchemaWarnings = /* @__PURE__ */ new Set();
+Cadenza.helperExecutionDepth = 0;
 Cadenza.isBootstrapped = false;
 Cadenza.mode = "production";
 
+// src/runtime/RuntimeSubscriptionManager.ts
+import { v4 as uuid8 } from "uuid";
+function isObject3(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function asStringOrNull(value) {
+  return typeof value === "string" && value.length > 0 ? value : null;
+}
+function asNumberOrNull(value) {
+  return typeof value === "number" && Number.isFinite(value) ? value : null;
+}
+function normalizeEventContext(context) {
+  const sanitized = sanitizeForJson(context);
+  return isObject3(sanitized) ? sanitized : { value: sanitized };
+}
+function matchesSignalPattern(fullSignal, signalName, patterns) {
+  return patterns.some((pattern) => {
+    if (pattern === "*") {
+      return true;
+    }
+    if (pattern === fullSignal || pattern === signalName) {
+      return true;
+    }
+    if (!pattern.endsWith(".*")) {
+      return false;
+    }
+    const prefix = pattern.slice(0, -2);
+    return signalName === prefix || signalName.startsWith(`${prefix}.`);
+  });
+}
+var RuntimeSubscriptionManagerError = class extends Error {
+  constructor(code, message) {
+    super(message);
+    this.code = code;
+    this.name = "RuntimeSubscriptionManagerError";
+  }
+};
+var RuntimeSubscriptionManager = class {
+  constructor() {
+    this.subscriptions = /* @__PURE__ */ new Map();
+    this.removeBrokerListener = null;
+    this.nextSequence = 0;
+    this.attach();
+  }
+  dispose() {
+    this.reset();
+    this.removeBrokerListener?.();
+    this.removeBrokerListener = null;
+  }
+  subscribe(signalPatterns, maxQueueSize) {
+    this.attach();
+    const descriptor = {
+      subscriptionId: uuid8(),
+      signalPatterns: [...signalPatterns],
+      maxQueueSize,
+      createdAt: (/* @__PURE__ */ new Date()).toISOString(),
+      pendingEvents: 0
+    };
+    this.subscriptions.set(descriptor.subscriptionId, {
+      descriptor,
+      events: [],
+      nextWaiter: null
+    });
+    return { ...descriptor };
+  }
+  unsubscribe(subscriptionId) {
+    const subscription = this.requireSubscription(subscriptionId);
+    this.clearWaiter(
+      subscription,
+      new RuntimeSubscriptionManagerError(
+        "not_found",
+        `Subscription "${subscriptionId}" was closed`
+      )
+    );
+    this.subscriptions.delete(subscriptionId);
+    return { ...subscription.descriptor };
+  }
+  async nextEvent(subscriptionId, timeoutMs) {
+    const subscription = this.requireSubscription(subscriptionId);
+    if (subscription.events.length > 0) {
+      const event = subscription.events.shift() ?? null;
+      subscription.descriptor.pendingEvents = subscription.events.length;
+      return {
+        subscriptionId,
+        event,
+        timedOut: false,
+        pendingEvents: subscription.events.length
+      };
+    }
+    if (timeoutMs <= 0) {
+      return {
+        subscriptionId,
+        event: null,
+        timedOut: true,
+        pendingEvents: 0
+      };
+    }
+    if (subscription.nextWaiter) {
+      throw new RuntimeSubscriptionManagerError(
+        "conflict",
+        `Subscription "${subscriptionId}" already has a pending nextEvent request`
+      );
+    }
+    return new Promise((resolve, reject) => {
+      const timer = setTimeout(() => {
+        subscription.nextWaiter = null;
+        resolve({
+          subscriptionId,
+          event: null,
+          timedOut: true,
+          pendingEvents: subscription.events.length
+        });
+      }, timeoutMs);
+      subscription.nextWaiter = {
+        resolve: (result) => {
+          clearTimeout(timer);
+          subscription.nextWaiter = null;
+          resolve(result);
+        },
+        reject: (error) => {
+          clearTimeout(timer);
+          subscription.nextWaiter = null;
+          reject(error);
+        },
+        timer
+      };
+    });
+  }
+  pollEvents(subscriptionId, limit) {
+    const subscription = this.requireSubscription(subscriptionId);
+    const events = subscription.events.splice(0, limit);
+    subscription.descriptor.pendingEvents = subscription.events.length;
+    return {
+      subscriptionId,
+      events,
+      pendingEvents: subscription.events.length
+    };
+  }
+  reset() {
+    for (const subscription of this.subscriptions.values()) {
+      this.clearWaiter(
+        subscription,
+        new RuntimeSubscriptionManagerError(
+          "not_found",
+          `Subscription "${subscription.descriptor.subscriptionId}" was reset`
+        )
+      );
+      subscription.events.length = 0;
+      subscription.descriptor.pendingEvents = 0;
+    }
+    this.subscriptions.clear();
+  }
+  attach() {
+    if (this.removeBrokerListener) {
+      return;
+    }
+    Cadenza.bootstrap();
+    this.removeBrokerListener = Cadenza.signalBroker.addPassiveSignalListener(
+      (signal, context, metadata) => this.captureSignal(signal, context, metadata)
+    );
+  }
+  captureSignal(signal, context, metadata) {
+    if (this.subscriptions.size === 0) {
+      return;
+    }
+    const normalizedContext = normalizeEventContext(context);
+    const emission = isObject3(normalizedContext.__signalEmission) ? normalizedContext.__signalEmission : {};
+    const metadataObject = isObject3(normalizedContext.__metadata) ? normalizedContext.__metadata : {};
+    const fullSignal = signal;
+    const [baseSignalName, ...signalTagParts] = signal.split(":");
+    const signalName = baseSignalName ?? signal;
+    const signalTag = signalTagParts.length > 0 ? signalTagParts.join(":") : null;
+    const eventTemplate = {
+      type: "signal",
+      signal: fullSignal,
+      signalName,
+      signalTag,
+      emittedAt: asStringOrNull(emission.emittedAt),
+      isMeta: emission.isMeta === true || signalName.startsWith("meta."),
+      isSubMeta: normalizedContext.__isSubMeta === true || signalName.startsWith("sub_meta."),
+      metadata: sanitizeForJson(metadata) ?? null,
+      source: {
+        taskName: asStringOrNull(emission.taskName),
+        taskVersion: asNumberOrNull(emission.taskVersion),
+        taskExecutionId: asStringOrNull(emission.taskExecutionId),
+        routineName: asStringOrNull(normalizedContext.__routineName) ?? asStringOrNull(emission.routineName),
+        routineVersion: asNumberOrNull(normalizedContext.__routineVersion) ?? asNumberOrNull(emission.routineVersion),
+        routineExecutionId: asStringOrNull(normalizedContext.__routineExecId) ?? asStringOrNull(emission.routineExecutionId),
+        executionTraceId: asStringOrNull(emission.executionTraceId) ?? asStringOrNull(normalizedContext.__executionTraceId) ?? asStringOrNull(metadataObject.__executionTraceId),
+        consumed: emission.consumed === true,
+        consumedBy: asStringOrNull(emission.consumedBy)
+      },
+      context: normalizedContext
+    };
+    for (const subscription of this.subscriptions.values()) {
+      if (!matchesSignalPattern(
+        fullSignal,
+        signalName,
+        subscription.descriptor.signalPatterns
+      )) {
+        continue;
+      }
+      const event = {
+        id: uuid8(),
+        subscriptionId: subscription.descriptor.subscriptionId,
+        sequence: ++this.nextSequence,
+        ...eventTemplate
+      };
+      if (subscription.nextWaiter) {
+        subscription.nextWaiter.resolve({
+          subscriptionId: subscription.descriptor.subscriptionId,
+          event,
+          timedOut: false,
+          pendingEvents: subscription.events.length
+        });
+        continue;
+      }
+      subscription.events.push(event);
+      if (subscription.events.length > subscription.descriptor.maxQueueSize) {
+        subscription.events.shift();
+      }
+      subscription.descriptor.pendingEvents = subscription.events.length;
+    }
+  }
+  clearWaiter(subscription, error) {
+    if (!subscription.nextWaiter) {
+      return;
+    }
+    if (subscription.nextWaiter.timer) {
+      clearTimeout(subscription.nextWaiter.timer);
+    }
+    subscription.nextWaiter.reject(error);
+    subscription.nextWaiter = null;
+  }
+  requireSubscription(subscriptionId) {
+    const subscription = this.subscriptions.get(subscriptionId);
+    if (!subscription) {
+      throw new RuntimeSubscriptionManagerError(
+        "not_found",
+        `No subscription named "${subscriptionId}" exists`
+      );
+    }
+    return subscription;
+  }
+};
+
+// src/runtime/RuntimeHost.ts
+var SUPPORTED_OPERATIONS = [
+  "runtime.bootstrap",
+  "runtime.info",
+  "runtime.detach",
+  "runtime.shutdown",
+  "runtime.reset",
+  "runtime.snapshot",
+  "runtime.subscribe",
+  "runtime.unsubscribe",
+  "runtime.nextEvent",
+  "runtime.pollEvents",
+  "task.upsert",
+  "helper.upsert",
+  "global.upsert",
+  "task.link",
+  "task.observeSignal",
+  "task.emitSignal",
+  "task.respondToIntent",
+  "task.useHelper",
+  "task.useGlobal",
+  "helper.useHelper",
+  "helper.useGlobal",
+  "routine.upsert",
+  "routine.observeSignal",
+  "intent.upsert",
+  "actor.upsert",
+  "actorTask.upsert",
+  "run",
+  "emit",
+  "inquire"
+];
+var RuntimeProtocolException = class extends Error {
+  constructor(code, message, details) {
+    super(message);
+    this.code = code;
+    this.details = details;
+    this.name = "RuntimeProtocolException";
+  }
+};
+function isObject4(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function assertObject(value, message) {
+  if (!isObject4(value)) {
+    throw new RuntimeProtocolException("invalid_payload", message);
+  }
+}
+function assertString(value, fieldName) {
+  if (typeof value !== "string" || !value.trim()) {
+    throw new RuntimeProtocolException(
+      "invalid_payload",
+      `${fieldName} must be a non-empty string`
+    );
+  }
+  return value;
+}
+function assertStringArray(value, fieldName) {
+  if (!Array.isArray(value) || value.some((entry) => typeof entry !== "string")) {
+    throw new RuntimeProtocolException(
+      "invalid_payload",
+      `${fieldName} must be an array of strings`
+    );
+  }
+  return value;
+}
+function normalizeSignalDefinition2(signal) {
+  if (typeof signal === "string") {
+    return signal;
+  }
+  if (isObject4(signal) && typeof signal.name === "string" && signal.name.trim().length > 0) {
+    return {
+      name: signal.name,
+      deliveryMode: signal.deliveryMode === "single" || signal.deliveryMode === "broadcast" ? signal.deliveryMode : void 0,
+      broadcastFilter: signal.broadcastFilter && isObject4(signal.broadcastFilter) ? signal.broadcastFilter : null
+    };
+  }
+  throw new RuntimeProtocolException(
+    "invalid_payload",
+    "signal must be a signal string or structured signal definition"
+  );
+}
+var RuntimeHost = class {
+  constructor(options = {}) {
+    this.pendingControlAction = null;
+    this.subscriptionManager = new RuntimeSubscriptionManager();
+    this.runtimeSharing = options.runtimeSharing ?? "isolated";
+    this.runtimeName = options.runtimeName ?? null;
+    this.sessionId = options.sessionId ?? null;
+    this.sessionRole = options.sessionRole ?? null;
+    this.activeSessionCountProvider = options.activeSessionCountProvider ?? (() => 1);
+    this.daemonProcessId = options.daemonProcessId ?? null;
+    this.onResetRuntime = options.onResetRuntime ?? null;
+  }
+  dispose() {
+    this.subscriptionManager.dispose();
+  }
+  resetSubscriptions() {
+    this.subscriptionManager.reset();
+  }
+  consumeControlAction() {
+    const action = this.pendingControlAction;
+    this.pendingControlAction = null;
+    return action;
+  }
+  handshake() {
+    return {
+      ready: true,
+      protocol: "cadenza-runtime-jsonl",
+      protocolVersion: "1",
+      runtimeMode: "core",
+      runtimeSharing: this.runtimeSharing,
+      runtimeName: this.runtimeName,
+      sessionId: this.sessionId,
+      sessionRole: this.sessionRole,
+      supportedOperations: [...SUPPORTED_OPERATIONS]
+    };
+  }
+  async handle(request) {
+    try {
+      if (!request || typeof request !== "object") {
+        throw new RuntimeProtocolException(
+          "invalid_request",
+          "Request must be an object"
+        );
+      }
+      if (typeof request.operation !== "string" || !SUPPORTED_OPERATIONS.includes(
+        request.operation
+      )) {
+        throw new RuntimeProtocolException(
+          "unsupported_operation",
+          `Unsupported operation: ${String(request.operation ?? "")}`
+        );
+      }
+      const operation = request.operation;
+      this.assertOperationAllowed(operation);
+      const result = await this.dispatch(operation, request.payload);
+      return {
+        id: request.id,
+        operation,
+        ok: true,
+        result: sanitizeForJson(result)
+      };
+    } catch (error) {
+      const normalizedError = this.normalizeError(error);
+      return {
+        id: request?.id,
+        operation: typeof request?.operation === "string" ? request.operation : "runtime.snapshot",
+        ok: false,
+        error: normalizedError
+      };
+    }
+  }
+  normalizeError(error) {
+    if (error instanceof RuntimeSubscriptionManagerError) {
+      return {
+        code: error.code,
+        message: error.message
+      };
+    }
+    if (error instanceof RuntimeProtocolException) {
+      return {
+        code: error.code,
+        message: error.message,
+        details: error.details ? sanitizeForJson(error.details) : void 0
+      };
+    }
+    if (error instanceof Error) {
+      return {
+        code: "runtime_error",
+        message: error.message
+      };
+    }
+    return {
+      code: "runtime_error",
+      message: String(error)
+    };
+  }
+  async dispatch(operation, payload) {
+    switch (operation) {
+      case "runtime.bootstrap":
+        return this.bootstrapRuntime(payload);
+      case "runtime.info":
+        return this.runtimeInfo();
+      case "runtime.detach":
+        return this.detachRuntime();
+      case "runtime.shutdown":
+        return this.shutdownRuntime();
+      case "runtime.reset":
+        return this.resetRuntime();
+      case "runtime.snapshot":
+        return Cadenza.snapshotRuntime();
+      case "runtime.subscribe":
+        return this.subscribe(payload);
+      case "runtime.unsubscribe":
+        return this.unsubscribe(payload);
+      case "runtime.nextEvent":
+        return this.nextEvent(payload);
+      case "runtime.pollEvents":
+        return this.pollEvents(payload);
+      case "task.upsert":
+        return this.upsertTask(payload);
+      case "helper.upsert":
+        return this.upsertHelper(payload);
+      case "global.upsert":
+        return this.upsertGlobal(payload);
+      case "task.link":
+        return this.linkTasks(payload);
+      case "task.observeSignal":
+        return this.observeTaskSignal(payload);
+      case "task.emitSignal":
+        return this.emitTaskSignal(payload);
+      case "task.respondToIntent":
+        return this.bindTaskIntent(payload);
+      case "task.useHelper":
+        return this.bindTaskHelper(payload);
+      case "task.useGlobal":
+        return this.bindTaskGlobal(payload);
+      case "helper.useHelper":
+        return this.bindHelperHelper(payload);
+      case "helper.useGlobal":
+        return this.bindHelperGlobal(payload);
+      case "routine.upsert":
+        return this.upsertRoutine(payload);
+      case "routine.observeSignal":
+        return this.observeRoutineSignal(payload);
+      case "intent.upsert":
+        return this.upsertIntent(payload);
+      case "actor.upsert":
+        return this.upsertActor(payload);
+      case "actorTask.upsert":
+        return this.upsertActorTask(payload);
+      case "run":
+        return this.runTarget(payload);
+      case "emit":
+        return this.emitSignal(payload);
+      case "inquire":
+        return this.inquireIntent(payload);
+    }
+  }
+  assertOperationAllowed(operation) {
+    if (!this.sessionRole) {
+      return;
+    }
+    if (this.sessionRole === "owner") {
+      return;
+    }
+    if (this.sessionRole === "writer") {
+      if (operation === "runtime.reset" || operation === "runtime.shutdown") {
+        throw new RuntimeProtocolException(
+          "forbidden",
+          `Session role "${this.sessionRole}" cannot perform ${operation}`
+        );
+      }
+      return;
+    }
+    const observerOperations = /* @__PURE__ */ new Set([
+      "runtime.info",
+      "runtime.detach",
+      "runtime.snapshot",
+      "runtime.subscribe",
+      "runtime.unsubscribe",
+      "runtime.nextEvent",
+      "runtime.pollEvents",
+      "inquire"
+    ]);
+    if (!observerOperations.has(operation)) {
+      throw new RuntimeProtocolException(
+        "forbidden",
+        `Session role "${this.sessionRole}" cannot perform ${operation}`
+      );
+    }
+  }
+  bootstrapRuntime(payload) {
+    const mode = isObject4(payload) && typeof payload.mode === "string" ? payload.mode : void 0;
+    if (mode) {
+      Cadenza.setMode(mode);
+    } else {
+      Cadenza.bootstrap();
+    }
+    return {
+      bootstrapped: true,
+      mode: Cadenza.mode
+    };
+  }
+  runtimeInfo() {
+    return {
+      runtimeMode: "core",
+      runtimeSharing: this.runtimeSharing,
+      runtimeName: this.runtimeName,
+      sessionId: this.sessionId,
+      sessionRole: this.sessionRole,
+      activeSessionCount: this.activeSessionCountProvider(),
+      daemonProcessId: this.daemonProcessId,
+      bootstrapped: Cadenza.isBootstrapped,
+      mode: Cadenza.mode
+    };
+  }
+  detachRuntime() {
+    this.pendingControlAction = "detach";
+    return {
+      detached: true,
+      runtimeName: this.runtimeName,
+      sessionId: this.sessionId
+    };
+  }
+  shutdownRuntime() {
+    this.pendingControlAction = "shutdown";
+    return {
+      shutdown: true,
+      runtimeName: this.runtimeName
+    };
+  }
+  resetRuntime() {
+    if (this.onResetRuntime) {
+      this.onResetRuntime();
+    } else {
+      Cadenza.reset();
+      this.subscriptionManager.reset();
+    }
+    return {
+      reset: true,
+      bootstrapped: false
+    };
+  }
+  subscribe(payload) {
+    assertObject(payload, "runtime.subscribe payload must be an object");
+    const signalPatterns = this.parseSignalPatterns(payload.signalPatterns);
+    const maxQueueSize = this.parsePositiveInteger(
+      payload.maxQueueSize,
+      "maxQueueSize",
+      100
+    );
+    return {
+      subscription: this.subscriptionManager.subscribe(signalPatterns, maxQueueSize)
+    };
+  }
+  unsubscribe(payload) {
+    assertObject(payload, "runtime.unsubscribe payload must be an object");
+    const subscriptionId = assertString(payload.subscriptionId, "subscriptionId");
+    return {
+      unsubscribed: true,
+      subscription: this.subscriptionManager.unsubscribe(subscriptionId)
+    };
+  }
+  async nextEvent(payload) {
+    assertObject(payload, "runtime.nextEvent payload must be an object");
+    const subscriptionId = assertString(payload.subscriptionId, "subscriptionId");
+    const timeoutMs = this.parseNonNegativeInteger(
+      payload.timeoutMs,
+      "timeoutMs",
+      0
+    );
+    return this.subscriptionManager.nextEvent(subscriptionId, timeoutMs);
+  }
+  pollEvents(payload) {
+    assertObject(payload, "runtime.pollEvents payload must be an object");
+    const subscriptionId = assertString(payload.subscriptionId, "subscriptionId");
+    const limit = this.parsePositiveInteger(payload.limit, "limit", 50);
+    return this.subscriptionManager.pollEvents(subscriptionId, limit);
+  }
+  upsertTask(payload) {
+    assertObject(payload, "task.upsert payload must be an object");
+    const definition = payload;
+    definition.name = assertString(definition.name, "name");
+    definition.handlerSource = assertString(
+      definition.handlerSource,
+      "handlerSource"
+    );
+    definition.language = definition.language === "js" || definition.language === "ts" ? definition.language : (() => {
+      throw new RuntimeProtocolException(
+        "invalid_payload",
+        "language must be 'js' or 'ts'"
+      );
+    })();
+    definition.kind = definition.kind === "metaTask" ? "metaTask" : "task";
+    runtimeDefinitionRegistry.setTaskDefinition(definition);
+    const task = Cadenza.createTaskFromDefinition(definition);
+    this.applyTaskDecorations(definition.name);
+    this.applyAllTaskLinks();
+    this.rematerializeRoutinesStartingWith(definition.name);
+    return {
+      task: this.snapshotTask(task)
+    };
+  }
+  upsertHelper(payload) {
+    assertObject(payload, "helper.upsert payload must be an object");
+    const definition = payload;
+    definition.name = assertString(definition.name, "name");
+    definition.handlerSource = assertString(
+      definition.handlerSource,
+      "handlerSource"
+    );
+    definition.language = definition.language === "js" || definition.language === "ts" ? definition.language : (() => {
+      throw new RuntimeProtocolException(
+        "invalid_payload",
+        "language must be 'js' or 'ts'"
+      );
+    })();
+    definition.kind = definition.kind === "metaHelper" ? "metaHelper" : "helper";
+    runtimeDefinitionRegistry.setHelperDefinition(definition);
+    compileRuntimeHelperFunction(definition);
+    Cadenza.createHelperFromDefinition(definition);
+    this.applyHelperDecorations(definition.name);
+    return {
+      helper: this.snapshotHelper(definition.name)
+    };
+  }
+  upsertGlobal(payload) {
+    assertObject(payload, "global.upsert payload must be an object");
+    const definition = {
+      name: assertString(payload.name, "name"),
+      description: typeof payload.description === "string" ? payload.description : "",
+      kind: payload.kind === "metaGlobal" ? "metaGlobal" : "global",
+      value: payload.value
+    };
+    runtimeDefinitionRegistry.setGlobalDefinition(definition);
+    Cadenza.createGlobalFromDefinition(definition);
+    return {
+      global: this.snapshotGlobal(definition.name)
+    };
+  }
+  linkTasks(payload) {
+    assertObject(payload, "task.link payload must be an object");
+    const definition = {
+      predecessorTaskName: assertString(
+        payload.predecessorTaskName,
+        "predecessorTaskName"
+      ),
+      successorTaskName: assertString(
+        payload.successorTaskName,
+        "successorTaskName"
+      )
+    };
+    runtimeDefinitionRegistry.setTaskLink(definition);
+    this.applyAllTaskLinks();
+    return {
+      linked: true,
+      ...definition
+    };
+  }
+  observeTaskSignal(payload) {
+    assertObject(payload, "task.observeSignal payload must be an object");
+    const definition = {
+      taskName: assertString(payload.taskName, "taskName"),
+      signal: normalizeSignalDefinition2(payload.signal)
+    };
+    runtimeDefinitionRegistry.setTaskSignalObservation(definition);
+    this.requireTask(definition.taskName).doOn(definition.signal);
+    return {
+      observed: true,
+      taskName: definition.taskName,
+      signal: typeof definition.signal === "string" ? definition.signal : definition.signal.name
+    };
+  }
+  emitTaskSignal(payload) {
+    assertObject(payload, "task.emitSignal payload must be an object");
+    const mode = payload.mode === "attach" || payload.mode === "onFail" ? payload.mode : "after";
+    const definition = {
+      taskName: assertString(payload.taskName, "taskName"),
+      signal: normalizeSignalDefinition2(payload.signal),
+      mode
+    };
+    runtimeDefinitionRegistry.setTaskSignalEmission(definition);
+    const task = this.requireTask(definition.taskName);
+    if (definition.mode === "attach") {
+      task.attachSignal(definition.signal);
+    } else if (definition.mode === "onFail") {
+      task.emitsOnFail(definition.signal);
+    } else {
+      task.emits(definition.signal);
+    }
+    return {
+      attached: true,
+      taskName: definition.taskName,
+      mode: definition.mode,
+      signal: typeof definition.signal === "string" ? definition.signal : definition.signal.name
+    };
+  }
+  bindTaskIntent(payload) {
+    assertObject(payload, "task.respondToIntent payload must be an object");
+    const taskName = assertString(payload.taskName, "taskName");
+    const intentName = assertString(payload.intentName, "intentName");
+    runtimeDefinitionRegistry.setTaskIntentBinding({
+      taskName,
+      intentName
+    });
+    this.requireTask(taskName).respondsTo(intentName);
+    return {
+      bound: true,
+      taskName,
+      intentName
+    };
+  }
+  bindTaskHelper(payload) {
+    assertObject(payload, "task.useHelper payload must be an object");
+    const definition = {
+      taskName: assertString(payload.taskName, "taskName"),
+      alias: assertString(payload.alias, "alias"),
+      helperName: assertString(payload.helperName, "helperName")
+    };
+    runtimeDefinitionRegistry.setTaskHelperBinding(definition);
+    this.requireTask(definition.taskName).usesHelpers({
+      [definition.alias]: Cadenza.getHelper(definition.helperName)
+    });
+    return {
+      bound: true,
+      ...definition
+    };
+  }
+  bindTaskGlobal(payload) {
+    assertObject(payload, "task.useGlobal payload must be an object");
+    const definition = {
+      taskName: assertString(payload.taskName, "taskName"),
+      alias: assertString(payload.alias, "alias"),
+      globalName: assertString(payload.globalName, "globalName")
+    };
+    runtimeDefinitionRegistry.setTaskGlobalBinding(definition);
+    this.requireTask(definition.taskName).usesGlobals({
+      [definition.alias]: Cadenza.getGlobal(definition.globalName)
+    });
+    return {
+      bound: true,
+      ...definition
+    };
+  }
+  bindHelperHelper(payload) {
+    assertObject(payload, "helper.useHelper payload must be an object");
+    const definition = {
+      helperName: assertString(payload.helperName, "helperName"),
+      alias: assertString(payload.alias, "alias"),
+      dependencyHelperName: assertString(
+        payload.dependencyHelperName,
+        "dependencyHelperName"
+      )
+    };
+    runtimeDefinitionRegistry.setHelperHelperBinding(definition);
+    const helper = Cadenza.getHelper(definition.helperName);
+    if (!helper) {
+      throw new RuntimeProtocolException(
+        "not_found",
+        `No helper named "${definition.helperName}" exists`
+      );
+    }
+    helper.usesHelpers({
+      [definition.alias]: Cadenza.getHelper(definition.dependencyHelperName)
+    });
+    return {
+      bound: true,
+      ...definition
+    };
+  }
+  bindHelperGlobal(payload) {
+    assertObject(payload, "helper.useGlobal payload must be an object");
+    const definition = {
+      helperName: assertString(payload.helperName, "helperName"),
+      alias: assertString(payload.alias, "alias"),
+      globalName: assertString(payload.globalName, "globalName")
+    };
+    runtimeDefinitionRegistry.setHelperGlobalBinding(definition);
+    const helper = Cadenza.getHelper(definition.helperName);
+    if (!helper) {
+      throw new RuntimeProtocolException(
+        "not_found",
+        `No helper named "${definition.helperName}" exists`
+      );
+    }
+    helper.usesGlobals({
+      [definition.alias]: Cadenza.getGlobal(definition.globalName)
+    });
+    return {
+      bound: true,
+      ...definition
+    };
+  }
+  upsertRoutine(payload) {
+    assertObject(payload, "routine.upsert payload must be an object");
+    const definition = {
+      name: assertString(payload.name, "name"),
+      description: typeof payload.description === "string" ? payload.description : "",
+      startTaskNames: assertStringArray(payload.startTaskNames, "startTaskNames"),
+      isMeta: payload.isMeta === true
+    };
+    if (definition.startTaskNames.length === 0) {
+      throw new RuntimeProtocolException(
+        "invalid_payload",
+        "startTaskNames must contain at least one task name"
+      );
+    }
+    runtimeDefinitionRegistry.setRoutineDefinition(definition);
+    const routine = Cadenza.createRoutineFromDefinition(definition);
+    this.applyRoutineDecorations(definition.name);
+    return {
+      routine: this.snapshotRoutine(routine)
+    };
+  }
+  observeRoutineSignal(payload) {
+    assertObject(payload, "routine.observeSignal payload must be an object");
+    const routineName = assertString(payload.routineName, "routineName");
+    const signal = assertString(payload.signal, "signal");
+    runtimeDefinitionRegistry.setRoutineSignalObservation({
+      routineName,
+      signal
+    });
+    this.requireRoutine(routineName).doOn(signal);
+    return {
+      observed: true,
+      routineName,
+      signal
+    };
+  }
+  upsertIntent(payload) {
+    assertObject(payload, "intent.upsert payload must be an object");
+    const intent = {
+      name: assertString(payload.name, "name"),
+      description: typeof payload.description === "string" ? payload.description : "",
+      input: isObject4(payload.input) ? payload.input : { type: "object" },
+      output: isObject4(payload.output) ? payload.output : { type: "object" }
+    };
+    runtimeDefinitionRegistry.setIntentDefinition(intent);
+    Cadenza.defineIntent(intent);
+    return {
+      intent: sanitizeForJson(intent)
+    };
+  }
+  upsertActor(payload) {
+    assertObject(payload, "actor.upsert payload must be an object");
+    const definition = payload;
+    definition.name = assertString(definition.name, "name");
+    definition.description = assertString(definition.description, "description");
+    definition.defaultKey = assertString(definition.defaultKey, "defaultKey");
+    runtimeDefinitionRegistry.setActorDefinition(definition);
+    const actor = Cadenza.createActorFromDefinition(definition);
+    this.rematerializeActorTasksFor(definition.name);
+    return {
+      actor: sanitizeForJson({
+        name: actor.spec.name,
+        description: actor.spec.description ?? "",
+        defaultKey: actor.spec.defaultKey
+      })
+    };
+  }
+  upsertActorTask(payload) {
+    assertObject(payload, "actorTask.upsert payload must be an object");
+    const definition = {
+      actorName: assertString(payload.actorName, "actorName"),
+      taskName: assertString(payload.taskName, "taskName"),
+      description: typeof payload.description === "string" ? payload.description : "",
+      mode: payload.mode === "write" || payload.mode === "meta" ? payload.mode : "read",
+      handlerSource: assertString(payload.handlerSource, "handlerSource"),
+      language: payload.language === "js" || payload.language === "ts" ? payload.language : (() => {
+        throw new RuntimeProtocolException(
+          "invalid_payload",
+          "language must be 'js' or 'ts'"
+        );
+      })(),
+      options: isObject4(payload.options) ? { ...payload.options } : void 0
+    };
+    runtimeDefinitionRegistry.setActorTaskDefinition(definition);
+    const task = this.materializeActorTask(definition.taskName);
+    this.applyTaskDecorations(definition.taskName);
+    this.applyAllTaskLinks();
+    this.rematerializeRoutinesStartingWith(definition.taskName);
+    return {
+      actorTask: this.snapshotTask(task)
+    };
+  }
+  async runTarget(payload) {
+    assertObject(payload, "run payload must be an object");
+    const targetName = assertString(payload.targetName, "targetName");
+    const context = isObject4(payload.context) ? payload.context : {};
+    let target = Cadenza.getRoutine(targetName);
+    if (!target) {
+      const routineDefinition = runtimeDefinitionRegistry.routineDefinitions.get(targetName);
+      if (routineDefinition) {
+        target = Cadenza.createRoutineFromDefinition(routineDefinition);
+        this.applyRoutineDecorations(targetName);
+      }
+    }
+    target = target ?? Cadenza.get(targetName);
+    if (!target) {
+      throw new RuntimeProtocolException(
+        "not_found",
+        `No task or routine named "${targetName}" exists`
+      );
+    }
+    const runner = "isMeta" in target && target.isMeta ? Cadenza.metaRunner : Cadenza.runner;
+    const runResult = runner.run(target, context);
+    const completedRun = await Promise.resolve(runResult);
+    return {
+      targetName,
+      run: completedRun.export()
+    };
+  }
+  emitSignal(payload) {
+    assertObject(payload, "emit payload must be an object");
+    const signal = assertString(payload.signal, "signal");
+    const context = isObject4(payload.context) ? payload.context : {};
+    const options = isObject4(payload.options) ? payload.options : {};
+    Cadenza.emit(signal, context, options);
+    return {
+      emitted: true,
+      signal
+    };
+  }
+  async inquireIntent(payload) {
+    assertObject(payload, "inquire payload must be an object");
+    const inquiry = assertString(payload.intent, "intent");
+    const context = isObject4(payload.context) ? payload.context : {};
+    const options = isObject4(payload.options) ? payload.options : {};
+    const response = await Cadenza.inquire(inquiry, context, options);
+    return {
+      inquiry,
+      response
+    };
+  }
+  requireTask(taskName) {
+    const task = Cadenza.get(taskName);
+    if (!task) {
+      throw new RuntimeProtocolException(
+        "not_found",
+        `No task named "${taskName}" exists`
+      );
+    }
+    return task;
+  }
+  requireRoutine(routineName) {
+    const routine = Cadenza.getRoutine(routineName);
+    if (!routine) {
+      throw new RuntimeProtocolException(
+        "not_found",
+        `No routine named "${routineName}" exists`
+      );
+    }
+    return routine;
+  }
+  applyTaskDecorations(taskName) {
+    const task = this.requireTask(taskName);
+    for (const observation of runtimeDefinitionRegistry.taskSignalObservations.values()) {
+      if (observation.taskName !== taskName) {
+        continue;
+      }
+      task.doOn(observation.signal);
+    }
+    for (const emission of runtimeDefinitionRegistry.taskSignalEmissions.values()) {
+      if (emission.taskName !== taskName) {
+        continue;
+      }
+      if (emission.mode === "attach") {
+        task.attachSignal(emission.signal);
+      } else if (emission.mode === "onFail") {
+        task.emitsOnFail(emission.signal);
+      } else {
+        task.emits(emission.signal);
+      }
+    }
+    for (const binding of runtimeDefinitionRegistry.taskIntentBindings.values()) {
+      if (binding.taskName !== taskName) {
+        continue;
+      }
+      task.respondsTo(binding.intentName);
+    }
+    for (const binding of runtimeDefinitionRegistry.taskHelperBindings.values()) {
+      if (binding.taskName !== taskName) {
+        continue;
+      }
+      task.usesHelpers({
+        [binding.alias]: Cadenza.getHelper(binding.helperName)
+      });
+    }
+    for (const binding of runtimeDefinitionRegistry.taskGlobalBindings.values()) {
+      if (binding.taskName !== taskName) {
+        continue;
+      }
+      task.usesGlobals({
+        [binding.alias]: Cadenza.getGlobal(binding.globalName)
+      });
+    }
+  }
+  applyHelperDecorations(helperName) {
+    const helper = Cadenza.getHelper(helperName);
+    if (!helper) {
+      throw new RuntimeProtocolException(
+        "not_found",
+        `No helper named "${helperName}" exists`
+      );
+    }
+    for (const binding of runtimeDefinitionRegistry.helperHelperBindings.values()) {
+      if (binding.helperName !== helperName) {
+        continue;
+      }
+      helper.usesHelpers({
+        [binding.alias]: Cadenza.getHelper(binding.dependencyHelperName)
+      });
+    }
+    for (const binding of runtimeDefinitionRegistry.helperGlobalBindings.values()) {
+      if (binding.helperName !== helperName) {
+        continue;
+      }
+      helper.usesGlobals({
+        [binding.alias]: Cadenza.getGlobal(binding.globalName)
+      });
+    }
+  }
+  applyAllTaskLinks() {
+    for (const link of runtimeDefinitionRegistry.taskLinks.values()) {
+      const predecessor = Cadenza.get(link.predecessorTaskName);
+      const successor = Cadenza.get(link.successorTaskName);
+      if (!predecessor || !successor) {
+        continue;
+      }
+      predecessor.then(successor);
+    }
+  }
+  applyRoutineDecorations(routineName) {
+    const routine = this.requireRoutine(routineName);
+    for (const observation of runtimeDefinitionRegistry.routineSignalObservations.values()) {
+      if (observation.routineName !== routineName) {
+        continue;
+      }
+      routine.doOn(observation.signal);
+    }
+  }
+  rematerializeRoutinesStartingWith(taskName) {
+    for (const definition of runtimeDefinitionRegistry.routineDefinitions.values()) {
+      if (!definition.startTaskNames.includes(taskName)) {
+        continue;
+      }
+      const recreated = Cadenza.createRoutineFromDefinition(definition);
+      this.applyRoutineDecorations(recreated.name);
+    }
+  }
+  rematerializeActorTasksFor(actorName) {
+    for (const definition of runtimeDefinitionRegistry.actorTaskDefinitions.values()) {
+      if (definition.actorName !== actorName) {
+        continue;
+      }
+      this.materializeActorTask(definition.taskName);
+      this.applyTaskDecorations(definition.taskName);
+      this.applyAllTaskLinks();
+      this.rematerializeRoutinesStartingWith(definition.taskName);
+    }
+  }
+  materializeActorTask(taskName) {
+    const definition = runtimeDefinitionRegistry.actorTaskDefinitions.get(taskName);
+    if (!definition) {
+      throw new RuntimeProtocolException(
+        "not_found",
+        `No actor task definition named "${taskName}" exists`
+      );
+    }
+    const actor = Cadenza.getActor(definition.actorName);
+    if (!actor) {
+      throw new RuntimeProtocolException(
+        "not_found",
+        `No actor named "${definition.actorName}" exists`
+      );
+    }
+    const existingTask = Cadenza.get(definition.taskName);
+    if (existingTask && !runtimeDefinitionRegistry.isRuntimeOwnedTask(existingTask.name)) {
+      throw new RuntimeProtocolException(
+        "conflict",
+        `Task "${definition.taskName}" already exists and is not runtime-owned`
+      );
+    }
+    existingTask?.destroy();
+    const handler = compileRuntimeActorTaskHandler(definition);
+    return Cadenza.createTask(
+      definition.taskName,
+      actor.task(handler, { mode: definition.mode }),
+      definition.description ?? "",
+      definition.options ?? {}
+    );
+  }
+  snapshotTask(task) {
+    const snapshot = Cadenza.snapshotRuntime();
+    const existing = snapshot.tasks.find((entry) => entry.name === task.name);
+    if (existing) {
+      return existing;
+    }
+    const runtimeTaskDefinition = runtimeDefinitionRegistry.taskDefinitions.get(
+      task.name
+    );
+    const runtimeActorTaskDefinition = runtimeDefinitionRegistry.actorTaskDefinitions.get(task.name);
+    return {
+      name: task.name,
+      version: task.version,
+      description: task.description,
+      kind: runtimeActorTaskDefinition ? "actorTask" : task.isMeta ? "metaTask" : "task",
+      runtimeOwned: runtimeDefinitionRegistry.isRuntimeOwnedTask(task.name),
+      language: runtimeTaskDefinition?.language ?? runtimeActorTaskDefinition?.language ?? null,
+      handlerSource: runtimeTaskDefinition?.handlerSource ?? runtimeActorTaskDefinition?.handlerSource ?? null,
+      tools: {
+        helpers: Object.fromEntries(task.helperAliases),
+        globals: Object.fromEntries(task.globalAliases)
+      }
+    };
+  }
+  snapshotHelper(helperName) {
+    const snapshot = Cadenza.snapshotRuntime();
+    return snapshot.helpers.find((entry) => entry.name === helperName) ?? {
+      name: helperName
+    };
+  }
+  snapshotGlobal(globalName) {
+    const snapshot = Cadenza.snapshotRuntime();
+    return snapshot.globals.find((entry) => entry.name === globalName) ?? {
+      name: globalName
+    };
+  }
+  snapshotRoutine(routine) {
+    const snapshot = Cadenza.snapshotRuntime();
+    return snapshot.routines.find((entry) => entry.name === routine.name) ?? {
+      name: routine.name,
+      version: routine.version,
+      description: routine.description,
+      isMeta: routine.isMeta,
+      runtimeOwned: runtimeDefinitionRegistry.isRuntimeOwnedRoutine(
+        routine.name
+      ),
+      startTaskNames: Array.from(routine.tasks).map((task) => task.name),
+      observedSignals: Array.from(routine.observedSignals)
+    };
+  }
+  parseSignalPatterns(value) {
+    if (value === void 0) {
+      return ["*"];
+    }
+    if (!Array.isArray(value) || value.some((entry) => typeof entry !== "string" || entry.trim().length === 0)) {
+      throw new RuntimeProtocolException(
+        "invalid_payload",
+        "signalPatterns must be an array of non-empty strings"
+      );
+    }
+    return Array.from(new Set(value.map((entry) => entry.trim())));
+  }
+  parsePositiveInteger(value, fieldName, fallback) {
+    if (value === void 0) {
+      return fallback;
+    }
+    if (typeof value !== "number" || !Number.isInteger(value) || value <= 0) {
+      throw new RuntimeProtocolException(
+        "invalid_payload",
+        `${fieldName} must be a positive integer`
+      );
+    }
+    return value;
+  }
+  parseNonNegativeInteger(value, fieldName, fallback) {
+    if (value === void 0) {
+      return fallback;
+    }
+    if (typeof value !== "number" || !Number.isInteger(value) || value < 0) {
+      throw new RuntimeProtocolException(
+        "invalid_payload",
+        `${fieldName} must be a non-negative integer`
+      );
+    }
+    return value;
+  }
+};
+
 // src/index.ts
 var index_default = Cadenza;
 export {
   Actor,
   DebounceTask,
   EphemeralTask,
+  GlobalDefinition,
   GraphContext,
   GraphRegistry,
   GraphRoutine,
   GraphRun,
   GraphRunner,
+  HelperDefinition,
   InquiryBroker,
   META_ACTOR_SESSION_STATE_PERSIST_INTENT,
+  RuntimeHost,
   SignalBroker,
   SignalEmitter,
   Task,