Out-of-order delivery

Labels do not reliably send the XML before the audio, or the audio before the XML. //SCHEMA is built so the order does not matter.

The problem#

A DDEX delivery is a message — the ERN XML describing a release — plus the files it references. In practice they arrive in whatever order the sender's tooling uploads them: the audio first and the XML last, the XML first and the artwork an hour later, or a retry that resends half of it.

A system that required the message first would reject real deliveries. One that required the files first could never tell a slow delivery from a broken one. //SCHEMA accepts both orders and converges on the same result.

Expectations and arrivals#

When a message arrives, //SCHEMA records every file it references as an expectation: this delivery expects resources/A1_Signal_Fire.flac, with this checksum. The resources it describes exist from that moment, in state incoming.

When a file arrives, //SCHEMA stores it and records the arrival: this delivery received resources/A1_Signal_Fire.flac, with these bytes.

Whichever comes second completes the match. An expectation meeting its arrival attaches the bytes to the resource and moves it to stored. When the last expectation of a release is met, and it has cover art, the release goes active.

The delivery namespace#

A file and an expectation match only if they belong to the same delivery. That is what the delivery namespace is: over SFTP it is the directory the delivery was uploaded into; through the API it is the value deliverMessage returns.

It is compared exactly. A file delivered under a different namespace, or with a path spelled differently from the message's <File> element, will not match — it stays an orphan. That is the most common reason a delivery sits in blockedReleases.

Namespaces are also scoped to the delivery account over SFTP, so two partners who happen to choose the same directory name never match each other's files.

Why a resource can exist before its bytes#

Because the message can come first, a resource can be fully described — ISRC, title, credits, duration — with no file behind it. That is the incoming state, and it is normal, not an error. url is null until the file lands.

Nothing is lost by arriving early#

A file that arrives before its message is kept, not rejected. It is an orphan only in the sense that nothing is waiting for it yet; when the message arrives, the match happens then. A periodic sweep also re-checks anything both sides missed, so a delivery completes even if its last piece arrived at an unlucky moment.

Watching it converge#

A webhook shows the choreography as it happens. message.processed arrives when the XML has been read — with status: "partial" and a missingFileCount when files it declared have not arrived yet. message.completed follows when the last of them lands and is matched. Neither fires for a replayed message.

Replays are harmless#

Senders retry. //SCHEMA treats a repeated message as a duplicate and changes nothing, and a repeated file at the same path as a duplicate too. Delivering the same thing twice converges on the same state as delivering it once, which is what makes it safe to retry a failed upload without first finding out what succeeded.

Checksums#

If a message declares a checksum for a file and the file that arrives does not match, the resource is marked failed and the release is not promoted. Delivering the correct file clears it; no one has to intervene.