@particle-academy/fancy-conformance 0.26.0 → 0.28.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.28.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@particle-academy/fancy-conformance",
-  "version": "0.26.0",
+  "version": "0.28.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/graph-runs/cases.json

@@ -293,13 +293,10 @@
           "lg": {
             "logged": "regular Bo",
             "level": "info"
-          },
-          "o": {
-            "logged": "regular Bo",
-            "level": "info"
           }
         }
-      }
+      },
+      "notes": "THE GOLDEN CHANGED IN 0.28.0, and the change is the point of the row. `lg` is a `log` node — a terminal kind, which declares an EMPTY output port list — and edge e3 leaves it for `o`. Every runtime used to refuse that empty list and publish `out` instead, so the chain continued straight through a node that had declared it publishes nothing, and `o` ran. Under the owner's strict-but-loud ruling the declaration is honoured: `lg` terminates, `o` never runs, and the run raises the undelivered-edge warning naming e3 rather than truncating in silence. A runtime that still reports `o` here is one that has not taken the ruling."
     },
     {
       "id": "0004-switch-case",

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

@@ -0,0 +1,166 @@
+{
+  "$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": [],
+      "notes": "THREE STATES, NOT TWO. `null` falls back to `out` (row 0302); `[]` means a node that genuinely publishes nothing. Collapsing them is how a terminal node starts publishing — and downstream of that, an edge nobody drew starts delivering. THIS ROW WAS SKIPPED FOR NODE IN 0.27.0 and is unskipped in 0.28.0: it recorded a real divergence (that engine collapsed `[]` to `out` while PHP, Python and Rust published nothing), the owner ruled strict-but-loud, and all four now agree. The skip was the right way to carry a disagreement — visible in every runner's summary — and removing it is what settling the disagreement looks like."
+    }
+  ]
+}

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

@@ -0,0 +1,32 @@
+{
+  "$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 WAS THE DIVERGENCE, AND IT IS NOW SETTLED. `declaredOutputs: []` means 'this node explicitly has no output ports'. PHP, Python and Rust honoured it and published nothing; `@particle-academy/fancy-flow` collapsed it to `[\"out\"]` because its fallback tested `declared?.length` and an empty array is falsy, so the three states became two. Measured on fancy-flow 0.74.1, carried as a `skip` for node in 0.27.0 so every runner printed the disagreement, and resolved in 0.28.0 by the owner's ruling: STRICT, BUT A TERMINAL NODE MUST BE LOUD. All four now publish nothing, and the skip is gone. Carrying a disagreement as a visible skip, then removing it when it is decided, is what this mechanism is for.",
+    "THE SAME RULE APPLIES TO A PORT SET INHERITED FROM THE KIND, and it is pinned by `flow/graph-runs` row 0003 rather than here, because it needs a registered kind and these rows deliberately name one no runtime ships. Every runtime used to REFUSE an empty declaration coming from a kind — a terminal `log` / `output` kind declares one — and published `out` instead, on the stated grounds that honouring it would silently cut every chain through such a node. That reasoning held only while the cut was silent. It no longer is, so the refusal is gone in all four and 0003's golden changed with it: a `log` node now terminates, and the node after it does not run.",
+    "STRICT IS ONLY HALF THE RULING; THE OTHER HALF IS NOT OPTIONAL. An edge leaving a node that published nothing must raise the undelivered-edge warning (`flow/run-diagnostics`). Both gates that shape a port set have to honour the empty declaration — the one that decides what a node PUBLISHES, and the one behind the warning that decides what is DELIVERABLE. A runtime that fixes only the first truncates chains while its own diagnostic still reports the edge as fine, which is strictly worse than the lenient behaviour it replaced.",
+    "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."
+  ]
+}