@particle-academy/fancy-conformance 0.2.0 → 0.4.0

package/suites/shared/flow-run-identity/cases.json

@@ -0,0 +1,241 @@
+{
+  "$schema": "../../../schema/case-table.schema.json",
+  "suite": "shared/flow-run-identity",
+  "cases": [
+    {
+      "id": "0001-top-level-step",
+      "title": "A node at the top level of a run keys on the run and its own id",
+      "since": "0.4.0",
+      "tags": ["stepkey"],
+      "fn": "stepKey",
+      "input": { "runKey": "run_9f2c1b0e77a4d310", "path": [], "nodeId": "pay", "occurrence": null, "attempt": 1 },
+      "expected": "run_9f2c1b0e77a4d310:pay"
+    },
+    {
+      "id": "0002-occurrence-zero-is-not-absent",
+      "title": "Occurrence 0 is a real occurrence and appears in the key",
+      "since": "0.4.0",
+      "tags": ["stepkey", "loop"],
+      "fn": "stepKey",
+      "input": { "runKey": "run_a", "path": [], "nodeId": "pay", "occurrence": 0, "attempt": 1 },
+      "expected": "run_a:pay#0",
+      "notes": "A falsy-but-present occurrence is the classic place a language's truthiness quietly drops the segment, collapsing iteration 0 into the un-iterated key."
+    },
+    {
+      "id": "0003-occurrence-distinguishes-iterations",
+      "title": "A different loop iteration is a different logical step",
+      "since": "0.4.0",
+      "tags": ["stepkey", "loop"],
+      "fn": "stepKey",
+      "input": { "runKey": "run_a", "path": [], "nodeId": "pay", "occurrence": 7, "attempt": 1 },
+      "expected": "run_a:pay#7"
+    },
+    {
+      "id": "0004-one-invocation-segment",
+      "title": "A node inside a subflow carries the invoking node as a path segment",
+      "since": "0.4.0",
+      "tags": ["stepkey", "subflow"],
+      "fn": "stepKey",
+      "input": { "runKey": "run_a", "path": ["billing"], "nodeId": "pay", "occurrence": null, "attempt": 1 },
+      "expected": "run_a:billing/pay"
+    },
+    {
+      "id": "0005-nested-invocations",
+      "title": "Nesting composes outermost-first",
+      "since": "0.4.0",
+      "tags": ["stepkey", "subflow"],
+      "fn": "stepKey",
+      "input": { "runKey": "run_a", "path": ["billing", "dunning#2"], "nodeId": "pay", "occurrence": null, "attempt": 1 },
+      "expected": "run_a:billing/dunning#2/pay",
+      "notes": "Path segments arrive already rendered - an invocation that repeats renders its own occurrence before it is pushed."
+    },
+    {
+      "id": "0006-node-id-slash-is-escaped",
+      "title": "A slash in a node id is escaped, never a separator",
+      "since": "0.4.0",
+      "tags": ["stepkey", "escaping"],
+      "fn": "stepKey",
+      "input": { "runKey": "run_a", "path": [], "nodeId": "a/b", "occurrence": null, "attempt": 1 },
+      "expected": "run_a:a%2Fb"
+    },
+    {
+      "id": "0007-the-collision-escaping-prevents",
+      "title": "A node `b` inside an invocation of `a` is NOT the node named `a/b`",
+      "since": "0.4.0",
+      "tags": ["stepkey", "escaping"],
+      "fn": "stepKey",
+      "input": { "runKey": "run_a", "path": ["a"], "nodeId": "b", "occurrence": null, "attempt": 1 },
+      "expected": "run_a:a/b",
+      "notes": "Read together with 0006. Unescaped, both spell run_a:a/b - two unrelated writes sharing one idempotency key, which the provider collapses into a single charge."
+    },
+    {
+      "id": "0008-node-id-hash-is-escaped",
+      "title": "A hash in a node id is escaped, so # only ever means occurrence",
+      "since": "0.4.0",
+      "tags": ["stepkey", "escaping"],
+      "fn": "stepKey",
+      "input": { "runKey": "run_a", "path": [], "nodeId": "a#2", "occurrence": null, "attempt": 1 },
+      "expected": "run_a:a%232"
+    },
+    {
+      "id": "0009-percent-is-escaped-first",
+      "title": "The escape character is itself escaped, and before everything else",
+      "since": "0.4.0",
+      "tags": ["stepkey", "escaping"],
+      "fn": "stepKey",
+      "input": { "runKey": "run_a", "path": [], "nodeId": "a%2Fb", "occurrence": null, "attempt": 1 },
+      "expected": "run_a:a%252Fb",
+      "notes": "An implementation that escapes / before % turns a literal a%2Fb into the same text as the escaped a/b from 0006 - the collision, reintroduced by the fix for it."
+    },
+    {
+      "id": "0010-escaping-and-occurrence-compose",
+      "title": "Escaping applies to the id, the occurrence marker stays structural",
+      "since": "0.4.0",
+      "tags": ["stepkey", "escaping", "loop"],
+      "fn": "stepKey",
+      "input": { "runKey": "run_a", "path": [], "nodeId": "a/b", "occurrence": 2, "attempt": 1 },
+      "expected": "run_a:a%2Fb#2"
+    },
+    {
+      "id": "0011-attempt-one-key",
+      "title": "The key on the first attempt",
+      "since": "0.4.0",
+      "tags": ["stepkey", "retry"],
+      "fn": "stepKey",
+      "input": { "runKey": "run_a", "path": [], "nodeId": "pay", "occurrence": null, "attempt": 1 },
+      "expected": "run_a:pay"
+    },
+    {
+      "id": "0012-attempt-does-not-change-the-key",
+      "title": "The fifth attempt of the SAME step sends the SAME key",
+      "since": "0.4.0",
+      "tags": ["stepkey", "retry"],
+      "fn": "stepKey",
+      "input": { "runKey": "run_a", "path": [], "nodeId": "pay", "occurrence": null, "attempt": 5 },
+      "expected": "run_a:pay",
+      "notes": "The load-bearing row of the whole suite, and it only means anything read against 0011. An implementation that mixes attempt into the key passes every other case here and double-charges in production on the first timeout."
+    },
+    {
+      "id": "0013-first-attempt-is-always-replay-safe",
+      "title": "Attempt 1 is safe however long the run was parked - nothing was sent before",
+      "since": "0.4.0",
+      "tags": ["replaysafe", "human-gate"],
+      "fn": "isReplaySafe",
+      "input": { "attempt": 1, "firstAttemptAt": "2026-08-01T00:00:00Z", "now": "2026-08-19T00:00:00Z", "windowSeconds": 86400 },
+      "expected": true,
+      "notes": "This is the human-gate case: a run parks on an approval for eighteen days, resumes, and the writing node executes for the first time. There is no earlier attempt for the provider to have forgotten."
+    },
+    {
+      "id": "0014-retry-inside-the-window",
+      "title": "A prompt retry is inside the provider dedup window",
+      "since": "0.4.0",
+      "tags": ["replaysafe", "retry"],
+      "fn": "isReplaySafe",
+      "input": { "attempt": 2, "firstAttemptAt": "2026-08-19T00:00:00Z", "now": "2026-08-19T00:00:30Z", "windowSeconds": 86400 },
+      "expected": true
+    },
+    {
+      "id": "0015-the-boundary-is-inclusive",
+      "title": "Exactly at the window is still inside it",
+      "since": "0.4.0",
+      "tags": ["replaysafe", "boundary"],
+      "fn": "isReplaySafe",
+      "input": { "attempt": 2, "firstAttemptAt": "2026-08-18T00:00:00Z", "now": "2026-08-19T00:00:00Z", "windowSeconds": 86400 },
+      "expected": true
+    },
+    {
+      "id": "0016-one-second-past-the-window",
+      "title": "One second past the window is outside it",
+      "since": "0.4.0",
+      "tags": ["replaysafe", "boundary"],
+      "fn": "isReplaySafe",
+      "input": { "attempt": 2, "firstAttemptAt": "2026-08-18T00:00:00Z", "now": "2026-08-19T00:00:01Z", "windowSeconds": 86400 },
+      "expected": false
+    },
+    {
+      "id": "0017-stripe-twenty-five-hours",
+      "title": "A retry 25h after the first attempt is not protected by the Stripe 24h window",
+      "since": "0.4.0",
+      "tags": ["replaysafe", "stripe"],
+      "fn": "isReplaySafe",
+      "input": { "attempt": 4, "firstAttemptAt": "2026-08-18T00:00:00Z", "now": "2026-08-19T01:00:00Z", "windowSeconds": 86400 },
+      "expected": false,
+      "notes": "Stripe forgets an idempotency key after 24 hours. Resending it creates a second charge, and sending a fresh one creates a second charge - so the only safe answer is to refuse and let a person reconcile."
+    },
+    {
+      "id": "0018-parked-a-week-then-first-write",
+      "title": "A week parked, then the node first attempt",
+      "since": "0.4.0",
+      "tags": ["replaysafe", "human-gate"],
+      "fn": "isReplaySafe",
+      "input": { "attempt": 1, "firstAttemptAt": "2026-08-12T09:15:00Z", "now": "2026-08-19T09:15:00Z", "windowSeconds": 86400 },
+      "expected": true
+    },
+    {
+      "id": "0019-zero-window-permits-no-retry",
+      "title": "A zero window means only the first attempt may write",
+      "since": "0.4.0",
+      "tags": ["replaysafe", "boundary"],
+      "fn": "isReplaySafe",
+      "input": { "attempt": 2, "firstAttemptAt": "2026-08-19T00:00:00Z", "now": "2026-08-19T00:00:00Z", "windowSeconds": 0 },
+      "expected": false,
+      "notes": "Zero is a window, not an absent one. An implementation treating 0 as null turns this provider does not dedupe into this provider dedupes forever."
+    },
+    {
+      "id": "0020-zero-window-first-attempt",
+      "title": "A zero window still permits the first attempt",
+      "since": "0.4.0",
+      "tags": ["replaysafe", "boundary"],
+      "fn": "isReplaySafe",
+      "input": { "attempt": 1, "firstAttemptAt": "2026-08-19T00:00:00Z", "now": "2026-08-19T00:00:00Z", "windowSeconds": 0 },
+      "expected": true
+    },
+    {
+      "id": "0021-null-window-never-expires",
+      "title": "A provider that does not expire keys is always replay-safe",
+      "since": "0.4.0",
+      "tags": ["replaysafe"],
+      "fn": "isReplaySafe",
+      "input": { "attempt": 9, "firstAttemptAt": "2020-01-01T00:00:00Z", "now": "2026-08-19T00:00:00Z", "windowSeconds": null },
+      "expected": true
+    },
+    {
+      "id": "0022-clock-skew-clamps-to-zero",
+      "title": "A now earlier than the first attempt is treated as no elapsed time",
+      "since": "0.4.0",
+      "tags": ["replaysafe", "clock"],
+      "fn": "isReplaySafe",
+      "input": { "attempt": 2, "firstAttemptAt": "2026-08-19T00:00:10Z", "now": "2026-08-19T00:00:00Z", "windowSeconds": 86400 },
+      "expected": true,
+      "notes": "Two workers with a few seconds of skew must not turn a legitimate retry into a refusal."
+    },
+    {
+      "id": "0023-offset-and-zulu-are-the-same-instant",
+      "title": "A +00:00 offset parses as the same instant as Z",
+      "since": "0.4.0",
+      "tags": ["replaysafe", "clock"],
+      "fn": "isReplaySafe",
+      "input": { "attempt": 2, "firstAttemptAt": "2026-08-18T00:00:00+00:00", "now": "2026-08-19T00:00:01Z", "windowSeconds": 86400 },
+      "expected": false
+    },
+    {
+      "id": "0024-non-utc-offset-is-honoured",
+      "title": "A non-UTC offset is converted, not ignored",
+      "since": "0.4.0",
+      "tags": ["replaysafe", "clock"],
+      "fn": "isReplaySafe",
+      "input": { "attempt": 2, "firstAttemptAt": "2026-08-19T02:00:00+02:00", "now": "2026-08-19T00:00:30Z", "windowSeconds": 60 },
+      "expected": true,
+      "notes": "02:00+02:00 is midnight UTC, so 30 seconds have elapsed. An implementation that drops the offset reads it as two hours and refuses."
+    },
+    {
+      "id": "0025-fractional-seconds-parse",
+      "title": "Fractional seconds do not break the comparison",
+      "since": "0.4.0",
+      "tags": ["replaysafe", "clock"],
+      "fn": "isReplaySafe",
+      "input": { "attempt": 2, "firstAttemptAt": "2026-08-18T00:00:00.500Z", "now": "2026-08-19T00:00:00.400Z", "windowSeconds": 86400 },
+      "expected": true
+    }
+  ]
+}

package/suites/shared/flow-run-identity/manifest.json

@@ -0,0 +1,30 @@
+{
+  "$schema": "../../../schema/suite-manifest.schema.json",
+  "suite": "shared/flow-run-identity",
+  "title": "Stable run/step identity for fancy-flow, and when a retry may reuse it",
+  "since": "0.4.0",
+  "caseFormat": "table",
+  "cases": "cases.json",
+  "contract": {
+    "summary": "A workflow node that WRITES to a third party needs an idempotency key that is the same on every retry of one logical step and different for every other execution of the same node. `stepKey` derives it from the run identity; `isReplaySafe` says whether a retry is still inside the provider's dedup window.",
+    "functions": {
+      "stepKey": "stepKey(runKey: string, path: string[], nodeId: string, occurrence: int|null) -> string",
+      "isReplaySafe": "isReplaySafe(attempt: int, firstAttemptAt: string, now: string, windowSeconds: number|null) -> bool"
+    },
+    "reference": "node",
+    "referenceNote": "The format was designed here rather than lifted from an implementation; `node` is recorded because the TypeScript RunIdentity was written first and the other two were made to match it.",
+    "implementations": [
+      { "language": "node", "package": "@particle-academy/fancy-flow", "symbol": "RunIdentity" },
+      { "language": "php", "package": "particle-academy/fancy-flow-php", "symbol": "FancyFlow\\Runtime\\RunIdentity" },
+      { "language": "python", "package": "fancy-flow", "symbol": "fancy_flow.runtime.RunIdentity" }
+    ]
+  },
+  "notes": [
+    "`attempt` is deliberately NOT part of the step key, and case 0011/0012 are the pair that proves it. An idempotency key that changes per attempt creates a second charge on every retry — which is the exact failure the key exists to prevent. `attempt` is carried on the identity for logging and for `isReplaySafe`, never for the key.",
+    "`(run, node)` alone is NOT sufficient identity and the suite says so structurally: `path` and `occurrence` exist because a node legitimately executes more than once in one run — once per subflow invocation, once per loop iteration. Cases 0004-0005 pin nesting, 0002-0003 pin repetition.",
+    "Segments are escaped (`%` -> `%25`, `/` -> `%2F`, `#` -> `%23`) so the composition is injective. Without it a node literally named `a/b` at the top level and a node `b` inside an invocation of `a` produce the same key — two different writes sharing an idempotency key, which the provider deduplicates into one. Cases 0006-0010 are that pair and its relatives. Escape `%` FIRST or the escaping is not reversible.",
+    "`isReplaySafe` returns TRUE on attempt 1 whatever the elapsed time, and that is the case that lets a run park on a human gate for a week: nothing was sent on a previous attempt, so there is nothing for the provider to have forgotten. Cases 0013 and 0018.",
+    "The window is INCLUSIVE at its boundary (0015) and clock skew clamps to zero rather than going negative (0022). A null window means the provider does not expire keys (0021).",
+    "A FALSE from `isReplaySafe` must become a loud failure at the call site, never a silently omitted key and never a fresh one: past the window the provider has forgotten the first attempt, so both alternatives write twice. Refusing converts a silent double-charge into a visible stuck run."
+  ]
+}

package/suites/shared/image-header/cases.json

@@ -0,0 +1,275 @@
+{
+  "$schema": "../../../schema/case-table.schema.json",
+  "suite": "shared/image-header",
+  "cases": [
+    {
+      "id": "0001-png-1x1",
+      "title": "PNG, the smallest possible image",
+      "since": "0.3.0",
+      "tags": [
+        "png"
+      ],
+      "fn": "sniffImageSize",
+      "input": {
+        "base64": "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAAAElFTkSuQmCC"
+      },
+      "expected": {
+        "width": 1,
+        "height": 1
+      },
+      "notes": "The floor. A 1x1 PNG is what every fixture elsewhere in this org uses as a stand-in image, so if this ever fails nothing else here is worth reading."
+    },
+    {
+      "id": "0002-png-300x200",
+      "title": "PNG, dimensions past a single byte",
+      "since": "0.3.0",
+      "tags": [
+        "png"
+      ],
+      "fn": "sniffImageSize",
+      "input": {
+        "base64": "iVBORw0KGgoAAAANSUhEUgAAASwAAADICAYAAABS39xVAAAAAElFTkSuQmCC"
+      },
+      "expected": {
+        "width": 300,
+        "height": 200
+      }
+    },
+    {
+      "id": "0003-png-large",
+      "title": "PNG, dimensions past 16 bits (uint32 IHDR fields)",
+      "since": "0.3.0",
+      "tags": [
+        "png",
+        "edge"
+      ],
+      "fn": "sniffImageSize",
+      "input": {
+        "base64": "iVBORw0KGgoAAAANSUhEUgABEXAAAAADCAYAAAC/i9xAAAAAAElFTkSuQmCC"
+      },
+      "expected": {
+        "width": 70000,
+        "height": 3
+      },
+      "notes": "IHDR width and height are uint32. A sniffer that reads them as uint16, or that sign-extends the high byte, gets this wrong and nothing smaller catches it."
+    },
+    {
+      "id": "0004-png-truncated",
+      "title": "PNG signature but fewer than 24 bytes",
+      "since": "0.3.0",
+      "tags": [
+        "png",
+        "edge",
+        "rejects"
+      ],
+      "fn": "sniffImageSize",
+      "input": {
+        "base64": "iVBORw0KGgoAAAANSUhEUgAAAAE="
+      },
+      "expected": null,
+      "notes": "Fewer than 24 bytes. The read of offsets 16..23 must be bounds-checked BEFORE it happens, not after."
+    },
+    {
+      "id": "0005-png-not-ihdr",
+      "title": "PNG signature, first chunk is not IHDR",
+      "since": "0.3.0",
+      "tags": [
+        "png",
+        "hazard",
+        "rejects"
+      ],
+      "fn": "sniffImageSize",
+      "input": {
+        "base64": "iVBORw0KGgoAAAANZ0FNQQAAAAQAAAAECAYAAAB3rFQUAAAAAElFTkSuQmCC"
+      },
+      "expected": null,
+      "notes": "PNG signature, first chunk is gAMA rather than IHDR, with plausible numbers where IHDR's would be. Both hand-rolled sniffers verify the chunk name and return null; PHP's getimagesizefromstring reads offsets 16/20 blindly and answers 4x4. Checking the chunk name is the difference between reading a header and reading whatever is at that offset."
+    },
+    {
+      "id": "0006-png-zero-width",
+      "title": "PNG whose IHDR declares width 0",
+      "since": "0.3.0",
+      "tags": [
+        "png",
+        "edge",
+        "rejects"
+      ],
+      "fn": "sniffImageSize",
+      "input": {
+        "base64": "iVBORw0KGgoAAAANSUhEUgAAAAAAAAAJCAYAAAAchC3aAAAAAElFTkSuQmCC"
+      },
+      "expected": null,
+      "notes": "A zero dimension is not a size. It divides by zero in any aspect-ratio fit, and the writers do exactly that when widthPx is omitted."
+    },
+    {
+      "id": "0007-png-bad-signature",
+      "title": "one byte of the PNG signature flipped",
+      "since": "0.3.0",
+      "tags": [
+        "png",
+        "edge",
+        "rejects"
+      ],
+      "fn": "sniffImageSize",
+      "input": {
+        "base64": "iVBOWA0KGgoAAAANSUhEUgAAAAQAAAAECAYAAACp8Z5+AAAAAElFTkSuQmCC"
+      },
+      "expected": null
+    },
+    {
+      "id": "0008-jpeg-baseline",
+      "title": "JPEG, baseline SOF0",
+      "since": "0.3.0",
+      "tags": [
+        "jpeg"
+      ],
+      "fn": "sniffImageSize",
+      "input": {
+        "base64": "/9j/wAARCAHgAoADAAAAAAAAAAAA/9k="
+      },
+      "expected": {
+        "width": 640,
+        "height": 480
+      }
+    },
+    {
+      "id": "0009-jpeg-progressive",
+      "title": "JPEG, progressive SOF2",
+      "since": "0.3.0",
+      "tags": [
+        "jpeg",
+        "hazard"
+      ],
+      "fn": "sniffImageSize",
+      "input": {
+        "base64": "/9j/wgARCADwAUADAAAAAAAAAAAA/9k="
+      },
+      "expected": {
+        "width": 320,
+        "height": 240
+      },
+      "notes": "SOF2, not SOF0. A sniffer that only matches 0xC0 silently fails on every progressive JPEG, which is most photographs on the web."
+    },
+    {
+      "id": "0010-jpeg-exif-first",
+      "title": "JPEG with an APP1/Exif segment before the frame header",
+      "since": "0.3.0",
+      "tags": [
+        "jpeg"
+      ],
+      "fn": "sniffImageSize",
+      "input": {
+        "base64": "/9j/4QAcRXhpZgAAAAAAAAAAAAAAAAAAAAAAAAAAAAD/wAARCAAyAGQDAAAAAAAAAAAA/9k="
+      },
+      "expected": {
+        "width": 100,
+        "height": 50
+      },
+      "notes": "An APP1/Exif segment before the frame header - the ordinary shape of a camera JPEG. Pins segment-length skipping."
+    },
+    {
+      "id": "0011-jpeg-fill-bytes",
+      "title": "JPEG with 0xFF fill bytes padding the frame marker",
+      "since": "0.3.0",
+      "tags": [
+        "jpeg",
+        "live-divergence",
+        "hazard"
+      ],
+      "fn": "sniffImageSize",
+      "input": {
+        "base64": "/9j/////wAARCABkAMgDAAAAAAAAAAAA/9k="
+      },
+      "expected": {
+        "width": 200,
+        "height": 100
+      },
+      "skip": {
+        "node": "@particle-academy/last-word's jpegSize advances by 2 on a 0xFF fill byte instead of 1, steps over the real frame marker and returns null. Fill bytes before a marker are legal per ITU T.81 B.1.1.2. Fix is a one-character change (i += 2 -> i++ on the marker === 0xff branch); until it ships this case is red there."
+      },
+      "notes": "THE FIRST DIVERGENCE. ITU T.81 B.1.1.2: 'any marker may optionally be preceded by any number of fill bytes, which are bytes assigned code X\"FF\"'. On seeing 0xFF as the marker byte, the PHP sniffer advances by ONE and re-syncs; the Node sniffer advances by TWO and steps over the real marker, so it returns null and the writer sizes the image from a fallback instead of its intrinsic dimensions. getimagesizefromstring agrees with PHP. Legal input, produced by real encoders, and the same JPEG therefore embeds at a different size depending on which backend wrote the document."
+    },
+    {
+      "id": "0012-jpeg-sos-before-sof",
+      "title": "JPEG whose scan starts before any frame header",
+      "since": "0.3.0",
+      "tags": [
+        "jpeg",
+        "live-divergence",
+        "hazard",
+        "rejects"
+      ],
+      "fn": "sniffImageSize",
+      "input": {
+        "base64": "/9j/2gAIAAEAAD8A/8AAEQgAFgALAwAAAAAAAAAAAP/Z"
+      },
+      "expected": null,
+      "skip": {
+        "php": "particle-academy/last-word's ImageSize::jpeg has no start-of-scan stop, so it keeps walking into entropy-coded data and reports dimensions read out of compressed bytes. Both the Node port and PHP's own getimagesizefromstring stop at 0xFFDA. Until last-word gains the SOS stop this case is red there.",
+        "python": "The Python port is a faithful mirror of the PHP reference and therefore inherits the same missing SOS stop -- verified, not assumed: it answers 11x22 here. Deliberately NOT fixed unilaterally. .ai/plans/polyglot/parity/documents.md 1.4 rules that a defect producing wrong output is fixed in every engine in one release train, because fixing it in one language alone breaks part-level parity, which is the suite's whole contract. This skip disappears the day last-word gains the stop."
+      },
+      "notes": "THE SECOND DIVERGENCE, and it runs the other way. After a start-of-scan the bytes are entropy-coded, so an 0xFF 0xCx sequence found there is compressed data, not a frame header. The Node sniffer stops at SOS; the PHP sniffer keeps walking and reports dimensions it read out of the scan. getimagesizefromstring also stops. The failure mode is worse than the first one: a null sniff falls back, a WRONG sniff is believed."
+    },
+    {
+      "id": "0013-jpeg-truncated",
+      "title": "JPEG SOI and nothing else",
+      "since": "0.3.0",
+      "tags": [
+        "jpeg",
+        "edge",
+        "rejects"
+      ],
+      "fn": "sniffImageSize",
+      "input": {
+        "base64": "/9g="
+      },
+      "expected": null
+    },
+    {
+      "id": "0014-gif-8x8",
+      "title": "a GIF, which one engine in this family knows and another does not",
+      "since": "0.3.0",
+      "tags": [
+        "other",
+        "hazard",
+        "rejects"
+      ],
+      "fn": "sniffImageSize",
+      "input": {
+        "base64": "R0lGODlhCAAIAPcAADs="
+      },
+      "expected": null,
+      "notes": "The family cannot agree whether GIF is a format it reads. last-word (both engines) says no; dark-slide's PHP calls getimagesizefromstring, which says 8x8, while dark-slide's Node port hand-rolls a GIF branch. The golden follows the reference. Recorded here because the polyglot plan lists the coverage gap and nothing tested it."
+    },
+    {
+      "id": "0015-not-an-image",
+      "title": "arbitrary bytes",
+      "since": "0.3.0",
+      "tags": [
+        "other",
+        "rejects"
+      ],
+      "fn": "sniffImageSize",
+      "input": {
+        "base64": "dGhpcyBpcyBub3QgYW4gaW1hZ2UgYXQgYWxsLCBub3QgZXZlbiBzbGlnaHRseQ=="
+      },
+      "expected": null
+    },
+    {
+      "id": "0016-empty",
+      "title": "zero bytes",
+      "since": "0.3.0",
+      "tags": [
+        "other",
+        "edge",
+        "rejects"
+      ],
+      "fn": "sniffImageSize",
+      "input": {
+        "base64": ""
+      },
+      "expected": null,
+      "notes": "Zero bytes. Every length check must survive it."
+    }
+  ]
+}

package/suites/shared/image-header/manifest.json

@@ -0,0 +1,51 @@
+{
+  "$schema": "../../../schema/suite-manifest.schema.json",
+  "suite": "shared/image-header",
+  "title": "Intrinsic image dimensions, sniffed from PNG and JPEG headers",
+  "since": "0.3.0",
+  "caseFormat": "table",
+  "cases": "cases.json",
+  "contract": {
+    "function": "sniffImageSize(bytes) -> {width: int, height: int} | null",
+    "summary": "Read an image's intrinsic pixel dimensions straight from its header bytes, with no decoder. Every document writer in this org needs it, because a model that omits widthPx/heightPx has to be sized from the image itself - so a sniffer that returns null silently changes the size a picture is embedded at, and one that returns the WRONG numbers changes it and is believed.",
+    "runShape": {
+      "width": "int",
+      "height": "int"
+    },
+    "reference": "php",
+    "referenceNote": "particle-academy/last-word's Helpers\\ImageSize::sniff, which is the most explicit hand-rolled sniffer in the family. Case 0012 is the one exception and it is marked: there the reference is demonstrably reading entropy-coded data as a header, PHP's own getimagesizefromstring and the Node port both refuse, and the golden follows the two that agree while the reference carries a skip with the reason. Every golden in this file is still the output of RUNNING an implementation - never what the value obviously ought to be.",
+    "implementations": [
+      {
+        "language": "php",
+        "package": "particle-academy/last-word",
+        "symbol": "Helpers\\ImageSize::sniff"
+      },
+      {
+        "language": "node",
+        "package": "@particle-academy/last-word",
+        "symbol": "sniffImageSize"
+      },
+      {
+        "language": "php",
+        "package": "particle-academy/dark-slide",
+        "symbol": "Writer\\PptxWriter (getimagesizefromstring)"
+      },
+      {
+        "language": "node",
+        "package": "@particle-academy/dark-slide",
+        "symbol": "writer/pptx-writer.ts getImageSize"
+      },
+      {
+        "language": "python",
+        "package": "last-word",
+        "symbol": "helpers.image_size.sniff"
+      }
+    ]
+  },
+  "notes": [
+    "FOUR implementations of this one concern already exist inside this family - two hand-rolled sniffers, one call to PHP's platform library, and a fourth hand-rolled sniffer in dark-slide-js with different format coverage again. That is the duplication .ai/plans/polyglot/parity/documents.md \u00a70.3 nominates for a shared fancy-ooxml package, and this suite is what stops a fifth copy from inheriting a defect.",
+    "The two divergences here (0011, 0012) were found by writing this suite on 2026-08-18. They are live at the time of writing, and they run in OPPOSITE directions: the Node port is wrong about fill bytes, the PHP reference is wrong about the start-of-scan. Neither sniffer is a superset of the other, which is why 'just follow the reference' would have shipped one of the two defects into every new implementation.",
+    "Bytes are carried as base64 in `input.base64` because a JSON cell cannot hold a byte string. A runner decodes and passes raw bytes to the function under test.",
+    "GIF, WebP, BMP, TIFF and ICO are deliberately NOT in the contract. PHP's getimagesizefromstring knows them all and both hand-rolled sniffers know none of them; widening the contract is a decision for the pair owners, not something a fixture should smuggle in."
+  ]
+}