Write immutable commits to a destination

Before you write anything

You need a registered destination that has been planned, registered, tested and read back. A destination that has never passed its test is not ready to receive a run.

You also need a terminal bundle. result-manifest.json is written last and is the only complete-bundle marker, so delivery of an unfinished bundle is delivery of nothing you can trust.

Choose create-new or versioned writes

Deliveries write new objects or new versions. They never modify an object that is already there.

Configure your destination target so that each delivery lands at a path or version that did not exist before. A run-scoped prefix or a version-aware table both satisfy this.

In-place overwrite is the one shape to avoid. It destroys the evidence that a second attempt disagreed with the first, which is what the rest of this page depends on.

Verify before you call it delivered

Delivery moves through its own states, and each one asks a different question.

1. AUTHORITY_READY — the destination authority is current and scoped.
2. WRITING — bytes are going out.
3. WRITTEN_UNVERIFIED — bytes are out, and nothing has checked them yet.
4. VERIFIED — what landed matches what the manifest declared.
5. COMMITTED — the provider's own commit succeeded.
6. CUSTOMER_ACKNOWLEDGED — you confirmed you took it.

WRITTEN_UNVERIFIED is not delivery. Verify against the manifest's file list, byte counts and declared integrity digests before you move on.

VERIFIED is still not delivery either. Many stores treat a write and a commit as separate acts, and only the provider's own commit makes the bytes visible to readers.

Detect a conflicting replay

Destination writes carry their own idempotency scope. An exact replay of the same write returns the prior result, so a network retry is safe.

The same identity with a different payload digest is different. That is equivocation, and it refuses rather than overwriting — you get COMMIT_CONFLICT, not a silently replaced file.

Treat that refusal as information. Something asked to write different bytes to a place accepted bytes already occupy, and the accepted bytes won.

What success looks like

The delivery record reaches COMMITTED, and then CUSTOMER_ACKNOWLEDGED once your side confirms. The object in your store carries the run's own path or version, with nothing displaced.

The manifest's file list, counts and digests match what your store now holds. You can name which job produced each object without reading the file.

If a commit conflicts

Do not force the write. Read the existing object first and compare its digest against the manifest.

If the digests match, the write already succeeded and the conflict is a duplicate attempt. Acknowledge the original and stop.

If the digests differ, two different payloads are competing for one target. Deliver to a new path or version, then work out which run produced the object already in place before you change anything.

If the destination authority lapsed mid-write, that is AUTHORITY_EXPIRED and it is not a compute failure. Reauthorize and resume the same bundle, following retry delivery without rerunning the job. Every state and its next action is listed in delivery states and acknowledgements.