@particle-academy/fancy-conformance 0.6.0 → 0.9.1

package/suites/flow/workflow-props/cases.json

@@ -0,0 +1,558 @@
+{
+  "$schema": "../../../schema/cases.schema.json",
+  "suite": "flow/workflow-props",
+  "cases": [
+    {
+      "id": "0001-supplied-value-passes-through",
+      "title": "A declared, supplied value arrives in the resolved map unchanged.",
+      "since": "0.9.0",
+      "tags": [
+        "happy-path"
+      ],
+      "input": {
+        "declared": [
+          {
+            "name": "topic",
+            "type": "string"
+          }
+        ],
+        "passed": {
+          "topic": "otters"
+        }
+      },
+      "expected": {
+        "ok": true,
+        "props": {
+          "topic": "otters"
+        }
+      }
+    },
+    {
+      "id": "0002-default-fills-an-omitted-value",
+      "title": "An omitted input with a default resolves to the default.",
+      "since": "0.9.0",
+      "tags": [
+        "defaults"
+      ],
+      "input": {
+        "declared": [
+          {
+            "name": "limit",
+            "type": "number",
+            "default": 10
+          }
+        ],
+        "passed": {}
+      },
+      "expected": {
+        "ok": true,
+        "props": {
+          "limit": 10
+        }
+      }
+    },
+    {
+      "id": "0003-supplied-beats-default",
+      "title": "An explicitly supplied value wins over the declared default.",
+      "since": "0.9.0",
+      "tags": [
+        "defaults"
+      ],
+      "input": {
+        "declared": [
+          {
+            "name": "limit",
+            "type": "number",
+            "default": 10
+          }
+        ],
+        "passed": {
+          "limit": 25
+        }
+      },
+      "expected": {
+        "ok": true,
+        "props": {
+          "limit": 25
+        }
+      }
+    },
+    {
+      "id": "0004-explicit-zero-is-not-replaced-by-a-default",
+      "title": "A supplied 0 survives a non-zero default.",
+      "since": "0.9.0",
+      "tags": [
+        "defaults",
+        "falsy",
+        "trap"
+      ],
+      "input": {
+        "declared": [
+          {
+            "name": "limit",
+            "type": "number",
+            "default": 10
+          }
+        ],
+        "passed": {
+          "limit": 0
+        }
+      },
+      "expected": {
+        "ok": true,
+        "props": {
+          "limit": 0
+        }
+      }
+    },
+    {
+      "id": "0005-explicit-false-is-not-replaced-by-a-default",
+      "title": "A supplied false survives a true default.",
+      "since": "0.9.0",
+      "tags": [
+        "defaults",
+        "falsy",
+        "trap"
+      ],
+      "input": {
+        "declared": [
+          {
+            "name": "dryRun",
+            "type": "boolean",
+            "default": true
+          }
+        ],
+        "passed": {
+          "dryRun": false
+        }
+      },
+      "expected": {
+        "ok": true,
+        "props": {
+          "dryRun": false
+        }
+      }
+    },
+    {
+      "id": "0006-explicit-empty-string-is-not-replaced-by-a-default",
+      "title": "A supplied empty string survives a non-empty default.",
+      "since": "0.9.0",
+      "tags": [
+        "defaults",
+        "falsy",
+        "trap"
+      ],
+      "input": {
+        "declared": [
+          {
+            "name": "note",
+            "type": "string",
+            "default": "unset"
+          }
+        ],
+        "passed": {
+          "note": ""
+        }
+      },
+      "expected": {
+        "ok": true,
+        "props": {
+          "note": ""
+        }
+      }
+    },
+    {
+      "id": "0007-absent-optional-is-absent-not-null",
+      "title": "An optional input with no default and no value is missing from the map entirely.",
+      "since": "0.9.0",
+      "tags": [
+        "absence"
+      ],
+      "input": {
+        "declared": [
+          {
+            "name": "topic",
+            "type": "string"
+          },
+          {
+            "name": "note",
+            "type": "string"
+          }
+        ],
+        "passed": {
+          "topic": "otters"
+        }
+      },
+      "expected": {
+        "ok": true,
+        "props": {
+          "topic": "otters"
+        }
+      }
+    },
+    {
+      "id": "0008-untyped-declaration-accepts-anything",
+      "title": "An input declaring no type accepts a nested object.",
+      "since": "0.9.0",
+      "tags": [
+        "types"
+      ],
+      "input": {
+        "declared": [
+          {
+            "name": "payload"
+          }
+        ],
+        "passed": {
+          "payload": {
+            "nested": [
+              1,
+              2
+            ]
+          }
+        }
+      },
+      "expected": {
+        "ok": true,
+        "props": {
+          "payload": {
+            "nested": [
+              1,
+              2
+            ]
+          }
+        }
+      }
+    },
+    {
+      "id": "0009-required-is-satisfied-by-its-default",
+      "title": "A required input carrying a default does not need the caller to supply it.",
+      "since": "0.9.0",
+      "tags": [
+        "required",
+        "defaults"
+      ],
+      "input": {
+        "declared": [
+          {
+            "name": "limit",
+            "type": "number",
+            "required": true,
+            "default": 5
+          }
+        ],
+        "passed": {}
+      },
+      "expected": {
+        "ok": true,
+        "props": {
+          "limit": 5
+        }
+      }
+    },
+    {
+      "id": "0010-array-satisfies-array-not-object",
+      "title": "A list satisfies a declared array.",
+      "since": "0.9.0",
+      "tags": [
+        "types",
+        "trap"
+      ],
+      "input": {
+        "declared": [
+          {
+            "name": "tags",
+            "type": "array"
+          }
+        ],
+        "passed": {
+          "tags": [
+            "a",
+            "b"
+          ]
+        }
+      },
+      "expected": {
+        "ok": true,
+        "props": {
+          "tags": [
+            "a",
+            "b"
+          ]
+        }
+      }
+    },
+    {
+      "id": "0011-object-satisfies-object",
+      "title": "A map satisfies a declared object.",
+      "since": "0.9.0",
+      "tags": [
+        "types"
+      ],
+      "input": {
+        "declared": [
+          {
+            "name": "meta",
+            "type": "object"
+          }
+        ],
+        "passed": {
+          "meta": {
+            "k": "v"
+          }
+        }
+      },
+      "expected": {
+        "ok": true,
+        "props": {
+          "meta": {
+            "k": "v"
+          }
+        }
+      }
+    },
+    {
+      "id": "0012-no-declaration-and-no-props",
+      "title": "A workflow that declares nothing, called with nothing, resolves to an empty map.",
+      "since": "0.9.0",
+      "tags": [
+        "happy-path",
+        "absence"
+      ],
+      "input": {
+        "declared": null,
+        "passed": null
+      },
+      "expected": {
+        "ok": true,
+        "props": {}
+      }
+    },
+    {
+      "id": "0101-an-unknown-key-fails",
+      "title": "A misspelled input name FAILS rather than sitting unread.",
+      "since": "0.9.0",
+      "tags": [
+        "validation",
+        "regression",
+        "silent-failure"
+      ],
+      "input": {
+        "declared": [
+          {
+            "name": "topic",
+            "type": "string"
+          }
+        ],
+        "passed": {
+          "topik": "otters"
+        }
+      },
+      "expected": {
+        "ok": false,
+        "code": "unknown_input"
+      }
+    },
+    {
+      "id": "0102-props-passed-to-a-workflow-declaring-none-fails",
+      "title": "Passing anything to a workflow that declares no inputs FAILS.",
+      "since": "0.9.0",
+      "tags": [
+        "validation",
+        "silent-failure"
+      ],
+      "input": {
+        "declared": null,
+        "passed": {
+          "topic": "otters"
+        }
+      },
+      "expected": {
+        "ok": false,
+        "code": "unknown_input"
+      }
+    },
+    {
+      "id": "0103-unknown-is-reported-before-missing-required",
+      "title": "A caller who misspells a required input is told about the word they typed.",
+      "since": "0.9.0",
+      "tags": [
+        "validation",
+        "ordering"
+      ],
+      "input": {
+        "declared": [
+          {
+            "name": "topic",
+            "type": "string",
+            "required": true
+          }
+        ],
+        "passed": {
+          "topik": "otters"
+        }
+      },
+      "expected": {
+        "ok": false,
+        "code": "unknown_input"
+      }
+    },
+    {
+      "id": "0104-missing-required-fails",
+      "title": "A required input with no default and no value FAILS.",
+      "since": "0.9.0",
+      "tags": [
+        "validation",
+        "required"
+      ],
+      "input": {
+        "declared": [
+          {
+            "name": "topic",
+            "type": "string",
+            "required": true
+          }
+        ],
+        "passed": {}
+      },
+      "expected": {
+        "ok": false,
+        "code": "missing_required"
+      }
+    },
+    {
+      "id": "0105-wrong-type-fails",
+      "title": "A string supplied where a number is declared FAILS.",
+      "since": "0.9.0",
+      "tags": [
+        "validation",
+        "types"
+      ],
+      "input": {
+        "declared": [
+          {
+            "name": "limit",
+            "type": "number"
+          }
+        ],
+        "passed": {
+          "limit": "ten"
+        }
+      },
+      "expected": {
+        "ok": false,
+        "code": "type_mismatch"
+      }
+    },
+    {
+      "id": "0106-object-does-not-satisfy-array",
+      "title": "A map supplied where an array is declared FAILS.",
+      "since": "0.9.0",
+      "tags": [
+        "validation",
+        "types",
+        "trap"
+      ],
+      "input": {
+        "declared": [
+          {
+            "name": "tags",
+            "type": "array"
+          }
+        ],
+        "passed": {
+          "tags": {
+            "0": "a"
+          }
+        }
+      },
+      "expected": {
+        "ok": false,
+        "code": "type_mismatch"
+      },
+      "skip": {
+        "php": "Not representable in PHP. `json_decode('{\"0\":\"a\"}', true)` coerces the numeric STRING key to int 0, producing a list -- so the map this case describes cannot exist on that runtime and `array_is_list` correctly reports a list. The rule itself is pinned for every runtime by 0109, which uses a non-numeric key."
+      },
+      "notes": "Kept rather than rewritten because the divergence is worth recording: a JS host and a PHP host genuinely disagree about this value, and the reason is PHP's key coercion rather than either implementation being wrong."
+    },
+    {
+      "id": "0107-array-does-not-satisfy-object",
+      "title": "A list supplied where an object is declared FAILS.",
+      "since": "0.9.0",
+      "tags": [
+        "validation",
+        "types",
+        "trap"
+      ],
+      "input": {
+        "declared": [
+          {
+            "name": "meta",
+            "type": "object"
+          }
+        ],
+        "passed": {
+          "meta": [
+            "a"
+          ]
+        }
+      },
+      "expected": {
+        "ok": false,
+        "code": "type_mismatch"
+      }
+    },
+    {
+      "id": "0108-null-does-not-satisfy-a-declared-type",
+      "title": "An explicit null supplied where a string is declared FAILS.",
+      "since": "0.9.0",
+      "tags": [
+        "validation",
+        "types"
+      ],
+      "input": {
+        "declared": [
+          {
+            "name": "topic",
+            "type": "string"
+          }
+        ],
+        "passed": {
+          "topic": null
+        }
+      },
+      "expected": {
+        "ok": false,
+        "code": "type_mismatch"
+      }
+    },
+    {
+      "id": "0109-a-string-keyed-map-does-not-satisfy-array",
+      "title": "A map with a non-numeric key supplied where an array is declared FAILS.",
+      "since": "0.9.1",
+      "tags": [
+        "validation",
+        "types",
+        "trap"
+      ],
+      "notes": "The runnable half of 0106. A non-numeric key survives json_decode on PHP as a string-keyed array, so `array_is_list` reports false and every runtime agrees. This is the case that actually pins object-is-not-array across all three.",
+      "input": {
+        "declared": [
+          {
+            "name": "tags",
+            "type": "array"
+          }
+        ],
+        "passed": {
+          "tags": {
+            "a": 1
+          }
+        }
+      },
+      "expected": {
+        "ok": false,
+        "code": "type_mismatch"
+      }
+    }
+  ]
+}

package/suites/flow/workflow-props/manifest.json

@@ -0,0 +1,28 @@
+{
+  "$schema": "../../../schema/suite-manifest.schema.json",
+  "suite": "flow/workflow-props",
+  "title": "Resolving a caller's props against what a workflow declares",
+  "since": "0.9.0",
+  "caseFormat": "table",
+  "cases": "cases.json",
+  "contract": {
+    "function": "resolveWorkflowProps(declared: array|null, passed: object|null) -> {ok: true, props: object} | {ok: false, code: string}",
+    "summary": "Check the flat, by-name object a caller passed against the `inputs` a workflow declares, and fill in declared defaults. `declared` is the list of input declarations ({name, type?, required?, default?}) or null when the workflow declares none. `passed` is what the caller supplied, or null. On success the result carries the RESOLVED map -- supplied values plus defaults for anything omitted, and nothing else. On failure it carries a stable `code`; the human-readable message is deliberately NOT part of the contract.",
+    "reference": "node",
+    "referenceNote": "@particle-academy/fancy-flow's src/runtime/workflow-props.ts is the behavioural source of truth, and the rules were designed there with this table written alongside rather than after.",
+    "implementations": [
+      { "language": "node", "package": "@particle-academy/fancy-flow", "symbol": "resolveWorkflowProps" },
+      { "language": "php", "package": "particle-academy/fancy-flow-php", "symbol": "FancyFlow\\Runtime\\WorkflowProps::resolve" },
+      { "language": "python", "package": "fancy-flow", "symbol": "fancy_flow.runtime.workflow_props.resolve_workflow_props" }
+    ]
+  },
+  "notes": [
+    "The CODE is asserted, never the message. Each runtime words its errors idiomatically and an English sentence is not a behaviour -- pinning the prose would hold three implementations to a translation, and would go red on a wording improvement that changed nothing.",
+    "The reason this feature exists is case 0101: passing a MISSPELLED key. Before workflow props, `initialInputs` was keyed by node id and an unrecognised key was not an error -- the value simply sat unread, the node saw nothing, and the run reported success with output that was quietly wrong. Every implementation must fail that case, because the silent version is what shipped.",
+    "Cases 0004-0006 are the falsy-value trap and they are the ones a re-implementation gets wrong. `0`, `false` and `\"\"` are values a caller MEANT to pass. A default applied with `||`, or with `??` on the wrong side, silently replaces them -- and a declared limit of 0 quietly becoming 10 is not an error anybody observes.",
+    "Absent is ABSENT. An input that is not supplied, has no default and is not required must not appear in the resolved map at all -- not as null, not as an empty string. PHP has one absent value and JS has two; letting that difference leak would make `{{ $props.x }}` disagree across runtimes for no useful reason.",
+    "`type` is optional and an omitted type accepts ANYTHING (case 0008). 'I am not asserting a shape' must not degrade into 'nothing is allowed', which is the failure mode of a validator written defensively.",
+    "Arrays are checked before objects (case 0010). `typeof []` is `\"object\"` in JavaScript, and a declaration saying `array` that accepts `{}` is a check that passes while meaning nothing.",
+    "Unknown keys are checked BEFORE required ones (case 0103). A caller who typed `topik` instead of `topic` should be told about `topik` -- the word they wrote -- rather than that `topic` is missing, which describes a key they believe they supplied."
+  ]
+}