@particle-academy/fancy-conformance 0.0.0 → 0.1.0

package/schema/suite-manifest.schema.json

@@ -0,0 +1,75 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://ui.particle.academy/schemas/conformance-suite-manifest.schema.json",
+  "title": "Fancy conformance suite manifest",
+  "type": "object",
+  "required": ["suite", "title", "since", "caseFormat", "contract"],
+  "properties": {
+    "$schema": { "type": "string" },
+    "suite": {
+      "description": "Path-shaped id, matching this file's directory under suites/.",
+      "type": "string",
+      "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*(?:/[a-z0-9]+(?:-[a-z0-9]+)*)*$"
+    },
+    "title": { "type": "string", "minLength": 1 },
+    "since": {
+      "description": "Suite version in which this suite first appeared.",
+      "type": "string",
+      "pattern": "^[0-9]+\\.[0-9]+\\.[0-9]+$"
+    },
+    "caseFormat": {
+      "description": "'table' — one cases.json whose rows are the cases; for pure functions. 'directory' — cases/<id>/ holding input + expected artifacts; for capabilities that emit files.",
+      "enum": ["table", "directory"]
+    },
+    "cases": {
+      "description": "For caseFormat=table, the file holding the rows. Defaults to cases.json.",
+      "type": "string"
+    },
+    "contract": {
+      "type": "object",
+      "required": ["summary", "implementations"],
+      "properties": {
+        "summary": { "type": "string", "minLength": 1 },
+        "function": { "type": "string" },
+        "functions": {
+          "type": "object",
+          "additionalProperties": { "type": "string" }
+        },
+        "runShape": { "type": "object" },
+        "reference": {
+          "description": "Which language's behaviour the goldens were taken from. Goldens are never what a value 'obviously' is.",
+          "enum": ["php", "node", "rust", "python", "go"]
+        },
+        "referenceNote": { "type": "string" },
+        "implementations": {
+          "type": "array",
+          "minItems": 1,
+          "items": {
+            "type": "object",
+            "required": ["language", "package"],
+            "properties": {
+              "language": { "enum": ["php", "node", "rust", "python", "go"] },
+              "package": { "type": "string", "minLength": 1 },
+              "symbol": { "type": "string" }
+            },
+            "additionalProperties": false
+          }
+        }
+      },
+      "additionalProperties": false
+    },
+    "normalisation": {
+      "description": "For artifact suites only: which parts of an emitted document are ignored when comparing. Declared once per suite so a comparison never quietly loosens per case.",
+      "type": "object",
+      "properties": {
+        "ignoreAttributes": { "type": "array", "items": { "type": "string" } },
+        "orderInsensitive": { "type": "array", "items": { "type": "string" } },
+        "whitespace": { "enum": ["preserve", "collapse-between-elements"] },
+        "newline": { "enum": ["lf", "crlf", "preserve"] }
+      },
+      "additionalProperties": false
+    },
+    "notes": { "type": "array", "items": { "type": "string" } }
+  },
+  "additionalProperties": false
+}

package/suites/shared/decimal/cases.json

@@ -0,0 +1,182 @@
+{
+  "$schema": "../../../schema/case-table.schema.json",
+  "suite": "shared/decimal",
+  "cases": [
+    {
+      "id": "0001-format-plain",
+      "title": "formatFloat leaves ordinary numbers alone",
+      "since": "0.1.0",
+      "tags": ["formatFloat", "regression"],
+      "fn": "formatFloat",
+      "input": { "value": 1.5 },
+      "expected": "1.5"
+    },
+    {
+      "id": "0002-format-integral",
+      "title": "formatFloat keeps trailing zeros in the integer part",
+      "since": "0.1.0",
+      "tags": ["formatFloat"],
+      "fn": "formatFloat",
+      "input": { "value": 1200 },
+      "expected": "1200",
+      "notes": "Only the FRACTION is trimmed. A blanket trailing-zero strip turns 1200 into 12."
+    },
+    {
+      "id": "0003-format-1e300",
+      "title": "formatFloat expands 1e300 exactly, never exponentially",
+      "since": "0.1.0",
+      "tags": ["formatFloat", "exponent", "hazard"],
+      "fn": "formatFloat",
+      "input": { "value": 1e300 },
+      "expected": "1000000000000000052504760255204420248704468581108159154915854115511802457988908195786371375080447864043704443832883878176942523235360430575644792184786706982848387200926575803737830233794788090059368953234970799945081119038967640880074652742780142494579258788820056842838115669472196386865459400540160",
+      "notes": "The severe one. toFixed goes exponential at 1e21, and a trailing-zero strip then eats the EXPONENT: (1e300).toFixed(14) is '1e+300', which strips to '1e+3'. 1e300 was written into spreadsheets as 1e3 — not a crash, not invalid XML, just a different number in a file someone opens later and believes. NOTE the golden is NOT 1 followed by 300 zeros: number_format prints the exact value of the double, and the nearest double to 1e300 is not 10^300."
+    },
+    {
+      "id": "0004-format-1e21-boundary",
+      "title": "formatFloat does not go exponential at the 1e21 boundary",
+      "since": "0.1.0",
+      "tags": ["formatFloat", "exponent", "hazard"],
+      "fn": "formatFloat",
+      "input": { "value": 1e21 },
+      "expected": "1000000000000000000000",
+      "notes": "1e21 is exactly where JS toFixed switches notation. `<v>1e+21</v>` is not valid cell content, so a reader may reject the whole sheet."
+    },
+    {
+      "id": "0005-format-negative-zero",
+      "title": "formatFloat collapses negative zero to 0",
+      "since": "0.1.0",
+      "tags": ["formatFloat", "edge"],
+      "fn": "formatFloat",
+      "input": { "value": -0.0 },
+      "expected": "0",
+      "notes": "Both engines already agreed here — this was listed as a divergence in the polyglot plan and checking proved it was not one. Kept because both sides drop the sign INCIDENTALLY (via number_format / toFixed) rather than by decision, so a faster hand-rolled formatter would reintroduce it."
+    },
+    {
+      "id": "0006-format-repeating",
+      "title": "formatFloat keeps 14 decimal places",
+      "since": "0.1.0",
+      "tags": ["formatFloat", "precision"],
+      "fn": "formatFloat",
+      "input": { "value": 0.3333333333333333 },
+      "expected": "0.33333333333333",
+      "notes": "14, not 15 or 17. The step where two implementations pick different precision is invisible until someone diffs two documents."
+    },
+    {
+      "id": "0007-format-negative",
+      "title": "formatFloat keeps the sign on a real negative",
+      "since": "0.1.0",
+      "tags": ["formatFloat", "regression"],
+      "fn": "formatFloat",
+      "input": { "value": -2.25 },
+      "expected": "-2.25"
+    },
+    {
+      "id": "0008-coerce-exponent",
+      "title": "numericStringToNumber reads exponent notation",
+      "since": "0.1.0",
+      "tags": ["numericStringToNumber", "exponent", "hazard"],
+      "fn": "numericStringToNumber",
+      "input": { "value": "1e5" },
+      "expected": 100000,
+      "notes": "parseInt stops at the first non-digit, so '1e5' became 1. PHP has read exponent notation in numeric strings since PHP 7, and the JS helper's own docstring claimed it mirrored PHP."
+    },
+    {
+      "id": "0009-coerce-negative-exponent",
+      "title": "numericStringToNumber reads a negative exponent",
+      "since": "0.1.0",
+      "tags": ["numericStringToNumber", "exponent"],
+      "fn": "numericStringToNumber",
+      "input": { "value": "2e-3" },
+      "expected": 0.002,
+      "notes": "PHP's dot-test-then-(int) path returned 0 for this — a value silently becoming zero is the worst failure mode in the table."
+    },
+    {
+      "id": "0010-coerce-int-overflow",
+      "title": "numericStringToNumber does not clamp at the platform integer max",
+      "since": "0.1.0",
+      "tags": ["numericStringToNumber", "overflow", "hazard"],
+      "fn": "numericStringToNumber",
+      "input": { "value": "1e21" },
+      "expected": 1e21,
+      "notes": "PHP's (int) '1e21' clamps to PHP_INT_MAX (9223372036854775807), which is not the number anyone wrote. Rust and Go have the same trap with i64."
+    },
+    {
+      "id": "0011-coerce-leading-zeros",
+      "title": "numericStringToNumber ignores leading zeros",
+      "since": "0.1.0",
+      "tags": ["numericStringToNumber", "regression"],
+      "fn": "numericStringToNumber",
+      "input": { "value": "007" },
+      "expected": 7,
+      "notes": "Must NOT be read as octal — a trap in several languages' parse routines."
+    },
+    {
+      "id": "0012-coerce-leading-dot",
+      "title": "numericStringToNumber accepts a leading dot",
+      "since": "0.1.0",
+      "tags": ["numericStringToNumber", "regression"],
+      "fn": "numericStringToNumber",
+      "input": { "value": ".5" },
+      "expected": 0.5
+    },
+    {
+      "id": "0013-round-positive-half",
+      "title": "roundMoney rounds a positive half away from zero",
+      "since": "0.1.0",
+      "tags": ["roundMoney", "money"],
+      "fn": "roundMoney",
+      "input": { "value": 2.5 },
+      "expected": 3,
+      "notes": "PHP round() and JS Math.round() agree here, which is exactly why the divergence below went unnoticed."
+    },
+    {
+      "id": "0014-round-negative-half",
+      "title": "roundMoney rounds a negative half away from zero",
+      "since": "0.1.0",
+      "tags": ["roundMoney", "money", "hazard", "live-divergence"],
+      "fn": "roundMoney",
+      "input": { "value": -2.5 },
+      "expected": -3,
+      "notes": "LIVE DIVERGENCE at the time this suite was written. PHP round(-2.5) is -3 (half away from zero); JS Math.round(-2.5) is -2 (half toward +Infinity). fancy-mlm-js's amountAsInt is documented as a mirror of fancy-mlm-php's and is not one. Reachable through configuration: levelFactors is `.map(Number)` off host config with no sign validation, so a negative factor produces a negative reward, and the two backends then pay different amounts for the same event."
+    },
+    {
+      "id": "0015-round-negative-half-small",
+      "title": "roundMoney rounds -0.5 to -1, not to zero",
+      "since": "0.1.0",
+      "tags": ["roundMoney", "money", "hazard", "live-divergence"],
+      "fn": "roundMoney",
+      "input": { "value": -0.5 },
+      "expected": -1,
+      "notes": "The starkest row: JS Math.round(-0.5) is -0, so a clawback of half a unit becomes NOTHING on one backend and a whole unit on the other."
+    },
+    {
+      "id": "0016-round-symmetry",
+      "title": "roundMoney is symmetric about zero",
+      "since": "0.1.0",
+      "tags": ["roundMoney", "money"],
+      "fn": "roundMoney",
+      "input": { "value": -1.5 },
+      "expected": -2,
+      "notes": "The property that matters for money: |round(-x)| == |round(x)|. A credit and its matching clawback must cancel exactly, or a ledger drifts by a unit per reversal."
+    },
+    {
+      "id": "0017-round-below-half",
+      "title": "roundMoney rounds below a half toward zero",
+      "since": "0.1.0",
+      "tags": ["roundMoney", "regression"],
+      "fn": "roundMoney",
+      "input": { "value": -2.4 },
+      "expected": -2,
+      "notes": "Both engines already agree. Present so an implementation switching to a blanket floor/ceil fails rather than passing the halves by luck."
+    },
+    {
+      "id": "0018-round-above-half",
+      "title": "roundMoney rounds above a half away from zero",
+      "since": "0.1.0",
+      "tags": ["roundMoney", "regression"],
+      "fn": "roundMoney",
+      "input": { "value": -2.6 },
+      "expected": -3
+    }
+  ]
+}

package/suites/shared/decimal/manifest.json

@@ -0,0 +1,29 @@
+{
+  "$schema": "../../../schema/suite-manifest.schema.json",
+  "suite": "shared/decimal",
+  "title": "Number formatting, numeric-string coercion, and money rounding",
+  "since": "0.1.0",
+  "caseFormat": "table",
+  "cases": "cases.json",
+  "contract": {
+    "summary": "Three separate functions that every backend needs and that every backend has so far gotten subtly differently.",
+    "functions": {
+      "formatFloat": "formatFloat(v: float) -> string — a float as it is written into a document, plain decimal, never exponential",
+      "numericStringToNumber": "numericStringToNumber(s: string) -> number — coercion of a numeric STRING supplied by a host",
+      "roundMoney": "roundMoney(v: float) -> int — the rounding applied to a currency/points amount before it is paid out"
+    },
+    "reference": "php",
+    "referenceNote": "PHP is the reference for all three because the pair's contract is 'same result either backend' and PHP is what shipped first. formatFloat is `rtrim(rtrim(number_format((float) $v, 14, '.', ''), '0'), '.')`; roundMoney is `(int) round($v)`.",
+    "implementations": [
+      { "language": "php", "package": "particle-academy/holy-sheet", "symbol": "formatFloat, numericStringToNumber" },
+      { "language": "node", "package": "@particle-academy/holy-sheet-js", "symbol": "formatFloat, numericStringToNumber" },
+      { "language": "php", "package": "particle-academy/fancy-mlm-php", "symbol": "RewardComputation::amountAsInt" },
+      { "language": "node", "package": "@particle-academy/fancy-mlm-js", "symbol": "amountAsInt" }
+    ]
+  },
+  "notes": [
+    "Every formatFloat/numericStringToNumber case here was a live PHP-vs-JS disagreement in shipped packages, fixed in holy-sheet 2.0.1 / holy-sheet-js 2.1.0. They are pinned so a third language inherits the behaviour rather than the assumption.",
+    "The roundMoney cases are NOT historical. They were found by writing this suite on 2026-08-10 and are a live divergence at the time of writing: PHP round() is half-away-from-zero, JS Math.round() is half-toward-positive-infinity, and they disagree on every negative half.",
+    "Goldens are not what the value 'obviously' is. number_format prints the exact value of the double, and the nearest double to 1e300 is not 10^300 — see case 0003."
+  ]
+}

package/suites/shared/satisfies-range/cases.json

@@ -0,0 +1,147 @@
+{
+  "$schema": "../../../schema/case-table.schema.json",
+  "suite": "shared/satisfies-range",
+  "cases": [
+    {
+      "id": "0001-caret-pre-1.0-patch",
+      "title": "^0.15 accepts a patch bump",
+      "since": "0.1.0",
+      "tags": ["caret", "pre-1.0"],
+      "input": { "version": "0.15.1", "range": "^0.15" },
+      "expected": true
+    },
+    {
+      "id": "0002-caret-pre-1.0-minor",
+      "title": "^0.15 rejects a minor bump",
+      "since": "0.1.0",
+      "tags": ["caret", "pre-1.0"],
+      "input": { "version": "0.16.0", "range": "^0.15" },
+      "expected": false,
+      "notes": "Below 1.0.0 a minor bump is breaking, so ^0.15 means 0.15.x. This is the range every pre-1.0 package in the suite actually needs."
+    },
+    {
+      "id": "0003-caret-post-1.0-minor",
+      "title": "^1.0 accepts a minor bump",
+      "since": "0.1.0",
+      "tags": ["caret"],
+      "input": { "version": "1.2.0", "range": "^1.0" },
+      "expected": true
+    },
+    {
+      "id": "0004-caret-post-1.0-major",
+      "title": "^1.0 rejects a major bump",
+      "since": "0.1.0",
+      "tags": ["caret"],
+      "input": { "version": "2.0.0", "range": "^1.0" },
+      "expected": false
+    },
+    {
+      "id": "0005-gte-equal",
+      "title": ">=0.7 accepts the boundary itself",
+      "since": "0.1.0",
+      "tags": ["comparator"],
+      "input": { "version": "0.7.0", "range": ">=0.7" },
+      "expected": true
+    },
+    {
+      "id": "0006-gte-below",
+      "title": ">=0.7 rejects a lower version",
+      "since": "0.1.0",
+      "tags": ["comparator"],
+      "input": { "version": "0.5.0", "range": ">=0.7" },
+      "expected": false
+    },
+    {
+      "id": "0007-tilde-patch",
+      "title": "~0.7.1 accepts a higher patch",
+      "since": "0.1.0",
+      "tags": ["tilde"],
+      "input": { "version": "0.7.3", "range": "~0.7.1" },
+      "expected": true
+    },
+    {
+      "id": "0008-tilde-minor",
+      "title": "~0.7.1 rejects a minor bump",
+      "since": "0.1.0",
+      "tags": ["tilde"],
+      "input": { "version": "0.8.0", "range": "~0.7.1" },
+      "expected": false
+    },
+    {
+      "id": "0009-wildcard",
+      "title": "* accepts anything",
+      "since": "0.1.0",
+      "tags": ["wildcard"],
+      "input": { "version": "9.9.9", "range": "*" },
+      "expected": true
+    },
+    {
+      "id": "0010-union",
+      "title": "A || union accepts either side",
+      "since": "0.1.0",
+      "tags": ["union"],
+      "input": { "version": "0.7.0", "range": "^0.5 || ^0.7" },
+      "expected": true
+    },
+    {
+      "id": "0011-prerelease-included",
+      "title": "^1.2 accepts a prerelease of a matching version",
+      "since": "0.1.0",
+      "tags": ["caret", "prerelease", "non-standard"],
+      "input": { "version": "1.2.3-beta.1", "range": "^1.2" },
+      "expected": true,
+      "notes": "DIFFERS FROM STANDARD SEMVER, which returns false because prereleases are excluded from ranges unless the range itself carries one. Reaching for a stock semver library gives the wrong answer here: a node the host would accept is refused at load."
+    },
+    {
+      "id": "0012-caret-zero-zero",
+      "title": "^0.0.1 accepts a higher 0.0.x patch",
+      "since": "0.1.0",
+      "tags": ["caret", "pre-1.0", "non-standard"],
+      "input": { "version": "0.0.2", "range": "^0.0.1" },
+      "expected": true,
+      "notes": "DIFFERS FROM STANDARD SEMVER, where ^0.0.1 pins 0.0.1 exactly. Here the caret rule keys on the major being 0 and compares the MINOR, so 0.0.x is an open patch range. Wrong in the opposite direction from case 0011: a node loads that standard semver would have refused."
+    },
+    {
+      "id": "0013-empty-range",
+      "title": "An empty range accepts anything",
+      "since": "0.1.0",
+      "tags": ["wildcard", "edge"],
+      "input": { "version": "1.0.0", "range": "" },
+      "expected": true
+    },
+    {
+      "id": "0014-bare-version-exact",
+      "title": "A bare version is an exact match",
+      "since": "0.1.0",
+      "tags": ["exact"],
+      "input": { "version": "1.2.3", "range": "1.2.3" },
+      "expected": true
+    },
+    {
+      "id": "0015-whitespace-trimmed",
+      "title": "Surrounding whitespace is trimmed",
+      "since": "0.1.0",
+      "tags": ["edge"],
+      "input": { "version": "1.2.3", "range": " ^1.2 " },
+      "expected": true
+    },
+    {
+      "id": "0016-two-digit-major-union",
+      "title": "A union parses a two-digit major",
+      "since": "0.1.0",
+      "tags": ["union", "edge"],
+      "input": { "version": "10.0.0", "range": "^9 || ^10" },
+      "expected": true,
+      "notes": "Guards the naive single-digit regex. An implementation that matches \\d rather than \\d+ passes every other row in this table and fails only here."
+    },
+    {
+      "id": "0017-unparseable-fails-closed",
+      "title": "An unparseable range is unsatisfied, not waved through",
+      "since": "0.1.0",
+      "tags": ["edge", "fail-closed"],
+      "input": { "version": "1.0.0", "range": "not-a-range" },
+      "expected": false,
+      "notes": "Fails CLOSED. The tempting alternative — treat anything unrecognised as permissive — turns a typo in a manifest into a node that loads on hosts it was never checked against."
+    }
+  ]
+}

package/suites/shared/satisfies-range/manifest.json

@@ -0,0 +1,21 @@
+{
+  "$schema": "../../../schema/suite-manifest.schema.json",
+  "suite": "shared/satisfies-range",
+  "title": "Minimal semver range matching",
+  "since": "0.1.0",
+  "caseFormat": "table",
+  "cases": "cases.json",
+  "contract": {
+    "function": "satisfiesRange(version: string, range: string): boolean",
+    "summary": "Does a concrete version satisfy a manifest's declared range?",
+    "implementations": [
+      { "language": "node", "package": "@particle-academy/fancy-ui-cli", "symbol": "satisfiesRange" },
+      { "language": "node", "package": "@particle-academy/fancy-flow", "symbol": "satisfiesRange" },
+      { "language": "php", "package": "particle-academy/fancy-flow-php", "symbol": "NodeManifest::satisfiesRange" }
+    ]
+  },
+  "notes": [
+    "This suite is the one promoted verbatim from code that already existed, because it is the proof the method works. Three independent implementations of this function have NOT drifted, and the only thing they do differently from the suite's other triplicated contracts is that each carries this identical table in its own CI.",
+    "Two rows deliberately disagree with standard semver. They are tagged `non-standard` and a fourth implementation reaching for a stock semver library will fail exactly those two. That is the intended outcome: the disagreement should be a red build, not a discovery."
+  ]
+}