sync-contract.md specifies what the back office must implement. It does not
say how to get a terminal talking to one, which is the question anyone
actually deploying this hits first.
Five hops, in the order they should be proved:
1. NATS with the MQTT gateway on — config snippet, narrow per-topic
permissions, and a file-backed JetStream stream, because a memory stream
loses a shop's bills on restart after the terminal has been told they
landed.
2. Pointing the terminal at it from Settings.
3. Watching a bill publish.
4. Consuming, committing, and acknowledging — with the table schema, an
idempotent insert, and the rule that the ack comes from the consumer after
the commit rather than from an ingest handler that merely queued the work.
5. The catalogue pull, and the mid-day push that triggers it.
Each hop has a command that proves it works, because a failure at hop 4 looks
identical to a failure at hop 2 from the terminal's side — it just keeps
queueing.
Plus a troubleshooting table mapping symptoms to causes (queue refilling with
the same bills means the ack arrived after the 20s timeout; two terminals
fighting for the connection means they share a client id), and a pre-rollout
checklist: back up the database before the one-way v7 migration, build
per-ABI to cut 69MB to ~23MB, change the seed PINs, turn TLS on.
Every topic, timeout, query parameter and pill label in the guide was checked
against the code rather than written from memory.
README now points at both documents and states the default: the terminal runs
against a local stub until it is configured.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
