@vaudience/aigentflow-flow-validator 0.25.0 → 0.27.0

package/PARITY.md

@@ -4,7 +4,73 @@ 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.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.
+**Tracks AIgentFlow flow schema: `v2.833.0`** (`SPEC_VERSION` in [`src/spec/aigentflow-spec.json`](./src/spec/aigentflow-spec.json)), which removes the `exons://` and `agent://` executors and the `ai://` agent-loop parameters and adds the errors `executor_removed` and `agentic_param_removed` (package 0.27.0, below). Earlier: it added 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.27.0 — **the agent surfaces are removed (BREAKING).** AIgentFlow v2.833.0 no longer
+> runs agents of its own: the `ai://<provider>/…` agent loop, the `exons://` scheme and the
+> `agent://` scheme are gone. Two new ERROR codes, both addressed to the step (`steps.<id>`, or
+> `steps.<id>.loop.steps[<index>]` for a loop sub-step), as the atlas findings are, so a host that
+> merges several verdicts drops a finding only when code and field both match.
+> `executor_removed`: a step or loop sub-step whose executor scheme (the text before `://`,
+> whitespace-trimmed, case-insensitive) is `exons` or `agent`; and a top-level `exons_uploads` key
+> (field `exons_uploads`). A step on a removed scheme yields **only** this code: no
+> `unknown_executor_scheme` warning and no executor-URL-shape error. `agentic_param_removed`: an
+> `ai://` step or loop sub-step whose `query` carries any of `agentic`, `max_tool_turns`,
+> `parallel_tool_calls`, `mcp_server_url`, `tool_auth_token`, `tool_discovery`, `discoverable_tools`,
+> `enable_signals`, `deny_tools`, `max_tool_calls`, `require_confirmation`, `guardrails`,
+> `timeout_seconds`. A key is refused on **presence**: a null value and `agentic: false` included.
+> **One** finding per step, the keys sorted in the message. Only the `ai` scheme is judged. Not
+> refused: a templated executor, `aiv://` (it keeps its own `agentic` flag), `atlas://`, any other
+> scheme, `tools` / `tool_choice` / `autofix` / `content_parts` / `stream` on `ai://`, the flow-level
+> `tool_discovery` / `discoverable_tools`, and the `orchestrator:` block's own keys. The vocabulary
+> is the spec block `removedAgentSurfaces`. Removals: `exons` and `agent` leave `executorSchemes`
+> (40 protocols; a near-miss no longer suggests them); `spec.exons` keeps only the frontmatter
+> delimiter. The rules that judge the **orchestrator's** `.exons` document stay, since the
+> orchestrator is not removed in this release; the flow-level `exons_uploads` key stays a known key
+> so it reports `executor_removed` rather than `unknown_yaml_key`. `SPEC_VERSION` is `2.833.0`.
+> Fixtures: `invalid-exons-step-attributes.yaml` and `valid-exons-step-attributes-skipped.yaml` are
+> deleted (both judged an `exons://` step's inline document); added, byte-identical to the Go
+> port's: `invalid-executor-removed-{exons,agent,scheme-case-whitespace,loop-substep,
+exons-uploads}.yaml`, `invalid-agentic-param-removed{,-false,-null-value,-loop-substep}.yaml` and
+> `valid-removed-surfaces-not-refused.yaml` (the no-false-positive control). The Go port carries the
+> same two codes (v0.17.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>`:
@@ -152,7 +218,7 @@ own state, so it is not seeded.` and the suggestion its text (spec keys `message
 > `executor_config.<provider>.base_url`). The provider is the literal segment of
 > `ai://<provider>/<operation>`, lower-cased for the lane test and printed as written; an
 > empty, slash-less or templated one is skipped, as are providers with no region lane
-> (anthropic native, scaleway, vaiembed) and `exons://` / `aiv://` steps. The
+> (anthropic native, scaleway, vaiembed) and `aiv://` steps. The
 > orchestrator's provider is `execution.provider` of its `.exons` frontmatter, read by the
 > same light frontmatter reader the save-door rules use; a document that reader cannot
 > read the way the engine would is skipped. Finding: code `compliance_residency_unenforced`,
@@ -1077,7 +1143,7 @@ max_retries` and `QualityGateDefinition.max_retries` are unchanged. Removing
 >    separate target functions; widening `hasCycle` too would invent a divergence
 >    and emit a spurious `potential_infinite_loop` on any rendezvous or error
 >    redirect back to an earlier step.
-> 4. **`executorSchemes` is AIgentFlow's registered set exactly** (43 protocols at v2.608.0, 42 since the AigentChat executor was removed,
+> 4. **`executorSchemes` is AIgentFlow's registered set exactly** (43 protocols at v2.608.0, 42 since the AigentChat executor was removed, 40 since `exons` and `agent` were,
 >    enumerated from `NewExecutorSchemaRegistry`). `web://` was missing, so a
 >    correct step warned; nine schemes AIgentFlow does not register (`openai`,
 >    `anthropic`, `perplexity`, `vertexai`, `ollama`, `vllm`, `aigentchat`,

package/README.md

@@ -170,6 +170,7 @@ interface ValidationIssue {
 - **Connectivity** — `next.default` / `next.conditions[].goto` references (error; only `null` and `orchestrator` need no step, so `end` must name one, and is then an ordinary step); unreachable steps (warning); cycles (warning).
 - **Parallel + orchestrator routing** — `next.parallel` rendezvous/steps; `orchestrator` next requires an orchestrator block.
 - **Loop / for_each / throttle** — required fields, iteration limits, mutual exclusions, throttle ceilings.
+- **Removed agent surfaces** — `executor_removed` (an `exons://` or `agent://` step, or the `exons_uploads` key) and `agentic_param_removed` (an `ai://` step carrying `agentic`, `max_tool_turns`, `mcp_server_url`, …); both errors, one finding per step.
 - **Orchestrator / campaign** — exons presence, trigger types, timer intervals, tool names; campaign requires an orchestrator and at least one child flow, each naming a `flow_id` or `flow_name`; `max_credits_per_child` >= 0.
 - **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`).
@@ -192,7 +193,7 @@ These need a live server / org context and are intentionally out of scope:
 
 - **Credentials** — whether a bound credential actually exists or is authorised.
 - **Model compliance** — the `compliance:` block is enforced against the provider catalogue at flow-create time on the server. (The one catalogue-free part, the warning `compliance_residency_unenforced` for an EU-only residency beside an unpinned call, is checked here.)
-- **`.exons` document bodies** — whether an inline `.exons` document parses and whether its tags can render (`exons_attributes`) needs the `.exons` template engine, which this package does not embed.
+- **`.exons` document bodies** — whether the orchestrator's inline `.exons` document parses and whether its tags can render (`exons_attributes`) needs the `.exons` template engine, which this package does not embed.
 - **Template field resolution** — whether `.data.x.y` will actually be populated at runtime (we validate syntax, not data flow).
 - **Publish gates** — `visibility`/`classification`/template-metadata publish rules are server- and org-context dependent.