@vaudience/aigentflow-flow-validator 0.21.0 → 0.22.0

package/dist/index.js

@@ -449,7 +449,7 @@ function validateBasicStructure(flow, issues) {
 
 // src/spec/aigentflow-spec.json
 var aigentflow_spec_default = {
-  specVersion: "2.827.0",
+  specVersion: "2.828.0",
   inputSchemaVersion: 1,
   executorSchemes: [
     "a2a",
@@ -946,6 +946,33 @@ var aigentflow_spec_default = {
     stepFieldFormat: "steps.%s.query.%s",
     loopStepFieldFormat: "steps.%s.loop.steps.%s.query.%s"
   },
+  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 +1910,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,
@@ -3802,16 +3837,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 +4449,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 +6940,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);