@vaudience/aigentflow-flow-validator 0.25.0 → 0.26.0

package/PARITY.md

@@ -6,6 +6,43 @@ discipline for keeping the two in sync.
 
 **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.26.0 — **three new rules, and the atlas rules brought in line with the reference.**
+> `reserved_input_name` (error): an input the flow declares under the top-level `query:` map, or as an
+> `input_schema` field name, that starts with two underscores. That namespace belongs to the platform
+> (the acting person, the credential manifest, the untrusted-input marker), and a value or default
+> written under such a name is never delivered. Every name the platform reserves today starts with
+> `__`; one leading underscore (`_private`) or an inner `__` (`a__b`) is an ordinary name. Fields:
+> `query.<name>` (names sorted) and `input_schema.fields.<name>` (file order), no step id. The schema
+> field is addressed by **name**, not by index like this port's other `input_schema` findings, because
+> the reference reports it that way and a host that merges several verdicts drops a finding only when
+> code and field both match. `atlas_model_not_literal` (error): an `atlas://agent/run` step whose
+> `query.model` holds a string containing `{{` anywhere (provider, model, reasoning_effort, or any
+> nested value). The model choice is fixed in the flow, never computed from input.
+> `atlas_param_refused` (error): **one** finding per atlas step listing, sorted, the `query` keys the
+> platform owns. An agent run refuses `api_key`, `attribution`, `base_url`, `host`, `idempotency_key`,
+> `org_id`, `person`, `untrusted_input`, `untrusted_input_override`, `url`, `user_id`; a capability step
+> refuses only `attribution`, `idempotency_key`, `untrusted_input`, `untrusted_input_override` (its
+> query is the tool's own arguments, so a `url` is legitimate there). The key sets live in the spec
+> block `atlasExecutor.paramRefused`; the reserved-name prefix in the new top-level block
+> `reservedInputNames`.
+>
+> _Alignments (the reference is authoritative; the old behaviour was looser)._ `agent`, `prompt` and
+> `prompt_template` are present only when they are non-empty strings **after trimming whitespace**: an
+> `agent` that is not a string (`42`) is missing, `prompt: "   "` is absent, and `prompt: ""` next to a
+> `prompt_template` is **not** `atlas_prompt_both`. The `{{` check on `capabilities` is deep (any
+> string entry or nested string) and applies to every `atlas://` step with a valid operation. The
+> capability reference pattern is now `^[A-Za-z0-9][A-Za-z0-9_-]{0,127}$` (a dot or colon is refused).
+> An `atlas://` URL that the shared executor-URL shape refuses is no longer skipped by the atlas
+> rules: it is split at the first slash after `atlas://` and judged (a reference with a dot is
+> `atlas_capability_ref_invalid`, `atlas://agent/run/extra` is `atlas_operation_unknown`); the shape's own
+> `invalid_executor_url` finding is still reported beside it. The scheme match stays exact. The
+> `atlas_agent_missing` message now ends "missing, empty or not a string". `specVersion` is unchanged
+> (`2.831.0`). Modules: `validators/executors.ts`, `validators/reservedInputs.ts`. Gates: thirteen new
+> shared fixtures (one invalid per code, the valid ones forbid every atlas code, `reserved_input_name`
+> and `unknown_executor_scheme`), byte-identical with the Go port, and
+> `test/v0260-atlas-contract.test.ts`. On the 227 bundled example flows plus the six atlas examples,
+> both ports report zero new findings and agree finding for finding (0 errors, 36 warnings).
+
 > package 0.25.0 — **the `atlas://` executor scheme and seven rules**. `atlas` becomes a known
 > scheme (no `unknown_executor_scheme` warning). The URL form is `atlas://<provider>/<resource>`:
 > provider `agent` has the single resource `run`, provider `capability` takes a capability reference

package/dist/cli.js

@@ -1008,12 +1008,12 @@ var aigentflow_spec_default = {
     ]
   },
   atlasExecutor: {
-    $comment: "atlas://<provider>/<resource>: calls into the Atlas platform. Providers are agent (the one resource is run) and capability (the resource is a capability reference). All findings are ERRORS, field = the step (loop sub-steps use the composite step id and the sub-step path). Templated executors, unparsable URLs and other schemes are skipped. A literal agent and literal capabilities keep a step from being steered by data: query.agent and every string in query.capabilities may not contain templateActionOpen, while prompt, inputs and capability args may. A message format takes the quoted step id first.",
+    $comment: "atlas://<provider>/<resource>: calls into the Atlas platform. Providers are agent (the one resource is run) and capability (the resource is a capability reference). All findings are ERRORS, field = the step (loop sub-steps use the composite step id and the sub-step path). Templated executors, unparsable URLs and other schemes are skipped. A literal agent and literal capabilities keep a step from being steered by data: query.agent and every string anywhere in query.capabilities and query.model may not contain templateActionOpen, while prompt, inputs and capability args may. agent, prompt and prompt_template count as present only when they are non-empty strings after trimming whitespace. A message format takes the quoted step id first. A URL the shared executor-URL shape refuses (a dot or colon in a reference, say) is still judged here, split at the first slash after atlas://.",
     scheme: "atlas",
     providerAgent: "agent",
     providerCapability: "capability",
     agentResource: "run",
-    capabilityRefPattern: "^[A-Za-z0-9][A-Za-z0-9_.:-]{0,127}$",
+    capabilityRefPattern: "^[A-Za-z0-9][A-Za-z0-9_-]{0,127}$",
     operationUnknown: {
       code: "atlas_operation_unknown",
       messageFormat: "step %s uses %s, which is not an Atlas operation. The providers are agent (resource run) and capability (resource: a capability reference).",
@@ -1021,7 +1021,7 @@ var aigentflow_spec_default = {
     },
     agentMissing: {
       code: "atlas_agent_missing",
-      messageFormat: "step %s runs an Atlas agent but query.agent is missing or empty.",
+      messageFormat: "step %s runs an Atlas agent but query.agent is missing, empty or not a string.",
       suggestion: "Set query.agent to the agent to run, written out as a literal such as @acme/reporter."
     },
     agentNotLiteral: {
@@ -1047,9 +1047,47 @@ var aigentflow_spec_default = {
     capabilityRefInvalid: {
       code: "atlas_capability_ref_invalid",
       messageFormat: "step %s uses atlas://capability/%s, which is not a valid capability reference.",
-      suggestion: "A capability reference starts with a letter or digit and continues with letters, digits and _ . : - up to 128 characters in all."
+      suggestion: "A capability reference starts with a letter or digit and continues with letters, digits, _ and - up to 128 characters in all."
+    },
+    modelNotLiteral: {
+      code: "atlas_model_not_literal",
+      messageFormat: "step %s computes a value of query.model from a template. The provider, model and reasoning_effort must be fixed literals, never derived from input.",
+      suggestion: "Write the model choice out as literals. Data may go into the prompt or the inputs instead."
+    },
+    paramRefused: {
+      code: "atlas_param_refused",
+      messageFormat: "step %s sets %s under query. Atlas decides these itself, so a step may not set them.",
+      suggestion: "Remove these keys from the query.",
+      agentKeys: [
+        "api_key",
+        "attribution",
+        "base_url",
+        "host",
+        "idempotency_key",
+        "org_id",
+        "person",
+        "untrusted_input",
+        "untrusted_input_override",
+        "url",
+        "user_id"
+      ],
+      capabilityKeys: [
+        "attribution",
+        "idempotency_key",
+        "untrusted_input",
+        "untrusted_input_override"
+      ]
     }
   },
+  reservedInputNames: {
+    $comment: "reserved_input_name (ERROR): an input the flow declares under the top-level query: map, or as an input_schema field name, that starts with prefix. The platform keeps that namespace for values it writes itself (the acting person, the credential manifest, the untrusted-input marker); a value or default written under such a name is never delivered. Every name the platform reserves today starts with the prefix. Matching is exact and case-sensitive: one leading underscore is an ordinary name. Findings carry no step id. queryFieldFormat takes the input name; schemaFieldFormat takes the field name as written (a non-string name is skipped). Query names are reported sorted, then schema fields in file order.",
+    prefix: "__",
+    code: "reserved_input_name",
+    messageFormat: "the input %s starts with two underscores. That namespace belongs to the platform (the acting person, the credential manifest, the untrusted-input marker): a flow cannot declare an input there, and a value or default written under such a name is never delivered.",
+    suggestion: 'Rename the input so it does not start with "__".',
+    queryFieldFormat: "query.%s",
+    schemaFieldFormat: "input_schema.fields.%s"
+  },
   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",
@@ -2186,7 +2224,23 @@ var ATLAS_EXECUTOR = {
   capabilitiesNotLiteral: atlas.capabilitiesNotLiteral,
   promptMissing: atlas.promptMissing,
   promptBoth: atlas.promptBoth,
-  capabilityRefInvalid: atlas.capabilityRefInvalid
+  capabilityRefInvalid: atlas.capabilityRefInvalid,
+  modelNotLiteral: atlas.modelNotLiteral,
+  paramRefused: {
+    code: atlas.paramRefused.code,
+    messageFormat: atlas.paramRefused.messageFormat,
+    suggestion: atlas.paramRefused.suggestion,
+    agentKeys: atlas.paramRefused.agentKeys,
+    capabilityKeys: atlas.paramRefused.capabilityKeys
+  }
+};
+var RESERVED_INPUT_NAMES = {
+  prefix: aigentflow_spec_default.reservedInputNames.prefix,
+  code: aigentflow_spec_default.reservedInputNames.code,
+  messageFormat: aigentflow_spec_default.reservedInputNames.messageFormat,
+  suggestion: aigentflow_spec_default.reservedInputNames.suggestion,
+  queryFieldFormat: aigentflow_spec_default.reservedInputNames.queryFieldFormat,
+  schemaFieldFormat: aigentflow_spec_default.reservedInputNames.schemaFieldFormat
 };
 
 // src/validators/executors.ts
@@ -2253,10 +2307,12 @@ function checkExecutor(executor, field, stepID, issues) {
 }
 function checkAtlasStep(executor, query, stepField, stepID, issues) {
   if (executor.includes(TEMPLATE_ACTION_OPEN)) return;
-  const m = EXECUTOR_URL_PATTERN.exec(executor);
-  if (m === null || m[1] !== ATLAS_EXECUTOR.scheme) return;
-  const provider = m[2];
-  const resource = m[3];
+  const prefix = `${ATLAS_EXECUTOR.scheme}://`;
+  if (!executor.startsWith(prefix)) return;
+  const rest = executor.slice(prefix.length);
+  const slash = rest.indexOf("/");
+  const provider = slash < 0 ? rest : rest.slice(0, slash);
+  const resource = slash < 0 ? "" : rest.slice(slash + 1);
   const quoted = JSON.stringify(stepID);
   const report = (rule, ...args) => {
     let message = rule.messageFormat.replace("%s", () => quoted);
@@ -2270,31 +2326,41 @@ function checkAtlasStep(executor, query, stepField, stepID, issues) {
     });
   };
   const q2 = isRecord(query) ? query : {};
+  let refusedKeys = ATLAS_EXECUTOR.paramRefused.capabilityKeys;
   if (provider === ATLAS_EXECUTOR.providerCapability) {
     if (!ATLAS_EXECUTOR.capabilityRefPattern.test(resource)) {
       report(ATLAS_EXECUTOR.capabilityRefInvalid, resource);
     }
   } else if (provider === ATLAS_EXECUTOR.providerAgent && resource === ATLAS_EXECUTOR.agentResource) {
+    refusedKeys = ATLAS_EXECUTOR.paramRefused.agentKeys;
     const agent = q2.agent;
-    if (typeof agent !== "string" || agent === "") {
+    if (typeof agent !== "string" || agent.trim() === "") {
       report(ATLAS_EXECUTOR.agentMissing);
     } else if (agent.includes(TEMPLATE_ACTION_OPEN)) {
       report(ATLAS_EXECUTOR.agentNotLiteral);
     }
-    const prompt = q2.prompt;
-    const promptTemplate = q2.prompt_template;
-    const hasPrompt = prompt !== void 0 && prompt !== null && prompt !== "";
-    const hasTemplate = promptTemplate !== void 0 && promptTemplate !== null && promptTemplate !== "";
+    const hasPrompt = atlasTextPresent(q2.prompt);
+    const hasTemplate = atlasTextPresent(q2.prompt_template);
     if (!hasPrompt && !hasTemplate) report(ATLAS_EXECUTOR.promptMissing);
     else if (hasPrompt && hasTemplate) report(ATLAS_EXECUTOR.promptBoth);
+    if (anyTemplate(q2.model)) report(ATLAS_EXECUTOR.modelNotLiteral);
   } else {
     report(ATLAS_EXECUTOR.operationUnknown, executor);
     return;
   }
-  const caps = q2.capabilities;
-  if (Array.isArray(caps) && caps.some((c) => typeof c === "string" && c.includes(TEMPLATE_ACTION_OPEN))) {
-    report(ATLAS_EXECUTOR.capabilitiesNotLiteral);
-  }
+  if (anyTemplate(q2.capabilities)) report(ATLAS_EXECUTOR.capabilitiesNotLiteral);
+  const refused = refusedKeys.filter((key) => Object.prototype.hasOwnProperty.call(q2, key)).sort();
+  if (refused.length > 0) report(ATLAS_EXECUTOR.paramRefused, refused.join(", "));
+}
+function anyTemplate(v) {
+  if (typeof v === "string") return v.includes(TEMPLATE_ACTION_OPEN);
+  if (Array.isArray(v)) return v.some(anyTemplate);
+  if (isRecord(v)) return Object.values(v).some(anyTemplate);
+  return false;
+}
+function atlasTextPresent(v) {
+  if (v === void 0 || v === null) return false;
+  return typeof v !== "string" || v.trim() !== "";
 }
 function checkFunctionOperation(executor, field, stepID, templated, issues) {
   if (templated) return;
@@ -3980,6 +4046,37 @@ function validateInputSchema(flow, issues) {
   validateSchemaDefinition(flow.input_schema, "input_schema", issues);
 }
 
+// src/validators/reservedInputs.ts
+function formatField(format, name) {
+  return format.replace("%s", () => name);
+}
+function validateReservedInputNames(flow, issues) {
+  const rule = RESERVED_INPUT_NAMES;
+  const report = (name, fieldFormat) => {
+    issues.error({
+      field: formatField(fieldFormat, name),
+      message: rule.messageFormat.replace("%s", () => JSON.stringify(name)),
+      code: rule.code,
+      suggestion: rule.suggestion
+    });
+  };
+  const query = flow.query;
+  if (isRecord(query)) {
+    for (const name of Object.keys(query).sort()) {
+      if (name.startsWith(rule.prefix)) report(name, rule.queryFieldFormat);
+    }
+  }
+  const schema = flow.input_schema;
+  const fields = isRecord(schema) ? schema.fields : void 0;
+  if (!Array.isArray(fields)) return;
+  for (const f of fields) {
+    if (!isRecord(f)) continue;
+    if (typeof f.name === "string" && f.name.startsWith(rule.prefix)) {
+      report(f.name, rule.schemaFieldFormat);
+    }
+  }
+}
+
 // src/validators/outputSchema.ts
 function validateOutputSchemas(flow, issues) {
   const steps = flow.steps;
@@ -5094,7 +5191,7 @@ var CODE2 = "server_owned_query_key";
 var KEY_QUERY = "query";
 var KEY_ID = "id";
 var SERVER_OWNED = new Set(SERVER_OWNED_QUERY_KEYS.keys);
-function formatField(format, ...args) {
+function formatField2(format, ...args) {
   let i = 0;
   return format.replace(/%s/g, () => args[i++] ?? "");
 }
@@ -5112,7 +5209,7 @@ function validateServerOwnedQueryKeys(flow, issues) {
           issues,
           stepID,
           key,
-          formatField(SERVER_OWNED_QUERY_KEYS.stepFieldFormat, stepID, key)
+          formatField2(SERVER_OWNED_QUERY_KEYS.stepFieldFormat, stepID, key)
         );
       }
     }
@@ -5126,7 +5223,7 @@ function validateServerOwnedQueryKeys(flow, issues) {
           issues,
           stepID,
           key,
-          formatField(SERVER_OWNED_QUERY_KEYS.loopStepFieldFormat, stepID, subID, key)
+          formatField2(SERVER_OWNED_QUERY_KEYS.loopStepFieldFormat, stepID, subID, key)
         );
       }
     }
@@ -5395,7 +5492,7 @@ function own(m, key) {
   if (!isRecord(m) || !Object.prototype.hasOwnProperty.call(m, key)) return void 0;
   return m[key];
 }
-function formatField2(format, ...args) {
+function formatField3(format, ...args) {
   let i = 0;
   return format.replace(/%s/g, () => args[i++] ?? "");
 }
@@ -5417,14 +5514,14 @@ function credentialEndpointSteps(flow, issues) {
     out.push({
       executor: issues.stringOf(step, KEY_EXECUTOR, `steps.${stepId}`) ?? "",
       query: own(step, KEY_QUERY2),
-      field: (key) => formatField2(CREDENTIAL_ENDPOINT_PAIRING.stepFieldFormat, stepId, key)
+      field: (key) => formatField3(CREDENTIAL_ENDPOINT_PAIRING.stepFieldFormat, stepId, key)
     });
     for (const sub of loopSubStepsOfStep(stepId, step)) {
       const subId = issues.stringOf(sub.raw, KEY_ID2, sub.basePath) ?? "";
       out.push({
         executor: issues.stringOf(sub.raw, KEY_EXECUTOR, sub.basePath) ?? "",
         query: own(sub.raw, KEY_QUERY2),
-        field: (key) => formatField2(CREDENTIAL_ENDPOINT_PAIRING.loopStepFieldFormat, stepId, subId, key)
+        field: (key) => formatField3(CREDENTIAL_ENDPOINT_PAIRING.loopStepFieldFormat, stepId, subId, key)
       });
     }
   }
@@ -5488,7 +5585,7 @@ function validateAI(flow, steps, issues) {
     if ((stepsUsing.get(provider) ?? 0) > 0 && (stepsWithoutOwnKey.get(provider) ?? 0) === 0) {
       continue;
     }
-    warnStoredShape(issues, formatField2(CREDENTIAL_ENDPOINT_PAIRING.executorConfigBaseUrlFieldFormat, provider), provider);
+    warnStoredShape(issues, formatField3(CREDENTIAL_ENDPOINT_PAIRING.executorConfigBaseUrlFieldFormat, provider), provider);
   }
 }
 function warnStoredShape(issues, field, provider) {
@@ -5535,7 +5632,7 @@ function familySecret(flow, family, step, issues) {
     if (apiKey !== "" && listHas(family.secretParams, family.configApiKeyParam)) {
       return {
         envName: serverEnvRef(family, apiKey),
-        field: formatField2(
+        field: formatField3(
           CREDENTIAL_ENDPOINT_PAIRING.executorConfigKeyFieldFormat,
           configKey,
           CREDENTIAL_ENDPOINT_PAIRING.executorConfigApiKeyField
@@ -5548,7 +5645,7 @@ function familySecret(flow, family, step, issues) {
       if (v !== null) {
         return {
           envName: serverEnvRef(family, v),
-          field: formatField2(CREDENTIAL_ENDPOINT_PAIRING.executorConfigExtraFieldFormat, configKey, key)
+          field: formatField3(CREDENTIAL_ENDPOINT_PAIRING.executorConfigExtraFieldFormat, configKey, key)
         };
       }
     }
@@ -5574,13 +5671,13 @@ function familyAuthorEndpoint(flow, family, step, issues) {
     if (inst === null) continue;
     const baseUrl = configStringField(inst, configKey, CREDENTIAL_ENDPOINT_PAIRING.executorConfigBaseUrlField, issues);
     if (baseUrl !== "" && listHas(family.endpointParams, family.configBaseUrlParam)) {
-      return decide(baseUrl, formatField2(CREDENTIAL_ENDPOINT_PAIRING.executorConfigBaseUrlFieldFormat, configKey));
+      return decide(baseUrl, formatField3(CREDENTIAL_ENDPOINT_PAIRING.executorConfigBaseUrlFieldFormat, configKey));
     }
     const extra = own(inst, EXECUTOR_CONFIG_ENV_SCOPES.extraKey);
     for (const key of family.endpointParams) {
       const v = nonEmptyEndpoint(extra, key);
       if (v !== null)
-        return decide(v, formatField2(CREDENTIAL_ENDPOINT_PAIRING.executorConfigExtraFieldFormat, configKey, key));
+        return decide(v, formatField3(CREDENTIAL_ENDPOINT_PAIRING.executorConfigExtraFieldFormat, configKey, key));
     }
   }
   return null;
@@ -7291,6 +7388,7 @@ function validateParsed(flow, opts, sources) {
   validateOrchestratorCampaign(f, issues, opts);
   validateCredentialBindings(f, issues);
   validateInputSchema(f, issues);
+  validateReservedInputNames(f, issues);
   validateOutputSchemas(f, issues);
   validateQualityGates(f, issues);
   validateProcessingOperations(f, issues);

package/dist/index.cjs

@@ -994,7 +994,7 @@ var aigentflow_spec_default = {
     providerAgent: "agent",
     providerCapability: "capability",
     agentResource: "run",
-    capabilityRefPattern: "^[A-Za-z0-9][A-Za-z0-9_.:-]{0,127}$",
+    capabilityRefPattern: "^[A-Za-z0-9][A-Za-z0-9_-]{0,127}$",
     operationUnknown: {
       code: "atlas_operation_unknown",
       messageFormat: "step %s uses %s, which is not an Atlas operation. The providers are agent (resource run) and capability (resource: a capability reference).",
@@ -1002,7 +1002,7 @@ var aigentflow_spec_default = {
     },
     agentMissing: {
       code: "atlas_agent_missing",
-      messageFormat: "step %s runs an Atlas agent but query.agent is missing or empty.",
+      messageFormat: "step %s runs an Atlas agent but query.agent is missing, empty or not a string.",
       suggestion: "Set query.agent to the agent to run, written out as a literal such as @acme/reporter."
     },
     agentNotLiteral: {
@@ -1028,9 +1028,46 @@ var aigentflow_spec_default = {
     capabilityRefInvalid: {
       code: "atlas_capability_ref_invalid",
       messageFormat: "step %s uses atlas://capability/%s, which is not a valid capability reference.",
-      suggestion: "A capability reference starts with a letter or digit and continues with letters, digits and _ . : - up to 128 characters in all."
+      suggestion: "A capability reference starts with a letter or digit and continues with letters, digits, _ and - up to 128 characters in all."
+    },
+    modelNotLiteral: {
+      code: "atlas_model_not_literal",
+      messageFormat: "step %s computes a value of query.model from a template. The provider, model and reasoning_effort must be fixed literals, never derived from input.",
+      suggestion: "Write the model choice out as literals. Data may go into the prompt or the inputs instead."
+    },
+    paramRefused: {
+      code: "atlas_param_refused",
+      messageFormat: "step %s sets %s under query. Atlas decides these itself, so a step may not set them.",
+      suggestion: "Remove these keys from the query.",
+      agentKeys: [
+        "api_key",
+        "attribution",
+        "base_url",
+        "host",
+        "idempotency_key",
+        "org_id",
+        "person",
+        "untrusted_input",
+        "untrusted_input_override",
+        "url",
+        "user_id"
+      ],
+      capabilityKeys: [
+        "attribution",
+        "idempotency_key",
+        "untrusted_input",
+        "untrusted_input_override"
+      ]
     }
   },
+  reservedInputNames: {
+    prefix: "__",
+    code: "reserved_input_name",
+    messageFormat: "the input %s starts with two underscores. That namespace belongs to the platform (the acting person, the credential manifest, the untrusted-input marker): a flow cannot declare an input there, and a value or default written under such a name is never delivered.",
+    suggestion: 'Rename the input so it does not start with "__".',
+    queryFieldFormat: "query.%s",
+    schemaFieldFormat: "input_schema.fields.%s"
+  },
   flowDataReservedKeys: {
     code: "flow_data_key_reserved",
     fieldFormat: "data.%s",
@@ -2086,7 +2123,23 @@ var ATLAS_EXECUTOR = {
   capabilitiesNotLiteral: atlas.capabilitiesNotLiteral,
   promptMissing: atlas.promptMissing,
   promptBoth: atlas.promptBoth,
-  capabilityRefInvalid: atlas.capabilityRefInvalid
+  capabilityRefInvalid: atlas.capabilityRefInvalid,
+  modelNotLiteral: atlas.modelNotLiteral,
+  paramRefused: {
+    code: atlas.paramRefused.code,
+    messageFormat: atlas.paramRefused.messageFormat,
+    suggestion: atlas.paramRefused.suggestion,
+    agentKeys: atlas.paramRefused.agentKeys,
+    capabilityKeys: atlas.paramRefused.capabilityKeys
+  }
+};
+var RESERVED_INPUT_NAMES = {
+  prefix: aigentflow_spec_default.reservedInputNames.prefix,
+  code: aigentflow_spec_default.reservedInputNames.code,
+  messageFormat: aigentflow_spec_default.reservedInputNames.messageFormat,
+  suggestion: aigentflow_spec_default.reservedInputNames.suggestion,
+  queryFieldFormat: aigentflow_spec_default.reservedInputNames.queryFieldFormat,
+  schemaFieldFormat: aigentflow_spec_default.reservedInputNames.schemaFieldFormat
 };
 
 // src/validators/executors.ts
@@ -2153,10 +2206,12 @@ function checkExecutor(executor, field, stepID, issues) {
 }
 function checkAtlasStep(executor, query, stepField, stepID, issues) {
   if (executor.includes(TEMPLATE_ACTION_OPEN)) return;
-  const m = EXECUTOR_URL_PATTERN.exec(executor);
-  if (m === null || m[1] !== ATLAS_EXECUTOR.scheme) return;
-  const provider = m[2];
-  const resource = m[3];
+  const prefix = `${ATLAS_EXECUTOR.scheme}://`;
+  if (!executor.startsWith(prefix)) return;
+  const rest = executor.slice(prefix.length);
+  const slash = rest.indexOf("/");
+  const provider = slash < 0 ? rest : rest.slice(0, slash);
+  const resource = slash < 0 ? "" : rest.slice(slash + 1);
   const quoted = JSON.stringify(stepID);
   const report = (rule, ...args) => {
     let message = rule.messageFormat.replace("%s", () => quoted);
@@ -2170,31 +2225,41 @@ function checkAtlasStep(executor, query, stepField, stepID, issues) {
     });
   };
   const q2 = isRecord(query) ? query : {};
+  let refusedKeys = ATLAS_EXECUTOR.paramRefused.capabilityKeys;
   if (provider === ATLAS_EXECUTOR.providerCapability) {
     if (!ATLAS_EXECUTOR.capabilityRefPattern.test(resource)) {
       report(ATLAS_EXECUTOR.capabilityRefInvalid, resource);
     }
   } else if (provider === ATLAS_EXECUTOR.providerAgent && resource === ATLAS_EXECUTOR.agentResource) {
+    refusedKeys = ATLAS_EXECUTOR.paramRefused.agentKeys;
     const agent = q2.agent;
-    if (typeof agent !== "string" || agent === "") {
+    if (typeof agent !== "string" || agent.trim() === "") {
       report(ATLAS_EXECUTOR.agentMissing);
     } else if (agent.includes(TEMPLATE_ACTION_OPEN)) {
       report(ATLAS_EXECUTOR.agentNotLiteral);
     }
-    const prompt = q2.prompt;
-    const promptTemplate = q2.prompt_template;
-    const hasPrompt = prompt !== void 0 && prompt !== null && prompt !== "";
-    const hasTemplate = promptTemplate !== void 0 && promptTemplate !== null && promptTemplate !== "";
+    const hasPrompt = atlasTextPresent(q2.prompt);
+    const hasTemplate = atlasTextPresent(q2.prompt_template);
     if (!hasPrompt && !hasTemplate) report(ATLAS_EXECUTOR.promptMissing);
     else if (hasPrompt && hasTemplate) report(ATLAS_EXECUTOR.promptBoth);
+    if (anyTemplate(q2.model)) report(ATLAS_EXECUTOR.modelNotLiteral);
   } else {
     report(ATLAS_EXECUTOR.operationUnknown, executor);
     return;
   }
-  const caps = q2.capabilities;
-  if (Array.isArray(caps) && caps.some((c) => typeof c === "string" && c.includes(TEMPLATE_ACTION_OPEN))) {
-    report(ATLAS_EXECUTOR.capabilitiesNotLiteral);
-  }
+  if (anyTemplate(q2.capabilities)) report(ATLAS_EXECUTOR.capabilitiesNotLiteral);
+  const refused = refusedKeys.filter((key) => Object.prototype.hasOwnProperty.call(q2, key)).sort();
+  if (refused.length > 0) report(ATLAS_EXECUTOR.paramRefused, refused.join(", "));
+}
+function anyTemplate(v) {
+  if (typeof v === "string") return v.includes(TEMPLATE_ACTION_OPEN);
+  if (Array.isArray(v)) return v.some(anyTemplate);
+  if (isRecord(v)) return Object.values(v).some(anyTemplate);
+  return false;
+}
+function atlasTextPresent(v) {
+  if (v === void 0 || v === null) return false;
+  return typeof v !== "string" || v.trim() !== "";
 }
 function checkFunctionOperation(executor, field, stepID, templated, issues) {
   if (templated) return;
@@ -3880,6 +3945,37 @@ function validateInputSchema(flow, issues) {
   validateSchemaDefinition(flow.input_schema, "input_schema", issues);
 }
 
+// src/validators/reservedInputs.ts
+function formatField(format, name) {
+  return format.replace("%s", () => name);
+}
+function validateReservedInputNames(flow, issues) {
+  const rule = RESERVED_INPUT_NAMES;
+  const report = (name, fieldFormat) => {
+    issues.error({
+      field: formatField(fieldFormat, name),
+      message: rule.messageFormat.replace("%s", () => JSON.stringify(name)),
+      code: rule.code,
+      suggestion: rule.suggestion
+    });
+  };
+  const query = flow.query;
+  if (isRecord(query)) {
+    for (const name of Object.keys(query).sort()) {
+      if (name.startsWith(rule.prefix)) report(name, rule.queryFieldFormat);
+    }
+  }
+  const schema = flow.input_schema;
+  const fields = isRecord(schema) ? schema.fields : void 0;
+  if (!Array.isArray(fields)) return;
+  for (const f of fields) {
+    if (!isRecord(f)) continue;
+    if (typeof f.name === "string" && f.name.startsWith(rule.prefix)) {
+      report(f.name, rule.schemaFieldFormat);
+    }
+  }
+}
+
 // src/validators/outputSchema.ts
 function validateOutputSchemas(flow, issues) {
   const steps = flow.steps;
@@ -4994,7 +5090,7 @@ var CODE2 = "server_owned_query_key";
 var KEY_QUERY = "query";
 var KEY_ID = "id";
 var SERVER_OWNED = new Set(SERVER_OWNED_QUERY_KEYS.keys);
-function formatField(format, ...args) {
+function formatField2(format, ...args) {
   let i = 0;
   return format.replace(/%s/g, () => args[i++] ?? "");
 }
@@ -5012,7 +5108,7 @@ function validateServerOwnedQueryKeys(flow, issues) {
           issues,
           stepID,
           key,
-          formatField(SERVER_OWNED_QUERY_KEYS.stepFieldFormat, stepID, key)
+          formatField2(SERVER_OWNED_QUERY_KEYS.stepFieldFormat, stepID, key)
         );
       }
     }
@@ -5026,7 +5122,7 @@ function validateServerOwnedQueryKeys(flow, issues) {
           issues,
           stepID,
           key,
-          formatField(SERVER_OWNED_QUERY_KEYS.loopStepFieldFormat, stepID, subID, key)
+          formatField2(SERVER_OWNED_QUERY_KEYS.loopStepFieldFormat, stepID, subID, key)
         );
       }
     }
@@ -5293,7 +5389,7 @@ function own(m, key) {
   if (!isRecord(m) || !Object.prototype.hasOwnProperty.call(m, key)) return void 0;
   return m[key];
 }
-function formatField2(format, ...args) {
+function formatField3(format, ...args) {
   let i = 0;
   return format.replace(/%s/g, () => args[i++] ?? "");
 }
@@ -5315,14 +5411,14 @@ function credentialEndpointSteps(flow, issues) {
     out.push({
       executor: issues.stringOf(step, KEY_EXECUTOR, `steps.${stepId}`) ?? "",
       query: own(step, KEY_QUERY2),
-      field: (key) => formatField2(CREDENTIAL_ENDPOINT_PAIRING.stepFieldFormat, stepId, key)
+      field: (key) => formatField3(CREDENTIAL_ENDPOINT_PAIRING.stepFieldFormat, stepId, key)
     });
     for (const sub of loopSubStepsOfStep(stepId, step)) {
       const subId = issues.stringOf(sub.raw, KEY_ID2, sub.basePath) ?? "";
       out.push({
         executor: issues.stringOf(sub.raw, KEY_EXECUTOR, sub.basePath) ?? "",
         query: own(sub.raw, KEY_QUERY2),
-        field: (key) => formatField2(CREDENTIAL_ENDPOINT_PAIRING.loopStepFieldFormat, stepId, subId, key)
+        field: (key) => formatField3(CREDENTIAL_ENDPOINT_PAIRING.loopStepFieldFormat, stepId, subId, key)
       });
     }
   }
@@ -5386,7 +5482,7 @@ function validateAI(flow, steps, issues) {
     if ((stepsUsing.get(provider) ?? 0) > 0 && (stepsWithoutOwnKey.get(provider) ?? 0) === 0) {
       continue;
     }
-    warnStoredShape(issues, formatField2(CREDENTIAL_ENDPOINT_PAIRING.executorConfigBaseUrlFieldFormat, provider), provider);
+    warnStoredShape(issues, formatField3(CREDENTIAL_ENDPOINT_PAIRING.executorConfigBaseUrlFieldFormat, provider), provider);
   }
 }
 function warnStoredShape(issues, field, provider) {
@@ -5433,7 +5529,7 @@ function familySecret(flow, family, step, issues) {
     if (apiKey !== "" && listHas(family.secretParams, family.configApiKeyParam)) {
       return {
         envName: serverEnvRef(family, apiKey),
-        field: formatField2(
+        field: formatField3(
           CREDENTIAL_ENDPOINT_PAIRING.executorConfigKeyFieldFormat,
           configKey,
           CREDENTIAL_ENDPOINT_PAIRING.executorConfigApiKeyField
@@ -5446,7 +5542,7 @@ function familySecret(flow, family, step, issues) {
       if (v !== null) {
         return {
           envName: serverEnvRef(family, v),
-          field: formatField2(CREDENTIAL_ENDPOINT_PAIRING.executorConfigExtraFieldFormat, configKey, key)
+          field: formatField3(CREDENTIAL_ENDPOINT_PAIRING.executorConfigExtraFieldFormat, configKey, key)
         };
       }
     }
@@ -5472,13 +5568,13 @@ function familyAuthorEndpoint(flow, family, step, issues) {
     if (inst === null) continue;
     const baseUrl = configStringField(inst, configKey, CREDENTIAL_ENDPOINT_PAIRING.executorConfigBaseUrlField, issues);
     if (baseUrl !== "" && listHas(family.endpointParams, family.configBaseUrlParam)) {
-      return decide(baseUrl, formatField2(CREDENTIAL_ENDPOINT_PAIRING.executorConfigBaseUrlFieldFormat, configKey));
+      return decide(baseUrl, formatField3(CREDENTIAL_ENDPOINT_PAIRING.executorConfigBaseUrlFieldFormat, configKey));
     }
     const extra = own(inst, EXECUTOR_CONFIG_ENV_SCOPES.extraKey);
     for (const key of family.endpointParams) {
       const v = nonEmptyEndpoint(extra, key);
       if (v !== null)
-        return decide(v, formatField2(CREDENTIAL_ENDPOINT_PAIRING.executorConfigExtraFieldFormat, configKey, key));
+        return decide(v, formatField3(CREDENTIAL_ENDPOINT_PAIRING.executorConfigExtraFieldFormat, configKey, key));
     }
   }
   return null;
@@ -7189,6 +7285,7 @@ function validateParsed(flow, opts, sources) {
   validateOrchestratorCampaign(f, issues, opts);
   validateCredentialBindings(f, issues);
   validateInputSchema(f, issues);
+  validateReservedInputNames(f, issues);
   validateOutputSchemas(f, issues);
   validateQualityGates(f, issues);
   validateProcessingOperations(f, issues);