Sync styles, changelog generation, and outgoing-sync filters

This document describes how Open-mSupply decides what records leave a site, what records arrive at a site, and over which transport. It is descriptive — read it to understand the rules, then go to the code if you need to see them in action.

Re-generating this document: see the bottom of the file.

1. Sync transports

A record that lands in the changelog can leave a site through one of three transports. They are not alternatives — a single record may travel on more than one of them depending on its sync style.

Coexistence:

• A v5 site keeps using the legacy transport, plus v6 selectively for the OMS-native tables.
• A v7 site uses only v7. v7 is a superset transport — it covers every table that has any sync style.
• A v7 site may additionally be flagged a multi-device site — one logical site (one site id) shared by several physical devices syncing independently. It then syncs only the subset of tables tagged for multi-device (see §2), and its pull drops the usual self-echo guard so a record authored on one device still reaches the others.

2. The classification matrix — two axes plus transport

A table's sync style is a point on a two-axis matrix, because two questions are genuinely independent:

• Authoring — who is allowed to create or edit this record and push it? This gates what a receiver accepts on an incoming push — checked both when central receives a push from a remote and when a remote receives one back.
• Distribution — which sites are eligible to receive this record on pull-down? This gates which sites central sends a row to.

A table has a set of authoring values and a set of distribution values, each OR'd: an incoming push is accepted if any one authoring clause accepts it, and a row reaches a site if any one distribution clause includes it. A third, separate tag records the transport (legacy v5 / OMS-native v6).

The axes are independent because some records need different answers on each: a clinician is authored on remotes (central must accept its push) yet must reach every site (so it broadcasts, rather than route to one owner). No single label can say "accept remote pushes and broadcast" — two axes can.

Authoring — what a receiver accepts on a push

Because authoring is a set, a push is accepted if any clause accepts it. A patient-typed name, for example, is tagged Central + Patient: central rejects it under the Central clause but accepts it under the Patient clause, so the only name-push central accepts is a patient one.

Distribution — who is an eligible recipient

The split between Remote and RemoteOwned is about write authority, not routing. Both styles use the same "owning site" predicate to pick a recipient. The difference shows up on the central → remote return path: for Remote tables central may legitimately have authored an edit on behalf of the site, so those rows are forwarded every cycle; for RemoteOwned tables central can't author edits, so the return path is suppressed except during initialisation (when the site needs a full snapshot to start from).

Central broadcasts a row when it carries no routing scope; a scoped row of a mixed table (for example a patient-typed name) is claimed by its own clause instead.

Transport-flag per table

Filters that ask for "v6 only" pull just the OMS-native tables. Filters that ask for "v5 only" pull just the legacy-only tables. Filters that pass no transport flag (used by v7) pull every table that has any sync style.

Multi-device flag per table

Independently of transport, every table carries a boolean multi-device flag. It matters only for a v7 site flagged as a multi-device site — one logical site whose single site id is shared by several physical devices. Such a site does not sync everything; it syncs only the tables whose multi-device flag is set. Two consequences follow from the shared site id:

• Reduced table set — both the multi-device site's push (rows it authored) and its pull (rows distributed to it) are intersected with the multi-device-tagged tables, so untagged tables never travel either way.
• No self-echo guard on pull — normally a site never pulls back rows it sourced (they carry its own source-site). But the devices on a multi-device site share one site id, so a row authored on one device looks self-sourced to the others. The multi-device pull therefore keeps those rows rather than excluding them, so edits relay between the devices.

The multi-device flag is shown as a column in §3 and consumed by the two multi-device filters in §6.

3. The matrix — every table by axis

One row per table, grouped by matrix cell (distribution-set and transport, with authoring alongside) so tables that route and validate identically sit together. Both authoring and distribution are sets — a push is accepted if any one authoring clause accepts it, and a row reaches a site if any one distribution clause includes it. The final column marks tables that sync on a multi-device site (see §2). The lists mirror the code exactly. Per-cell notes follow the table.

Per-cell notes

• RemoteOwned · RemoteOwned · v5 (IndicatorValue, LocationMovement, StockLine, Stocktake, …) — site-owned data on the legacy transport. A remote pushes these up to legacy 4D central, which fans them back out via its own routing. From the OMS central perspective there is nothing to send back, so the OMS-side return path is suppressed except at initialisation.
• RemoteOwned + Transfer · RemoteOwned + Transfer · v5 (Requisition, RequisitionLine) — site-owned plus a transfer counterpart store. The changelog records the row's own store and a transfer store, so the row routes to the owning site (RemoteOwned) and to the counterpart site (Transfer); a push is accepted from whichever site owns either store.
• RemoteOwned + Transfer + Patient · RemoteOwned + Transfer + Patient · v5 (Invoice, InvoiceLine) — adds patient routing on top of RemoteOwned+Transfer; an invoice also follows its patient (prescriptions only) through name-store-join.
• RemoteOwned · RemoteOwned · v6 (RnrForm, RnrFormLine, StockRelocation, StockRelocationLine) — site-owned data on the OMS-native transport. Central does not author edits; the return path is suppressed except at initialisation.
• Remote + Patient · Remote + Patient · v6 (Encounter, Vaccination, ContactTrace) — store-scoped clinical records that should also follow the patient. Each row carries the authoring store and the patient. The Remote clause delivers it to the owning site; the Patient clause delivers it to every other site that knows the patient. Authoring is Remote (not RemoteOwned): the owning site keeps accepting updates even after it has initialised.
• Remote · Remote · v5 (ActivityLog, Location, Sensor, TemperatureBreach, TemperatureLog, UserPermission, UserStoreJoin) — store-scoped data on the legacy transport that routes only to the site owning the referenced store, and on every cycle (the Remote distribution clause, not RemoteOwned). Remote authoring means the owning site keeps accepting these even after it has initialised, and the every-cycle return path exists because central may legitimately author edits to push back. The cold-chain and activity tables (ActivityLog, Location, Sensor, TemperatureBreach, TemperatureLog) are all multi-device-tagged, and that is why they sit here rather than in the RemoteOwned · RemoteOwned cell: on a multi-device site an edit made on one device must relay through central to the sibling devices every cycle, and those siblings must keep accepting it after they have initialised — behaviour only the Remote cell provides. For the user-access tables, UserStoreJoin is in practice authored on central (it originates from legacy 4D's user_store table); the Remote authoring clause simply means central would also accept a push from the owning site rather than rejecting it.
• Central · Central · v5 (Abbreviation, Barcode, …) — central data still served from legacy 4D. This bucket also acts as a catch-all for tables that exist in the changelog but haven't been classified into a more specific cell yet.
• Central · Central · v6 (AncillaryItem, AssetCatalogueItem, …) — authored on OMS central, fans out to every v6 site. Some (notably the vaccine-course family) are re-published to legacy 4D so v5-only stores still receive them (see §7).
• Central + Remote · Central + Remote · v6 (PluginData, Preference) — store-or-global data on the OMS-native transport. If the record carries a store it routes to the owning site (the Remote clause); if it doesn't it broadcasts to every site (the Central clause). Authoring is Central + Remote, so both central and the owning site may edit.
• Central + Patient · Central + Patient · v5 + v6 (Name) — names are central data — every site needs the full directory — but a patient-typed name additionally carries its own id as the patient on the changelog. Non-patient names route via the broadcast (Central) clause; patient names route via the Patient clause to every site that knows the patient. On central the Central authoring clause rejects and only the Patient clause accepts, so the only name-push central accepts is a patient name. Name is the only table tagged for both transports.
• Patient · Patient · v5 (Document, NameInsuranceJoin, ProgramEnrolment, ProgramEvent) — pure patient-scoped data on the legacy transport. The changelog row carries only the patient, no store, so routing is purely by Patient and the record follows the patient across stores.
• Anyone · Remote · v5 (NameStoreJoin, ItemStoreJoin, ClinicianStoreJoin) — store-scoped join tables that central accepts from any pusher (no authoring checks) and routes to the owning site on every cycle. NameStoreJoin in particular is rewritten on central whenever a name's patient visibility changes, whenever the customer/supplier flag on a name flips (which cascades across every site's join row for that name), or when a prescription is translated for a patient with no visibility in the prescription's store (central synthesizes the join so the patient syncs to the site holding the prescription — see §7); because central authors those edits, the return path is on every cycle.
• Anyone · Remote · v6 (Asset, AssetInternalLocation, AssetLog) — asset data on the OMS-native transport, accepted from any pusher and routed to the owning site on every cycle. AssetLog and AssetInternalLocation don't carry a store directly, so the changelog generator looks one up from a related row (see §5).
• Anyone · Central · v5 (Clinician) — remote-authored data that broadcasts to every site. The changelog row is keyless — no store, no patient — so it matches the broadcast predicate; the clinician's own store travels in the record data, where store-join and invoice foreign keys still resolve it.
• Anyone · Central · v6 (NameOmsFields, SyncFileReference) — keyless broadcast records that central accepts from any pusher and fans out to every site. NameOmsFields carries a name's properties (which live on the name row but sync as their own record); accepting from anyone is what lets a store edit the properties on its own name and have the change reach central — the record is keyless, so no store-scoped authoring clause could accept it. For SyncFileReference, every site receives every reference row; the file bytes themselves are negotiated separately by the file-sync pipeline — the origin site uploads them to central in the background, and a non-origin site fetches them from central on demand the first time the file is opened.
• Anyone · Central + Remote · v5 (SyncMessage) — accepted from any pusher, with a broadcast clause plus a Remote clause. The changelog store_id is populated from the message's destination store, so the routing matches PluginData / Preference: with a destination store only the owning site receives the message; without one it fans out to every site. Used to ship cross-site instructions like name/item/clinician merges from OMS central down to v7 remotes (see §7).
• Anyone · NotDistributed · v6 (ContactForm, SystemLog) — pushed up to OMS central; not sent back to remotes. On re-initialisation a site does not get its old contact-forms / system-logs back.
• LegacyOnly · NotDistributed · v5 (Site) — pushed to legacy 4D central; never re-sent down to remotes, and never a valid v7 record.

Special — MasterList

MasterList is in the Central/Central/v5 bucket, but its translator does not declare a changelog mapping for push, so nothing actually ships on the wire. The changelog entry exists purely so in-process processors can react to changes; legacy mSupply remains the source of truth and pushes master lists down via its own sync.

4. Changelog row metadata

Each changelog row carries a small set of metadata fields. Each filter joins through one of these fields to decide "is this row for me?".

The source-site field is always populated. When a record is authored locally, it's the current site. When a record is integrated from another site, the original source is preserved. This is what powers every echo guard.

5. How records become changelog rows

When a record is mutated, a changelog row is generated. The patterns differ by what fields the changelog needs.

For deletes, the same generator is used; only the row_action field changes.

6. Outgoing-sync filters

Seven filters compose the metadata above into "this site, this transport" predicates. The distribution-keyed filters read the distribution axis; the legacy-push filter reads the transport flag; the v7 push filter reads only the source-site field; the two multi-device filters additionally intersect with the per-table multi-device flag.

Per-distribution behaviour inside all-data-for-site

The filter joins changelog → store, changelog → transfer-store, changelog → name-store-join → patient-store. A row matches if any one of its applicable distribution clauses holds.

multi-device-all-data-for-site reuses exactly these per-distribution predicates (both filters share one helper, so they can't drift), then intersects the result with the multi-device-tagged tables and drops the self-source guard.

7. Translation

For v5 and v6, a per-table translator decides which transport actually carries a row, and reshapes it for the wire. Three directions exist:

Notable special cases:

For v7 there is no per-table translation step — the database row is serialised directly and deserialised on the other side. As a consequence, v7 push for a given table works whether or not its translator has a v6 opt-in. The one wire-shape exception is SyncFileReference, which serialises only its shared subset and merges on arrival (see the special cases above); a handful of other tables keep generic wire data but add integration-side behaviour on pull (store reassignment raising a re-sync request, for example).

8. The single useful invariant

A row reaches a site only if both of the following agree:

1. The matrix (authoring + distribution + transport flag) says the site is an eligible recipient on this transport.
2. The transport-specific machinery actually carries the row — for v5/v6 that's a translator opt-in; for v7 it's blanket (any table with a sync style).

The matrix answers who is eligible and in which direction. The transport answers which wire format. A row only moves when both agree.

How to regenerate this document

Run the slash command:

/sync-styles-doc

(skill defined at .claude/skills/sync-styles-doc/SKILL.md). It reads the current code and rewrites this file from scratch — useful after sync-style changes, new tables, or new translators.