@vaudience/aigentflow-flow-validator 0.26.0 → 0.28.0

package/PARITY.md

@@ -4,8 +4,100 @@ 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.837.0`** (`SPEC_VERSION` in [`src/spec/aigentflow-spec.json`](./src/spec/aigentflow-spec.json)), which makes `nexus://` the canonical agent-runtime scheme with `atlas://` as its alias, removes signals, dynamic flow modification and campaigns (`signal_removed`, `flow_modification_removed`, `removed_key_ignored`, `campaign_removed`) and drops share links from the removal advice (package 0.28.0, below). Earlier: it removed 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.28.0 — **`nexus://` with `atlas://` as its alias; signals, DFM and campaigns removed
+> (BREAKING).** `SPEC_VERSION` is `2.837.0`. Contracts: AIgentFlow's traps doc, sections "An executor
+> scheme with two spellings", "AGENTCUT B1 validator contract" and "AGENTCUT B2 validator contract".
+>
+> _`nexus://` (AIgentFlow v2.835.0)._ `nexus` joins `executorSchemes` (no `unknown_executor_scheme`
+> warning). The `atlasExecutor` block names `scheme: nexus` and `aliases: [atlas]`; every rule
+> (`atlas_operation_unknown`, `atlas_agent_missing`, `atlas_agent_not_literal`,
+> `atlas_capabilities_not_literal`, `atlas_prompt_missing`, `atlas_prompt_both`,
+> `atlas_capability_ref_invalid`, `atlas_model_not_literal`, `atlas_param_refused`) answers
+> identically for both spellings; the codes keep their `atlas_` prefix, and the messages say
+> `nexus://` / "Nexus". The scheme match stays exact and case-sensitive. An AigentChat-shaped
+> `nexus://<org>/<agent>` (that executor was removed in v2.819.0) is now `atlas_operation_unknown`,
+> no longer an `unknown_executor_scheme` warning; `aigentchat://` stays an unknown scheme.
+>
+> _Signals and DFM (AIgentFlow v2.834.0)._ **`signal_removed`** (ERROR): `orchestrator.enable_signals:
+true`; one of `aif_signal_complete`, `aif_signal_need_human`, `aif_signal_delegate`,
+> `aif_signal_need_tool`, `aif_signal_modify_flow` in `orchestrator.tools`, `deny_tools`,
+> `require_approval_for` (field = the list) or in the orchestrator definition's `tools.allow` (field
+> `orchestrator.exons`), ONE finding per list naming the removed names in list order, each once; and
+> `enable_signals` on an `aiv://` step or loop sub-step (on presence, null included).
+> **`flow_modification_removed`** (ERROR): a `dfm_suggestion` trigger (one finding, field
+> `orchestrator.triggers`) and `flow_modification_allowed` in any step's or loop sub-step's query.
+> Step keys skip templated executors, removed schemes and `flow://` (its query is the child's inputs).
+> **`removed_key_ignored`** (WARNING, never an error): `checkpoint.pre_dfm` (any non-null value; AIgentFlow
+> wrote it into stored flows itself) and `orchestrator.enable_signals: false`. A YAML null on either
+> block key is absent.
+>
+> _Campaigns (AIgentFlow v2.836.0)._ **`campaign_removed`** (ERROR): a `campaign` key with ANY non-null
+> value (field `campaign`; the block is refused whole), one of `aif_campaign_spawn`,
+> `aif_campaign_status`, `aif_campaign_results`, `aif_campaign_cancel` in one of the four tool lists
+> (one finding per list), and a `campaign_child_completed` / `campaign_child_failed` trigger (one
+> finding, the removed types in order). Steps are never judged.
+>
+> _Removals._ The removed tool and trigger names leave `orchestrator.tools` / `orchestrator.triggers`
+> but are TOLERATED by `orchestrator_tool_unknown` and `orchestrator_trigger_unknown` (also under
+> `strictRegistries`), so each is reported once, with advice. `orchestrator_tool_withheld` loses its
+> signal exemption and its campaign arm and never names a removed tool; `orchestratorToolAllow` drops
+> `enableSignalsDefault`, `signalTools` and `campaignTools`. The campaign rules are deleted
+> (`campaign_requires_orchestrator`, `campaign_handoff_step_unknown`,
+> `campaign_invalid_max_credits_per_child`, `campaign_no_child_flows`, `campaign_child_flow_no_id`, and
+> the retired-key arm for `campaign.budget_max_per_child`), and the `campaign` block decodes untyped
+> (`knownKeys`: `any`; `CampaignConfig` and `CampaignChildFlowDef` are gone), so nothing inside it is
+> an unknown key. `enable_signals` and `pre_dfm` stay in `knownKeys`.
+>
+> _Share links (AIgentFlow v2.837.0)._ The `executor_removed` / `agentic_param_removed` suggestion is
+> AIgentFlow's current `SUGGESTION_REMOVED_AGENT_ADVICE`: it writes `nexus://`, says share links no
+> longer exist, and names the run's responsible person.
+>
+> _Fixtures_, byte-identical to the Go port's (v0.18.0). Added: `valid-nexus-agent-run`,
+> `valid-nexus-capability`, `valid-atlas-alias-agent-run`, `invalid-nexus-agent-missing`,
+> `invalid-nexus-loop-substep-agent-not-literal`, `invalid-nexus-aigentchat-shape`,
+> `invalid-signal-removed-{enable-signals,tool-lists,aiv-step}`,
+> `invalid-flow-modification-removed-{trigger,step}`,
+> `warn-removed-key-ignored-{pre-dfm,enable-signals-false}`, `valid-signal-surfaces-not-refused`,
+> `invalid-campaign-removed-{block,empty-block,retired-key,tool-lists,triggers}` and
+> `valid-campaign-surfaces-not-refused`. Renamed: `warn-removed-executor-nexus` →
+> `warn-removed-executor-aigentchat` (aigentchat:// only). Edited: `warn-orchestrator-tool-withheld-named`,
+> `valid-orchestrator-tool-allow-consistent`, `valid-orchestrator-tool-allow-absent` (no removed names).
+> Deleted: `valid-campaign-handoff`, `valid-campaign-decoded-shapes`,
+> `invalid-campaign-{handoff-unknown-step,no-child-flows,child-flow-no-id}`,
+> `invalid-retired-campaign-budget-max-per-child`, `valid-orchestrator-tool-allow-campaign`,
+> `warn-orchestrator-tool-withheld-{campaign,signals-off}`.
+
+> 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
@@ -189,7 +281,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`,
@@ -1114,7 +1206,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,7 +170,10 @@ 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.
-- **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.
+- **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** — exons presence, trigger types, timer intervals, tool names.
+- **Removed surfaces** — the `exons://` / `agent://` executors and the `ai://` agent-loop parameters (`executor_removed`, `agentic_param_removed`); agent signals and dynamic flow modification (`signal_removed`, `flow_modification_removed`, and the `removed_key_ignored` warning for `checkpoint.pre_dfm` and `orchestrator.enable_signals: false`); campaigns (`campaign_removed`: the `campaign:` block, the campaign tools and triggers).
+- **Nexus agent steps** — `nexus://agent/run` and `nexus://capability/<ref>` (also written `atlas://`, an accepted alias): a literal agent and capabilities, exactly one of `prompt` / `prompt_template`, a valid capability reference, no refused parameters (`atlas_*` codes).
 - **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`).
@@ -192,7 +195,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.