@particle-academy/fancy-conformance 0.16.0 → 0.17.0

package/VERSION

@@ -1 +1 @@
-0.16.0
+0.17.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@particle-academy/fancy-conformance",
-  "version": "0.16.0",
+  "version": "0.17.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 \u2014 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/expr/evaluate/cases.json

@@ -1470,6 +1470,81 @@
         "value": null
       },
       "notes": "The companion to 0904, and the form every runtime can express. PHP cannot distinguish an EMPTY object from an empty array -- both decode to the same value and both read as a list -- so 0904 is skipped there. A non-empty object is unambiguous in all three, which keeps the rule pinned rather than merely skipped. Same shape as flow/workflow-props 0106/0109."
+    },
+    {
+      "id": "1001-the-normalisation-an-agent-writes",
+      "title": "The production expression that started this package: object literal, || fallback chains and a ternary, every operand legitimately absent.",
+      "since": "0.17.0",
+      "tags": [
+        "expr",
+        "field-report"
+      ],
+      "notes": "VERBATIM from a consumer's production Op, authored by a chat agent that reasonably assumed `{{ }}` was an expression language. Under the old dot-path-only resolver the WHOLE thing evaluated to null and the run reported success. They describe it as 'what an agent writes when it is trying to normalise two trigger shapes into one, which is the single most common thing they attempt' -- so this is the shape to keep working, not a toy. Every other row here isolates one rule; this one is the rules COMPOSED, which is how they actually arrive.",
+      "input": {
+        "expression": "{ transcript: in.transcript || in.file_content || '', deal_id: in.deal_id || '', file_name: in.name || 'Pasted transcript', source: in.transcript ? 'manual' : 'file_event' }",
+        "context": {
+          "in": {
+            "transcript": null,
+            "file_content": "…the call went well…",
+            "deal_id": "D-1",
+            "name": null
+          }
+        }
+      },
+      "expected": {
+        "ok": true,
+        "value": {
+          "transcript": "…the call went well…",
+          "deal_id": "D-1",
+          "file_name": "Pasted transcript",
+          "source": "file_event"
+        }
+      }
+    },
+    {
+      "id": "1002-the-branch-condition-that-took-the-wrong-road",
+      "title": "The other half of the same Op: a branch condition using && and !==.",
+      "since": "0.17.0",
+      "tags": [
+        "expr",
+        "field-report"
+      ],
+      "notes": "The expensive face of the defect. `truthy(null)` is false, so a condition the engine could not evaluate did not error -- it silently picked the false road on EVERY run while the run reported success. 0406 pins the same expression against a present deal_id; this pins it against an ABSENT one, where the honest answer is a real false rather than a false that means 'could not tell'.",
+      "input": {
+        "expression": "in.deal_id && in.deal_id !== ''",
+        "context": {
+          "in": {
+            "deal_id": null
+          }
+        }
+      },
+      "expected": {
+        "ok": true,
+        "value": null
+      }
+    },
+    {
+      "id": "1003-empty-string-fallback-survives-the-chain",
+      "title": "A || chain ending in '' yields the empty string, not null.",
+      "since": "0.17.0",
+      "tags": [
+        "expr",
+        "field-report"
+      ],
+      "notes": "Extracted from 1001 because the composed row would still pass if this rule broke -- its `transcript` key never reaches the final fallback. An author writes `|| ''` precisely so a missing field becomes a printable gap rather than the word null.",
+      "input": {
+        "expression": "in.a || in.b || ''",
+        "context": {
+          "in": {
+            "a": null,
+            "b": null
+          }
+        }
+      },
+      "expected": {
+        "ok": true,
+        "value": ""
+      }
     }
   ]
 }

package/suites/expr/references/cases.json

@@ -0,0 +1,226 @@
+{
+  "$schema": "../../../schema/case-table.schema.json",
+  "suite": "expr/references",
+  "cases": [
+    {
+      "id": "0101-single-root",
+      "title": "One path reads one root.",
+      "since": "0.17.0",
+      "tags": [
+        "expr",
+        "references"
+      ],
+      "input": {
+        "expression": "in.content"
+      },
+      "expected": {
+        "ok": true,
+        "value": [
+          "in"
+        ]
+      }
+    },
+    {
+      "id": "0102-unique-and-sorted",
+      "title": "Repeated roots collapse; the order is sorted, not source order.",
+      "since": "0.17.0",
+      "tags": [
+        "expr",
+        "references"
+      ],
+      "notes": "Sorted and unique so three languages produce the SAME list. A set iterated in insertion order agrees with a sorted list often enough to look correct and not always -- and the disagreement would surface as a host rejecting an expression in one runtime and accepting it in another.",
+      "input": {
+        "expression": "user.name + in.a + in.b + user.id"
+      },
+      "expected": {
+        "ok": true,
+        "value": [
+          "in",
+          "user"
+        ]
+      }
+    },
+    {
+      "id": "0103-dollar-root-is-reported-like-any-other",
+      "title": "A $-prefixed root is returned, not filtered and not special-cased.",
+      "since": "0.17.0",
+      "tags": [
+        "expr",
+        "references"
+      ],
+      "notes": "THE REPORTED CASE. This package does not know whether `$now` exists -- `$json`, `$input` and `$props` do exist in one host and mean nothing in another. It reports what is read; the HOST owns the list. Filtering `$` names here would silently delete the only signal the check needs.",
+      "input": {
+        "expression": "$now"
+      },
+      "expected": {
+        "ok": true,
+        "value": [
+          "$now"
+        ]
+      }
+    },
+    {
+      "id": "0104-mixed-dollar-and-plain",
+      "title": "Both kinds in one expression.",
+      "since": "0.17.0",
+      "tags": [
+        "expr",
+        "references"
+      ],
+      "input": {
+        "expression": "$props.content || in.content"
+      },
+      "expected": {
+        "ok": true,
+        "value": [
+          "$props",
+          "in"
+        ]
+      }
+    },
+    {
+      "id": "0105-computed-index-is-a-reference",
+      "title": "A computed index reads a root too.",
+      "since": "0.17.0",
+      "tags": [
+        "expr",
+        "references"
+      ],
+      "notes": "An implementation that walked only `.name` steps passes every other row in this suite and fails exactly here. A typo'd index gets the same silent empty as `$now`, so it needs the same static answer.",
+      "input": {
+        "expression": "items[i]"
+      },
+      "expected": {
+        "ok": true,
+        "value": [
+          "i",
+          "items"
+        ]
+      }
+    },
+    {
+      "id": "0106-object-keys-are-not-references",
+      "title": "An object literal's KEYS are written, not read.",
+      "since": "0.17.0",
+      "tags": [
+        "expr",
+        "references"
+      ],
+      "notes": "The damaging direction: an implementation collecting every identifier would report `transcript` and `source`, and the host would reject a perfectly valid expression. A false rejection at save time is worse than a missed one, because the author has no way to comply.",
+      "input": {
+        "expression": "{ transcript: in.content, source: 'manual' }"
+      },
+      "expected": {
+        "ok": true,
+        "value": [
+          "in"
+        ]
+      }
+    },
+    {
+      "id": "0107-literals-read-nothing",
+      "title": "An expression with no paths reads nothing.",
+      "since": "0.17.0",
+      "tags": [
+        "expr",
+        "references"
+      ],
+      "input": {
+        "expression": "1 + 2 === 3 ? 'yes' : 'no'"
+      },
+      "expected": {
+        "ok": true,
+        "value": []
+      }
+    },
+    {
+      "id": "0108-both-sides-of-a-branch",
+      "title": "Every branch is read, not only the taken one.",
+      "since": "0.17.0",
+      "tags": [
+        "expr",
+        "references"
+      ],
+      "notes": "A static question has no run to take a branch in. An implementation that short-circuited here -- reusing the evaluator's logic -- would report only what one run happened to touch, and the host would approve an expression that fails on the other road.",
+      "input": {
+        "expression": "a ? b : c"
+      },
+      "expected": {
+        "ok": true,
+        "value": [
+          "a",
+          "b",
+          "c"
+        ]
+      }
+    },
+    {
+      "id": "0109-the-field-report-normalisation",
+      "title": "The consumer's production expression reads exactly one root.",
+      "since": "0.17.0",
+      "tags": [
+        "expr",
+        "references"
+      ],
+      "notes": "The same expression as expr/evaluate 1001, asked the static question. Four keys, three fallback chains and a ternary, and the honest answer is one root -- which is what makes the check cheap enough for a host to run on every save.",
+      "input": {
+        "expression": "{ transcript: in.transcript || in.file_content || '', deal_id: in.deal_id || '', file_name: in.name || 'Pasted transcript', source: in.transcript ? 'manual' : 'file_event' }"
+      },
+      "expected": {
+        "ok": true,
+        "value": [
+          "in"
+        ]
+      }
+    },
+    {
+      "id": "0110-length-is-not-a-root",
+      "title": "`.length` is a step, never a name to supply.",
+      "since": "0.17.0",
+      "tags": [
+        "expr",
+        "references"
+      ],
+      "input": {
+        "expression": "results.length === 0"
+      },
+      "expected": {
+        "ok": true,
+        "value": [
+          "results"
+        ]
+      }
+    },
+    {
+      "id": "0201-malformed-does-not-parse",
+      "title": "A malformed expression fails here exactly as it fails in parse().",
+      "since": "0.17.0",
+      "tags": [
+        "expr",
+        "references"
+      ],
+      "notes": "Same outcome, same reason: this is a question about a syntax tree, and there is no tree. Returning an empty list instead would tell a host 'this expression needs nothing', and it would save a node that can never run.",
+      "input": {
+        "expression": "in.a &&"
+      },
+      "expected": {
+        "ok": false
+      }
+    },
+    {
+      "id": "0202-a-call-does-not-parse",
+      "title": "A call is still refused at parse time.",
+      "since": "0.17.0",
+      "tags": [
+        "expr",
+        "references"
+      ],
+      "input": {
+        "expression": "count(in.items)"
+      },
+      "expected": {
+        "ok": false
+      }
+    }
+  ]
+}

package/suites/expr/references/manifest.json

@@ -0,0 +1,26 @@
+{
+  "$schema": "../../../schema/suite-manifest.schema.json",
+  "suite": "expr/references",
+  "title": "What an expression READS -- the root names a host must be able to supply",
+  "since": "0.17.0",
+  "caseFormat": "table",
+  "cases": "cases.json",
+  "contract": {
+    "function": "references(expression: string) -> { ok: true, value: string[] } | { ok: false }",
+    "summary": "Return the ROOT identifiers an expression reads, unique and sorted, without evaluating anything and without a context. `{ ok: false }` when the expression cannot PARSE -- the same failure `parse()` reports, because this is a static question asked of the same syntax tree. Object-literal KEYS are not references; a computed index IS one.",
+    "reference": "node",
+    "implementations": [
+      { "language": "node", "package": "@particle-academy/fancy-expr", "symbol": "references" },
+      { "language": "php", "package": "particle-academy/fancy-expr", "symbol": "FancyExpr\\Expr::references" },
+      { "language": "python", "package": "fancy-expr", "symbol": "fancy_expr.references" }
+    ]
+  },
+  "notes": [
+    "WHY THIS EXISTS, and it is not a convenience. A consumer reported that `{{ $now }}` renders as nothing: `$`-prefixed roots read to an author as ENGINE-PROVIDED, so agents reach for `$now` / `$today` / `$index` the way they reach for the two that exist. A real document shipped titled 'Deal List Export -' with the date silently missing. Their words: an unknown `$` root is detectable at PARSE time in a way `in.genuinely_absent` is not.",
+    "THE HOST DECIDES, NOT THIS PACKAGE. `fancy-expr` must never carry a list of magic root names -- it does not know whether `$props` exists, and inventing an allowlist would make it wrong for every host but one. So it answers the only question it CAN answer honestly ('what does this expression read?') and the host compares that against what it actually provides. That keeps the grammar host-agnostic while making the check possible at all.",
+    "IT ALSO CATCHES THE SECOND REPORTED SHAPE. The same consumer reported `{{ n2.transcript }}` -- a REAL node id, two hops upstream, which is legal-looking and resolves to nothing because a node id only addresses a direct predecessor. A host holding the predecessor set can refuse that from these roots too. One primitive, both shapes, and neither rule living in this package.",
+    "WHAT IT DELIBERATELY CANNOT CATCH: `{{ in.output }}` -- a real port and a field that node never emits. The root is legitimate, so nothing static can tell an absent field from a field that is absent THIS RUN. That is the boundary of the idea and is recorded so nobody reads a green check as covering it.",
+    "COMPUTED INDICES COUNT (0105). `items[i]` reads `i`, and an author who typo'd it gets the same silent empty as `$now`. An implementation that walked only `.name` steps would pass every other row here.",
+    "OBJECT KEYS DO NOT COUNT (0106). `{ transcript: in.content }` reads `in` and nothing else -- `transcript` is a key being written, not a name being read. An implementation collecting every identifier it sees would report both and make the host reject a valid expression, which is the more damaging direction of wrong."
+  ]
+}