@cadenza.io/core 3.23.0 → 3.25.0

package/dist/index.js

@@ -29,6 +29,7 @@ __export(index_exports, {
   GraphRun: () => GraphRun,
   GraphRunner: () => GraphRunner,
   InquiryBroker: () => InquiryBroker,
+  META_ACTOR_SESSION_STATE_PERSIST_INTENT: () => META_ACTOR_SESSION_STATE_PERSIST_INTENT,
   SignalBroker: () => SignalBroker,
   SignalEmitter: () => SignalEmitter,
   Task: () => Task,
@@ -2675,7 +2676,8 @@ var GraphNode = class _GraphNode extends SignalEmitter {
     if (!this.divided && !this.processing) {
       this.processing = true;
       const inputValidation = this.task.validateInput(
-        this.isMeta() ? this.context.getMetadata() : this.context.getContext()
+        this.isMeta() ? this.context.getFullContext() : this.context.getContext(),
+        this.context.getMetadata()
       );
       if (inputValidation !== true) {
         this.onError(inputValidation.__validationErrors);
@@ -2768,7 +2770,7 @@ var GraphNode = class _GraphNode extends SignalEmitter {
     }
   }
   inquire(inquiry, context, options) {
-    return Cadenza.inquire(
+    return Cadenza.resolveRuntimeInquiryDelegate()(
       inquiry,
       { ...context, __executionTraceId: this.executionTraceId },
       options
@@ -3010,7 +3012,10 @@ var GraphNode = class _GraphNode extends SignalEmitter {
         return this.divideAsync(current);
       }
       while (!current.done && current.value !== void 0) {
-        const outputValidation = this.task.validateOutput(current.value);
+        const outputValidation = this.task.validateOutput(
+          current.value,
+          this.context.getMetadata()
+        );
         if (outputValidation !== true) {
           this.onError(outputValidation.__validationErrors);
           break;
@@ -3022,7 +3027,10 @@ var GraphNode = class _GraphNode extends SignalEmitter {
     } else if (this.result !== void 0 && !this.errored) {
       newNodes.push(...this.generateNewNodes(this.result));
       if (typeof this.result !== "boolean") {
-        const outputValidation = this.task.validateOutput(this.result);
+        const outputValidation = this.task.validateOutput(
+          this.result,
+          this.context.getMetadata()
+        );
         if (outputValidation !== true) {
           this.onError(outputValidation.__validationErrors);
         }
@@ -3054,7 +3062,10 @@ var GraphNode = class _GraphNode extends SignalEmitter {
   async divideAsync(current) {
     const nextNodes = [];
     const _current = await current;
-    const outputValidation = this.task.validateOutput(_current.value);
+    const outputValidation = this.task.validateOutput(
+      _current.value,
+      this.context.getMetadata()
+    );
     if (outputValidation !== true) {
       this.onError(outputValidation.__validationErrors);
       return nextNodes;
@@ -3062,7 +3073,10 @@ var GraphNode = class _GraphNode extends SignalEmitter {
       nextNodes.push(...this.generateNewNodes(_current.value));
     }
     for await (const result of this.result) {
-      const outputValidation2 = this.task.validateOutput(result);
+      const outputValidation2 = this.task.validateOutput(
+        result,
+        this.context.getMetadata()
+      );
       if (outputValidation2 !== true) {
         this.onError(outputValidation2.__validationErrors);
         return [];
@@ -3509,6 +3523,11 @@ var GraphRunner = class extends SignalEmitter {
     context.__executionTraceId = executionTraceId;
     const routineExecId = context.__routineExecId ?? (0, import_uuid5.v4)();
     context.__routineExecId = routineExecId;
+    Cadenza.applyRuntimeValidationScopesToContext(
+      context,
+      routineName,
+      allTasks
+    );
     const ctx = new GraphContext(context || {});
     if (!isSubMeta) {
       if (isNewTrace) {
@@ -3663,6 +3682,7 @@ var TaskIterator = class {
 // src/actors/Actor.ts
 var ACTOR_TASK_METADATA = /* @__PURE__ */ Symbol.for("@cadenza.io/core/actor-task-meta");
 var ACTOR_INVOCATION_OPTIONS_KEY = "__actorOptions";
+var META_ACTOR_SESSION_STATE_PERSIST_INTENT = "meta-actor-session-state-persist";
 function deepClone(value) {
   if (value === void 0 || value === null || typeof value !== "object" || value instanceof Date) {
     return value;
@@ -3921,10 +3941,19 @@ var Actor = class {
         if (invocationOptions.writeContract === "reducer" && typeof handlerResult === "function") {
           reduceDurableState(handlerResult);
         }
+        const nextDurableVersion = stateRecord.version + (durableStateChanged ? 1 : 0);
+        if (durableStateChanged) {
+          await this.persistDurableStateIfConfigured(
+            actorKey,
+            nextDurableState,
+            nextDurableVersion,
+            inquire
+          );
+        }
         const writeTimestamp = Date.now();
         if (durableStateChanged) {
           stateRecord.durableState = cloneForDurableState(nextDurableState);
-          stateRecord.version += 1;
+          stateRecord.version = nextDurableVersion;
           stateRecord.lastDurableWriteAt = writeTimestamp;
         }
         if (runtimeStateChanged) {
@@ -4232,6 +4261,34 @@ var Actor = class {
     }
     return record;
   }
+  async persistDurableStateIfConfigured(actorKey, durableState, durableVersion, inquire) {
+    const shouldPersist = this.spec.session?.persistDurableState ?? false;
+    if (!shouldPersist) {
+      return;
+    }
+    const timeoutMs = normalizePositiveInteger(this.spec.session?.persistenceTimeoutMs) ?? 5e3;
+    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
+      },
+      {
+        timeout: timeoutMs,
+        rejectOnTimeout: true
+      }
+    );
+    if (!isObject2(response) || response.__success !== true || response.persisted !== true) {
+      const reason = isObject2(response) ? response.__error ?? response.error : void 0;
+      throw new Error(
+        `Actor "${this.spec.name}" durable state persistence failed for key "${actorKey}"${reason ? `: ${String(reason)}` : ""}`
+      );
+    }
+  }
   emitActorCreatedSignal() {
     Cadenza.signalBroker.registerEmittedSignal("meta.actor.created");
     const definition = sanitizeActorMetadataValue(
@@ -4284,7 +4341,7 @@ var Task = class _Task extends SignalEmitter {
    * @param {number} [retryDelayMax=0] - The maximum delay (in milliseconds) allowed between retries.
    * @param {number} [retryDelayFactor=1] - The factor by which the retry delay increases after each attempt.
    */
-  constructor(name, task, description = "", concurrency = 0, timeout = 0, register = true, isUnique = false, isMeta = false, isSubMeta = false, isHidden = false, getTagCallback = void 0, inputSchema = { type: "object" }, validateInputContext = false, outputSchema = { type: "object" }, validateOutputContext = false, retryCount = 0, retryDelay = 0, retryDelayMax = 0, retryDelayFactor = 1) {
+  constructor(name, task, description = "", concurrency = 0, timeout = 0, register = true, isUnique = false, isMeta = false, isSubMeta = false, isHidden = false, getTagCallback = void 0, inputSchema, validateInputContext = false, outputSchema, validateOutputContext = false, retryCount = 0, retryDelay = 0, retryDelayMax = 0, retryDelayFactor = 1) {
     super(isSubMeta || isHidden);
     this.version = 1;
     this.isMeta = false;
@@ -4297,8 +4354,10 @@ var Task = class _Task extends SignalEmitter {
     this.isEphemeral = false;
     this.isDebounce = false;
     this.inputContextSchema = { type: "object" };
+    this.hasExplicitInputContextSchema = false;
     this.validateInputContext = false;
     this.outputContextSchema = { type: "object" };
+    this.hasExplicitOutputContextSchema = false;
     this.validateOutputContext = false;
     this.retryCount = 0;
     this.retryDelay = 0;
@@ -4328,9 +4387,11 @@ var Task = class _Task extends SignalEmitter {
     this.isMeta = isMeta;
     this.isSubMeta = isSubMeta;
     this.isHidden = isHidden;
-    this.inputContextSchema = inputSchema;
+    this.inputContextSchema = inputSchema ?? { type: "object" };
+    this.hasExplicitInputContextSchema = inputSchema !== void 0;
     this.validateInputContext = validateInputContext;
-    this.outputContextSchema = outputSchema;
+    this.outputContextSchema = outputSchema ?? { type: "object" };
+    this.hasExplicitOutputContextSchema = outputSchema !== void 0;
     this.validateOutputContext = validateOutputContext;
     this.retryCount = retryCount;
     this.retryDelay = retryDelay;
@@ -4347,6 +4408,8 @@ var Task = class _Task extends SignalEmitter {
       "meta.task.destroyed",
       "meta.task.output_validation_failed",
       "meta.task.input_validation_failed",
+      "meta.task.input_schema_missing",
+      "meta.task.output_schema_missing",
       "meta.task.relationship_added",
       "meta.task.relationship_removed",
       "meta.task.layer_index_changed",
@@ -4435,9 +4498,9 @@ var Task = class _Task extends SignalEmitter {
       this.isSubMeta,
       this.isHidden,
       this.getTag,
-      this.inputContextSchema,
+      this.hasExplicitInputContextSchema ? this.inputContextSchema : void 0,
       this.validateInputContext,
-      this.outputContextSchema,
+      this.hasExplicitOutputContextSchema ? this.outputContextSchema : void 0,
       this.validateOutputContext,
       this.retryCount,
       this.retryDelay,
@@ -4484,9 +4547,11 @@ var Task = class _Task extends SignalEmitter {
   }
   setInputContextSchema(schema) {
     this.inputContextSchema = schema;
+    this.hasExplicitInputContextSchema = true;
   }
   setOutputContextSchema(schema) {
     this.outputContextSchema = schema;
+    this.hasExplicitOutputContextSchema = true;
   }
   setValidateInputContext(value) {
     this.validateInputContext = value;
@@ -4723,19 +4788,86 @@ var Task = class _Task extends SignalEmitter {
    * @param {AnyObject} context - The input context to validate.
    * @return {true | AnyObject} - Returns `true` if validation succeeds, otherwise returns an error object containing details of the validation failure.
    */
-  validateInput(context) {
-    if (this.validateInputContext) {
-      const validationResult = this.validateSchema(
-        context,
-        this.inputContextSchema
-      );
-      if (!validationResult.valid) {
-        this.emitWithMetadata("meta.task.input_validation_failed", {
-          __taskName: this.name,
-          __taskVersion: this.version,
-          __context: context,
-          __errors: validationResult.errors
-        });
+  getEffectiveValidationMode(direction, metadata = {}) {
+    const resolvedPolicy = Cadenza.resolveRuntimeValidationPolicyForTask(
+      this,
+      metadata
+    );
+    const policyMode = direction === "input" ? resolvedPolicy.inputMode : resolvedPolicy.outputMode;
+    const isExplicit = direction === "input" ? this.validateInputContext : this.validateOutputContext;
+    return {
+      resolvedPolicy,
+      mode: isExplicit ? "enforce" : policyMode,
+      warnOnMissingSchema: direction === "input" ? resolvedPolicy.warnOnMissingInputSchema : resolvedPolicy.warnOnMissingOutputSchema,
+      hasExplicitSchema: direction === "input" ? this.hasExplicitInputContextSchema : this.hasExplicitOutputContextSchema,
+      schema: direction === "input" ? this.inputContextSchema : this.outputContextSchema
+    };
+  }
+  warnMissingSchema(direction, metadata = {}) {
+    const resolvedPolicy = Cadenza.resolveRuntimeValidationPolicyForTask(
+      this,
+      metadata
+    );
+    const cacheKey = `${this.name}:${this.version}:${direction}:${resolvedPolicy.layer}`;
+    if (!Cadenza.shouldEmitMissingSchemaWarning(cacheKey)) {
+      return;
+    }
+    const ctx = {
+      __taskName: this.name,
+      __taskVersion: this.version,
+      __layer: resolvedPolicy.layer,
+      __activeScopeIds: resolvedPolicy.activeScopeIds
+    };
+    this.emitWithMetadata(`meta.task.${direction}_schema_missing`, ctx);
+    console.warn(
+      `[CADENZA_VALIDATION] Missing ${direction} schema for task '${this.name}'`,
+      {
+        taskName: this.name,
+        taskVersion: this.version,
+        direction,
+        layer: resolvedPolicy.layer,
+        activeScopeIds: resolvedPolicy.activeScopeIds
+      }
+    );
+  }
+  logValidationFailure(direction, validationErrors, metadata = {}) {
+    const resolvedPolicy = Cadenza.resolveRuntimeValidationPolicyForTask(
+      this,
+      metadata
+    );
+    console.error(
+      `[CADENZA_VALIDATION] ${direction} validation failed for task '${this.name}'`,
+      {
+        taskName: this.name,
+        taskVersion: this.version,
+        direction,
+        layer: resolvedPolicy.layer,
+        activeScopeIds: resolvedPolicy.activeScopeIds,
+        errors: validationErrors
+      }
+    );
+  }
+  validateInput(context, metadata = {}) {
+    const config = this.getEffectiveValidationMode("input", metadata);
+    if (config.mode === "off") {
+      return true;
+    }
+    if (!config.hasExplicitSchema) {
+      if (config.warnOnMissingSchema) {
+        this.warnMissingSchema("input", metadata);
+      }
+      return true;
+    }
+    const validationResult = this.validateSchema(context, config.schema);
+    if (!validationResult.valid) {
+      this.emitWithMetadata("meta.task.input_validation_failed", {
+        __taskName: this.name,
+        __taskVersion: this.version,
+        __context: context,
+        __errors: validationResult.errors
+      });
+      this.logValidationFailure("input", validationResult.errors, metadata);
+      if (config.mode === "enforce") {
         return {
           errored: true,
           __error: "Input context validation failed",
@@ -4752,19 +4884,27 @@ var Task = class _Task extends SignalEmitter {
    * @return {true | AnyObject} Returns `true` if the output context is valid; otherwise, returns an object
    * containing error information when validation fails.
    */
-  validateOutput(context) {
-    if (this.validateOutputContext) {
-      const validationResult = this.validateSchema(
-        context,
-        this.outputContextSchema
-      );
-      if (!validationResult.valid) {
-        this.emitWithMetadata("meta.task.output_validation_failed", {
-          __taskName: this.name,
-          __taskVersion: this.version,
-          __result: context,
-          __errors: validationResult.errors
-        });
+  validateOutput(context, metadata = {}) {
+    const config = this.getEffectiveValidationMode("output", metadata);
+    if (config.mode === "off") {
+      return true;
+    }
+    if (!config.hasExplicitSchema) {
+      if (config.warnOnMissingSchema) {
+        this.warnMissingSchema("output", metadata);
+      }
+      return true;
+    }
+    const validationResult = this.validateSchema(context, config.schema);
+    if (!validationResult.valid) {
+      this.emitWithMetadata("meta.task.output_validation_failed", {
+        __taskName: this.name,
+        __taskVersion: this.version,
+        __result: context,
+        __errors: validationResult.errors
+      });
+      this.logValidationFailure("output", validationResult.errors, metadata);
+      if (config.mode === "enforce") {
         return {
           errored: true,
           __error: "Output context validation failed",
@@ -5155,6 +5295,7 @@ var Task = class _Task extends SignalEmitter {
           intentName,
           intent.input
         );
+        this.hasExplicitInputContextSchema = true;
       }
       if (intent?.output) {
         this.outputContextSchema = this.mergeSchemaVariant(
@@ -5162,6 +5303,7 @@ var Task = class _Task extends SignalEmitter {
           intentName,
           intent.output
         );
+        this.hasExplicitOutputContextSchema = true;
       }
     }
     return this;
@@ -6865,6 +7007,146 @@ var Cadenza = class {
   static async inquire(inquiry, context, options) {
     return this.inquiryBroker?.inquire(inquiry, context, options);
   }
+  static setRuntimeInquiryDelegate(delegate) {
+    this.runtimeInquiryDelegate = delegate;
+  }
+  static resolveRuntimeInquiryDelegate() {
+    return this.runtimeInquiryDelegate ?? ((inquiry, context, options) => this.inquire(inquiry, context, options));
+  }
+  static getRuntimeValidationPolicy() {
+    return { ...this.runtimeValidationPolicy };
+  }
+  static setRuntimeValidationPolicy(policy = {}) {
+    this.runtimeValidationPolicy = {
+      ...this.runtimeValidationPolicy,
+      ...policy
+    };
+    this.emittedMissingSchemaWarnings.clear();
+    return this.getRuntimeValidationPolicy();
+  }
+  static replaceRuntimeValidationPolicy(policy = {}) {
+    this.runtimeValidationPolicy = { ...policy };
+    this.emittedMissingSchemaWarnings.clear();
+    return this.getRuntimeValidationPolicy();
+  }
+  static clearRuntimeValidationPolicy() {
+    this.runtimeValidationPolicy = {};
+    this.emittedMissingSchemaWarnings.clear();
+  }
+  static getRuntimeValidationScopes() {
+    return Array.from(this.runtimeValidationScopes.values()).map((scope) => ({
+      ...scope,
+      startTaskNames: scope.startTaskNames ? [...scope.startTaskNames] : void 0,
+      startRoutineNames: scope.startRoutineNames ? [...scope.startRoutineNames] : void 0,
+      policy: scope.policy ? { ...scope.policy } : void 0
+    }));
+  }
+  static upsertRuntimeValidationScope(scope) {
+    if (!scope.id?.trim()) {
+      throw new Error("Runtime validation scope id is required");
+    }
+    const normalizedScope = {
+      id: scope.id,
+      active: scope.active !== false,
+      startTaskNames: scope.startTaskNames ? [...new Set(scope.startTaskNames)] : void 0,
+      startRoutineNames: scope.startRoutineNames ? [...new Set(scope.startRoutineNames)] : void 0,
+      policy: scope.policy ? { ...scope.policy } : void 0
+    };
+    this.runtimeValidationScopes.set(scope.id, normalizedScope);
+    this.emittedMissingSchemaWarnings.clear();
+    return {
+      ...normalizedScope,
+      startTaskNames: normalizedScope.startTaskNames ? [...normalizedScope.startTaskNames] : void 0,
+      startRoutineNames: normalizedScope.startRoutineNames ? [...normalizedScope.startRoutineNames] : void 0,
+      policy: normalizedScope.policy ? { ...normalizedScope.policy } : void 0
+    };
+  }
+  static removeRuntimeValidationScope(id) {
+    this.runtimeValidationScopes.delete(id);
+    this.emittedMissingSchemaWarnings.clear();
+  }
+  static clearRuntimeValidationScopes() {
+    this.runtimeValidationScopes.clear();
+    this.emittedMissingSchemaWarnings.clear();
+  }
+  static applyRuntimeValidationScopesToContext(context, routineName, tasks) {
+    const existingScopeIds = /* @__PURE__ */ new Set();
+    const metadataScopeIds = context.__metadata?.__runtimeValidationScopeIds;
+    const rootScopeIds = context.__runtimeValidationScopeIds;
+    if (Array.isArray(rootScopeIds)) {
+      rootScopeIds.forEach((id) => existingScopeIds.add(id));
+    }
+    if (Array.isArray(metadataScopeIds)) {
+      metadataScopeIds.forEach((id) => existingScopeIds.add(id));
+    }
+    const taskNames = new Set(tasks.map((task) => task.name));
+    for (const scope of this.runtimeValidationScopes.values()) {
+      if (scope.active === false) {
+        continue;
+      }
+      const matchesRoutine = scope.startRoutineNames?.includes(routineName) === true;
+      const matchesTask = scope.startTaskNames?.some((taskName) => taskNames.has(taskName)) === true;
+      if (matchesRoutine || matchesTask) {
+        existingScopeIds.add(scope.id);
+      }
+    }
+    if (existingScopeIds.size > 0) {
+      const scopeIds = Array.from(existingScopeIds);
+      context.__runtimeValidationScopeIds = scopeIds;
+      context.__metadata = {
+        ...context.__metadata ?? {},
+        __runtimeValidationScopeIds: scopeIds
+      };
+    }
+    return context;
+  }
+  static resolveRuntimeValidationPolicyForTask(task, metadata = {}) {
+    const layer = task.isMeta || task.isSubMeta || metadata.__isSubMeta ? "meta" : "business";
+    const activeScopeIds = /* @__PURE__ */ new Set();
+    const rootScopeIds = metadata.__runtimeValidationScopeIds;
+    const nestedScopeIds = metadata.__metadata?.__runtimeValidationScopeIds;
+    if (Array.isArray(rootScopeIds)) {
+      rootScopeIds.forEach((id) => activeScopeIds.add(id));
+    }
+    if (Array.isArray(nestedScopeIds)) {
+      nestedScopeIds.forEach((id) => activeScopeIds.add(id));
+    }
+    const mergedPolicy = {
+      ...this.runtimeValidationPolicy
+    };
+    for (const scopeId of activeScopeIds) {
+      const scope = this.runtimeValidationScopes.get(scopeId);
+      if (!scope?.policy || scope.active === false) {
+        continue;
+      }
+      Object.assign(mergedPolicy, scope.policy);
+    }
+    if (layer === "meta") {
+      return {
+        layer,
+        inputMode: mergedPolicy.metaInput ?? "off",
+        outputMode: mergedPolicy.metaOutput ?? "off",
+        warnOnMissingInputSchema: mergedPolicy.warnOnMissingMetaInputSchema === true,
+        warnOnMissingOutputSchema: mergedPolicy.warnOnMissingMetaOutputSchema === true,
+        activeScopeIds: Array.from(activeScopeIds)
+      };
+    }
+    return {
+      layer,
+      inputMode: mergedPolicy.businessInput ?? "off",
+      outputMode: mergedPolicy.businessOutput ?? "off",
+      warnOnMissingInputSchema: mergedPolicy.warnOnMissingBusinessInputSchema === true,
+      warnOnMissingOutputSchema: mergedPolicy.warnOnMissingBusinessOutputSchema === true,
+      activeScopeIds: Array.from(activeScopeIds)
+    };
+  }
+  static shouldEmitMissingSchemaWarning(cacheKey) {
+    if (this.emittedMissingSchemaWarnings.has(cacheKey)) {
+      return false;
+    }
+    this.emittedMissingSchemaWarnings.add(cacheKey);
+    return true;
+  }
   /**
    * Creates an in-memory actor runtime instance.
    *
@@ -7464,11 +7746,18 @@ var Cadenza = class {
     this.registry?.reset();
     this.taskCache.clear();
     this.actorCache.clear();
+    this.runtimeInquiryDelegate = void 0;
+    this.runtimeValidationPolicy = {};
+    this.runtimeValidationScopes.clear();
+    this.emittedMissingSchemaWarnings.clear();
     this.isBootstrapped = false;
   }
 };
 Cadenza.taskCache = /* @__PURE__ */ new Map();
 Cadenza.actorCache = /* @__PURE__ */ new Map();
+Cadenza.runtimeValidationPolicy = {};
+Cadenza.runtimeValidationScopes = /* @__PURE__ */ new Map();
+Cadenza.emittedMissingSchemaWarnings = /* @__PURE__ */ new Set();
 Cadenza.isBootstrapped = false;
 Cadenza.mode = "production";
 
@@ -7485,6 +7774,7 @@ var index_default = Cadenza;
   GraphRun,
   GraphRunner,
   InquiryBroker,
+  META_ACTOR_SESSION_STATE_PERSIST_INTENT,
   SignalBroker,
   SignalEmitter,
   Task,