@cadenza.io/core 3.25.0 → 3.26.0

package/dist/index.mjs

@@ -1240,6 +1240,7 @@ var SignalBroker = class _SignalBroker {
     // TODO: Signals should be a class with a the observers, registered flag and other data.
     this.signalObservers = /* @__PURE__ */ new Map();
     this.emittedSignalsRegistry = /* @__PURE__ */ new Set();
+    this.signalMetadataRegistry = /* @__PURE__ */ new Map();
     // ── Flush Strategy Management ───────────────────────────────────────
     this.flushStrategies = /* @__PURE__ */ new Map();
     this.strategyData = /* @__PURE__ */ new Map();
@@ -1272,6 +1273,47 @@ var SignalBroker = class _SignalBroker {
   setVerbose(value) {
     this.verbose = value;
   }
+  resolveSignalMetadataKey(signal) {
+    const normalizedSignal = typeof signal === "string" ? signal.trim() : "";
+    if (!normalizedSignal) {
+      return "";
+    }
+    return normalizedSignal.split(":")[0] ?? normalizedSignal;
+  }
+  normalizeSignalMetadata(metadata) {
+    if (!metadata) {
+      return void 0;
+    }
+    const deliveryMode = metadata.deliveryMode === "broadcast" ? "broadcast" : "single";
+    const broadcastFilter = metadata.broadcastFilter && typeof metadata.broadcastFilter === "object" && !Array.isArray(metadata.broadcastFilter) ? merge_default({}, metadata.broadcastFilter) : null;
+    return {
+      deliveryMode,
+      broadcastFilter
+    };
+  }
+  setSignalMetadata(signal, metadata) {
+    const metadataKey = this.resolveSignalMetadataKey(signal);
+    if (!metadataKey) {
+      return;
+    }
+    const normalized = this.normalizeSignalMetadata(metadata);
+    if (!normalized) {
+      this.signalMetadataRegistry.delete(metadataKey);
+      return;
+    }
+    this.signalMetadataRegistry.set(metadataKey, normalized);
+  }
+  getSignalMetadata(signal) {
+    const metadataKey = this.resolveSignalMetadataKey(signal);
+    if (!metadataKey) {
+      return void 0;
+    }
+    const metadata = this.signalMetadataRegistry.get(metadataKey);
+    if (!metadata) {
+      return void 0;
+    }
+    return merge_default({}, metadata);
+  }
   // Dor debugging
   logMemoryFootprint(label = "current") {
     console.log(`[${label}] SignalBroker state sizes:`);
@@ -1356,7 +1398,8 @@ var SignalBroker = class _SignalBroker {
       const processedSignals = uniqueSignals.map((signal) => ({
         signal,
         data: {
-          registered: this.signalObservers.get(signal)?.registered ?? false
+          registered: this.signalObservers.get(signal)?.registered ?? false,
+          metadata: this.getSignalMetadata(signal) ?? null
         }
       }));
       return {
@@ -1706,10 +1749,11 @@ var SignalBroker = class _SignalBroker {
   execute(signal, context) {
     const isMeta = signal.includes("meta.");
     const isSubMeta = signal.includes("sub_meta.") || context.__isSubMeta;
+    const isReceivedSignalTransmission = context.__receivedSignalTransmission === true;
     const isMetric = context.__signalEmission?.isMetric;
+    const isNewTrace = !context.__signalEmission?.executionTraceId && !context.__metadata?.__executionTraceId && !context.__executionTraceId;
     const executionTraceId = context.__signalEmission?.executionTraceId ?? context.__metadata?.__executionTraceId ?? context.__executionTraceId ?? uuid();
     if (!isSubMeta && (!isMeta || this.debug)) {
-      const isNewTrace = !context.__signalEmission?.executionTraceId && !context.__metadata?.__executionTraceId && !context.__executionTraceId;
       if (isNewTrace) {
         this.emit("sub_meta.signal_broker.new_trace", {
           data: {
@@ -1738,21 +1782,33 @@ var SignalBroker = class _SignalBroker {
       const signalParts = signal.split(":");
       const signalName = signalParts[0];
       const signalTag = signalParts.length > 1 ? signalParts[1] : null;
+      const existingSignalEmission = context.__signalEmission && typeof context.__signalEmission === "object" ? context.__signalEmission : {};
       context.__signalEmission = {
-        ...context.__signalEmission ?? {},
-        uuid: uuid(),
-        executionTraceId,
-        signalName,
-        signalTag,
-        emittedAt: formatTimestamp(emittedAt),
-        consumed: false,
-        consumedBy: null,
-        isMeta
+        ...existingSignalEmission,
+        fullSignalName: existingSignalEmission.fullSignalName ?? signal,
+        uuid: existingSignalEmission.uuid ?? uuid(),
+        executionTraceId: existingSignalEmission.executionTraceId ?? executionTraceId,
+        signalName: existingSignalEmission.signalName ?? signalName,
+        signalTag: existingSignalEmission.signalTag ?? signalTag,
+        emittedAt: existingSignalEmission.emittedAt ?? formatTimestamp(emittedAt),
+        consumed: existingSignalEmission.consumed ?? false,
+        consumedBy: existingSignalEmission.consumedBy ?? null,
+        isMeta: existingSignalEmission.isMeta ?? isMeta,
+        __traceCreatedBySignalBroker: existingSignalEmission.__traceCreatedBySignalBroker ?? isNewTrace
       };
-      this.emit("sub_meta.signal_broker.emitting_signal", { ...context });
+      if (!isReceivedSignalTransmission) {
+        if (isNewTrace) {
+          context.__traceCreatedBySignalBroker = true;
+        }
+        this.emit("sub_meta.signal_broker.emitting_signal", { ...context });
+        if (isNewTrace) {
+          delete context.__traceCreatedBySignalBroker;
+        }
+      }
     } else if (isSubMeta) {
       context.__isSubMeta = true;
     }
+    delete context.__receivedSignalTransmission;
     context.__metadata = {
       ...context.__metadata,
       __executionTraceId: executionTraceId
@@ -1816,8 +1872,11 @@ var SignalBroker = class _SignalBroker {
    * @param {string} signal - The name of the signal to be added.
    * @return {void} This method does not return any value.
    */
-  addSignal(signal) {
+  addSignal(signal, metadata) {
     let _signal = signal;
+    if (metadata) {
+      this.setSignalMetadata(signal, metadata);
+    }
     if (!this.signalObservers.has(_signal)) {
       this.validateSignalName(_signal);
       this.signalObservers.set(_signal, {
@@ -1847,11 +1906,14 @@ var SignalBroker = class _SignalBroker {
    * @param routineOrTask The observer.
    * @edge Duplicates ignored; supports wildcards for broad listening.
    */
-  observe(signal, routineOrTask) {
-    this.addSignal(signal);
+  observe(signal, routineOrTask, metadata) {
+    this.addSignal(signal, metadata);
     this.signalObservers.get(signal).tasks.add(routineOrTask);
   }
-  registerEmittedSignal(signal) {
+  registerEmittedSignal(signal, metadata) {
+    if (metadata) {
+      this.setSignalMetadata(signal, metadata);
+    }
     this.emittedSignalsRegistry.add(signal);
   }
   /**
@@ -1886,6 +1948,7 @@ var SignalBroker = class _SignalBroker {
     this.clearThrottleState();
     this.signalObservers.clear();
     this.emittedSignalsRegistry.clear();
+    this.signalMetadataRegistry.clear();
   }
   shutdown() {
     this.reset();
@@ -2294,6 +2357,27 @@ var SignalEmitter = class {
 };
 
 // src/graph/execution/GraphNode.ts
+function normalizeGraphErrorMessage(error) {
+  if (typeof error === "string") {
+    return error;
+  }
+  if (error instanceof Error) {
+    return error.message;
+  }
+  if (error && typeof error === "object") {
+    const record = error;
+    if (typeof record.__error === "string") {
+      return record.__error;
+    }
+    if (typeof record.error === "string") {
+      return record.error;
+    }
+    if (typeof record.message === "string") {
+      return record.message;
+    }
+  }
+  return String(error);
+}
 var GraphNode = class _GraphNode extends SignalEmitter {
   constructor(task, context, routineExecId, prevNodes = [], debug = false, verbose = false) {
     super(
@@ -2455,6 +2539,7 @@ var GraphNode = class _GraphNode extends SignalEmitter {
             uuid: this.id,
             routineExecutionId: this.routineExecId,
             executionTraceId: this.executionTraceId,
+            inquiryId: context.__inquiryId ?? null,
             context: this.context.getContext(),
             metaContext: this.context.getMetadata(),
             taskName: this.task.name,
@@ -2477,7 +2562,8 @@ var GraphNode = class _GraphNode extends SignalEmitter {
           {
             data: {
               taskExecutionId: this.id,
-              previousTaskExecutionId: node.id
+              previousTaskExecutionId: node.id,
+              executionTraceId: context.__metadata?.__executionTraceId ?? context.__executionTraceId ?? null
             },
             filter: {
               taskName: this.task.name,
@@ -2495,7 +2581,8 @@ var GraphNode = class _GraphNode extends SignalEmitter {
           {
             data: {
               taskExecutionId: this.id,
-              previousTaskExecutionId: context.__previousTaskExecutionId
+              previousTaskExecutionId: context.__previousTaskExecutionId,
+              executionTraceId: context.__metadata?.__executionTraceId ?? context.__executionTraceId ?? null
             },
             filter: {
               taskName: this.task.name,
@@ -2732,7 +2819,14 @@ var GraphNode = class _GraphNode extends SignalEmitter {
   inquire(inquiry, context, options) {
     return Cadenza.resolveRuntimeInquiryDelegate()(
       inquiry,
-      { ...context, __executionTraceId: this.executionTraceId },
+      {
+        ...context,
+        __executionTraceId: context.__executionTraceId ?? context.__metadata?.__executionTraceId ?? this.executionTraceId,
+        __inquirySourceTaskName: this.task.name,
+        __inquirySourceTaskVersion: this.task.version,
+        __inquirySourceTaskExecutionId: this.id,
+        __inquirySourceRoutineExecutionId: this.routineExecId
+      },
       options
     );
   }
@@ -2902,11 +2996,12 @@ var GraphNode = class _GraphNode extends SignalEmitter {
    * @return {void} This method does not return any value.
    */
   onError(error, errorData = {}) {
+    const normalizedError = normalizeGraphErrorMessage(error);
     this.result = {
       ...this.context.getFullContext(),
-      __error: `Node error: ${error}`,
+      __error: `Node error: ${normalizedError}`,
       __retries: this.retries,
-      error: `Node error: ${error}`,
+      error: `Node error: ${normalizedError}`,
       errored: true,
       returnedValue: this.result,
       ...errorData
@@ -3481,8 +3576,16 @@ var GraphRunner = class extends SignalEmitter {
     const isNewTrace = !context.__routineExecId && !context.__metadata?.__executionTraceId && !context.__executionTraceId;
     const executionTraceId = context.__metadata?.__executionTraceId ?? context.__executionTraceId ?? uuid5();
     context.__executionTraceId = executionTraceId;
+    context.__traceCreatedByRunner = isNewTrace;
+    const isNewRoutine = !context.__routineExecId;
     const routineExecId = context.__routineExecId ?? uuid5();
     context.__routineExecId = routineExecId;
+    const routineCreatedAt = formatTimestamp(Date.now());
+    context.__routineCreatedByRunner = isNewRoutine;
+    context.__routineName = routineName;
+    context.__routineVersion = routineVersion;
+    context.__routineCreatedAt = routineCreatedAt;
+    context.__routineIsMeta = isMeta;
     Cadenza.applyRuntimeValidationScopesToContext(
       context,
       routineName,
@@ -3517,8 +3620,7 @@ var GraphRunner = class extends SignalEmitter {
           executionTraceId,
           context: ctx.getContext(),
           metaContext: ctx.getMetadata(),
-          previousRoutineExecution: context.__localRoutineExecId ?? context.__metadata?.__routineExecId ?? null,
-          created: formatTimestamp(Date.now())
+          created: routineCreatedAt
         },
         __metadata: {
           __executionTraceId: executionTraceId
@@ -3751,6 +3853,7 @@ var Actor = class {
     this.stateByKey = /* @__PURE__ */ new Map();
     this.sessionByKey = /* @__PURE__ */ new Map();
     this.idempotencyByKey = /* @__PURE__ */ new Map();
+    this.writeQueueByKey = /* @__PURE__ */ new Map();
     this.nextTaskBindingIndex = 0;
     if (!spec.name || typeof spec.name !== "string") {
       throw new Error("Actor name must be a non-empty string");
@@ -3932,7 +4035,7 @@ var Actor = class {
         taskBindingId,
         actorKey,
         invocationOptions,
-        runTask
+        () => this.runWithPerKeyWriteSerialization(actorKey, mode, runTask)
       );
     };
     wrapped[ACTOR_TASK_METADATA] = {
@@ -4210,6 +4313,24 @@ var Actor = class {
     });
     return promise;
   }
+  runWithPerKeyWriteSerialization(actorKey, mode, runTask) {
+    if (mode === "read") {
+      return runTask();
+    }
+    const previous = this.writeQueueByKey.get(actorKey) ?? Promise.resolve();
+    let releaseCurrent;
+    const currentGate = new Promise((resolve) => {
+      releaseCurrent = resolve;
+    });
+    const currentTail = previous.catch(() => void 0).then(() => currentGate);
+    this.writeQueueByKey.set(actorKey, currentTail);
+    return previous.catch(() => void 0).then(runTask).finally(() => {
+      releaseCurrent();
+      if (this.writeQueueByKey.get(actorKey) === currentTail) {
+        this.writeQueueByKey.delete(actorKey);
+      }
+    });
+  }
   getActiveIdempotencyRecord(compositeKey) {
     const record = this.idempotencyByKey.get(compositeKey);
     if (!record) {
@@ -4227,23 +4348,25 @@ var Actor = class {
       return;
     }
     const timeoutMs = normalizePositiveInteger(this.spec.session?.persistenceTimeoutMs) ?? 5e3;
+    const persistenceContext = {
+      actor_name: this.spec.name,
+      actor_version: 1,
+      actor_key: actorKey,
+      durable_state: cloneForDurableState(durableState),
+      durable_version: durableVersion,
+      expires_at: null
+    };
     const response = await inquire(
       META_ACTOR_SESSION_STATE_PERSIST_INTENT,
-      {
-        actor_name: this.spec.name,
-        actor_version: 1,
-        actor_key: actorKey,
-        durable_state: cloneForDurableState(durableState),
-        durable_version: durableVersion,
-        expires_at: null
-      },
+      persistenceContext,
       {
         timeout: timeoutMs,
+        requireComplete: true,
         rejectOnTimeout: true
       }
     );
     if (!isObject2(response) || response.__success !== true || response.persisted !== true) {
-      const reason = isObject2(response) ? response.__error ?? response.error : void 0;
+      const reason = isObject2(response) ? response.__error ?? response.error ?? response.internalError ?? (response.errored === true ? `errored response keys: ${Object.keys(response).join(",")}` : response.failed === true ? `failed response keys: ${Object.keys(response).join(",")}` : void 0) : void 0;
       throw new Error(
         `Actor "${this.spec.name}" durable state persistence failed for key "${actorKey}"${reason ? `: ${String(reason)}` : ""}`
       );
@@ -4277,6 +4400,20 @@ var Actor = class {
 };
 
 // src/graph/definition/Task.ts
+function normalizeSignalDefinition(input) {
+  if (typeof input === "string") {
+    return {
+      name: input
+    };
+  }
+  return {
+    name: input.name,
+    metadata: {
+      deliveryMode: input.deliveryMode,
+      broadcastFilter: input.broadcastFilter ?? null
+    }
+  };
+}
 var Task = class _Task extends SignalEmitter {
   /**
    * Constructs an instance of the task with the specified properties and configuration options.
@@ -4372,6 +4509,7 @@ var Task = class _Task extends SignalEmitter {
       "meta.task.output_schema_missing",
       "meta.task.relationship_added",
       "meta.task.relationship_removed",
+      "meta.task.intent_associated",
       "meta.task.layer_index_changed",
       "meta.node.scheduled",
       "meta.node.mapped",
@@ -5096,9 +5234,10 @@ var Task = class _Task extends SignalEmitter {
    * @return {this} The current instance after adding the specified signals.
    */
   doOn(...signals) {
-    signals.forEach((signal) => {
+    signals.forEach((input) => {
+      const { name: signal, metadata } = normalizeSignalDefinition(input);
       if (this.observedSignals.has(signal)) return;
-      Cadenza.signalBroker.observe(signal, this);
+      Cadenza.signalBroker.observe(signal, this, metadata);
       this.observedSignals.add(signal);
       if (this.register) {
         this.emitWithMetadata("meta.task.observed_signal", {
@@ -5119,13 +5258,14 @@ var Task = class _Task extends SignalEmitter {
    * @return {this} The current instance for method chaining.
    */
   emits(...signals) {
-    signals.forEach((signal) => {
+    signals.forEach((input) => {
+      const { name: signal } = normalizeSignalDefinition(input);
       if (this.observedSignals.has(signal))
         throw new Error(
           `Detected signal loop for task ${this.name}. Signal name: ${signal}`
         );
       this.signalsToEmitAfter.add(signal);
-      this.attachSignal(signal);
+      this.attachSignal(input);
     });
     return this;
   }
@@ -5137,9 +5277,10 @@ var Task = class _Task extends SignalEmitter {
    * @return {this} Returns the current instance for chaining.
    */
   emitsOnFail(...signals) {
-    signals.forEach((signal) => {
+    signals.forEach((input) => {
+      const { name: signal } = normalizeSignalDefinition(input);
       this.signalsToEmitOnFail.add(signal);
-      this.attachSignal(signal);
+      this.attachSignal(input);
     });
     return this;
   }
@@ -5150,9 +5291,10 @@ var Task = class _Task extends SignalEmitter {
    * @return {void} This method does not return a value.
    */
   attachSignal(...signals) {
-    signals.forEach((signal) => {
+    signals.forEach((input) => {
+      const { name: signal, metadata } = normalizeSignalDefinition(input);
       this.emitsSignals.add(signal);
-      Cadenza.signalBroker.registerEmittedSignal(signal);
+      Cadenza.signalBroker.registerEmittedSignal(signal, metadata);
       if (this.register) {
         const data = {
           signals: {
@@ -5246,8 +5388,20 @@ var Task = class _Task extends SignalEmitter {
   }
   respondsTo(...inquires) {
     for (const intentName of inquires) {
+      if (this.handlesIntents.has(intentName)) {
+        continue;
+      }
       this.handlesIntents.add(intentName);
       Cadenza.inquiryBroker.observe(intentName, this);
+      if (this.register) {
+        this.emitWithMetadata("meta.task.intent_associated", {
+          data: {
+            intentName,
+            taskName: this.name,
+            taskVersion: this.version
+          }
+        });
+      }
       const intent = Cadenza.inquiryBroker.intents.get(intentName);
       if (intent?.input) {
         this.inputContextSchema = this.mergeSchemaVariant(