Queue Lease Semantics

A broker-agnostic lease manager for at-least-once message queues -- SQS, Pub/Sub, Service Bus, Redis Streams, and anything shaped like them. It does not talk to a queue: you hand it the lease facts your broker SDK already returned plus an injected clock, and it hands back typed decisions with reasons.

THE SILENT FAILURE. Four failures, none of which throw. All four are indistinguishable from success in your logs, your dashboards and your queue-depth graph. The only trace is in the effects: a customer charged twice, an email sent twice, a counter incremented twice.

VISIBILITY TIMEOUT SHORTER THAN THE WORK. The message becomes visible again while the first worker is still processing it, a second worker picks it up, and the job runs TWICE CONCURRENTLY. Both workers report success, because from each worker's point of view nothing went wrong.

ACKING AN EXPIRED LEASE. The first worker finishes late and deletes the message with a receipt handle from a lease that already expired -- acknowledging a delivery that is no longer its own. In some brokers that removes work another worker is midway through.

THE POISON MESSAGE LOOP. A message that always fails is retried forever. Throughput looks fine, queue depth looks stable, and one message quietly consumes a worker slot permanently.

HEARTBEAT DRIFT. A long job extends its lease on a timer and assumes the extension succeeded. If the broker refuses it -- already redelivered, lock already lost -- and the heartbeat call is a fire-and-forget boolean nobody checks, the worker keeps going believing it holds a lease it lost.

Each becomes a checkable question with a typed answer: isHeld(); an ack()/nack() that is REFUSED rather than silently accepted once a lease has expired; an extend() that cannot be mistaken for success because there is no boolean to ignore; a classifyDelivery() that names why a redelivery is happening; and a checkVisibilityTimeoutSafety() that turns 'is my timeout big enough' into an actual number before you ship rather than an incident after.

VERIFIED: 80 tests, re-measured by running the suite. Every mutation was observed FAILING before the source was restored. Independently reviewed by a verifier whose job was to find what is wrong, not to agree.

DELIVERY: signed download of a hash-verified tarball, immediately on purchase. Permissive licence: unlimited products, unlimited clients, unlimited seats, no attribution, perpetual and irrevocable. One restriction, do not republish the source as source.

Interface

What you call, and what comes back. Types and signatures only — the implementation ships with the source.

  export function classifyDelivery(ctx: DeliveryContext): DeliveryClassification;
  export function systemClock(): Clock;
  export function manualClock(startAt = 0): ManualClock;
  export function isDuplicateDelivery( candidateKey: string, seenKeys: ReadonlySet<string> | readonly string[] ): boolean;
  export function checkVisibilityTimeoutSafety( input: VisibilityTimeoutSafetyInput ): VisibilityTimeoutSafetyResult;

  export type PriorOutcome = "timeout" | "nack";
  export type DeliveryClassification = | { kind: "first-attempt";
  export type LeaseStatus = | { state: "held";