@xyo-network/event-kit-testing

Shared conformance harness for Event Kit provider ports.

const report = await runWakeQueueConformance('sqlite', {
  create: () => createSqliteWakeQueue({ path }),
  reopen: () => createSqliteWakeQueue({ path }),
})

Why a shared suite

A port is only swappable if every implementation agrees on the contract. The suite is what makes WakeQueue providers interchangeable rather than merely similar: adding a backend means implementing the interface and running this.

It throws on the first violated clause with the clause name and what it saw, and otherwise returns the full report, so one test surfaces which clauses ran.

Declared capability, not assumed

reopen is optional and is how a provider states it is durable. A subject that omits it has its durability clauses reported as skipped, never silently passed — an in-process queue must not appear to satisfy a clause it cannot. That keeps the report an honest description of what a provider proved.

WakeQueue clauses

| Clause | Property | |---|---| | empty-claim | An empty queue yields undefined rather than blocking | | append-visible | What was appended comes back intact | | lease-withholds | A held lease is invisible to other consumers | | release-returns | Releasing makes the entry claimable again | | ack-removes | Acking removes it permanently | | arrival-order | Entries are served in arrival order | | single-claimer | Exactly one claimer wins a contested entry | | recover-inflight | An abandoned lease is reclaimable | | survives-restart | Entries and acks outlive the instance (durable only) | | recovers-after-restart | A lease held at process death is reclaimable (durable only) |

single-claimer is the clause that catches the subtle failures — a provider built on rename rather than an atomic claim passes everything else and still hands one entry to two consumers.