@cadenza.io/core 1.4.0 → 1.5.0

package/dist/index.js

@@ -30,8 +30,6 @@ __export(index_exports, {
   SignalParticipant: () => SignalParticipant,
   SignalTask: () => SignalTask,
   Task: () => Task,
-  ThrottledTask: () => ThrottledTask,
-  UniqueTask: () => UniqueTask,
   default: () => index_default
 });
 module.exports = __toCommonJS(index_exports);
@@ -143,7 +141,7 @@ var SignalBroker = class _SignalBroker {
   executeListener(signal, context) {
     const obs = this.signalObservers.get(signal);
     const runner = this.getRunner(signal);
-    if (obs && runner) {
+    if (obs && obs.tasks.size && runner) {
       obs.fn(runner, Array.from(obs.tasks), context);
       return true;
     }
@@ -732,6 +730,14 @@ var GraphNode = class _GraphNode extends SignalEmitter {
     if (!this.divided && !this.processing) {
       this.start();
       this.processing = true;
+      const inputValidation = this.task.validateInput(
+        this.context.getContext()
+      );
+      if (inputValidation !== true) {
+        this.onError(inputValidation.__validationErrors);
+        this.postProcess();
+        return this.nextNodes;
+      }
       try {
         this.result = this.work();
       } catch (e) {
@@ -786,12 +792,13 @@ var GraphNode = class _GraphNode extends SignalEmitter {
     }
     this.end();
   }
-  onError(error) {
+  onError(error, errorData = {}) {
     this.result = {
       ...this.context.getFullContext(),
       __error: `Node error: ${error}`,
       error: `Node error: ${error}`,
-      returnedValue: this.result
+      returnedValue: this.result,
+      ...errorData
     };
     this.migrate(this.result);
     this.errored = true;
@@ -803,15 +810,26 @@ var GraphNode = class _GraphNode extends SignalEmitter {
       const generator = this.result;
       let current = generator.next();
       while (!current.done && current.value !== void 0) {
-        newNodes.push(...this.generateNewNodes(current.value));
-        current = generator.next();
+        const outputValidation = this.task.validateOutput(current.value);
+        if (outputValidation !== true) {
+          this.onError(outputValidation.__validationErrors);
+          break;
+        } else {
+          newNodes.push(...this.generateNewNodes(current.value));
+          current = generator.next();
+        }
       }
     } 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);
+        if (outputValidation !== true) {
+          this.onError(outputValidation.__validationErrors);
+        }
         this.migrate({ ...this.result, ...this.context.getMetaData() });
       }
-    } else if (this.errored) {
+    }
+    if (this.errored) {
       newNodes.push(
         ...this.task.mapNext(
           (t) => this.clone().split((0, import_uuid3.v4)()).differentiate(t).migrate({ ...this.result }),
@@ -1183,9 +1201,14 @@ var Task = class extends SignalParticipant {
    * @param register Register via signal (default true).
    * @param isUnique
    * @param isMeta
+   * @param getTagCallback
+   * @param inputSchema
+   * @param validateInputContext
+   * @param outputSchema
+   * @param validateOutputContext
    * @edge Emits 'meta.task.created' with { __task: this } for seed.
    */
-  constructor(name, task, description = "", concurrency = 0, timeout = 0, register = true, isUnique = false, isMeta = false) {
+  constructor(name, task, description = "", concurrency = 0, timeout = 0, register = true, isUnique = false, isMeta = false, getTagCallback = void 0, inputSchema = void 0, validateInputContext = false, outputSchema = void 0, validateOutputContext = false) {
     super();
     this.isMeta = false;
     this.isUnique = false;
@@ -1193,6 +1216,10 @@ var Task = class extends SignalParticipant {
     this.isSignal = false;
     this.isDeputy = false;
     this.isEphemeral = false;
+    this.inputContextSchema = void 0;
+    this.validateInputContext = false;
+    this.outputContextSchema = void 0;
+    this.validateOutputContext = false;
     this.layerIndex = 0;
     this.progressWeight = 0;
     this.nextTasks = /* @__PURE__ */ new Set();
@@ -1207,6 +1234,14 @@ var Task = class extends SignalParticipant {
     this.timeout = timeout;
     this.isUnique = isUnique;
     this.isMeta = isMeta;
+    this.inputContextSchema = inputSchema;
+    this.validateInputContext = validateInputContext;
+    this.outputContextSchema = outputSchema;
+    this.validateOutputContext = validateOutputContext;
+    if (getTagCallback) {
+      this.getTag = (context) => getTagCallback(context, this);
+      this.throttled = true;
+    }
     if (register) {
       this.emit("meta.task.created", { __task: this });
     }
@@ -1228,6 +1263,169 @@ var Task = class extends SignalParticipant {
   setProgressWeight(weight) {
     this.progressWeight = weight;
   }
+  setInputContextSchema(schema) {
+    this.inputContextSchema = schema;
+  }
+  setOutputContextSchema(schema) {
+    this.outputContextSchema = schema;
+  }
+  setValidateInputContext(value) {
+    this.validateInputContext = value;
+  }
+  setValidateOutputContext(value) {
+    this.validateOutputContext = value;
+  }
+  /**
+   * Validates a context deeply against a schema.
+   * @param data - The data to validate (input context or output result).
+   * @param schema - The schema definition.
+   * @param path - The current path for error reporting (default: 'root').
+   * @returns { { valid: boolean, errors: Record<string, string> } } - Validation result with detailed errors if invalid.
+   * @description Recursively checks types, required fields, and constraints; allows extra properties not in schema.
+   */
+  validateSchema(data, schema, path = "context") {
+    const errors = {};
+    if (!schema || typeof schema !== "object") return { valid: true, errors };
+    const required = schema.required || [];
+    for (const key of required) {
+      if (!(key in data)) {
+        errors[`${path}.${key}`] = `Required field '${key}' is missing`;
+      }
+    }
+    const properties = schema.properties || {};
+    for (const [key, value] of Object.entries(data)) {
+      if (key in properties) {
+        const prop = properties[key];
+        const propType = prop.type;
+        if (propType === "string" && typeof value !== "string") {
+          errors[`${path}.${key}`] = `Expected 'string' for '${key}', got '${typeof value}'`;
+        } else if (propType === "number" && typeof value !== "number") {
+          errors[`${path}.${key}`] = `Expected 'number' for '${key}', got '${typeof value}'`;
+        } else if (propType === "boolean" && typeof value !== "boolean") {
+          errors[`${path}.${key}`] = `Expected 'boolean' for '${key}', got '${typeof value}'`;
+        } else if (propType === "array" && !Array.isArray(value)) {
+          errors[`${path}.${key}`] = `Expected 'array' for '${key}', got '${typeof value}'`;
+        } else if (propType === "object" && (typeof value !== "object" || value === null || Array.isArray(value))) {
+          errors[`${path}.${key}`] = `Expected 'object' for '${key}', got '${typeof value}'`;
+        } else if (propType === "array" && prop.items) {
+          if (Array.isArray(value)) {
+            value.forEach((item, index) => {
+              const subValidation = this.validateSchema(
+                item,
+                prop.items,
+                `${path}.${key}[${index}]`
+              );
+              if (!subValidation.valid) {
+                Object.assign(errors, subValidation.errors);
+              }
+            });
+          }
+        } else if (propType === "object" && !Array.isArray(value) && value !== null) {
+          const subValidation = this.validateSchema(
+            value,
+            prop,
+            `${path}.${key}`
+          );
+          if (!subValidation.valid) {
+            Object.assign(errors, subValidation.errors);
+          }
+        }
+        const constraints = prop.constraints || {};
+        if (typeof value === "string") {
+          if (constraints.minLength && value.length < constraints.minLength) {
+            errors[`${path}.${key}`] = `String '${key}' shorter than minLength ${constraints.minLength}`;
+          }
+          if (constraints.maxLength && value.length > constraints.maxLength) {
+            errors[`${path}.${key}`] = `String '${key}' exceeds maxLength ${constraints.maxLength}`;
+          }
+          if (constraints.pattern && !new RegExp(constraints.pattern).test(value)) {
+            errors[`${path}.${key}`] = `String '${key}' does not match pattern ${constraints.pattern}`;
+          }
+        } else if (typeof value === "number") {
+          if (constraints.min && value < constraints.min) {
+            errors[`${path}.${key}`] = `Number '${key}' below min ${constraints.min}`;
+          }
+          if (constraints.max && value > constraints.max) {
+            errors[`${path}.${key}`] = `Number '${key}' exceeds max ${constraints.max}`;
+          }
+          if (constraints.multipleOf && value % constraints.multipleOf !== 0) {
+            errors[`${path}.${key}`] = `Number '${key}' not multiple of ${constraints.multipleOf}`;
+          }
+        } else if (constraints.enum && !constraints.enum.includes(value)) {
+          errors[`${path}.${key}`] = `Value '${value}' for '${key}' not in enum ${JSON.stringify(constraints.enum)}`;
+        } else if (constraints.format) {
+          const formats = {
+            email: /^[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}$/,
+            url: /^(https?|ftp):\/\/[^\s/$.?#].[^\s]*$/,
+            "date-time": /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(\.\d+)?(Z|[+-]\d{2}:\d{2})?$/,
+            uuid: /^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$/,
+            custom: /.*/
+            // Placeholder; override with prop.constraints.pattern if present
+          };
+          const regex = formats[constraints.format] || new RegExp(constraints.pattern || ".*");
+          if (typeof value === "string" && !regex.test(value)) {
+            errors[`${path}.${key}`] = `Value '${value}' for '${key}' does not match format '${constraints.format}'`;
+          }
+        } else if (constraints.oneOf && !constraints.oneOf.includes(value)) {
+          errors[`${path}.${key}`] = `Value '${value}' for '${key}' not in oneOf ${JSON.stringify(constraints.oneOf)}`;
+        }
+      }
+    }
+    if (Object.keys(errors).length > 0) {
+      return { valid: false, errors };
+    }
+    return { valid: true, errors: {} };
+  }
+  validateInput(context) {
+    if (this.validateInputContext) {
+      const validationResult = this.validateSchema(
+        context,
+        this.inputContextSchema
+      );
+      if (!validationResult.valid) {
+        this.emit("meta.task.validationFailed", {
+          __taskId: this.id,
+          __context: context,
+          __errors: validationResult.errors
+        });
+        return {
+          errored: true,
+          __error: "Input context validation failed",
+          __validationErrors: JSON.stringify(validationResult.errors)
+        };
+      }
+    }
+    return true;
+  }
+  validateOutput(context) {
+    if (this.validateOutputContext) {
+      const validationResult = this.validateSchema(
+        context,
+        this.outputContextSchema
+      );
+      if (!validationResult.valid) {
+        this.emit("meta.task.outputValidationFailed", {
+          __taskId: this.id,
+          __result: context,
+          __errors: validationResult.errors
+        });
+        return {
+          errored: true,
+          __error: "Output context validation failed",
+          __validationErrors: JSON.stringify(validationResult.errors)
+        };
+      }
+    }
+    return true;
+  }
+  /**
+   * Executes the task function after optional input validation.
+   * @param context - The GraphContext to validate and execute.
+   * @param progressCallback - Callback for progress updates.
+   * @returns TaskResult from the taskFunction or error object on validation failure.
+   * @edge If validateInputContext is true, validates context; on failure, emits 'meta.task.validationFailed' with detailed errors.
+   * @edge If validateOutputContext is true, validates output; on failure, emits 'meta.task.outputValidationFailed' with detailed errors.
+   */
   execute(context, progressCallback) {
     return this.taskFunction(context.getClonedContext(), progressCallback);
   }
@@ -1375,6 +1573,10 @@ var Task = class extends SignalParticipant {
       __timeout: this.timeout,
       __functionString: this.taskFunction.toString(),
       __getTagCallback: this.getTag.toString(),
+      __inputSchema: this.inputContextSchema,
+      __validateInputContext: this.validateInputContext,
+      __outputSchema: this.outputContextSchema,
+      __validateOutputContext: this.validateOutputContext,
       __nextTasks: Array.from(this.nextTasks).map((t) => t.id),
       __onFailTasks: Array.from(this.onFailTasks).map((t) => t.id),
       __previousTasks: Array.from(this.predecessorTasks).map((t) => t.id)
@@ -1602,7 +1804,7 @@ var GraphRunner = class extends SignalEmitter {
    * @edge Emits 'meta.runner.added_tasks' with metadata.
    * @edge Empty tasks warns no-op.
    */
-  addTasks(tasks, context) {
+  addTasks(tasks, context = {}) {
     var _a, _b, _c, _d, _e, _f;
     let _tasks = Array.isArray(tasks) ? tasks : [tasks];
     if (_tasks.length === 0) {
@@ -1708,27 +1910,9 @@ var GraphRunner = class extends SignalEmitter {
   }
 };
 
-// src/graph/definition/ThrottledTask.ts
-var ThrottledTask = class extends Task {
-  constructor(name, task, description = "", getTagCallback = (context, task2) => "default", concurrency = 1, timeout = 0, register = true, isUnique = false, isMeta = false) {
-    super(
-      name,
-      task,
-      description,
-      concurrency,
-      timeout,
-      register,
-      isUnique,
-      isMeta
-    );
-    this.throttled = true;
-    this.getTag = (context) => getTagCallback(context, this);
-  }
-};
-
 // src/graph/definition/DebounceTask.ts
 var DebounceTask = class extends Task {
-  constructor(name, task, description = "", debounceTime = 1e3, leading = false, trailing = true, concurrency = 0, timeout = 0, register = true, isUnique = false, isMeta = false) {
+  constructor(name, task, description = "", debounceTime = 1e3, leading = false, trailing = true, concurrency = 0, timeout = 0, register = true, isUnique = false, isMeta = false, inputSchema = void 0, validateInputSchema = false, outputSchema = void 0, validateOutputSchema = false) {
     super(
       name,
       task,
@@ -1737,7 +1921,12 @@ var DebounceTask = class extends Task {
       timeout,
       register,
       isUnique,
-      isMeta
+      isMeta,
+      void 0,
+      inputSchema,
+      validateInputSchema,
+      outputSchema,
+      validateOutputSchema
     );
     this.timer = null;
     this.lastResolve = null;
@@ -1809,7 +1998,7 @@ var DebounceTask = class extends Task {
 
 // src/graph/definition/EphemeralTask.ts
 var EphemeralTask = class extends Task {
-  constructor(name, task, description = "", once = true, condition = () => true, concurrency = 0, timeout = 0, register = false, isUnique = false, isMeta = false) {
+  constructor(name, task, description = "", once = true, condition = () => true, concurrency = 0, timeout = 0, register = false, isUnique = false, isMeta = false, getTagCallback = void 0, inputSchema = void 0, validateInputContext = false, outputSchema = void 0, validateOutputContext = false) {
     super(
       name,
       task,
@@ -1818,7 +2007,12 @@ var EphemeralTask = class extends Task {
       timeout,
       register,
       isUnique,
-      isMeta
+      isMeta,
+      getTagCallback,
+      inputSchema,
+      validateInputContext,
+      outputSchema,
+      validateOutputContext
     );
     this.isEphemeral = true;
     this.once = once;
@@ -2384,7 +2578,12 @@ var Cadenza = class {
     timeout: 0,
     register: true,
     isUnique: false,
-    isMeta: false
+    isMeta: false,
+    getTagCallback: void 0,
+    inputSchema: void 0,
+    validateInputContext: false,
+    outputSchema: void 0,
+    validateOutputContext: false
   }) {
     this.bootstrap();
     this.validateName(name);
@@ -2396,7 +2595,12 @@ var Cadenza = class {
       options.timeout,
       options.register,
       options.isUnique,
-      options.isMeta
+      options.isMeta,
+      options.getTagCallback,
+      options.inputSchema,
+      options.validateInputContext,
+      options.outputSchema,
+      options.validateOutputContext
     );
   }
   /**
@@ -2414,7 +2618,12 @@ var Cadenza = class {
     timeout: 0,
     register: true,
     isUnique: false,
-    isMeta: true
+    isMeta: true,
+    getTagCallback: void 0,
+    inputSchema: void 0,
+    validateInputContext: false,
+    outputSchema: void 0,
+    validateOutputContext: false
   }) {
     options.isMeta = true;
     return this.createTask(name, func, description, options);
@@ -2434,7 +2643,12 @@ var Cadenza = class {
     timeout: 0,
     register: true,
     isUnique: true,
-    isMeta: false
+    isMeta: false,
+    getTagCallback: void 0,
+    inputSchema: void 0,
+    validateInputContext: false,
+    outputSchema: void 0,
+    validateOutputContext: false
   }) {
     options.isUnique = true;
     return this.createTask(name, func, description, options);
@@ -2452,7 +2666,12 @@ var Cadenza = class {
     timeout: 0,
     register: true,
     isUnique: true,
-    isMeta: true
+    isMeta: true,
+    getTagCallback: void 0,
+    inputSchema: void 0,
+    validateInputContext: false,
+    outputSchema: void 0,
+    validateOutputContext: false
   }) {
     options.isMeta = true;
     return this.createUniqueTask(name, func, description, options);
@@ -2467,26 +2686,19 @@ var Cadenza = class {
    * @returns The created ThrottledTask.
    * @edge If no getter, throttles per task ID; use for resource protection.
    */
-  static createThrottledTask(name, func, throttledIdGetter, description, options = {
+  static createThrottledTask(name, func, throttledIdGetter = () => "default", description, options = {
     concurrency: 1,
     timeout: 0,
     register: true,
     isUnique: false,
-    isMeta: false
+    isMeta: false,
+    inputSchema: void 0,
+    validateInputContext: false,
+    outputSchema: void 0,
+    validateOutputContext: false
   }) {
-    this.bootstrap();
-    this.validateName(name);
-    return new ThrottledTask(
-      name,
-      func,
-      description,
-      throttledIdGetter,
-      options.concurrency,
-      options.timeout,
-      options.register,
-      options.isUnique,
-      options.isMeta
-    );
+    options.getTagCallback = throttledIdGetter;
+    return this.createTask(name, func, description, options);
   }
   /**
    * Creates a ThrottledMetaTask for meta-layer throttling.
@@ -2502,7 +2714,11 @@ var Cadenza = class {
     timeout: 0,
     register: true,
     isUnique: false,
-    isMeta: true
+    isMeta: true,
+    inputSchema: void 0,
+    validateInputContext: false,
+    outputSchema: void 0,
+    validateOutputContext: false
   }) {
     options.isMeta = true;
     return this.createThrottledTask(
@@ -2530,7 +2746,11 @@ var Cadenza = class {
     leading: false,
     trailing: true,
     isUnique: false,
-    isMeta: false
+    isMeta: false,
+    inputSchema: void 0,
+    validateInputContext: false,
+    outputSchema: void 0,
+    validateOutputContext: false
   }) {
     this.bootstrap();
     this.validateName(name);
@@ -2545,7 +2765,11 @@ var Cadenza = class {
       options.timeout,
       options.register,
       options.isUnique,
-      options.isMeta
+      options.isMeta,
+      options.inputSchema,
+      options.validateInputContext,
+      options.outputSchema,
+      options.validateOutputContext
     );
   }
   /**
@@ -2564,7 +2788,11 @@ var Cadenza = class {
     leading: false,
     trailing: true,
     isUnique: false,
-    isMeta: false
+    isMeta: false,
+    inputSchema: void 0,
+    validateInputContext: false,
+    outputSchema: void 0,
+    validateOutputContext: false
   }) {
     options.isMeta = true;
     return this.createDebounceTask(
@@ -2592,7 +2820,12 @@ var Cadenza = class {
     timeout: 0,
     register: true,
     isUnique: false,
-    isMeta: false
+    isMeta: false,
+    getTagCallback: void 0,
+    inputSchema: void 0,
+    validateInputContext: false,
+    outputSchema: void 0,
+    validateOutputContext: false
   }) {
     this.bootstrap();
     this.validateName(name);
@@ -2606,7 +2839,12 @@ var Cadenza = class {
       options.timeout,
       options.register,
       options.isUnique,
-      options.isMeta
+      options.isMeta,
+      options.getTagCallback,
+      options.inputSchema,
+      options.validateInputContext,
+      options.outputSchema,
+      options.validateOutputContext
     );
   }
   /**
@@ -2622,7 +2860,14 @@ var Cadenza = class {
   static createEphemeralMetaTask(name, func, description, once = true, destroyCondition = () => true, options = {
     concurrency: 0,
     timeout: 0,
-    register: true
+    register: true,
+    isUnique: false,
+    isMeta: true,
+    getTagCallback: void 0,
+    inputSchema: void 0,
+    validateInputContext: false,
+    outputSchema: void 0,
+    validateOutputContext: false
   }) {
     options.isMeta = true;
     return this.createEphemeralTask(
@@ -2681,14 +2926,6 @@ var SignalTask = class extends Task {
   }
 };
 
-// src/graph/definition/UniqueTask.ts
-var UniqueTask = class extends Task {
-  constructor() {
-    super(...arguments);
-    this.isUnique = true;
-  }
-};
-
 // src/index.ts
 var index_default = Cadenza;
 // Annotate the CommonJS export names for ESM import in node:
@@ -2702,8 +2939,6 @@ var index_default = Cadenza;
   SignalEmitter,
   SignalParticipant,
   SignalTask,
-  Task,
-  ThrottledTask,
-  UniqueTask
+  Task
 });
 //# sourceMappingURL=index.js.map