feat: Dead-letter Queue

[Chriztiaan]

Problem

When mutations are uploaded to the backend, non-transient/fatal errors in the flow can cause the upload pipeline to be stuck as it can't progress the uploaded queue. To avoid this, some of our demos call transaction.complete() on fatal errors to let the upload queue progress but in turn causing the mutation to be thrown out.

Solution

The PowerSync docs mention dead-letter queues as a mechanism for keeping these entries that would otherwise be lost. Fatal errors are caught on the server side and the mutation payload alongside debugging information is stored in a database allowing developers/admins to inspect the data and handle the entry however they need (replay, reshape, etc).

This PR introduces an example of how this could be implemented, alongside a hook that fires when a new dead-letter queue entry is added (typically users could use that to kick off a notification or even their reconciliation logic).

Outstanding

• Avoiding schema versioning (which might be important for reconciliation logic when schema issues were the cause for the entry).

Diagram

Data flow

AI disclosure

This PR was created with the help of Claude Code. Help constitutes assistance in research, planning, and rough outline of implementation. Beyond having a hand in the implementation, I have also manually tested this work.