@vaudience/aigentflow-flow-validator 0.21.0 → 0.23.0

package/PARITY.md

@@ -4,7 +4,57 @@ This document maps every rule in this JavaScript validator back to the AIgentFlo
 Go reference implementation, records the intentional divergences, and defines the
 discipline for keeping the two in sync.
 
-**Tracks AIgentFlow flow schema: `v2.827.0`** (`SPEC_VERSION` in [`src/spec/aigentflow-spec.json`](./src/spec/aigentflow-spec.json)), which adds the `here` executor scheme, the `strict_templates` flow key and the rule `template_default_piped` (package 0.21.0, below). Earlier: the warning `compliance_residency_unenforced` (package 0.20.0). `orchestrator.region` / `orchestrator.enforce_region` (package 0.19.0). Earlier: the AigentChat executor was removed (package 0.18.0). Earlier additions: the `examples:` block (package 0.17.0), `server_owned_query_key` (package 0.15.1) from the AIgentFlow release after v2.790.0, `credential_endpoint_unpaired` (package 0.15.2) from AIgentFlow v2.793.0 and the release after it, and `display_name_too_long` (package 0.15.3) from AIgentFlow v2.802.0.
+**Tracks AIgentFlow flow schema: `v2.831.0`** (`SPEC_VERSION` in [`src/spec/aigentflow-spec.json`](./src/spec/aigentflow-spec.json)), which adds the rule `unknown_function_operation` and a clearer `unknown_executor_scheme` message (package 0.23.0, below). Earlier: the rule `flow_data_key_reserved` (package 0.22.0). Earlier: the `here` executor scheme, the `strict_templates` flow key and the rule `template_default_piped` (package 0.21.0). Earlier: the warning `compliance_residency_unenforced` (package 0.20.0). `orchestrator.region` / `orchestrator.enforce_region` (package 0.19.0). Earlier: the AigentChat executor was removed (package 0.18.0). Earlier additions: the `examples:` block (package 0.17.0), `server_owned_query_key` (package 0.15.1) from the AIgentFlow release after v2.790.0, `credential_endpoint_unpaired` (package 0.15.2) from AIgentFlow v2.793.0 and the release after it, and `display_name_too_long` (package 0.15.3) from AIgentFlow v2.802.0.
+
+> package 0.23.0 — **`unknown_function_operation`**, in step with the reference (AIgentFlow
+> v2.831.0; `specVersion` 2.831.0). One new **error**: a step or loop sub-step whose executor
+> is `function://<a>/<b>` where `<a>/<b>` is not one of the 32 registered built-ins. Before
+> this, `function://utils/noop` validated and then failed every run with "function
+> 'utils/noop' not found".
+>
+> | Rule (reference)                             | Code                         | Severity | Module                                               |
+> | -------------------------------------------- | ---------------------------- | -------- | ---------------------------------------------------- |
+> | `validateFunctionOperationKnown` (parser.go) | `unknown_function_operation` | error    | `validators/executors.ts`, spec `functionOperations` |
+>
+> - **Operation** = authority + `/` + path of the executor URL (so `binary-processor/validate-and-store`).
+>   The set is closed and sorted in spec `functionOperations.operations`. Templated executors
+>   (containing `{{`), unparsable URLs (`invalid_executor_url` owns them) and other schemes are
+>   skipped; the scheme match is exact and case-sensitive.
+> - **Finding.** Field `steps.<id>.executor` (loop sub-step: `steps.<id>.loop.steps[i].executor`,
+>   step id `<id>.<sub>`); message `step "<id>" uses function://<op>, which is not a built-in
+function. Available: <sorted list, ", ">`; the suggestion carries the list.
+> - **Divergence 23** (below): the reference tolerates this code on its load door.
+> - **`unknown_executor_scheme` text (still a warning).** For `decide` the message appends
+>   `Decision models run through ai://{provider}/decide (for example ai://openai/decide), not
+through a scheme of their own.`; for any other unknown scheme with a known scheme within
+>   edit distance 2 (case-insensitive; the closest, ties to the alphabetically first) it
+>   appends `Did you mean '<scheme>'?`. No verdict changes.
+
+> package 0.22.0 — **`flow_data_key_reserved`**, in step with the reference (AIgentFlow
+> v2.828.0; `specVersion` 2.828.0). One new **error**: a key of the top-level `data:` map
+> may not name engine state. `data:` is seeded into the mission's `.data` namespace, which
+> is also where the engine keeps its own bookkeeping, so a flow declaring such a key would
+> pre-seed or forge it (a taint list, the current flow, the mission's organization).
+>
+> | Rule (reference)                                               | Code                     | Severity | Module                                                    |
+> | -------------------------------------------------------------- | ------------------------ | -------- | --------------------------------------------------------- |
+> | `FlowDataKeyReservation`, `validateFlowDataKeysAreNotReserved` | `flow_data_key_reserved` | error    | `validators/flowDataKeys.ts`, spec `flowDataReservedKeys` |
+>
+> - **Reserved** (exact, case-sensitive; spec `flowDataReservedKeys`): `memory`,
+>   `orchestrator`, `campaign`, `voiceagent`, `org_id`, `current_flow`, `modified_flow`,
+>   `modification_history`, `modification_pending`, `modification_requests`,
+>   `bottleneck_state`; or a key starting with `_`, `.`, `memory.`, `orchestrator.`,
+>   `campaign.` or `voiceagent.`. Each carries the reference's reason. A key that merely
+>   contains a reserved word (`memory_notes`, `orgid`, `my_memory`) or differs in case is legal.
+> - **Finding.** Field `data.<key>`, one per key, sorted by key; the message is the
+>   reference's `data: key "<key>" is reserved: <reason>. It would write into the engine's
+own state, so it is not seeded.` and the suggestion its text (spec keys `messageFormat`,
+>   `suggestion`). There is no loop-body twin, so no demotion.
+> - **Divergence from the reference's run door.** The reference tolerates this code when a
+>   stored flow is _run_ (the key is skipped, the flow still runs) and refuses it at save.
+>   This validator answers "would this save", so it is an error here, as for every other
+>   save-door rule. Key order is JavaScript's UTF-16 code-unit order, Go's is byte order;
+>   they differ only for keys with characters outside the Basic Multilingual Plane.
 
 > package 0.21.0 — **`here://`, `strict_templates` and `template_default_piped`**, in step
 > with the reference (AIgentFlow v2.827.0; `specVersion` 2.827.0). Three changes.
@@ -1084,6 +1134,8 @@ Comparison contract: **error `code` + `valid` verdict**, not message wording. Th
 | `tool_discovery` vocabulary, mock scenario `delay`, empty `output:` entry                                               | `validateToolDiscoveryVocabulary`, `validateMockScenarioDelays`, `validateOutputParameters` (parser.go) | `validators/saveDoor.ts`                                  | `validate.test.ts`, `conformance.test.ts`                     |
 | `executor_config` `${NAME}` references outside the key's scope (`executor_config_env_scope`)                            | `ValidateExecutorConfigEnvScopes` (parser.go)                                                           | `validators/executorConfigEnv.ts`                         | `v0150-save-door.test.ts`, `conformance.test.ts`              |
 | A step or loop sub-step `query:` declaring a server-owned key (`server_owned_query_key`)                                | `validateNoServerOwnedStepQueryKeys` (validation.go), `IsServerOwnedParamKey`                           | `validators/serverOwnedQueryKeys.ts`                      | `v0151-save-door.test.ts`, `conformance.test.ts`              |
+| A `function://` operation outside the built-in set (`unknown_function_operation`)                                       | `validateFunctionOperationKnown` (parser.go)                                                            | `validators/executors.ts`                                 | `v0230-function-operation.test.ts`, `conformance.test.ts`     |
+| A top-level `data:` key naming engine state (`flow_data_key_reserved`)                                                  | `FlowDataKeyReservation`, `validateFlowDataKeysAreNotReserved` (validation.flowdata.go)                 | `validators/flowDataKeys.ts`                              | `v0220-flow-data-keys.test.ts`, `conformance.test.ts`         |
 | An endpoint a server-supplied credential will never be sent to (`credential_endpoint_unpaired`, warning)                | `validateCredentialEndpointPairing`, `validateFamilyCredentialEndpointPairing` (validation.go)          | `validators/credentialEndpoint.ts`, `validators/goUrl.ts` | `v0152-credential-endpoint.test.ts`, `conformance.test.ts`    |
 | The `examples:` block: 58 codes, one walker (ids, inputs, references, expectations, checkpoints, variants)              | the examples walker (`ValidateExamples`)                                                                | `validators/examples.ts`, `validators/goUrl.ts`           | `examples.test.ts`, `conformance.test.ts`                     |
 | Orchestrator `.exons` frontmatter: spec, provider, `requirements.resources`, `tools.allow` withholds                    | `validateOrchestrator` (parser.go), `validateOrchestratorToolAllowWithholds`                            | `validators/exons.ts`                                     | `v0150-save-door.test.ts`, `conformance.test.ts`              |
@@ -1353,6 +1405,11 @@ number their shared divergences alike._
     - The recursion bound of 32 on a nested value is the reference's own and is not in the
       spec.
 
+23. **`unknown_function_operation` is tolerated on the reference's load door (0.23.0).** The
+    reference refuses an unknown `function://` operation when a flow is _saved_ but loads
+    (and then fails at run time) a stored flow that already carries one. This validator
+    answers "would this save", so it is an error here, as for every other save-door rule.
+
 ---
 
 ## The examples block

package/README.md

@@ -116,7 +116,7 @@ Low-level: parse YAML into `{ flow?, parseErrors, parseWarnings }` without valid
 
 ### `SPEC_VERSION: string`
 
-The AIgentFlow flow-schema version this build tracks (e.g. `"2.827.0"`).
+The AIgentFlow flow-schema version this build tracks (e.g. `"2.831.0"`).
 
 ### Options
 
@@ -174,6 +174,7 @@ interface ValidationIssue {
 - **Orchestrator `.exons` frontmatter** — the document must open with a closed `---` frontmatter spec (`orchestrator_exons_parse_failed`) that sets `execution.provider` (`orchestrator_exons_no_provider`) and declares no `requirements.resources` (`exons_resources_unhonoured`); a tool that `orchestrator.tools` and the definition's `tools.allow` disagree about is never offered (`orchestrator_tool_withheld`, warning). The document body is not parsed: that needs the `.exons` engine (see PARITY.md).
 - **`executor_config` environment references** — a `${NAME}` value may name only the variables of the provider or protocol it is written under (`executor_config_env_scope`).
 - **Server-owned query keys** — a step's or loop sub-step's `query:` may not declare `aiv_api_key`, `aiv_base_url` or `aiv_delegation`, which only the server sets (`server_owned_query_key`).
+- **Reserved `data:` keys** — a key of the top-level `data:` map may not name engine state: `memory`, `orchestrator`, `campaign`, `voiceagent`, `org_id`, `current_flow`, the `modif*`/`bottleneck_state` bookkeeping names, a key starting with `_` or `.`, or one under `memory.`, `orchestrator.`, `campaign.`, `voiceagent.` (`flow_data_key_reserved`).
 - **Credential endpoints** — an endpoint a server-supplied credential will never be sent to (warning, `credential_endpoint_unpaired`): an `ai://` `<provider>_base_url` or a literal `executor_config.<provider>.base_url` with no key of the flow's own, a family secret that is a server `${AIGENTFLOW_…}` variable beside a literal non-default endpoint.
 - **Credential bindings** — `stored/{provider}/{name}` format, `inject_as`, `credential`/`credentials` mutual exclusion.
 - **Expression functions** — exactly one of `package`/`function`.

package/dist/cli.js

@@ -438,7 +438,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({
@@ -455,7 +455,7 @@ function validateBasicStructure(flow, issues) {
 // src/spec/aigentflow-spec.json
 var aigentflow_spec_default = {
   $comment: "Vendored enum surface mirrored from the AIgentFlow Go reference implementation. Regenerate / review on every flow-YAML schema change. See PARITY.md. Values here are public protocol/type names only.",
-  specVersion: "2.827.0",
+  specVersion: "2.831.0",
   inputSchemaVersion: 1,
   executorSchemes: [
     "a2a",
@@ -965,6 +965,75 @@ var aigentflow_spec_default = {
     stepFieldFormat: "steps.%s.query.%s",
     loopStepFieldFormat: "steps.%s.loop.steps.%s.query.%s"
   },
+  functionOperations: {
+    $comment: `unknown_function_operation (ERROR): a step or loop sub-step whose executor is function://<authority>/<path> where authority+"/"+path is not in operations. Templated executors (containing templateActionOpen), unparsable URLs (invalid_executor_url owns them) and other schemes are skipped; the scheme match is exact and case-sensitive, as in the reference. The message is messageFormat with the stepId, the operation, then operations joined by ', '. Reference: validateFunctionOperationKnown (parser.go), functionSchemaOperations.`,
+    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: {
+    $comment: "flow_data_key_reserved (ERROR, no loop demotion): a key of the top-level data: map that names engine state. data: is seeded into the mission's .data namespace, where the engine keeps its own bookkeeping, so a flow declaring such a key would forge it. Matching is exact and case-sensitive. A key is reserved when it is one of exact (each with its reason), or starts with one of prefixes (checked in order, first wins; each with its reason). The finding's field is fieldFormat with the key; the message is messageFormat with the key (JSON-quoted, as Go's %q) then the reason; the suggestion is verbatim. Findings are sorted by key. Reference: FlowDataKeyReservation, validateFlowDataKeysAreNotReserved (aigentflow#247 review).",
+    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: {
     $comment: "credential_endpoint_unpaired (WARNING, never an error): the one statically certain shape of AIgentFlow's run-time credential/endpoint pairing refusal. ai: an ai://<provider>/... step (top-level or loop sub-step) whose query holds a non-empty string <provider>+providerBaseUrlParamSuffix while neither its query (genericKeyParam or <provider>+providerKeyParamSuffix, non-empty strings) nor executor_config.<provider>.api_key (a literal, not an env reference) supplies a key; and executor_config.<provider>.base_url for a provider in executorConfigProviders when it is a literal, the block has no literal api_key, and it is not the case that at least one step uses the provider and every such step brings its own query key. keylessProviders are exempt from both. families: a step whose executor resolves (the key protocol+familyKeySeparator+driver, else protocol) to a row. implicitServerCredential rows are never judged. A row warns when its secret (the first non-empty string secretParam in the query, else per configKey in order: executor_config api_key when configApiKeyParam is a secretParam, else the first non-empty string secretParam under extra) is exactly an env reference to a serverEnv name on a row with expandsServerEnvReferences, and its endpoint (the first non-empty string endpointParam in the query, else per configKey: base_url when configBaseUrlParam is an endpointParam, else the first non-empty string endpointParam under extra) is a literal: no templateActionOpen, not an env reference, and not of the same origin as a defaultEndpoint (lower-cased scheme://host:port, defaultPorts filled). serverEnv is the reference's per-family server-variable set, evaluated. Field formats are the reference's. Reference: validateCredentialEndpointPairing (DC-FORGE-231) and validateFamilyCredentialEndpointPairing (DC-FORGE-233).",
     stepFieldFormat: "steps.%s.query.%s",
@@ -1979,6 +2048,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,
@@ -2044,9 +2121,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) : "";
@@ -2065,11 +2184,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;
@@ -3901,16 +4037,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;
@@ -4513,6 +4649,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 = "{{";
@@ -6977,6 +7142,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);

package/dist/index.cjs

@@ -435,7 +435,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({
@@ -451,7 +451,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",
@@ -948,6 +948,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",
@@ -1885,6 +1952,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,
@@ -1947,9 +2022,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) : "";
@@ -1968,11 +2085,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;
@@ -3804,16 +3938,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;
@@ -4416,6 +4550,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 = "{{";
@@ -6878,6 +7041,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);