@vaudience/aigentflow-flow-validator 0.19.0 → 0.20.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/PARITY.md +73 -35
- package/README.md +2 -2
- package/dist/cli.js +257 -73
- package/dist/index.cjs +256 -73
- package/dist/index.cjs.map +1 -1
- package/dist/index.js +256 -73
- package/dist/index.js.map +1 -1
- package/package.json +1 -1
package/PARITY.md
CHANGED
|
@@ -4,8 +4,45 @@ This document maps every rule in this JavaScript validator back to the AIgentFlo
|
|
|
4
4
|
Go reference implementation, records the intentional divergences, and defines the
|
|
5
5
|
discipline for keeping the two in sync.
|
|
6
6
|
|
|
7
|
-
**Tracks AIgentFlow flow schema: `v2.
|
|
8
|
-
|
|
7
|
+
**Tracks AIgentFlow flow schema: `v2.821.0`** (`SPEC_VERSION` in [`src/spec/aigentflow-spec.json`](./src/spec/aigentflow-spec.json)), which adds the warning `compliance_residency_unenforced` (package 0.20.0, below). Earlier: `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.
|
|
8
|
+
|
|
9
|
+
> package 0.20.0 — **`compliance_residency_unenforced`**, in step with the reference
|
|
10
|
+
> (AIgentFlow v2.821.0; `specVersion` 2.821.0). A **warning**, never an error, and it
|
|
11
|
+
> needs no catalogue. `compliance.residency` is, in the reference, a check against the
|
|
12
|
+
> model catalogue's declared deployments: it says a (provider, model) pair is _eligible_,
|
|
13
|
+
> not which host a call dials. The new rule is the catalogue-free counterpart. When the
|
|
14
|
+
> residency is non-empty and **every** code (trimmed, upper-cased) is `EU`, `DE`, `FR`,
|
|
15
|
+
> `IE`, `NL`, `IT` or `ES` (so `["EU","US"]` is not EU-only), each top-level step and
|
|
16
|
+
> loop sub-step whose executor starts `ai://`, then the orchestrator, warns when its
|
|
17
|
+
> provider is a **region-lane provider** (the providers whose adapter routes on `region`:
|
|
18
|
+
> `bedrock`, `google`, `azure`, `openai`, `assemblyai`, `speechmatics`, `deepgram`,
|
|
19
|
+
> `mistral`; spec key `complianceResidency.regionLaneProviders`) and nothing pins the
|
|
20
|
+
> call. Pinned means: `region` a non-empty string; or `enforce_region` true (a step
|
|
21
|
+
> query: a bool, or the strings `true`/`1`/`yes`; the orchestrator: a bool); or the
|
|
22
|
+
> author named the host (`<provider>_base_url` in the step query, or
|
|
23
|
+
> `executor_config.<provider>.base_url`). The provider is the literal segment of
|
|
24
|
+
> `ai://<provider>/<operation>`, lower-cased for the lane test and printed as written; an
|
|
25
|
+
> empty, slash-less or templated one is skipped, as are providers with no region lane
|
|
26
|
+
> (anthropic native, scaleway, vaiembed) and `exons://` / `aiv://` steps. The
|
|
27
|
+
> orchestrator's provider is `execution.provider` of its `.exons` frontmatter, read by the
|
|
28
|
+
> same light frontmatter reader the save-door rules use; a document that reader cannot
|
|
29
|
+
> read the way the engine would is skipped. Finding: code `compliance_residency_unenforced`,
|
|
30
|
+
> severity warning, field `steps.<id>.executor`, `steps.<id>.loop.steps.<sub-step id>.executor`
|
|
31
|
+
> or `orchestrator.exons`, `stepId` the top-level step (absent for the orchestrator); the
|
|
32
|
+
> message and suggestion are the reference's text (spec keys `messageFormat`,
|
|
33
|
+
> `suggestion`). Order: steps by id, each followed by its loop sub-steps, then the
|
|
34
|
+
> orchestrator. A run-level `region` input is invisible to a static check, so write
|
|
35
|
+
> `region: "{{ .query.region }}"` on the step to state it. **Not ported:** the reference's
|
|
36
|
+
> catalogue check itself (`compliance_violation`, `compliance_unknown_deployment`,
|
|
37
|
+
> `compliance_dynamic_skipped`, and its widening to loop bodies, `quality_gate` judges and
|
|
38
|
+
> the orchestrator's model) — it needs the model catalogue, which this package has never
|
|
39
|
+
> carried (divergence #6). New conformance fixtures:
|
|
40
|
+
> `warn-compliance-residency-unenforced.yaml`, `warn-compliance-residency-unenforced-loop.yaml`,
|
|
41
|
+
> `valid-compliance-residency-pinned.yaml`, `valid-compliance-residency-silent-providers.yaml`
|
|
42
|
+
> (the two `valid-` ones forbid the warning code: their whole risk is a false positive).
|
|
43
|
+
> The mixed-residency, blank-region and `enforce_region` spelling matrix lives in
|
|
44
|
+
> `test/v0200-compliance-residency.test.ts`.
|
|
45
|
+
>
|
|
9
46
|
> package 0.19.0 — **`orchestrator.region` and `orchestrator.enforce_region`**, in step
|
|
10
47
|
> with the reference (AIgentFlow v2.820.0; `specVersion` 2.820.0). Both are new keys of
|
|
11
48
|
> the `orchestrator:` block (a `string` and a `bool`), added to the known-key table.
|
|
@@ -984,39 +1021,40 @@ Comparison contract: **error `code` + `valid` verdict**, not message wording. Th
|
|
|
984
1021
|
|
|
985
1022
|
## Rule map
|
|
986
1023
|
|
|
987
|
-
| Area | Go source | JS module | Tested by
|
|
988
|
-
| ----------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------- | --------------------------------------------------------- |
|
|
989
|
-
| Required fields, start-step existence, per-step executor, reserved `.` in IDs, reserved id `orchestrator` | `validateBasicStructure`, `ValidateFlow` head | `validators/basicStructure.ts` | `validate.test.ts`, `conformance.test.ts`
|
|
990
|
-
| Executor URI shape (the ONE parser) + scheme | `ValidateFlow` executor-URL rule (parser.go), `ParseExecutorURLString` | `validators/executors.ts` | `validate.test.ts`
|
|
991
|
-
| Query/property/array-item schema + array constraints | `validateQueryParameters`, `validateProperties`, `validateArrayItems`, `validateArrayConstraints` | `validators/querySchema.ts` | `validate.test.ts`
|
|
992
|
-
| Response-expectation types + array items + `required` | `ValidateFlow` (response block), `validateSemantics` | `validators/responseExpectation.ts` | `validate.test.ts`
|
|
993
|
-
| Response expectation nothing reads (`response_expectation_unread`, warning) | `validateResponseExpectationIsRead` (validation.go) | `validators/responseExpectation.ts` | `validate.test.ts`, `conformance.test.ts`
|
|
994
|
-
| Error strategy (action, goto, max_delay, backoff, retry_on) | `validateErrorStrategy` | `validators/errorStrategy.ts` | `validate.test.ts`
|
|
995
|
-
| Retired `budget:` / `max_retries:` (flow, step, loop sub-step) and `campaign.budget_max_per_child` → `unknown_yaml_key` | `retiredGrammarKeys` + `KnownFields(true)` (parser.go) | `validators/retiredKeys.ts` | `validate.test.ts`, `conformance.test.ts`
|
|
996
|
-
| `next` references (save-door sentinels `null`/`orchestrator`), reachability and cycles (`end` is an ordinary step) | `validateNextLogic` (parser.go), `findReachableSteps`, `checkForCycles` | `validators/connectivity.ts` | `validate.test.ts`, `conformance.test.ts`
|
|
997
|
-
| Unknown keys at every level (`unknown_yaml_key`) and value kinds (`invalid_type`) | `KnownFields(true)` over the reference's types (parser.go); `knownKeys` in the spec | `validators/unknownKeys.ts` | `validate.test.ts`, `conformance.test.ts`
|
|
998
|
-
| `next.parallel` + orchestrator-next requirement | `validateNextLogic`, `validateOrchestratorNext` | `validators/nextLogic.ts` | `validate.test.ts`
|
|
999
|
-
| Expression functions (XOR package/function) | `validateExpressionFunctions` | `validators/expressionFunctions.ts` | `validate.test.ts`
|
|
1000
|
-
| Expression-function catalog (`package:` refused, unknown `function:` refused) | `validateExpressionFunctionCatalog` (parser.go) | `validators/expressionFunctions.ts` | `validate.test.ts`, `conformance.test.ts`
|
|
1001
|
-
| Expression-function USE (`{{ fn_* }}` must be in the catalog AND declared) | `validateExpressionFunctionUsage` (parser.go) | `validators/expressionFunctions.ts` | `validate.test.ts`, `conformance.test.ts`
|
|
1002
|
-
| Loop / for_each / throttle | `validateLoop`, `validateForEach`, `validateThrottle` | `validators/loopForEachThrottle.ts` | `validate.test.ts`
|
|
1003
|
-
| Loop sub-step id that shadows a loop-result summary field (`loop_sub_step_id_reserved`, warning) | `validateLoopSubStepIDCollision` (validation.loopbody.go) | `validators/loopForEachThrottle.ts` | `validate.test.ts`, `conformance.test.ts`
|
|
1004
|
-
| Loop sub-step `next:` targets (same-loop only, sentinels, no parallel) | `validateLoopSubStepNext` (parser.go) | `validators/loopForEachThrottle.ts` | `validate.test.ts`, `conformance.test.ts`
|
|
1005
|
-
| Orchestrator structure + campaign requires orchestrator | `validateOrchestrator`, `validateAndNormalizeCampaign` | `validators/orchestratorCampaign.ts` | `validate.test.ts`
|
|
1006
|
-
| Campaign `max_credits_per_child` (decoded as int64, >= 0), `child_flows` | `CampaignConfig.Validate` (domain.campaign.go) | `validators/orchestratorCampaign.ts` | `validate.test.ts`, `conformance.test.ts`
|
|
1007
|
-
| `tool_discovery` vocabulary, mock scenario `delay`, empty `output:` entry | `validateToolDiscoveryVocabulary`, `validateMockScenarioDelays`, `validateOutputParameters` (parser.go) | `validators/saveDoor.ts` | `validate.test.ts`, `conformance.test.ts`
|
|
1008
|
-
| `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`
|
|
1009
|
-
| 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`
|
|
1010
|
-
| 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`
|
|
1011
|
-
| 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`
|
|
1012
|
-
| 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`
|
|
1013
|
-
| Credential bindings (`stored/...`, inject_as, exclusivity) | `validateStepCredentialBindings` | `validators/credentialBindings.ts` | `validate.test.ts`
|
|
1014
|
-
| `input_schema` definition + ordering lint | `ValidateInputSchemaDefinition`, `LintInputSchemaFieldOrdering` | `validators/inputSchema.ts` | `validate.test.ts`
|
|
1015
|
-
| Step `output_schema` definition (reuses the input-schema subset) | `ValidateInputSchemaDefinition` (on `step.OutputSchema`, parser.go) | `validators/outputSchema.ts` (+ shared `inputSchema.ts`) | `validate.test.ts`
|
|
1016
|
-
| `quality_gate:` block (rubric/threshold/on_fail/goto) | `FlowParser.validateQualityGate` (parser.go) | `validators/qualityGate.ts` | `validate.test.ts`
|
|
1017
|
-
| Processing-operation type + per-operation config keys | `validateProcessingOperationShape` | `validators/processingOperations.ts` | `validate.test.ts`, `conformance.test.ts`
|
|
1018
|
-
| Step `max_duration` the engine cannot apply (`step_max_duration_ignored`, warning) | `validateStepMaxDurationIsApplied` (validation.go), `parseStepMaxDuration` (flowengine.steptimeout.go) | `validators/stepMaxDuration.ts` | `validate.test.ts`, `conformance.test.ts`
|
|
1019
|
-
|
|
|
1024
|
+
| Area | Go source | JS module | Tested by |
|
|
1025
|
+
| ----------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------- | --------------------------------------------------------- | ----------------------------------------------------------- |
|
|
1026
|
+
| Required fields, start-step existence, per-step executor, reserved `.` in IDs, reserved id `orchestrator` | `validateBasicStructure`, `ValidateFlow` head | `validators/basicStructure.ts` | `validate.test.ts`, `conformance.test.ts` |
|
|
1027
|
+
| Executor URI shape (the ONE parser) + scheme | `ValidateFlow` executor-URL rule (parser.go), `ParseExecutorURLString` | `validators/executors.ts` | `validate.test.ts` |
|
|
1028
|
+
| Query/property/array-item schema + array constraints | `validateQueryParameters`, `validateProperties`, `validateArrayItems`, `validateArrayConstraints` | `validators/querySchema.ts` | `validate.test.ts` |
|
|
1029
|
+
| Response-expectation types + array items + `required` | `ValidateFlow` (response block), `validateSemantics` | `validators/responseExpectation.ts` | `validate.test.ts` |
|
|
1030
|
+
| Response expectation nothing reads (`response_expectation_unread`, warning) | `validateResponseExpectationIsRead` (validation.go) | `validators/responseExpectation.ts` | `validate.test.ts`, `conformance.test.ts` |
|
|
1031
|
+
| Error strategy (action, goto, max_delay, backoff, retry_on) | `validateErrorStrategy` | `validators/errorStrategy.ts` | `validate.test.ts` |
|
|
1032
|
+
| Retired `budget:` / `max_retries:` (flow, step, loop sub-step) and `campaign.budget_max_per_child` → `unknown_yaml_key` | `retiredGrammarKeys` + `KnownFields(true)` (parser.go) | `validators/retiredKeys.ts` | `validate.test.ts`, `conformance.test.ts` |
|
|
1033
|
+
| `next` references (save-door sentinels `null`/`orchestrator`), reachability and cycles (`end` is an ordinary step) | `validateNextLogic` (parser.go), `findReachableSteps`, `checkForCycles` | `validators/connectivity.ts` | `validate.test.ts`, `conformance.test.ts` |
|
|
1034
|
+
| Unknown keys at every level (`unknown_yaml_key`) and value kinds (`invalid_type`) | `KnownFields(true)` over the reference's types (parser.go); `knownKeys` in the spec | `validators/unknownKeys.ts` | `validate.test.ts`, `conformance.test.ts` |
|
|
1035
|
+
| `next.parallel` + orchestrator-next requirement | `validateNextLogic`, `validateOrchestratorNext` | `validators/nextLogic.ts` | `validate.test.ts` |
|
|
1036
|
+
| Expression functions (XOR package/function) | `validateExpressionFunctions` | `validators/expressionFunctions.ts` | `validate.test.ts` |
|
|
1037
|
+
| Expression-function catalog (`package:` refused, unknown `function:` refused) | `validateExpressionFunctionCatalog` (parser.go) | `validators/expressionFunctions.ts` | `validate.test.ts`, `conformance.test.ts` |
|
|
1038
|
+
| Expression-function USE (`{{ fn_* }}` must be in the catalog AND declared) | `validateExpressionFunctionUsage` (parser.go) | `validators/expressionFunctions.ts` | `validate.test.ts`, `conformance.test.ts` |
|
|
1039
|
+
| Loop / for_each / throttle | `validateLoop`, `validateForEach`, `validateThrottle` | `validators/loopForEachThrottle.ts` | `validate.test.ts` |
|
|
1040
|
+
| Loop sub-step id that shadows a loop-result summary field (`loop_sub_step_id_reserved`, warning) | `validateLoopSubStepIDCollision` (validation.loopbody.go) | `validators/loopForEachThrottle.ts` | `validate.test.ts`, `conformance.test.ts` |
|
|
1041
|
+
| Loop sub-step `next:` targets (same-loop only, sentinels, no parallel) | `validateLoopSubStepNext` (parser.go) | `validators/loopForEachThrottle.ts` | `validate.test.ts`, `conformance.test.ts` |
|
|
1042
|
+
| Orchestrator structure + campaign requires orchestrator | `validateOrchestrator`, `validateAndNormalizeCampaign` | `validators/orchestratorCampaign.ts` | `validate.test.ts` |
|
|
1043
|
+
| Campaign `max_credits_per_child` (decoded as int64, >= 0), `child_flows` | `CampaignConfig.Validate` (domain.campaign.go) | `validators/orchestratorCampaign.ts` | `validate.test.ts`, `conformance.test.ts` |
|
|
1044
|
+
| `tool_discovery` vocabulary, mock scenario `delay`, empty `output:` entry | `validateToolDiscoveryVocabulary`, `validateMockScenarioDelays`, `validateOutputParameters` (parser.go) | `validators/saveDoor.ts` | `validate.test.ts`, `conformance.test.ts` |
|
|
1045
|
+
| `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` |
|
|
1046
|
+
| 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` |
|
|
1047
|
+
| 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` |
|
|
1048
|
+
| 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` |
|
|
1049
|
+
| 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` |
|
|
1050
|
+
| Credential bindings (`stored/...`, inject_as, exclusivity) | `validateStepCredentialBindings` | `validators/credentialBindings.ts` | `validate.test.ts` |
|
|
1051
|
+
| `input_schema` definition + ordering lint | `ValidateInputSchemaDefinition`, `LintInputSchemaFieldOrdering` | `validators/inputSchema.ts` | `validate.test.ts` |
|
|
1052
|
+
| Step `output_schema` definition (reuses the input-schema subset) | `ValidateInputSchemaDefinition` (on `step.OutputSchema`, parser.go) | `validators/outputSchema.ts` (+ shared `inputSchema.ts`) | `validate.test.ts` |
|
|
1053
|
+
| `quality_gate:` block (rubric/threshold/on_fail/goto) | `FlowParser.validateQualityGate` (parser.go) | `validators/qualityGate.ts` | `validate.test.ts` |
|
|
1054
|
+
| Processing-operation type + per-operation config keys | `validateProcessingOperationShape` | `validators/processingOperations.ts` | `validate.test.ts`, `conformance.test.ts` |
|
|
1055
|
+
| Step `max_duration` the engine cannot apply (`step_max_duration_ignored`, warning) | `validateStepMaxDurationIsApplied` (validation.go), `parseStepMaxDuration` (flowengine.steptimeout.go) | `validators/stepMaxDuration.ts` | `validate.test.ts`, `conformance.test.ts` |
|
|
1056
|
+
| An EU-only residency beside an unpinned region-lane `ai://` call (`compliance_residency_unenforced`, warning) | `validateResidencyEnforcement` (validation.residency.go) | `validators/complianceResidency.ts` | `v0200-compliance-residency.test.ts`, `conformance.test.ts` |
|
|
1057
|
+
| Go-template syntax | `validateTemplateExpression` (Parse step) | `template/gotmpl-syntax.ts` + `validators/templates.ts` | `gotmpl-syntax.test.ts`, `validate.test.ts` |
|
|
1020
1058
|
|
|
1021
1059
|
---
|
|
1022
1060
|
|
package/README.md
CHANGED
|
@@ -116,7 +116,7 @@ Low-level: parse YAML into `{ flow?, parseErrors, parseWarnings }` without valid
|
|
|
116
116
|
|
|
117
117
|
### `SPEC_VERSION: string`
|
|
118
118
|
|
|
119
|
-
The AIgentFlow flow-schema version this build tracks (e.g. `"2.
|
|
119
|
+
The AIgentFlow flow-schema version this build tracks (e.g. `"2.821.0"`).
|
|
120
120
|
|
|
121
121
|
### Options
|
|
122
122
|
|
|
@@ -190,7 +190,7 @@ interface ValidationIssue {
|
|
|
190
190
|
These need a live server / org context and are intentionally out of scope:
|
|
191
191
|
|
|
192
192
|
- **Credentials** — whether a bound credential actually exists or is authorised.
|
|
193
|
-
- **Model compliance** — the `compliance:` block is enforced against the provider catalogue at flow-create time on the server.
|
|
193
|
+
- **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.)
|
|
194
194
|
- **`.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.
|
|
195
195
|
- **Template field resolution** — whether `.data.x.y` will actually be populated at runtime (we validate syntax, not data flow).
|
|
196
196
|
- **Publish gates** — `visibility`/`classification`/template-metadata publish rules are server- and org-context dependent.
|