Background jobs / Compatibility lab

Job Payloads & Rolling Deployments

Can every worker that might receive a queued job still understand its shape and preserve its business intent?

Interactive calculations run in your browser; the initial example is pre-rendered. There are no accounts, uploads, or live queue connections. Inputs stay in page memory; the site does not persist them, put them in URLs, or send them to analytics. A worksheet download includes only what you explicitly export.

Choose a rollout and an independent business intent

Already-queued payload version

1: legacy cents; 2: explicit currency; 3: nested amount.

New producer payload version

New payloads remain durable even if the deployment rolls back.

Previous / rollback reader

Still reachable during a mixed rollout and after rollback.

New worker reader

A strict new shape can strand older queued messages.

Intended business currency

V1 cannot encode EUR; a loose reader may silently assume USD.

Intended amount (minor units)

An integer fixture, not a payment or exchange-rate conversion.

Compatibility across the queue's lifetime

At least one reachable reader/payload pair rejects or changes intent

PHASE 01

Before deployment

0 incompatible / 1 reachable pairs

V1 + v2: preserves-intent

PHASE 02

Mixed rolling pool

2 incompatible / 4 reachable pairs

V1 + v2: preserves-intent
V1 + v3-strict: rejected
V3 + v2: rejected
V3 + v3-strict: preserves-intent

PHASE 03

New workers, delayed old jobs

1 incompatible / 2 reachable pairs

V1 + v3-strict: rejected
V3 + v3-strict: preserves-intent

PHASE 04

Rollback with new payloads still queued

1 incompatible / 2 reachable pairs

V1 + v2: preserves-intent
V3 + v2: rejected

PHASE 05

Replay after rollout

1 incompatible / 2 reachable pairs

V1 + v3-strict: rejected
V3 + v3-strict: preserves-intent

A successful parse can still change a charge's currency. Check the independent expected intent, not only the JSON shape. The dual-reader example assumes that compatible reader was already deployed to the entire previous pool before emitting V3 payloads; rollback must retain it too.

All twelve fixed producer/reader pairs, including those outside the selected rollout
Producer	Reader	Contract outcome	Interpretation
V1	Legacy reader: cents, assumes USD	preserves-intent	Reader interprets 1200 USD minor units; intended 1200 USD.
V1	V2 reader: legacy + explicit currency	preserves-intent	Reader interprets 1200 USD minor units; intended 1200 USD.
V1	V3 reader: nested amount only	rejected	Reader rejects this shape/version; no effect is applied.
V1	V3 dual reader: all three profiles	preserves-intent	Reader interprets 1200 USD minor units; intended 1200 USD.
V2	Legacy reader: cents, assumes USD	preserves-intent	Reader interprets 1200 USD minor units; intended 1200 USD.
V2	V2 reader: legacy + explicit currency	preserves-intent	Reader interprets 1200 USD minor units; intended 1200 USD.
V2	V3 reader: nested amount only	rejected	Reader rejects this shape/version; no effect is applied.
V2	V3 dual reader: all three profiles	preserves-intent	Reader interprets 1200 USD minor units; intended 1200 USD.
V3	Legacy reader: cents, assumes USD	rejected	Reader rejects this shape/version; no effect is applied.
V3	V2 reader: legacy + explicit currency	rejected	Reader rejects this shape/version; no effect is applied.
V3	V3 reader: nested amount only	preserves-intent	Reader interprets 1200 USD minor units; intended 1200 USD.
V3	V3 dual reader: all three profiles	preserves-intent	Reader interprets 1200 USD minor units; intended 1200 USD.

Versioned JSON fixtures and expected intent

{
  "expected": {
    "amountMinor": 1200,
    "currency": "USD"
  },
  "payloads": [
    {
      "schemaVersion": 1,
      "job": "charge",
      "accountId": "account-demo",
      "amountCents": 1200
    },
    {
      "schemaVersion": 2,
      "job": "charge",
      "accountId": "account-demo",
      "amountCents": 1200,
      "currency": "USD"
    },
    {
      "schemaVersion": 3,
      "job": "charge",
      "accountId": "account-demo",
      "amount": {
        "minor": 1200,
        "currency": "USD"
      }
    }
  ]
}

The queue outlives the deployment

A rename can break parsing; an optional currency field can be worse if a loose reader accepts it and silently assumes another currency. Deploy compatible readers before new producers, preserve delayed payload support, and include rollback and replay in the fixture set. Passing these small example profiles is not a certificate for your schema migration or business rules.

Assumptions and limits

These fixed charge-job profiles exercise structural and semantic compatibility. They do not inspect your schemas, workers, database migrations, or real customer payloads.
V1 has amountCents and no currency; legacy readers assume USD. V2 adds currency. V3 moves the amount and currency into a nested object.
The legacy reader ignores unknown fields and version values. It may accept a V2 EUR payload but interpret it as USD. Structural acceptance is not preservation of intent.
The V2 reader supports V1 as USD and V2 with explicit currency. The strict V3 reader only accepts V3; the dual reader preserves all three supported profiles.
A mixed pool can hand any queued job to either reader. The lab reports reachable incompatibilities, not failure percentages or an assumed routing distribution.
Old and new payloads remain queued through deploy, delayed delivery, rollback, and replay. Rolling back code does not rewrite durable payloads.
The expected intent is independently supplied by the example. V1 cannot faithfully encode a non-USD intent. Real migrations also need authorization, idempotency, retention, and business-invariant checks.