@vaudience/aigentflow-flow-validator 0.21.0 → 0.23.0

package/dist/index.js

@@ -433,7 +433,7 @@ function validateBasicStructure(flow, issues) {
           message: "Executor is required for each step",
           code: "missing_required_field",
           stepId: stepID,
-          suggestion: "Specify an executor URL (e.g., 'function://demo/processor')"
+          suggestion: "Specify an executor URL (e.g., 'function://utils/log')"
         });
       } else if (executorText === null) {
         issues.error({
@@ -449,7 +449,7 @@ function validateBasicStructure(flow, issues) {
 
 // src/spec/aigentflow-spec.json
 var aigentflow_spec_default = {
-  specVersion: "2.827.0",
+  specVersion: "2.831.0",
   inputSchemaVersion: 1,
   executorSchemes: [
     "a2a",
@@ -946,6 +946,73 @@ var aigentflow_spec_default = {
     stepFieldFormat: "steps.%s.query.%s",
     loopStepFieldFormat: "steps.%s.loop.steps.%s.query.%s"
   },
+  functionOperations: {
+    code: "unknown_function_operation",
+    scheme: "function",
+    messageFormat: "step %s uses function://%s, which is not a built-in function. Available: %s",
+    suggestionFormat: "Use one of the built-in function operations: %s. For custom logic use a script://, http:// or ai:// executor instead.",
+    operations: [
+      "binary-processor/validate-and-store",
+      "data/create",
+      "data/from-json",
+      "data/to-json",
+      "data/validate",
+      "demo/adult-processor",
+      "demo/calculator",
+      "demo/data-processor",
+      "demo/finalizer",
+      "demo/senior-processor",
+      "demo/youth-processor",
+      "document/finalize",
+      "document/prepare",
+      "json/validate",
+      "math/basic",
+      "math/calculate",
+      "math/sum",
+      "results-compiler/aggregate",
+      "system/info",
+      "text/analysis",
+      "text/count-characters",
+      "text/count-lines",
+      "text/count-occurrences",
+      "text/count-words",
+      "text/find-pattern",
+      "text/generate",
+      "text/replace-text",
+      "text/search",
+      "utils/datetime",
+      "utils/format-date",
+      "utils/log",
+      "utils/parse-date"
+    ]
+  },
+  flowDataReservedKeys: {
+    code: "flow_data_key_reserved",
+    fieldFormat: "data.%s",
+    messageFormat: "data: key %s is reserved: %s. It would write into the engine's own state, so it is not seeded.",
+    suggestion: "Rename the key (no leading `_` or `.`, and not one of the engine namespaces memory., orchestrator., campaign., voiceagent.).",
+    exact: {
+      org_id: "the mission's organization, set by the engine for Thalamus/Engram calls",
+      memory: "the memory scope namespace",
+      orchestrator: "the orchestrator's state namespace",
+      campaign: "the campaign's state namespace",
+      voiceagent: "the voice agent's state namespace",
+      current_flow: "engine bookkeeping (the current flow definition)",
+      modified_flow: "engine bookkeeping (dynamic flow modification)",
+      modification_history: "engine bookkeeping (dynamic flow modification)",
+      modification_pending: "engine bookkeeping (dynamic flow modification)",
+      modification_requests: "engine bookkeeping (dynamic flow modification)",
+      bottleneck_state: "engine bookkeeping (bottleneck analysis)"
+    },
+    prefixes: [
+      { prefix: "_", reason: "keys starting with `_` are engine bookkeeping (current flow, loop and for_each context, taint lists such as `__untrusted_*`)" },
+      { prefix: ".", reason: "keys starting with `.` are engine step-response slots" },
+      { prefix: "memory.", reason: "the `memory.` namespace belongs to the engine" },
+      { prefix: "orchestrator.", reason: "the `orchestrator.` namespace belongs to the orchestrator" },
+      { prefix: "campaign.", reason: "the `campaign.` namespace belongs to the campaign engine" },
+      { prefix: "voiceagent.", reason: "the `voiceagent.` namespace belongs to the voice agent" }
+    ]
+  },
   credentialEndpointPairing: {
     stepFieldFormat: "steps.%s.query.%s",
     loopStepFieldFormat: "steps.%s.loop.steps.%s.query.%s",
@@ -1883,6 +1950,14 @@ var SERVER_OWNED_QUERY_KEYS = {
   stepFieldFormat: aigentflow_spec_default.serverOwnedQueryKeys.stepFieldFormat,
   loopStepFieldFormat: aigentflow_spec_default.serverOwnedQueryKeys.loopStepFieldFormat
 };
+var FLOW_DATA_RESERVED_KEYS = {
+  code: aigentflow_spec_default.flowDataReservedKeys.code,
+  fieldFormat: aigentflow_spec_default.flowDataReservedKeys.fieldFormat,
+  messageFormat: aigentflow_spec_default.flowDataReservedKeys.messageFormat,
+  suggestion: aigentflow_spec_default.flowDataReservedKeys.suggestion,
+  exact: aigentflow_spec_default.flowDataReservedKeys.exact,
+  prefixes: aigentflow_spec_default.flowDataReservedKeys.prefixes
+};
 var CREDENTIAL_ENDPOINT_PAIRING = {
   stepFieldFormat: aigentflow_spec_default.credentialEndpointPairing.stepFieldFormat,
   loopStepFieldFormat: aigentflow_spec_default.credentialEndpointPairing.loopStepFieldFormat,
@@ -1945,9 +2020,51 @@ var TEMPLATE_DEFAULT_PIPED = {
   messageFormat: aigentflow_spec_default.templateDefaultPiped.messageFormat,
   suggestion: aigentflow_spec_default.templateDefaultPiped.suggestion
 };
+var FUNCTION_OPERATIONS = {
+  code: aigentflow_spec_default.functionOperations.code,
+  scheme: aigentflow_spec_default.functionOperations.scheme,
+  messageFormat: aigentflow_spec_default.functionOperations.messageFormat,
+  suggestionFormat: aigentflow_spec_default.functionOperations.suggestionFormat,
+  operations: new Set(aigentflow_spec_default.functionOperations.operations),
+  sorted: aigentflow_spec_default.functionOperations.operations
+};
 
 // src/validators/executors.ts
 var SCHEME_SEPARATOR = "://";
+var UNKNOWN_SCHEME_BASE = (scheme) => `Unknown executor scheme '${scheme}'. It may be valid in a newer AIgentFlow release, or it could be a typo.`;
+var DECIDE_SCHEME = "decide";
+var DECIDE_HINT = "Decision models run through ai://{provider}/decide (for example ai://openai/decide), not through a scheme of their own.";
+var MAX_SCHEME_EDIT_DISTANCE = 2;
+function editDistance(a, b) {
+  let prev = Array.from({ length: b.length + 1 }, (_, j) => j);
+  for (let i = 1; i <= a.length; i++) {
+    const cur = [i];
+    for (let j = 1; j <= b.length; j++) {
+      cur[j] = Math.min(
+        prev[j] + 1,
+        cur[j - 1] + 1,
+        prev[j - 1] + (a[i - 1] === b[j - 1] ? 0 : 1)
+      );
+    }
+    prev = cur;
+  }
+  return prev[b.length];
+}
+function unknownSchemeMessage(scheme) {
+  const lower = scheme.toLowerCase();
+  const base = UNKNOWN_SCHEME_BASE(scheme);
+  if (lower === DECIDE_SCHEME) return `${base} ${DECIDE_HINT}`;
+  let best;
+  let bestDist = MAX_SCHEME_EDIT_DISTANCE + 1;
+  for (const known of [...EXECUTOR_SCHEMES].sort()) {
+    const d = editDistance(lower, known);
+    if (d < bestDist) {
+      best = known;
+      bestDist = d;
+    }
+  }
+  return best === void 0 ? base : `${base} Did you mean '${best}'?`;
+}
 function checkExecutor(executor, field, stepID, issues) {
   const sepIdx = executor.indexOf(SCHEME_SEPARATOR);
   const scheme = sepIdx > 0 ? executor.slice(0, sepIdx) : "";
@@ -1966,11 +2083,28 @@ function checkExecutor(executor, field, stepID, issues) {
   if (!EXECUTOR_SCHEMES.has(scheme.toLowerCase())) {
     issues.warn({
       field,
-      message: `Unknown executor scheme '${scheme}'. It may be valid in a newer AIgentFlow release, or it could be a typo.`,
+      message: unknownSchemeMessage(scheme),
       code: "unknown_executor_scheme",
       stepId: stepID
     });
+    return;
   }
+  checkFunctionOperation(executor, field, stepID, templated, issues);
+}
+function checkFunctionOperation(executor, field, stepID, templated, issues) {
+  if (templated) return;
+  const m = EXECUTOR_URL_PATTERN.exec(executor);
+  if (m === null || m[1] !== FUNCTION_OPERATIONS.scheme) return;
+  const op = `${m[2]}/${m[3]}`;
+  if (FUNCTION_OPERATIONS.operations.has(op)) return;
+  const list = FUNCTION_OPERATIONS.sorted.join(", ");
+  issues.error({
+    field,
+    message: FUNCTION_OPERATIONS.messageFormat.replace("%s", () => JSON.stringify(stepID)).replace("%s", () => op).replace("%s", () => list),
+    code: FUNCTION_OPERATIONS.code,
+    stepId: stepID,
+    suggestion: FUNCTION_OPERATIONS.suggestionFormat.replace("%s", () => list)
+  });
 }
 function validateExecutors(flow, issues) {
   const steps = flow.steps;
@@ -3802,16 +3936,16 @@ function skipSpaces(src, idx) {
   }
   return i;
 }
-function scanString(src, start, quote) {
+function scanString(src, start, quote2) {
   let i = start + 1;
-  const raw = quote === "`";
+  const raw = quote2 === "`";
   while (i < src.length) {
     const c = src[i];
     if (!raw && c === "\\") {
       i += 2;
       continue;
     }
-    if (c === quote) return i;
+    if (c === quote2) return i;
     i += 1;
   }
   return -1;
@@ -4414,6 +4548,35 @@ function validateRetiredKeys(flow, issues) {
   }
 }
 
+// src/validators/flowDataKeys.ts
+var KEY_DATA = "data";
+function quote(key) {
+  return JSON.stringify(key);
+}
+function flowDataKeyReservation(key) {
+  if (Object.prototype.hasOwnProperty.call(FLOW_DATA_RESERVED_KEYS.exact, key)) {
+    return FLOW_DATA_RESERVED_KEYS.exact[key];
+  }
+  for (const p of FLOW_DATA_RESERVED_KEYS.prefixes) {
+    if (key.startsWith(p.prefix)) return p.reason;
+  }
+  return void 0;
+}
+function validateFlowDataKeys(flow, issues) {
+  const data = flow[KEY_DATA];
+  if (!isRecord(data)) return;
+  for (const key of Object.keys(data).sort()) {
+    const reason = flowDataKeyReservation(key);
+    if (reason === void 0) continue;
+    issues.error({
+      field: FLOW_DATA_RESERVED_KEYS.fieldFormat.replace("%s", () => key),
+      message: FLOW_DATA_RESERVED_KEYS.messageFormat.replace("%s", () => quote(key)).replace("%s", () => reason),
+      code: FLOW_DATA_RESERVED_KEYS.code,
+      suggestion: FLOW_DATA_RESERVED_KEYS.suggestion
+    });
+  }
+}
+
 // src/validators/saveDoor.ts
 var TOOL_DISCOVERY_MODES = /* @__PURE__ */ new Set(["eager", "lazy", "off"]);
 var TEMPLATE_ACTION_OPEN2 = "{{";
@@ -6876,6 +7039,7 @@ function validateParsed(flow, opts, sources) {
   validateSaveDoorExtras(f, issues);
   validateExecutorConfigEnvScopes(f, issues);
   validateServerOwnedQueryKeys(f, issues);
+  validateFlowDataKeys(f, issues);
   validateCredentialEndpointPairing(f, issues);
   validateExamples(f, issues);
   validateOrchestratorExons(f, issues);