@particle-academy/fancy-conformance 0.0.0 → 0.2.0

package/dist/index.js

@@ -0,0 +1,168 @@
+// src/index.ts
+import { readFileSync, readdirSync, statSync } from "fs";
+import { dirname, join, relative, resolve, sep } from "path";
+import { fileURLToPath } from "url";
+function packageRoot() {
+  let dir = dirname(fileURLToPath(import.meta.url));
+  for (let i = 0; i < 6; i++) {
+    try {
+      if (statSync(join(dir, "suites")).isDirectory()) {
+        return dir;
+      }
+    } catch {
+    }
+    const parent = dirname(dir);
+    if (parent === dir) break;
+    dir = parent;
+  }
+  throw new Error(
+    "fancy-conformance: could not locate the suites/ directory. If you vendored this package, keep suites/ next to dist/."
+  );
+}
+function suiteVersion() {
+  return readFileSync(join(packageRoot(), "VERSION"), "utf8").trim();
+}
+function listSuites() {
+  const root = join(packageRoot(), "suites");
+  const found = [];
+  const walk = (dir) => {
+    for (const entry of readdirSync(dir, { withFileTypes: true })) {
+      if (!entry.isDirectory()) continue;
+      const child = join(dir, entry.name);
+      try {
+        statSync(join(child, "manifest.json"));
+        found.push(relative(root, child).split(sep).join("/"));
+      } catch {
+        walk(child);
+      }
+    }
+  };
+  walk(root);
+  return found.sort();
+}
+function loadSuite(id) {
+  return loadSuiteFrom(packageRoot(), id);
+}
+function loadSuiteFrom(root, id) {
+  const dir = join(root, "suites", ...id.split("/"));
+  const manifest = JSON.parse(readFileSync(join(dir, "manifest.json"), "utf8"));
+  if (manifest.caseFormat !== "table") {
+    throw new Error(
+      `fancy-conformance: suite "${id}" uses caseFormat "${manifest.caseFormat}", which loadSuite() does not read. Use the artifact runner in runners/.`
+    );
+  }
+  const table = JSON.parse(
+    readFileSync(join(dir, manifest.cases ?? "cases.json"), "utf8")
+  );
+  assertUsableCases(id, table.cases);
+  return { manifest, cases: table.cases };
+}
+function assertUsableCases(id, cases) {
+  const seen = /* @__PURE__ */ new Set();
+  for (const c of cases) {
+    if (seen.has(c.id)) {
+      throw new Error(`fancy-conformance: suite "${id}" has duplicate case id "${c.id}".`);
+    }
+    seen.add(c.id);
+    for (const [lang, reason] of Object.entries(c.skip ?? {})) {
+      if (typeof reason !== "string" || reason.trim() === "") {
+        throw new Error(
+          `fancy-conformance: case "${id}/${c.id}" skips ${lang} with no reason. A skip must say why, because every runner prints it.`
+        );
+      }
+    }
+  }
+}
+function runTable(suiteId, impl, options) {
+  const { manifest, cases } = loadSuite(suiteId);
+  const equals = options.equals ?? deepEquals;
+  const results = [];
+  for (const c of cases) {
+    const reason = c.skip?.[options.language];
+    if (reason !== void 0) {
+      results.push({ id: c.id, title: c.title, status: "skip", reason });
+      continue;
+    }
+    let actual;
+    try {
+      actual = impl(c);
+    } catch (error) {
+      results.push({
+        id: c.id,
+        title: c.title,
+        status: "fail",
+        expected: c.expected,
+        actual: `threw: ${error instanceof Error ? error.message : String(error)}`
+      });
+      continue;
+    }
+    results.push(
+      equals(actual, c.expected) ? { id: c.id, title: c.title, status: "pass" } : { id: c.id, title: c.title, status: "fail", expected: c.expected, actual }
+    );
+  }
+  const failed = results.filter((r) => r.status === "fail").length;
+  return {
+    suite: manifest.suite,
+    language: options.language,
+    suiteVersion: suiteVersion(),
+    passed: results.filter((r) => r.status === "pass").length,
+    failed,
+    skipped: results.filter((r) => r.status === "skip").length,
+    results,
+    ok: failed === 0
+  };
+}
+function formatSummary(summary) {
+  const lines = [
+    `${summary.suite} [${summary.language}] \u2014 fancy-conformance ${summary.suiteVersion}`,
+    `  ${summary.passed} passed, ${summary.failed} failed, ${summary.skipped} skipped`
+  ];
+  for (const r of summary.results) {
+    if (r.status === "skip") {
+      lines.push(`  SKIP ${r.id} \u2014 ${r.reason}`);
+    }
+    if (r.status === "fail") {
+      lines.push(`  FAIL ${r.id} ${r.title}`);
+      lines.push(`       expected: ${preview(r.expected)}`);
+      lines.push(`       actual:   ${preview(r.actual)}`);
+    }
+  }
+  return lines.join("\n");
+}
+function preview(value) {
+  const s = typeof value === "string" ? value : JSON.stringify(value);
+  if (s === void 0) return String(value);
+  return s.length > 120 ? `${s.slice(0, 60)}\u2026${s.slice(-40)} (len ${s.length})` : s;
+}
+function deepEquals(a, b) {
+  if (Object.is(a, b)) return true;
+  if (typeof a !== typeof b) return false;
+  if (a === null || b === null) return false;
+  if (Array.isArray(a) || Array.isArray(b)) {
+    if (!Array.isArray(a) || !Array.isArray(b) || a.length !== b.length) return false;
+    return a.every((v, i) => deepEquals(v, b[i]));
+  }
+  if (typeof a === "object") {
+    const ka = Object.keys(a).sort();
+    const kb = Object.keys(b).sort();
+    if (ka.length !== kb.length || ka.some((k, i) => k !== kb[i])) return false;
+    return ka.every(
+      (k) => deepEquals(a[k], b[k])
+    );
+  }
+  return false;
+}
+function suitePath(id) {
+  return resolve(join(packageRoot(), "suites", ...id.split("/")));
+}
+export {
+  deepEquals,
+  formatSummary,
+  listSuites,
+  loadSuite,
+  loadSuiteFrom,
+  runTable,
+  suitePath,
+  suiteVersion
+};
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/index.ts"],"sourcesContent":["import { readFileSync, readdirSync, statSync } from \"node:fs\";\nimport { dirname, join, relative, resolve, sep } from \"node:path\";\nimport { fileURLToPath } from \"node:url\";\n\nimport type {\n  CaseResult,\n  ConformanceCase,\n  Language,\n  RunSummary,\n  Suite,\n  SuiteManifest,\n} from \"./types\";\n\nexport * from \"./types\";\n\n/**\n * The repository root, whether this is running from `dist/` in an installed\n * package or from `src/` in a checkout.\n *\n * Resolved by walking up to the directory that holds `suites/`, rather than by\n * a fixed `../..`. The two existing parity harnesses in this suite both\n * hard-coded a relative path to a sibling checkout (`../../holy-sheet/src/`),\n * which is why they work in exactly one directory layout and silently no-op\n * everywhere else. This package must not repeat that.\n */\nfunction packageRoot(): string {\n  let dir = dirname(fileURLToPath(import.meta.url));\n\n  for (let i = 0; i < 6; i++) {\n    try {\n      if (statSync(join(dir, \"suites\")).isDirectory()) {\n        return dir;\n      }\n    } catch {\n      // keep walking\n    }\n    const parent = dirname(dir);\n    if (parent === dir) break;\n    dir = parent;\n  }\n\n  throw new Error(\n    \"fancy-conformance: could not locate the suites/ directory. \" +\n      \"If you vendored this package, keep suites/ next to dist/.\",\n  );\n}\n\n/** The suite collection's own version — the thing a runner must print. */\nexport function suiteVersion(): string {\n  return readFileSync(join(packageRoot(), \"VERSION\"), \"utf8\").trim();\n}\n\n/** Every suite id present, e.g. `[\"shared/decimal\", \"shared/satisfies-range\", …]`. */\nexport function listSuites(): string[] {\n  const root = join(packageRoot(), \"suites\");\n  const found: string[] = [];\n\n  const walk = (dir: string): void => {\n    for (const entry of readdirSync(dir, { withFileTypes: true })) {\n      if (!entry.isDirectory()) continue;\n      const child = join(dir, entry.name);\n      try {\n        statSync(join(child, \"manifest.json\"));\n        found.push(relative(root, child).split(sep).join(\"/\"));\n      } catch {\n        walk(child);\n      }\n    }\n  };\n\n  walk(root);\n  return found.sort();\n}\n\n/** Load one suite's manifest and cases. Throws rather than returning a partial. */\nexport function loadSuite(id: string): Suite {\n  return loadSuiteFrom(packageRoot(), id);\n}\n\n/**\n * Load a suite from an explicit root.\n *\n * Exported so the load-time guards below can be tested against a throwaway\n * fixture tree, rather than a test re-implementing them. A guard asserted by a\n * copy of itself is the failure mode this whole repository exists to stop, and\n * it would be an embarrassing one to ship here.\n */\nexport function loadSuiteFrom(root: string, id: string): Suite {\n  const dir = join(root, \"suites\", ...id.split(\"/\"));\n  const manifest = JSON.parse(readFileSync(join(dir, \"manifest.json\"), \"utf8\")) as SuiteManifest;\n\n  if (manifest.caseFormat !== \"table\") {\n    throw new Error(\n      `fancy-conformance: suite \"${id}\" uses caseFormat \"${manifest.caseFormat}\", ` +\n        \"which loadSuite() does not read. Use the artifact runner in runners/.\",\n    );\n  }\n\n  const table = JSON.parse(\n    readFileSync(join(dir, manifest.cases ?? \"cases.json\"), \"utf8\"),\n  ) as { cases: ConformanceCase[] };\n\n  assertUsableCases(id, table.cases);\n\n  return { manifest, cases: table.cases };\n}\n\n/**\n * Reject a case table that cannot do its job, at LOAD time.\n *\n * A skip with no reason, and a duplicate id, are both silent in every other\n * respect: the suite still loads, still reports green, and still covers less\n * than it appears to. That is the exact failure this repository exists to stop,\n * so it is a hard error here rather than a lint somewhere else.\n */\nfunction assertUsableCases(id: string, cases: ConformanceCase[]): void {\n  const seen = new Set<string>();\n\n  for (const c of cases) {\n    if (seen.has(c.id)) {\n      throw new Error(`fancy-conformance: suite \"${id}\" has duplicate case id \"${c.id}\".`);\n    }\n    seen.add(c.id);\n\n    for (const [lang, reason] of Object.entries(c.skip ?? {})) {\n      if (typeof reason !== \"string\" || reason.trim() === \"\") {\n        throw new Error(\n          `fancy-conformance: case \"${id}/${c.id}\" skips ${lang} with no reason. ` +\n            \"A skip must say why, because every runner prints it.\",\n        );\n      }\n    }\n  }\n}\n\nexport interface RunOptions {\n  /** Which language is under test — decides which `skip` entries apply. */\n  language: Language;\n  /**\n   * Compare a produced value with the expected one. Defaults to a\n   * canonicalising deep equality: object keys sorted, arrays order-sensitive.\n   */\n  equals?: (actual: unknown, expected: unknown) => boolean;\n}\n\n/**\n * Run one implementation against a table suite.\n *\n * `impl` receives the case and returns the value to compare. Throwing is a\n * failure, not a crash — a case that blows up is data about the implementation.\n */\nexport function runTable(\n  suiteId: string,\n  impl: (c: ConformanceCase) => unknown,\n  options: RunOptions,\n): RunSummary {\n  const { manifest, cases } = loadSuite(suiteId);\n  const equals = options.equals ?? deepEquals;\n  const results: CaseResult[] = [];\n\n  for (const c of cases) {\n    const reason = c.skip?.[options.language];\n    if (reason !== undefined) {\n      results.push({ id: c.id, title: c.title, status: \"skip\", reason });\n      continue;\n    }\n\n    let actual: unknown;\n    try {\n      actual = impl(c);\n    } catch (error) {\n      results.push({\n        id: c.id,\n        title: c.title,\n        status: \"fail\",\n        expected: c.expected,\n        actual: `threw: ${error instanceof Error ? error.message : String(error)}`,\n      });\n      continue;\n    }\n\n    results.push(\n      equals(actual, c.expected)\n        ? { id: c.id, title: c.title, status: \"pass\" }\n        : { id: c.id, title: c.title, status: \"fail\", expected: c.expected, actual },\n    );\n  }\n\n  const failed = results.filter((r) => r.status === \"fail\").length;\n\n  return {\n    suite: manifest.suite,\n    language: options.language,\n    suiteVersion: suiteVersion(),\n    passed: results.filter((r) => r.status === \"pass\").length,\n    failed,\n    skipped: results.filter((r) => r.status === \"skip\").length,\n    results,\n    ok: failed === 0,\n  };\n}\n\n/**\n * A summary a CI log can be read from — including every skip, by name and\n * reason.\n *\n * Skips are printed unconditionally and never folded into a count. \"3 skipped\"\n * in a log is indistinguishable from full coverage at a glance, which is how a\n * suite stops meaning anything without anyone deciding that it should.\n */\nexport function formatSummary(summary: RunSummary): string {\n  const lines: string[] = [\n    `${summary.suite} [${summary.language}] — fancy-conformance ${summary.suiteVersion}`,\n    `  ${summary.passed} passed, ${summary.failed} failed, ${summary.skipped} skipped`,\n  ];\n\n  for (const r of summary.results) {\n    if (r.status === \"skip\") {\n      lines.push(`  SKIP ${r.id} — ${r.reason}`);\n    }\n    if (r.status === \"fail\") {\n      lines.push(`  FAIL ${r.id} ${r.title}`);\n      lines.push(`       expected: ${preview(r.expected)}`);\n      lines.push(`       actual:   ${preview(r.actual)}`);\n    }\n  }\n\n  return lines.join(\"\\n\");\n}\n\nfunction preview(value: unknown): string {\n  const s = typeof value === \"string\" ? value : JSON.stringify(value);\n  if (s === undefined) return String(value);\n  return s.length > 120 ? `${s.slice(0, 60)}…${s.slice(-40)} (len ${s.length})` : s;\n}\n\n/** Order-sensitive for arrays, order-insensitive for object keys. */\nexport function deepEquals(a: unknown, b: unknown): boolean {\n  if (Object.is(a, b)) return true;\n  if (typeof a !== typeof b) return false;\n  if (a === null || b === null) return false;\n\n  if (Array.isArray(a) || Array.isArray(b)) {\n    if (!Array.isArray(a) || !Array.isArray(b) || a.length !== b.length) return false;\n    return a.every((v, i) => deepEquals(v, b[i]));\n  }\n\n  if (typeof a === \"object\") {\n    const ka = Object.keys(a as object).sort();\n    const kb = Object.keys(b as object).sort();\n    if (ka.length !== kb.length || ka.some((k, i) => k !== kb[i])) return false;\n    return ka.every((k) =>\n      deepEquals((a as Record<string, unknown>)[k], (b as Record<string, unknown>)[k]),\n    );\n  }\n\n  return false;\n}\n\n/** Absolute path to a suite's directory — for runners that read artifacts. */\nexport function suitePath(id: string): string {\n  return resolve(join(packageRoot(), \"suites\", ...id.split(\"/\")));\n}\n"],"mappings":"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","names":[]}

package/package.json

@@ -1,13 +1,79 @@
 {
   "name": "@particle-academy/fancy-conformance",
-  "version": "0.0.0",
-  "description": "Placeholder to claim the name. The real package is published from CI with provenance — see https://github.com/Particle-Academy/fancy-conformance",
-  "license": "MIT",
+  "version": "0.2.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",
     "url": "git+https://github.com/Particle-Academy/fancy-conformance.git"
   },
+  "homepage": "https://github.com/Particle-Academy/fancy-conformance#readme",
+  "bugs": "https://github.com/Particle-Academy/fancy-conformance/issues",
+  "type": "module",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./dist/index.d.ts",
+        "default": "./dist/index.js"
+      },
+      "require": {
+        "types": "./dist/index.d.cts",
+        "default": "./dist/index.cjs"
+      }
+    },
+    "./suites/*": "./suites/*",
+    "./schema/*": "./schema/*",
+    "./parity/*": "./parity/*",
+    "./VERSION": "./VERSION",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist",
+    "suites",
+    "schema",
+    "parity",
+    "runners",
+    "VERSION",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "lint": "tsc --noEmit",
+    "test": "node --import tsx --test tests/*.test.ts",
+    "cross-check": "node --import tsx scripts/cross-check.mjs",
+    "clean": "rm -rf dist",
+    "prepublishOnly": "tsup"
+  },
+  "devDependencies": {
+    "@types/node": "^26.2.0",
+    "tsup": "^8.5.0",
+    "tsx": "^4.19.0",
+    "typescript": "^5.8.0"
+  },
   "publishConfig": {
     "access": "public"
+  },
+  "keywords": [
+    "conformance",
+    "fixtures",
+    "parity",
+    "cross-language",
+    "polyglot",
+    "golden-files",
+    "contract-testing",
+    "fancy-ui",
+    "particle-academy"
+  ],
+  "license": "MIT",
+  "sideEffects": false,
+  "overrides": {
+    "esbuild": "^0.28.1"
+  },
+  "engines": {
+    "node": ">=22"
   }
 }

package/parity/README.md

@@ -0,0 +1,41 @@
+# The release-parity ledger
+
+The fixtures in `suites/` answer one question: **does this implementation
+satisfy contract X?**
+
+They cannot answer a second, separate one: **has this implementation evaluated
+the newest canonical PHP release?** An implementation can pass every fixture it
+has and still be a release behind, because a PHP release that changed nothing
+about a contract does not change a single fixture — and a stale mirror looks
+exactly like a current one from the outside.
+
+That is what the ledger is for. It lives here, next to the fixtures, because the
+two are read together and a claim of "current" needs both.
+
+## The rules
+
+- A PHP release with **no contract change** requires no fixture churn and no
+  mirror release. It still **invalidates every stale attestation** until each
+  mirror runs its pinned suite against the newly declared PHP release.
+- A PHP release with a **compatible or breaking contract change** must publish
+  the new fixtures **before** any mirror can attest `current`.
+- `status: current` requires an `implementation`, a `conformance_ref`, an
+  `attestation_url`, an `owner` and an `updated_at`. Four of those five are
+  things a human has to be able to click, which is the point.
+- `status: pending` or `blocked` requires a `tracking_issue`. A mirror that is
+  behind with nowhere to look is indistinguishable from a mirror nobody owns.
+
+`ledger.schema.json` enforces all of the above, including the conditional
+requirements, so a hand-edited entry that omits its evidence fails validation
+rather than reading as a claim.
+
+## Why there is no `ledger.json` yet
+
+Because nothing has attested yet, and a ledger seeded with plausible-looking
+version numbers and commit hashes would be worse than an absent one — it would
+assert parity that no run has demonstrated, which is precisely the failure this
+repository exists to end.
+
+The first entry lands when the first mirror runs its pinned suite in its own CI
+and has an attestation URL to point at. Until then the schema is the contract
+and this file is the procedure.

package/parity/ledger.schema.json

@@ -0,0 +1,176 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://ui.particle.academy/schemas/parity-ledger.schema.json",
+  "title": "Fancy capability release parity ledger",
+  "type": "object",
+  "required": ["schema_version", "generated_at", "capabilities"],
+  "properties": {
+    "schema_version": {
+      "const": 1
+    },
+    "generated_at": {
+      "type": "string",
+      "format": "date-time"
+    },
+    "capabilities": {
+      "type": "array",
+      "items": {
+        "$ref": "#/$defs/capability"
+      }
+    }
+  },
+  "additionalProperties": false,
+  "$defs": {
+    "version": {
+      "type": "string",
+      "pattern": "^v?[0-9]+\\.[0-9]+\\.[0-9]+(?:[-+][0-9A-Za-z.-]+)?$"
+    },
+    "packageRelease": {
+      "type": "object",
+      "required": ["package", "version", "commit"],
+      "properties": {
+        "package": {
+          "type": "string",
+          "minLength": 1
+        },
+        "version": {
+          "$ref": "#/$defs/version"
+        },
+        "commit": {
+          "type": "string",
+          "pattern": "^[0-9a-f]{40}$"
+        }
+      },
+      "additionalProperties": false
+    },
+    "mirror": {
+      "type": "object",
+      "required": [
+        "language",
+        "status",
+        "canonical_php_version",
+        "contract_version"
+      ],
+      "properties": {
+        "language": {
+          "enum": ["node", "rust", "python", "go"]
+        },
+        "status": {
+          "enum": ["current", "pending", "blocked", "unsupported", "deprecated"]
+        },
+        "canonical_php_version": {
+          "$ref": "#/$defs/version"
+        },
+        "contract_version": {
+          "$ref": "#/$defs/version"
+        },
+        "implementation": {
+          "$ref": "#/$defs/packageRelease"
+        },
+        "conformance_ref": {
+          "type": "string",
+          "minLength": 1
+        },
+        "attestation_url": {
+          "type": "string",
+          "format": "uri"
+        },
+        "tracking_issue": {
+          "type": "string",
+          "format": "uri"
+        },
+        "reason": {
+          "type": "string",
+          "minLength": 1
+        },
+        "owner": {
+          "type": "string",
+          "minLength": 1
+        },
+        "updated_at": {
+          "type": "string",
+          "format": "date-time"
+        }
+      },
+      "allOf": [
+        {
+          "if": {
+            "properties": {
+              "status": {
+                "const": "current"
+              }
+            }
+          },
+          "then": {
+            "required": [
+              "implementation",
+              "conformance_ref",
+              "attestation_url",
+              "owner",
+              "updated_at"
+            ]
+          }
+        },
+        {
+          "if": {
+            "properties": {
+              "status": {
+                "enum": ["blocked", "unsupported", "deprecated"]
+              }
+            }
+          },
+          "then": {
+            "required": ["reason", "owner", "updated_at"]
+          }
+        },
+        {
+          "if": {
+            "properties": {
+              "status": {
+                "enum": ["pending", "blocked"]
+              }
+            }
+          },
+          "then": {
+            "required": ["tracking_issue"]
+          }
+        }
+      ],
+      "additionalProperties": false
+    },
+    "capability": {
+      "type": "object",
+      "required": [
+        "capability",
+        "contract_version",
+        "conformance_ref",
+        "canonical_php",
+        "mirrors"
+      ],
+      "properties": {
+        "capability": {
+          "type": "string",
+          "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$"
+        },
+        "contract_version": {
+          "$ref": "#/$defs/version"
+        },
+        "conformance_ref": {
+          "type": "string",
+          "minLength": 1
+        },
+        "canonical_php": {
+          "$ref": "#/$defs/packageRelease"
+        },
+        "mirrors": {
+          "type": "array",
+          "items": {
+            "$ref": "#/$defs/mirror"
+          },
+          "minItems": 1
+        }
+      },
+      "additionalProperties": false
+    }
+  }
+}

package/runners/README.md

@@ -0,0 +1,93 @@
+# Writing a runner
+
+A runner connects one implementation to the fixtures. There are two kinds,
+because there are two kinds of suite.
+
+## Table suites (`caseFormat: "table"`)
+
+The whole suite is one JSON file of rows. A runner loads it, calls the function
+under test once per row, and compares. No subprocess, no temp files.
+
+Both loaders shipped here — `src/index.ts` for Node, `php/src/Conformance.php`
+for PHP — do this for you and produce an identical summary shape:
+
+```ts
+import { runTable, formatSummary } from "@particle-academy/fancy-conformance";
+import { satisfiesRange } from "../src/marketplace/manifest";
+
+const summary = runTable(
+  "shared/satisfies-range",
+  (c) => satisfiesRange(c.input.version, c.input.range),
+  { language: "node" },
+);
+
+console.log(formatSummary(summary));   // ALWAYS print it — see below
+if (!summary.ok) process.exit(1);
+```
+
+```php
+use ParticleAcademy\Conformance\Conformance;
+
+$summary = Conformance::runTable(
+    'shared/satisfies-range',
+    fn (array $c) => NodeManifest::satisfiesRange($c['input']['version'], $c['input']['range']),
+);
+
+echo Conformance::formatSummary($summary), "\n";
+exit($summary['ok'] ? 0 : 1);
+```
+
+For a language with no loader yet, the file format is small enough to read
+directly: `suites/<id>/manifest.json` names the contract, `cases.json` holds
+`{id, title, since, tags?, fn?, input, expected, skip?, notes?}` rows.
+
+## Artifact suites (`caseFormat: "directory"`)
+
+For capabilities that emit a document rather than return a value. Each case is a
+directory holding `input.json`, `expected/`, and `meta.json`, and the
+implementation is driven as a subprocess through a fixed CLI:
+
+```
+<impl-cli> <suite> <case-dir> --out <dir> [--now <iso8601>] [--profile canonical]
+
+exit 0 — produced output
+exit 2 — case not supported (MUST match a `skip` entry in the case's meta)
+```
+
+One neutral runner drives every implementation through that CLI. This is
+deliberately *not* "each language writes its own harness": a per-language
+harness is how the `holy-sheet` and `dark-slide` parity suites became
+directory-layout-dependent and silently skippable.
+
+Binary containers are **never** compared byte-for-byte as shipped. PHP writes
+via `ZipArchive` (DEFLATE, real mtimes); the JS ports write STORE with a fixed
+1980-01-01 DOS date. Those files can never match. The comparison is two-tier —
+normalised parts first, then an optional rezip to a single canonical profile —
+and the normalisation is declared once in the suite manifest so it cannot
+quietly loosen per case.
+
+Every writer therefore needs a determinism flag (`--now` or equivalent).
+Without one, a case cannot be a golden fixture at all.
+
+## Four rules a runner must follow
+
+These are not style preferences. Each one is traceable to a suite in this org
+that reported green while covering nothing.
+
+1. **Run on every push and PR.** Not nightly, not at release.
+2. **A missing toolchain is a FAILURE, not a skip.** `skipIf(!HAS_PHP)`
+   returning green is the exact mechanism that hid two-way drift for months.
+   If the suite cannot run, the job goes red.
+3. **Print the summary unconditionally, including every skip and its reason.**
+   Both `formatSummary` helpers do this. A bare "3 skipped" in a log reads
+   identically to full coverage at a glance.
+4. **Print and assert the pinned suite version.** `suiteVersion()` /
+   `Conformance::version()`. "We're on an old fixture set" should be visible in
+   the log rather than inferred months later.
+
+## Adding a case
+
+A new case lands **here first, red**, then in each implementation. Where an
+implementation cannot pass it yet, it gets a `skip` entry with a real reason and
+a tracking issue — and the skip shows up in that repo's CI log every run until
+it is gone.

package/schema/case-table.schema.json

@@ -0,0 +1,55 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://ui.particle.academy/schemas/conformance-case-table.schema.json",
+  "title": "Fancy conformance case table",
+  "type": "object",
+  "required": ["suite", "cases"],
+  "properties": {
+    "$schema": { "type": "string" },
+    "suite": { "type": "string", "minLength": 1 },
+    "cases": {
+      "type": "array",
+      "minItems": 1,
+      "items": { "$ref": "#/$defs/case" }
+    }
+  },
+  "additionalProperties": false,
+  "$defs": {
+    "case": {
+      "type": "object",
+      "required": ["id", "title", "since", "input", "expected"],
+      "properties": {
+        "id": {
+          "description": "Stable, ordered, unique within the suite. Never renumber — an id appears in changelogs and in other repos' skip lists.",
+          "type": "string",
+          "pattern": "^[0-9]{4}-[a-z0-9]+(?:[-.][a-z0-9]+)*$"
+        },
+        "title": { "type": "string", "minLength": 1 },
+        "since": {
+          "type": "string",
+          "pattern": "^[0-9]+\\.[0-9]+\\.[0-9]+$"
+        },
+        "tags": {
+          "type": "array",
+          "items": { "type": "string", "minLength": 1 }
+        },
+        "fn": {
+          "description": "Which of the suite's functions this case exercises. Required when the suite declares contract.functions.",
+          "type": "string",
+          "minLength": 1
+        },
+        "input": { "type": "object" },
+        "expected": {},
+        "skip": {
+          "description": "The ONLY sanctioned way not to run a case. Keyed by language; the value is a REASON and may not be empty. A runner prints every skip in its summary — a silent skip is what turned two existing parity suites into decoration.",
+          "type": "object",
+          "propertyNames": { "enum": ["php", "node", "rust", "python", "go"] },
+          "additionalProperties": { "type": "string", "minLength": 1 },
+          "minProperties": 1
+        },
+        "notes": { "type": "string", "minLength": 1 }
+      },
+      "additionalProperties": false
+    }
+  }
+}