@particle-academy/fancy-conformance 0.26.0 → 0.27.0

package/README.md

@@ -70,6 +70,7 @@ verbatim.
 | `shared/flow-run-identity` | 25 | fancy-flow's run/step identity: the idempotency key a retrying connector sends, and when a retry may still reuse it |
 | `flow/graph-runs` | 23 | Whole-graph execution: the same `WorkflowSchema` in, the same `RunResult.outputs` out |
 | `flow/run-diagnostics` | 14 | The run-time warnings for a graph that delivers nothing: an edge naming a port its source can never publish, and a route taken on a path that did not resolve. Half the rows pin when to stay silent |
+| `flow/port-activation` | 12 | Which output ports a node lights and what each carries: a chosen SUBSET via `__ports`, one port via `__port` / `branch`, and the declared-port fallbacks. One row records a real disagreement as a skip rather than omitting it |
 | `flow/durable-dispatch` | 14 | How a queued run hands out nodes: one at a time by default, in declaration order, with a paused gate keeping its slot; a cap and the whole frontier only when a host asks |
 | `shared/subscription-lease` | 13 | A subscription that expires: when a renewal is due, when the lease has expired, and why a missed lease is a resync rather than a quiet re-create |
 

package/VERSION

@@ -1 +1 @@
-0.26.0
+0.27.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@particle-academy/fancy-conformance",
-  "version": "0.26.0",
+  "version": "0.27.0",
   "description": "Shared cross-language conformance fixtures for the Fancy suite. One contract, N implementations, and a single table that every implementation asserts in its own CI — so 'parity' is a test result rather than a claim. Ships the fixture data itself, so a Rust, Go or Python runner can consume it without a JavaScript toolchain.",
   "repository": {
     "type": "git",

package/suites/flow/port-activation/cases.json

@@ -0,0 +1,169 @@
+{
+  "$schema": "../../../schema/case-table.schema.json",
+  "suite": "flow/port-activation",
+  "cases": [
+    {
+      "id": "0101-ports-list-lights-the-named-subset",
+      "title": "A `__ports` LIST lights exactly those ports, each carrying the shared value.",
+      "since": "0.27.0",
+      "tags": ["subset"],
+      "input": {
+        "declaredOutputs": ["a", "b", "c", "d", "e"],
+        "result": { "__ports": ["a", "c"], "value": "matched" }
+      },
+      "expected": [
+        { "port": "a", "value": "matched" },
+        { "port": "c", "value": "matched" }
+      ],
+      "notes": "The rule fancy-flow-php#18 added. Before it the engine knew two answers — one port, or every port — so a router that matched two of five lanes had to drop the rest of the work or wake lanes nobody asked for. Ports `b`, `d` and `e` are declared and stay DARK, which is the half of this row that matters."
+    },
+    {
+      "id": "0102-ports-map-gives-each-port-its-own-payload",
+      "title": "A `__ports` MAP lights its keys, each carrying its own payload.",
+      "since": "0.27.0",
+      "tags": ["subset"],
+      "input": {
+        "declaredOutputs": ["a", "b", "c", "d", "e"],
+        "result": { "__ports": { "a": { "queue": "billing" }, "c": { "queue": "abuse" } } }
+      },
+      "expected": [
+        { "port": "a", "value": { "queue": "billing" } },
+        { "port": "c", "value": { "queue": "abuse" } }
+      ],
+      "notes": "One classifier, two lanes, two different payloads. Sharing one payload across the lit ports would force every lane to re-derive which part of the result was addressed to it."
+    },
+    {
+      "id": "0103-per-port-null-is-a-payload",
+      "title": "A per-port payload that is present and NULL is delivered as null.",
+      "since": "0.27.0",
+      "tags": ["subset", "null"],
+      "input": {
+        "declaredOutputs": ["a", "b"],
+        "result": { "__ports": { "a": null } }
+      },
+      "expected": [{ "port": "a", "value": null }],
+      "notes": "Key presence, not truthiness. `values[port] ?? value` reads this as 'absent' and hands the port the shared value instead — which is `undefined`/null here, so it would PASS by accident. It is asserted anyway because the same lookup is what row 0102 depends on, and the version of this bug that shipped in `branch` was invisible for exactly this reason."
+    },
+    {
+      "id": "0104-an-empty-ports-list-lights-nothing",
+      "title": "An explicitly empty `__ports` lights NOTHING.",
+      "since": "0.27.0",
+      "tags": ["subset", "empty"],
+      "input": {
+        "declaredOutputs": ["a", "b", "c"],
+        "result": { "__ports": [], "value": "unrouted" }
+      },
+      "expected": [],
+      "notes": "The honest answer for a router that matched no rule. Falling through to 'every declared port' here would wake all three lanes at precisely the moment the node decided none applied — and the run would look successful."
+    },
+    {
+      "id": "0105-map-order-is-emission-order",
+      "title": "A `__ports` map lights its ports in the order the map declares them.",
+      "since": "0.27.0",
+      "tags": ["subset", "order"],
+      "input": {
+        "declaredOutputs": ["a", "b", "c"],
+        "result": { "__ports": { "c": 1, "a": 2 } }
+      },
+      "expected": [
+        { "port": "c", "value": 1 },
+        { "port": "a", "value": 2 }
+      ],
+      "notes": "Declaration order, not the declared-outputs order and not sorted. A runtime that sorted these would deliver every payload correctly and still be wrong: two lanes touching one resource would interleave differently on different runtimes, which is the class of bug that only reproduces in production."
+    },
+    {
+      "id": "0106-a-malformed-ports-falls-through",
+      "title": "A `__ports` that is neither a list nor a map falls through to every declared port.",
+      "since": "0.27.0",
+      "tags": ["subset", "malformed"],
+      "input": {
+        "declaredOutputs": ["a", "b"],
+        "result": { "__ports": "a" }
+      },
+      "expected": [
+        { "port": "a", "value": { "__ports": "a" } },
+        { "port": "b", "value": { "__ports": "a" } }
+      ],
+      "notes": "A string is not a subset instruction. Reading an unreadable `__ports` as 'no ports' would turn one typo into a silently truncated run; falling through publishes the whole result, which is loud downstream. Note what each port carries: the WHOLE result, wrapper included, because no subset rule fired."
+    },
+    {
+      "id": "0201-port-sugar-lights-one-port",
+      "title": "`__port` lights exactly one port, carrying `value`.",
+      "since": "0.27.0",
+      "tags": ["single"],
+      "input": {
+        "declaredOutputs": ["a", "b", "c"],
+        "result": { "__port": "b", "value": "only-b" }
+      },
+      "expected": [{ "port": "b", "value": "only-b" }],
+      "notes": "Unchanged by #18 and asserted here so it stays that way. `__ports` was added as a sibling rule, not a replacement, and is checked AFTER `__port`."
+    },
+    {
+      "id": "0202-branch-with-an-explicit-null-payload",
+      "title": "`branch` with `value` present and null delivers null, not the wrapper.",
+      "since": "0.27.0",
+      "tags": ["single", "null"],
+      "input": {
+        "declaredOutputs": ["a", "b"],
+        "result": { "branch": "b", "value": null }
+      },
+      "expected": [{ "port": "b", "value": null }],
+      "notes": "ALL FOUR RUNTIMES SHIPPED THIS WRONG, IDENTICALLY, so no parity table caught it — they agreed on being wrong. `value ?? result` cannot tell 'no value key' (row 0203, where the whole result IS the payload) from 'value is null' (this row), so a branch whose payload was null leaked `{branch, value}` downstream: two fields no kind declares, while the declared ones were absent. The reachable path is an upstream `transform` whose dot-path did not resolve."
+    },
+    {
+      "id": "0203-branch-with-no-value-key-carries-the-whole-result",
+      "title": "`branch` with NO `value` key carries the entire result.",
+      "since": "0.27.0",
+      "tags": ["single"],
+      "input": {
+        "declaredOutputs": ["a", "b"],
+        "result": { "branch": "b", "verdict": "approved" }
+      },
+      "expected": [{ "port": "b", "value": { "branch": "b", "verdict": "approved" } }],
+      "notes": "The other half of 0202, and the reason the lookup must ask about key presence. An executor that returns its own object and names a branch inside it gets the object delivered; the wrapper is the payload here by design."
+    },
+    {
+      "id": "0301-a-plain-result-lights-every-declared-port",
+      "title": "A result naming no ports lights EVERY declared output port, each carrying the whole result.",
+      "since": "0.27.0",
+      "tags": ["fallback"],
+      "input": {
+        "declaredOutputs": ["a", "b", "c"],
+        "result": { "ok": true }
+      },
+      "expected": [
+        { "port": "a", "value": { "ok": true } },
+        { "port": "b", "value": { "ok": true } },
+        { "port": "c", "value": { "ok": true } }
+      ],
+      "notes": "The default, and what `__ports` narrows. Declared order."
+    },
+    {
+      "id": "0302-a-node-declaring-no-ports-lights-out",
+      "title": "A node that declares NO outputs lights the lone `out` port.",
+      "since": "0.27.0",
+      "tags": ["fallback"],
+      "input": {
+        "declaredOutputs": null,
+        "result": { "ok": true }
+      },
+      "expected": [{ "port": "out", "value": { "ok": true } }],
+      "notes": "`null` is 'undeclared', which is not the same as 'explicitly none' — see row 0303. The `out` fallback is what lets a hand-written document omit ports entirely and still chain."
+    },
+    {
+      "id": "0303-an-explicitly-empty-outputs-lights-nothing",
+      "title": "A node whose outputs are an explicitly EMPTY list lights nothing.",
+      "since": "0.27.0",
+      "tags": ["fallback", "empty", "divergence"],
+      "input": {
+        "declaredOutputs": [],
+        "result": { "ok": true }
+      },
+      "expected": [],
+      "skip": {
+        "node": "DIVERGENCE, not an exemption: @particle-academy/fancy-flow collapses an explicitly-empty outputs to ['out'] because its fallback tests `declared?.length` and [] is falsy, so the three states (undeclared / explicitly none / declared) become two. Measured on 0.74.1. PHP, Python and Rust all publish nothing. Tracked as an issue on fancy-flow; this row starts passing there the day it is fixed."
+      },
+      "notes": "THREE STATES, NOT TWO. `null` falls back to `out` (row 0302); `[]` means a terminal node that genuinely publishes nothing. Collapsing them is how a terminal node starts publishing — and downstream of that, an edge nobody drew starts delivering. Kept as a skipped row rather than deleted so every runner prints the disagreement: a table that omits the one case its implementations disagree on is a table that agrees by saying less."
+    }
+  ]
+}

package/suites/flow/port-activation/manifest.json

@@ -0,0 +1,30 @@
+{
+  "$schema": "../../../schema/suite-manifest.schema.json",
+  "suite": "flow/port-activation",
+  "title": "Which output ports a node lights, and what each one carries",
+  "since": "0.27.0",
+  "caseFormat": "table",
+  "cases": "cases.json",
+  "contract": {
+    "function": "run(node with declaredOutputs, executor returning result) -> ordered [{ port, value }]",
+    "summary": "Run a ONE-NODE graph whose node declares `declaredOutputs` as its output ports and whose executor returns `result`, and report the `node-output` events that node emitted, in order, as `[{ port, value }]`. The answer is the events rather than a private function's return value because every runtime keeps this logic private (`activatedPorts`, `_activated_ports`, `Walk::activated_ports`) and the events are what a consumer — and the durable layer — actually observes. A row with an empty `expected` asserts the node emitted NOTHING, which is a different claim from emitting one port with a null payload and is the claim several of these rows are about.",
+    "reference": "node",
+    "referenceNote": "The result-shape rules are `@particle-academy/fancy-flow`'s and predate this table; the `__ports` rows were added with fancy-flow-php#18 across all four runtimes in the same week and the goldens were captured by running each. Row 0303 is the one place the four do NOT agree, and it is recorded as a skip rather than removed — see the notes.",
+    "implementations": [
+      { "language": "node", "package": "@particle-academy/fancy-flow", "symbol": "activatedPorts" },
+      { "language": "php", "package": "particle-academy/fancy-flow-php", "symbol": "FancyFlow\\Engine\\FlowRunner::activatedPorts" },
+      { "language": "python", "package": "fancy-flow", "symbol": "fancy_flow.engine.runner.FlowRunner._activated_ports" },
+      { "language": "rust", "package": "fancy-flow", "symbol": "fancy_flow::engine::walk::Walk::activated_ports" }
+    ]
+  },
+  "notes": [
+    "`declaredOutputs` is a LIST OF PORT IDS, or null for a node that declares none. Each runtime puts it where its own FlowNode keeps ports: TypeScript's is an xyflow node so they live in `data.outputs` as `{ id }` descriptors, while PHP, Python and Rust have a flattened `node.outputs`. The table asks about the ENGINE's rule, not about where a document stores it.",
+    "The node's kind must NOT be registered in the runtime running these rows. The declared-port fallback consults the kind's ports before falling back to `out`, so a row that accidentally named a builtin would be asserting the builtin's ports instead of the rule under test. Every row uses `hostRouter`, which no runtime ships.",
+    "THE ORDER OF THE EXPECTED LIST IS PART OF THE ASSERTION. A map-shaped `__ports` lights its ports in the order the object declares them (row 0105), which every one of the four preserves — JavaScript for string keys, PHP for array keys, Python for dicts since 3.7, and Rust because `fancy_json::Map` is insertion-ordered. A runtime that sorted them would still deliver every payload correctly and would still be wrong, because a downstream node reading a shared resource would see a different interleaving.",
+    "PER-PORT PAYLOADS ARE READ BY KEY PRESENCE, NEVER BY TRUTHINESS (rows 0103, 0202). A payload that is present and null is a payload. `values[port] ?? value` and `$ports[$port] ?? $result` cannot tell 'no key' from 'null', and all four runtimes shipped exactly that confusion in `branch` — every downstream node received the `{branch, value}` WRAPPER, two fields no kind declares, while the fields it does declare were absent. No parity table caught it because the four agreed on being wrong; these rows exist so the next one cannot hide the same way.",
+    "AN EMPTY `__ports` LIGHTS NOTHING, DELIBERATELY (row 0104). It is the honest answer for a router that matched no rule, and it is the same answer an explicitly empty `outputs` gives in three of the four runtimes. Lighting every port instead would wake every lane precisely when the node decided none applied.",
+    "A MALFORMED `__ports` FALLS THROUGH to the every-declared-port rule rather than lighting nothing (row 0106). `__ports` that is a string, a number or null is not a subset instruction, and treating an unreadable one as 'no ports' would turn a typo into a silently truncated run — the failure mode this whole table is written against.",
+    "ROW 0303 IS THE DIVERGENCE, AND IT IS RECORDED RATHER THAN REMOVED. `declaredOutputs: []` means 'this node explicitly has no output ports'. PHP, Python and Rust honour it and publish nothing; `@particle-academy/fancy-flow` collapses it to `[\"out\"]`, because its fallback tests `declared?.length` and an empty array is falsy — so the three-state distinction (undeclared / explicitly none / declared) becomes two-state there. Measured on fancy-flow 0.74.1, not inferred. It is skipped for node with that reason so every runner PRINTS it, which is the only way a known disagreement stays visible; deleting the row would make the table agree by saying less. Tracked as an issue on fancy-flow.",
+    "Nothing here asserts that a lit port must be a DECLARED one. All four runtimes publish whatever `__port` / `__ports` / `branch` names, declared or not, and an edge from a port that does not exist simply matches nothing. That is deliberate slack for hosts whose ports are config-driven, and pinning it either way belongs in its own row once someone decides it — not smuggled in through a row about something else."
+  ]
+}