@particle-academy/fancy-conformance 0.25.0 → 0.27.0

package/README.md

@@ -70,7 +70,9 @@ verbatim.
 | `shared/flow-run-identity` | 25 | fancy-flow's run/step identity: the idempotency key a retrying connector sends, and when a retry may still reuse it |
 | `flow/graph-runs` | 23 | Whole-graph execution: the same `WorkflowSchema` in, the same `RunResult.outputs` out |
 | `flow/run-diagnostics` | 14 | The run-time warnings for a graph that delivers nothing: an edge naming a port its source can never publish, and a route taken on a path that did not resolve. Half the rows pin when to stay silent |
+| `flow/port-activation` | 12 | Which output ports a node lights and what each carries: a chosen SUBSET via `__ports`, one port via `__port` / `branch`, and the declared-port fallbacks. One row records a real disagreement as a skip rather than omitting it |
 | `flow/durable-dispatch` | 14 | How a queued run hands out nodes: one at a time by default, in declaration order, with a paused gate keeping its slot; a cap and the whole frontier only when a host asks |
+| `shared/subscription-lease` | 13 | A subscription that expires: when a renewal is due, when the lease has expired, and why a missed lease is a resync rather than a quiet re-create |
 
 Every case carries an `id`, a `title`, the suite version it arrived in, and —
 where it exists to catch something specific — a `notes` field saying what.

package/VERSION

@@ -1 +1 @@
-0.25.0
+0.27.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@particle-academy/fancy-conformance",
-  "version": "0.25.0",
+  "version": "0.27.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 — 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/schema/suite-manifest.schema.json

@@ -37,8 +37,8 @@
         },
         "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"]
+          "description": "Which language's behaviour the goldens were taken from. Goldens are never what a value 'obviously' is. 'authored' means the suite's author decided them rather than capturing them from a runtime; referenceNote must say by whom and on what evidence.",
+          "enum": ["php", "node", "rust", "python", "go", "authored"]
         },
         "referenceNote": { "type": "string" },
         "implementations": {
@@ -50,7 +50,8 @@
             "properties": {
               "language": { "enum": ["php", "node", "rust", "python", "go"] },
               "package": { "type": "string", "minLength": 1 },
-              "symbol": { "type": "string" }
+              "symbol": { "type": "string" },
+              "engine": { "type": "string", "description": "For an implementation that runs inside a workflow engine: the engine package and the range it is exercised against." }
             },
             "additionalProperties": false
           }

package/suites/flow/durable-dispatch/manifest.json

@@ -13,7 +13,8 @@
     "implementations": [
       { "language": "php", "package": "particle-academy/fancy-flow-php", "symbol": "FancyFlow\\Laravel\\Runs\\DispatchLimit" },
       { "language": "node", "package": "@particle-academy/fancy-flow", "symbol": "selectDispatch" },
-      { "language": "python", "package": "fancy-flow", "symbol": "fancy_flow.durable.select_dispatch" }
+      { "language": "python", "package": "fancy-flow", "symbol": "fancy_flow.durable.select_dispatch" },
+      { "language": "rust", "package": "fancy-flow", "symbol": "fancy_flow::durable::select_dispatch" }
     ]
   },
   "notes": [
@@ -24,7 +25,7 @@
     "THE BUDGET IS MEASURED AGAINST WORK ALREADY HELD, not the size of one batch. Two nodes settling at once each trigger an advance on a real queue; a per-batch cap lets each dispatch its own quota. The simulation cannot race, so 0014 and 0010 pin the held-count arithmetic directly, and each runtime's own suite pins the race.",
     "WORKERS ARE FIFO AND SETTLE ONE AT A TIME. That makes every row deterministic without pretending to model a real queue's timing. It is a model of the decision, not of the transport.",
     "SKIPS AND NOTES NEVER TAKE A SLOT (0011, 0012). The frontier settles a dead branch, everything below it, and a sticky note in the same pass, before selection.",
-    "RUST IS NOT LISTED: fancy-flow-rs has no durable coordinator. Whether it gets one is an open decision recorded in the envelope's .ai/plans/fancy-flow-serial-dispatch.md.",
+    "RUST JOINED IN 0.26.0. fancy-flow-rs had no durable coordinator when this table was written; the owner ruled to build one rather than record its absence, and it passes all 14 rows against its own frontier and selection. It also runs flow/run-diagnostics through its coordinator, and matches flow/graph-runs durably and in a single process.",
     "THERE IS A DISCRIMINATION PROBE (tests/discrimination-durable-dispatch.test.ts): a faithful frontier + selection passes every row, and four mutants each fail an exact set -- a paused node not held (0008, 0010), a per-batch cap (0008, 0010, 0014), the pre-#17 default (0001, 0004, 0005, 0007, 0008, 0013) and breadth-first order (0007). Writing it is what turned the goldens from dispatch batches into a trace: the batch shape let the first two mutants through."
   ]
 }

package/suites/flow/port-activation/cases.json

@@ -0,0 +1,169 @@
+{
+  "$schema": "../../../schema/case-table.schema.json",
+  "suite": "flow/port-activation",
+  "cases": [
+    {
+      "id": "0101-ports-list-lights-the-named-subset",
+      "title": "A `__ports` LIST lights exactly those ports, each carrying the shared value.",
+      "since": "0.27.0",
+      "tags": ["subset"],
+      "input": {
+        "declaredOutputs": ["a", "b", "c", "d", "e"],
+        "result": { "__ports": ["a", "c"], "value": "matched" }
+      },
+      "expected": [
+        { "port": "a", "value": "matched" },
+        { "port": "c", "value": "matched" }
+      ],
+      "notes": "The rule fancy-flow-php#18 added. Before it the engine knew two answers — one port, or every port — so a router that matched two of five lanes had to drop the rest of the work or wake lanes nobody asked for. Ports `b`, `d` and `e` are declared and stay DARK, which is the half of this row that matters."
+    },
+    {
+      "id": "0102-ports-map-gives-each-port-its-own-payload",
+      "title": "A `__ports` MAP lights its keys, each carrying its own payload.",
+      "since": "0.27.0",
+      "tags": ["subset"],
+      "input": {
+        "declaredOutputs": ["a", "b", "c", "d", "e"],
+        "result": { "__ports": { "a": { "queue": "billing" }, "c": { "queue": "abuse" } } }
+      },
+      "expected": [
+        { "port": "a", "value": { "queue": "billing" } },
+        { "port": "c", "value": { "queue": "abuse" } }
+      ],
+      "notes": "One classifier, two lanes, two different payloads. Sharing one payload across the lit ports would force every lane to re-derive which part of the result was addressed to it."
+    },
+    {
+      "id": "0103-per-port-null-is-a-payload",
+      "title": "A per-port payload that is present and NULL is delivered as null.",
+      "since": "0.27.0",
+      "tags": ["subset", "null"],
+      "input": {
+        "declaredOutputs": ["a", "b"],
+        "result": { "__ports": { "a": null } }
+      },
+      "expected": [{ "port": "a", "value": null }],
+      "notes": "Key presence, not truthiness. `values[port] ?? value` reads this as 'absent' and hands the port the shared value instead — which is `undefined`/null here, so it would PASS by accident. It is asserted anyway because the same lookup is what row 0102 depends on, and the version of this bug that shipped in `branch` was invisible for exactly this reason."
+    },
+    {
+      "id": "0104-an-empty-ports-list-lights-nothing",
+      "title": "An explicitly empty `__ports` lights NOTHING.",
+      "since": "0.27.0",
+      "tags": ["subset", "empty"],
+      "input": {
+        "declaredOutputs": ["a", "b", "c"],
+        "result": { "__ports": [], "value": "unrouted" }
+      },
+      "expected": [],
+      "notes": "The honest answer for a router that matched no rule. Falling through to 'every declared port' here would wake all three lanes at precisely the moment the node decided none applied — and the run would look successful."
+    },
+    {
+      "id": "0105-map-order-is-emission-order",
+      "title": "A `__ports` map lights its ports in the order the map declares them.",
+      "since": "0.27.0",
+      "tags": ["subset", "order"],
+      "input": {
+        "declaredOutputs": ["a", "b", "c"],
+        "result": { "__ports": { "c": 1, "a": 2 } }
+      },
+      "expected": [
+        { "port": "c", "value": 1 },
+        { "port": "a", "value": 2 }
+      ],
+      "notes": "Declaration order, not the declared-outputs order and not sorted. A runtime that sorted these would deliver every payload correctly and still be wrong: two lanes touching one resource would interleave differently on different runtimes, which is the class of bug that only reproduces in production."
+    },
+    {
+      "id": "0106-a-malformed-ports-falls-through",
+      "title": "A `__ports` that is neither a list nor a map falls through to every declared port.",
+      "since": "0.27.0",
+      "tags": ["subset", "malformed"],
+      "input": {
+        "declaredOutputs": ["a", "b"],
+        "result": { "__ports": "a" }
+      },
+      "expected": [
+        { "port": "a", "value": { "__ports": "a" } },
+        { "port": "b", "value": { "__ports": "a" } }
+      ],
+      "notes": "A string is not a subset instruction. Reading an unreadable `__ports` as 'no ports' would turn one typo into a silently truncated run; falling through publishes the whole result, which is loud downstream. Note what each port carries: the WHOLE result, wrapper included, because no subset rule fired."
+    },
+    {
+      "id": "0201-port-sugar-lights-one-port",
+      "title": "`__port` lights exactly one port, carrying `value`.",
+      "since": "0.27.0",
+      "tags": ["single"],
+      "input": {
+        "declaredOutputs": ["a", "b", "c"],
+        "result": { "__port": "b", "value": "only-b" }
+      },
+      "expected": [{ "port": "b", "value": "only-b" }],
+      "notes": "Unchanged by #18 and asserted here so it stays that way. `__ports` was added as a sibling rule, not a replacement, and is checked AFTER `__port`."
+    },
+    {
+      "id": "0202-branch-with-an-explicit-null-payload",
+      "title": "`branch` with `value` present and null delivers null, not the wrapper.",
+      "since": "0.27.0",
+      "tags": ["single", "null"],
+      "input": {
+        "declaredOutputs": ["a", "b"],
+        "result": { "branch": "b", "value": null }
+      },
+      "expected": [{ "port": "b", "value": null }],
+      "notes": "ALL FOUR RUNTIMES SHIPPED THIS WRONG, IDENTICALLY, so no parity table caught it — they agreed on being wrong. `value ?? result` cannot tell 'no value key' (row 0203, where the whole result IS the payload) from 'value is null' (this row), so a branch whose payload was null leaked `{branch, value}` downstream: two fields no kind declares, while the declared ones were absent. The reachable path is an upstream `transform` whose dot-path did not resolve."
+    },
+    {
+      "id": "0203-branch-with-no-value-key-carries-the-whole-result",
+      "title": "`branch` with NO `value` key carries the entire result.",
+      "since": "0.27.0",
+      "tags": ["single"],
+      "input": {
+        "declaredOutputs": ["a", "b"],
+        "result": { "branch": "b", "verdict": "approved" }
+      },
+      "expected": [{ "port": "b", "value": { "branch": "b", "verdict": "approved" } }],
+      "notes": "The other half of 0202, and the reason the lookup must ask about key presence. An executor that returns its own object and names a branch inside it gets the object delivered; the wrapper is the payload here by design."
+    },
+    {
+      "id": "0301-a-plain-result-lights-every-declared-port",
+      "title": "A result naming no ports lights EVERY declared output port, each carrying the whole result.",
+      "since": "0.27.0",
+      "tags": ["fallback"],
+      "input": {
+        "declaredOutputs": ["a", "b", "c"],
+        "result": { "ok": true }
+      },
+      "expected": [
+        { "port": "a", "value": { "ok": true } },
+        { "port": "b", "value": { "ok": true } },
+        { "port": "c", "value": { "ok": true } }
+      ],
+      "notes": "The default, and what `__ports` narrows. Declared order."
+    },
+    {
+      "id": "0302-a-node-declaring-no-ports-lights-out",
+      "title": "A node that declares NO outputs lights the lone `out` port.",
+      "since": "0.27.0",
+      "tags": ["fallback"],
+      "input": {
+        "declaredOutputs": null,
+        "result": { "ok": true }
+      },
+      "expected": [{ "port": "out", "value": { "ok": true } }],
+      "notes": "`null` is 'undeclared', which is not the same as 'explicitly none' — see row 0303. The `out` fallback is what lets a hand-written document omit ports entirely and still chain."
+    },
+    {
+      "id": "0303-an-explicitly-empty-outputs-lights-nothing",
+      "title": "A node whose outputs are an explicitly EMPTY list lights nothing.",
+      "since": "0.27.0",
+      "tags": ["fallback", "empty", "divergence"],
+      "input": {
+        "declaredOutputs": [],
+        "result": { "ok": true }
+      },
+      "expected": [],
+      "skip": {
+        "node": "DIVERGENCE, not an exemption: @particle-academy/fancy-flow collapses an explicitly-empty outputs to ['out'] because its fallback tests `declared?.length` and [] is falsy, so the three states (undeclared / explicitly none / declared) become two. Measured on 0.74.1. PHP, Python and Rust all publish nothing. Tracked as an issue on fancy-flow; this row starts passing there the day it is fixed."
+      },
+      "notes": "THREE STATES, NOT TWO. `null` falls back to `out` (row 0302); `[]` means a terminal node that genuinely publishes nothing. Collapsing them is how a terminal node starts publishing — and downstream of that, an edge nobody drew starts delivering. Kept as a skipped row rather than deleted so every runner prints the disagreement: a table that omits the one case its implementations disagree on is a table that agrees by saying less."
+    }
+  ]
+}

package/suites/flow/port-activation/manifest.json

@@ -0,0 +1,30 @@
+{
+  "$schema": "../../../schema/suite-manifest.schema.json",
+  "suite": "flow/port-activation",
+  "title": "Which output ports a node lights, and what each one carries",
+  "since": "0.27.0",
+  "caseFormat": "table",
+  "cases": "cases.json",
+  "contract": {
+    "function": "run(node with declaredOutputs, executor returning result) -> ordered [{ port, value }]",
+    "summary": "Run a ONE-NODE graph whose node declares `declaredOutputs` as its output ports and whose executor returns `result`, and report the `node-output` events that node emitted, in order, as `[{ port, value }]`. The answer is the events rather than a private function's return value because every runtime keeps this logic private (`activatedPorts`, `_activated_ports`, `Walk::activated_ports`) and the events are what a consumer — and the durable layer — actually observes. A row with an empty `expected` asserts the node emitted NOTHING, which is a different claim from emitting one port with a null payload and is the claim several of these rows are about.",
+    "reference": "node",
+    "referenceNote": "The result-shape rules are `@particle-academy/fancy-flow`'s and predate this table; the `__ports` rows were added with fancy-flow-php#18 across all four runtimes in the same week and the goldens were captured by running each. Row 0303 is the one place the four do NOT agree, and it is recorded as a skip rather than removed — see the notes.",
+    "implementations": [
+      { "language": "node", "package": "@particle-academy/fancy-flow", "symbol": "activatedPorts" },
+      { "language": "php", "package": "particle-academy/fancy-flow-php", "symbol": "FancyFlow\\Engine\\FlowRunner::activatedPorts" },
+      { "language": "python", "package": "fancy-flow", "symbol": "fancy_flow.engine.runner.FlowRunner._activated_ports" },
+      { "language": "rust", "package": "fancy-flow", "symbol": "fancy_flow::engine::walk::Walk::activated_ports" }
+    ]
+  },
+  "notes": [
+    "`declaredOutputs` is a LIST OF PORT IDS, or null for a node that declares none. Each runtime puts it where its own FlowNode keeps ports: TypeScript's is an xyflow node so they live in `data.outputs` as `{ id }` descriptors, while PHP, Python and Rust have a flattened `node.outputs`. The table asks about the ENGINE's rule, not about where a document stores it.",
+    "The node's kind must NOT be registered in the runtime running these rows. The declared-port fallback consults the kind's ports before falling back to `out`, so a row that accidentally named a builtin would be asserting the builtin's ports instead of the rule under test. Every row uses `hostRouter`, which no runtime ships.",
+    "THE ORDER OF THE EXPECTED LIST IS PART OF THE ASSERTION. A map-shaped `__ports` lights its ports in the order the object declares them (row 0105), which every one of the four preserves — JavaScript for string keys, PHP for array keys, Python for dicts since 3.7, and Rust because `fancy_json::Map` is insertion-ordered. A runtime that sorted them would still deliver every payload correctly and would still be wrong, because a downstream node reading a shared resource would see a different interleaving.",
+    "PER-PORT PAYLOADS ARE READ BY KEY PRESENCE, NEVER BY TRUTHINESS (rows 0103, 0202). A payload that is present and null is a payload. `values[port] ?? value` and `$ports[$port] ?? $result` cannot tell 'no key' from 'null', and all four runtimes shipped exactly that confusion in `branch` — every downstream node received the `{branch, value}` WRAPPER, two fields no kind declares, while the fields it does declare were absent. No parity table caught it because the four agreed on being wrong; these rows exist so the next one cannot hide the same way.",
+    "AN EMPTY `__ports` LIGHTS NOTHING, DELIBERATELY (row 0104). It is the honest answer for a router that matched no rule, and it is the same answer an explicitly empty `outputs` gives in three of the four runtimes. Lighting every port instead would wake every lane precisely when the node decided none applied.",
+    "A MALFORMED `__ports` FALLS THROUGH to the every-declared-port rule rather than lighting nothing (row 0106). `__ports` that is a string, a number or null is not a subset instruction, and treating an unreadable one as 'no ports' would turn a typo into a silently truncated run — the failure mode this whole table is written against.",
+    "ROW 0303 IS THE DIVERGENCE, AND IT IS RECORDED RATHER THAN REMOVED. `declaredOutputs: []` means 'this node explicitly has no output ports'. PHP, Python and Rust honour it and publish nothing; `@particle-academy/fancy-flow` collapses it to `[\"out\"]`, because its fallback tests `declared?.length` and an empty array is falsy — so the three-state distinction (undeclared / explicitly none / declared) becomes two-state there. Measured on fancy-flow 0.74.1, not inferred. It is skipped for node with that reason so every runner PRINTS it, which is the only way a known disagreement stays visible; deleting the row would make the table agree by saying less. Tracked as an issue on fancy-flow.",
+    "Nothing here asserts that a lit port must be a DECLARED one. All four runtimes publish whatever `__port` / `__ports` / `branch` names, declared or not, and an edge from a port that does not exist simply matches nothing. That is deliberate slack for hosts whose ports are config-driven, and pinning it either way belongs in its own row once someone decides it — not smuggled in through a row about something else."
+  ]
+}

package/suites/shared/subscription-lease/cases.json

@@ -0,0 +1,206 @@
+{
+  "$schema": "../../../schema/case-table.schema.json",
+  "suite": "shared/subscription-lease",
+  "cases": [
+    {
+      "id": "0001-active-well-before-renewal",
+      "title": "Three days into a seven-day lease with a one-day margin is active, nothing to do",
+      "since": "0.26.0",
+      "input": {
+        "expiresAt": "2026-09-22T00:00:00Z",
+        "renewBeforeSeconds": 86400,
+        "renewOperation": "subscription_renew",
+        "now": "2026-09-18T00:00:00Z"
+      },
+      "expected": {
+        "renewAt": "2026-09-21T00:00:00.000Z",
+        "state": "active",
+        "action": "none"
+      }
+    },
+    {
+      "id": "0002-due-at-the-boundary",
+      "title": "Exactly at renewAt the lease is DUE — the boundary is inclusive",
+      "since": "0.26.0",
+      "input": {
+        "expiresAt": "2026-09-22T00:00:00Z",
+        "renewBeforeSeconds": 86400,
+        "renewOperation": "subscription_renew",
+        "now": "2026-09-21T00:00:00Z"
+      },
+      "expected": {
+        "renewAt": "2026-09-21T00:00:00.000Z",
+        "state": "due",
+        "action": "renew"
+      }
+    },
+    {
+      "id": "0003-one-second-before-due",
+      "title": "One second before renewAt is still active",
+      "since": "0.26.0",
+      "input": {
+        "expiresAt": "2026-09-22T00:00:00Z",
+        "renewBeforeSeconds": 86400,
+        "renewOperation": "subscription_renew",
+        "now": "2026-09-20T23:59:59Z"
+      },
+      "expected": {
+        "renewAt": "2026-09-21T00:00:00.000Z",
+        "state": "active",
+        "action": "none"
+      }
+    },
+    {
+      "id": "0004-expired-at-the-boundary-beats-due",
+      "title": "Exactly at expiresAt the lease is EXPIRED, and expired wins over due",
+      "since": "0.26.0",
+      "input": {
+        "expiresAt": "2026-09-22T00:00:00Z",
+        "renewBeforeSeconds": 86400,
+        "renewOperation": "subscription_renew",
+        "now": "2026-09-22T00:00:00Z"
+      },
+      "expected": {
+        "renewAt": "2026-09-21T00:00:00.000Z",
+        "state": "expired",
+        "action": "resync"
+      }
+    },
+    {
+      "id": "0005-one-second-before-expiry-is-still-renewable",
+      "title": "One second before expiry the lease is due, not expired",
+      "since": "0.26.0",
+      "input": {
+        "expiresAt": "2026-09-22T00:00:00Z",
+        "renewBeforeSeconds": 86400,
+        "renewOperation": "subscription_renew",
+        "now": "2026-09-21T23:59:59Z"
+      },
+      "expected": {
+        "renewAt": "2026-09-21T00:00:00.000Z",
+        "state": "due",
+        "action": "renew"
+      }
+    },
+    {
+      "id": "0006-now-long-before-is-simply-active",
+      "title": "A now far before the lease (clock skew, or a lease issued for the future) is active — nothing clamps",
+      "since": "0.26.0",
+      "input": {
+        "expiresAt": "2026-09-22T00:00:00Z",
+        "renewBeforeSeconds": 86400,
+        "renewOperation": "subscription_renew",
+        "now": "2020-01-01T00:00:00Z"
+      },
+      "expected": {
+        "renewAt": "2026-09-21T00:00:00.000Z",
+        "state": "active",
+        "action": "none"
+      }
+    },
+    {
+      "id": "0007-missed-by-a-week-is-resync",
+      "title": "A lease nobody renewed is resync, however long ago it lapsed",
+      "since": "0.26.0",
+      "input": {
+        "expiresAt": "2026-09-22T00:00:00Z",
+        "renewBeforeSeconds": 86400,
+        "renewOperation": "subscription_renew",
+        "now": "2026-09-29T00:00:00Z"
+      },
+      "expected": {
+        "renewAt": "2026-09-21T00:00:00.000Z",
+        "state": "expired",
+        "action": "resync"
+      }
+    },
+    {
+      "id": "0008-offset-and-zulu-are-one-instant",
+      "title": "An expiry with a +02:00 offset and a Zulu now compare as instants",
+      "since": "0.26.0",
+      "input": {
+        "expiresAt": "2026-09-22T02:00:00+02:00",
+        "renewBeforeSeconds": 3600,
+        "renewOperation": "channel_create",
+        "now": "2026-09-21T23:30:00Z"
+      },
+      "expected": {
+        "renewAt": "2026-09-21T23:00:00.000Z",
+        "state": "due",
+        "action": "renew"
+      }
+    },
+    {
+      "id": "0009-fractional-seconds-parse",
+      "title": "Fractional seconds do not break the comparison",
+      "since": "0.26.0",
+      "input": {
+        "expiresAt": "2026-09-22T00:00:00.500Z",
+        "renewBeforeSeconds": 60,
+        "renewOperation": "subscription_renew",
+        "now": "2026-09-21T23:59:00.400Z"
+      },
+      "expected": {
+        "renewAt": "2026-09-21T23:59:00.500Z",
+        "state": "active",
+        "action": "none"
+      }
+    },
+    {
+      "id": "0010-an-epoch-is-refused-not-guessed",
+      "title": "A Google-shaped epoch-milliseconds expiry is refused — the connector converts, the lease never guesses units",
+      "since": "0.26.0",
+      "input": {
+        "expiresAt": "1789430400000",
+        "renewBeforeSeconds": 86400,
+        "renewOperation": "channel_create",
+        "now": "2026-09-18T00:00:00Z"
+      },
+      "expected": {
+        "refused": "expiresAt"
+      }
+    },
+    {
+      "id": "0011-zero-margin-is-refused",
+      "title": "renewBeforeSeconds of 0 is refused: due would be unreachable, and nobody would renew",
+      "since": "0.26.0",
+      "input": {
+        "expiresAt": "2026-09-22T00:00:00Z",
+        "renewBeforeSeconds": 0,
+        "renewOperation": "subscription_renew",
+        "now": "2026-09-18T00:00:00Z"
+      },
+      "expected": {
+        "refused": "renewBeforeSeconds"
+      }
+    },
+    {
+      "id": "0012-negative-margin-is-refused",
+      "title": "A negative renewBeforeSeconds is refused",
+      "since": "0.26.0",
+      "input": {
+        "expiresAt": "2026-09-22T00:00:00Z",
+        "renewBeforeSeconds": -60,
+        "renewOperation": "subscription_renew",
+        "now": "2026-09-18T00:00:00Z"
+      },
+      "expected": {
+        "refused": "renewBeforeSeconds"
+      }
+    },
+    {
+      "id": "0013-no-renew-operation-is-refused",
+      "title": "A lease with no renew operation is refused — a due lease with nothing to call is one nobody renews",
+      "since": "0.26.0",
+      "input": {
+        "expiresAt": "2026-09-22T00:00:00Z",
+        "renewBeforeSeconds": 86400,
+        "renewOperation": "",
+        "now": "2026-09-18T00:00:00Z"
+      },
+      "expected": {
+        "refused": "renewOperation"
+      }
+    }
+  ]
+}

package/suites/shared/subscription-lease/manifest.json

@@ -0,0 +1,41 @@
+{
+  "$schema": "../../../schema/suite-manifest.schema.json",
+  "suite": "shared/subscription-lease",
+  "title": "A subscription that EXPIRES, and when the host must act on it",
+  "since": "0.26.0",
+  "caseFormat": "table",
+  "cases": "cases.json",
+  "contract": {
+    "summary": "A `subscription` trigger is a webhook the provider stops delivering unless somebody renews it. The lease is the provider's expiry plus the connector's declaration of how early to renew and which operation does it, so a host runs ONE renewal scheduler for every expiring trigger instead of one per connector. `state` says where the lease is; `action` says what the host does about it.",
+    "functions": {
+      "renewAt": "renewAt(lease) -> instant  (expiresAt - renewBeforeSeconds)",
+      "state": "state(lease, now) -> active | due | expired",
+      "action": "action(lease, now) -> none | renew | resync"
+    },
+    "reference": "authored",
+    "referenceNote": "Boundaries are decided here, not measured: `due` is INCLUSIVE at renewAt, `expired` is INCLUSIVE at expiresAt and wins over `due` (Microsoft Graph refuses to renew a subscription that has expired; a Google Calendar channel simply stops). A missed lease is `resync`, never a quiet re-create: notifications during the gap are gone, so the host must re-list (sync token or full) AND re-subscribe.",
+    "implementations": [
+      {
+        "language": "node",
+        "package": "@particle-academy/fancy-connector-core",
+        "symbol": "subscriptionLease / leaseRenewAt / leaseState / leaseAction from \"@particle-academy/fancy-connector-core\""
+      },
+      {
+        "language": "php",
+        "package": "particle-academy/fancy-connector-core",
+        "symbol": "ParticleAcademy\\Connectors\\SubscriptionLease (renewAt(), state(), action())"
+      }
+    ]
+  },
+  "notes": [
+    "The lease carries the provider's expiry as an RFC 3339 INSTANT. Google Calendar hands back `expiration` as an epoch in MILLISECONDS as a string, Graph hands back `expirationDateTime` as ISO 8601 — the CONNECTOR converts on the way in; the lease refuses anything that is not an instant (case 0010) rather than guessing units.",
+    "`renewBeforeSeconds` must be positive (cases 0011, 0012). Zero would make `due` unreachable — the moment it applies is the moment `expired` wins — which is a lease nobody ever renews, declared in a way nothing would report.",
+    "`renewOperation` names the operation the host calls when the lease is due. For Graph that is a renew; for Google Calendar, whose channels cannot be renewed, it is the create again (the connector stops the old channel itself). The lease does not know the difference and does not need to: it says WHEN, the connector says WHAT.",
+    "`expired` beats `due` at the same instant (case 0004): a lease that has just expired cannot be renewed, so the only honest action is resync.",
+    "Clock skew clamps nothing here, unlike isReplaySafe: a `now` before renewAt is simply `active` (case 0006), because there is no earlier attempt to have forgotten.",
+    "LANDED AS AUTHORED. Taken from fancy-connector-core v0.7.0 `fixtures/subscription-lease/cases.json` (weaver.agi, owner-approved lease vocabulary 2026-09-14). Rows, contract and notes are unchanged; only the split into manifest.json + cases.json and a per-row `since` were added to fit this repository's format. Core deletes its local copy and reads this suite once it pins this release, so the table lives in one place.",
+    "EVERY ROW EXERCISES ALL THREE FUNCTIONS, so no row names an `fn`: a row pins `renewAt`, `state` and `action` together, or pins that constructing the lease is refused and names the field. A runner returns `{refused: <field>}` for a refusal and `{renewAt, state, action}` otherwise, with `renewAt` as an RFC 3339 instant in UTC with milliseconds (`...T00:00:00.000Z`).",
+    "PYTHON IS NOT LISTED: fancy-connector-core has no Python port yet. It joins the `implementations` when that package exists.",
+    "THERE IS A DISCRIMINATION PROBE (tests/discrimination-subscription-lease.test.ts): a faithful lease passes every row, and each mutant a competent author would write -- an exclusive `due`, an exclusive `expired`, `due` winning over `expired`, a missed lease re-created instead of resynced, an epoch guessed as milliseconds, a zero margin allowed, an offset dropped, fractional seconds truncated -- fails an exact set of rows."
+  ]
+}