@particle-academy/fancy-conformance 0.15.0 → 0.17.0

package/VERSION

@@ -1 +1 @@
-0.15.0
+0.17.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@particle-academy/fancy-conformance",
-  "version": "0.15.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

@@ -1390,7 +1390,10 @@
         "ok": true,
         "value": null
       },
-      "notes": "Deliberate. There is no count three languages would agree on for an object, and an object used as a collection is rare enough not to justify inventing one. Null here is the ordinary absent-path answer, not a special case."
+      "notes": "Deliberate. There is no count three languages would agree on for an object, and an object used as a collection is rare enough not to justify inventing one. Null here is the ordinary absent-path answer, not a special case. PHP cannot represent this case; see its skip reason and 0906.",
+      "skip": {
+        "php": "Not representable in PHP. json_decode('{}', true) and json_decode('[]', true) produce the IDENTICAL value, and array_is_list() calls both a list -- so an EMPTY object cannot be distinguished from an empty array, and the `.length` an empty array legitimately has is returned. The same limit shared/value-equality/0210 records. 0906 pins the same rule with a NON-EMPTY object, which every language can express."
+      }
     },
     {
       "id": "0905-length-is-not-host-reach",
@@ -1429,6 +1432,119 @@
         "value": null
       },
       "notes": "`.length` is a computed count, not an opening. Nothing else on the prototype chain resolves -- these expressions arrive from end users and from agents, over the wire."
+    },
+    {
+      "id": "0906-non-empty-object-has-no-length",
+      "title": "A NON-EMPTY object has no `.length` either.",
+      "since": "0.16.0",
+      "tags": [
+        "expr",
+        "length",
+        "deliberate"
+      ],
+      "input": {
+        "expression": "user.length",
+        "context": {
+          "in": {
+            "content": "hello",
+            "count": 3,
+            "deal_id": "D-1",
+            "transcript": null,
+            "items": [
+              1,
+              2
+            ],
+            "empty": [],
+            "obj": {},
+            "flag": true,
+            "zero": 0,
+            "blank": ""
+          },
+          "user": {
+            "name": "Ada"
+          }
+        }
+      },
+      "expected": {
+        "ok": true,
+        "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/evaluate/manifest.json

@@ -36,6 +36,7 @@
     "`&&` AND `||` RETURN THE OPERAND, NOT A BOOLEAN (0401-0404). That is what makes `in.transcript || in.content` a useful fallback rather than merely `true` — and the reported production case wrote exactly that shape.",
     "MALFORMED EXPRESSIONS FAIL (0801-0805) and never return null. A null there would be indistinguishable from an absent path, which is the defect being removed. 0805 pins that a function call does not parse: sandboxing is a security property here, not a style preference, because these expressions arrive from end users and from agents over the wire.",
     "This suite needs DISCRIMINATION PROBES before it can claim more than drift-guarding — deliberately-wrong evaluators that must each fail an exact set of ids. Notably: one that uses native truthiness (must fail 0301/0302), one that coerces on `==` (must fail 0503), and one that returns booleans from `&&`/`||` (must fail 0401/0403/0404). Not yet written; recorded so a green tick is not read as the stronger claim.",
-    "`.length` (0901-0905) IS the one pseudo-property, and it is load-bearing rather than convenient. Because `[]` is TRUTHY, a consumer with no `.length` would have no way to ask whether a collection is EMPTY -- the grammar would assert that an array which exists is a value and then leave nobody able to test the thing they care about. It is a computed count, not host reach: nothing is called and no prototype is walked, and 0905 pins that nothing else on the chain resolves. Objects deliberately have none (0904), since no count would survive three languages. These rows were added after writing the reference implementation's discrimination tests found the SPEC contradicting the CODE -- the truthiness rule was justified with `.length` while `.length` returned null."
+    "`.length` (0901-0905) IS the one pseudo-property, and it is load-bearing rather than convenient. Because `[]` is TRUTHY, a consumer with no `.length` would have no way to ask whether a collection is EMPTY -- the grammar would assert that an array which exists is a value and then leave nobody able to test the thing they care about. It is a computed count, not host reach: nothing is called and no prototype is walked, and 0905 pins that nothing else on the chain resolves. Objects deliberately have none (0904), since no count would survive three languages. These rows were added after writing the reference implementation's discrimination tests found the SPEC contradicting the CODE -- the truthiness rule was justified with `.length` while `.length` returned null.",
+    "THE TABLE EARNED ITS KEEP ON THE FIRST INDEPENDENT IMPLEMENTATION, exactly as this manifest predicted it would. The PHP port -- written against these rows rather than against the TypeScript source -- failed 1 of 44 on its first run: 0904, that an object has no `.length`. It is not a bug in the port. json_decode('{}', true) and json_decode('[]', true) produce the IDENTICAL value in PHP and array_is_list() calls both a list, so an EMPTY object is indistinguishable from an empty array and the length the array legitimately has is returned. A genuine cross-language expressiveness limit, the same one shared/value-equality/0210 records. Skipped there with the reason attached, and 0906 pins the identical rule with a NON-EMPTY object that every runtime can express -- the same two-row shape as flow/workflow-props 0106/0109."
   ]
 }

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."
+  ]
+}