12. Routing follow-up queries (reads & writes)

A result row including a c/uid/value, a COMPOSITION/VERSION uid, already contains the owning system id. No separate routing token is needed, and no uid is ever rewritten (N22).

The Tier’s registry (N21) maps creating_system_id/system_id → CDR base URL. The registry MUST include every observed creating_system_id, not just node `system_id`s, because a CDR can ingest versions created elsewhere (imported compositions, §10.2).

A versioned write (a CONTRIBUTION/commit against an existing object) MUST be routed to the single controlling CDR - the one whose system_id equals the creating_system_id of the target object. The Tier MUST reject (400) a write it cannot unambiguously route (N23).

New-object creation MUST target an explicitly chosen node - named via FROM ENDPOINT or the equivalent openEHR-federation-endpoint header (§8). Creating a new object that spans multiple nodes is disallowed in v1 (§2.3), matching the White Paper’s "Handling new records" caution that a façade needs a definite rule and multi-server references might not be allowed.

On every write, the Tier MUST convey the authenticated client identity to the target CDR (N24, §13).

A write derived from a de-duplicated row is routed by these same rules, and MUST NOT be sent to a node that merely holds an imported copy - see the hazard in §10.3.

The explicitly chosen node for a new object MAY be named by the FROM ENDPOINT directive, by the openEHR-federation-endpoint header, or by the request path (§8.4); for a non-AQL write the header or path is the only available mechanism.

A gateway MUST route each {base}/v1/definition/… request (template upload/retrieval, stored-query management) to a single, explicitly chosen node (§7a.1). It MUST NOT pick a node implicitly, and it MUST NOT present a union of nodes' templates as though it were one catalogue, because a client cannot act on a catalogue whose entries live in different places. (N43.)

A gateway MAY support fan-out template upload: a single PUT of an OPT/ADL template is applied to all member nodes (or to a named subset), so that a subsequent COMPOSITION commit validates wherever it lands. If offered, it MUST be:

Template upload is the only fan-out write this specification permits, and it is permitted because a template is idempotent, identical across nodes, and not patient data. None of that holds for a COMPOSITION. The v1 prohibition on creating clinical objects across multiple nodes is unchanged (N23, §2.3): a fanned-out COMPOSITION create would produce N distinct objects with N distinct uids, all purporting to be one clinical fact.

Where fan-out upload is not supported, the deployment MUST have another way to keep templates consistent, whether out-of-band template distribution or a shared template repository. A gateway SHOULD surface a template-missing validation failure from a node as a node-reported error (§11.2) instead of masking it.

A stored query is the other artefact under {base}/v1/definition/…, and single-node routing serves it less well than it serves a template. §12.7 offers a gateway an additive alternative: hold the definition itself, and fan the query out at execution time.

A gateway MAY offer a federated stored-query registry. If it does, the gateway is authoritative for the definition. A PUT {base}/v1/definition/query/{qualified_query_name}/{version} stores the AQL at the gateway, and a POST {base}/v1/query/{qualified_query_name} (ITS-REST stored-query execution) expands that stored AQL and fans it out under the ordinary rules of §7 (subject resolution, per-node ehr_id scoping, combine and annotate) exactly as if the client had submitted the text inline. Offering the registry MUST be declared in OPTIONS {base}/ (§7a.2). (N44.)

Versioning is mandatory. ITS-REST already versions stored queries with a semver path segment, and the registry MUST reuse it instead of inventing a parallel one. A stored version is immutable: a gateway MUST NOT overwrite a definition in place, and MUST refuse a second PUT to a {name}/{version} pair it already holds. Changing a definition means a new version. Immutability makes two things possible: a result can be reproduced, because the definition that produced it still exists unaltered, and a drift check has a fixed definition for a node’s copy to be compared against. (N44.)

Fan-out of the definition to nodes is OPTIONAL, and follows the template-upload model of §12.6 exactly. Where a gateway distributes a stored-query definition to member nodes, that distribution MUST be opt-in and explicit, MUST be reported per node in the meta.federation.endpoints[] shape (§9.5), MUST NOT be presented as atomic (partial success reported as partial, successes never rolled back, overall success never reported while a node failed), and MUST be declared in OPTIONS {base}/. These are the four conditions of §12.6’s template fan-out, cited by reference so that the two cannot drift apart. A stored-query definition is distributed on the same terms as a template, for the same reason: it is idempotent, identical across nodes, and carries no patient data.

Why a definition may legitimately need to exist at the nodes too. Fan-out is optional, but a node may execute a query by name locally, outside any federated request, and a deployment may want the definition auditable at the point of execution and not only at the gateway that dispatched it.

Drift. Fanning definitions out introduces a hazard that §12.6 did not have: the registry’s copy and a node’s copy of the same {name}/{version} can diverge, through a failed distribution, a local PUT at the node, a restore, or a node admitted after the distribution ran. The gateway SHOULD be able to report, per node, whether that node’s copy matches the registry version. It MUST NOT silently execute against a node whose copy differs from the definition it is answering under. It has two acceptable options: dispatch the registry’s AQL (the definition the client named, which is the safe default and what the registry model implies), or report the divergence. It must not dispatch a node’s differing copy and present the result as the named query’s answer. Divergence is the only failure mode the registry adds beyond §12.6, and nothing surfaces it unless the deployment checks for it. (N44.)

Where the registry is not offered, §12.6 is unchanged and governs: {base}/v1/definition/… routes to a single explicitly chosen node, no merged catalogue is presented, and a stored query is that node’s. A gateway is fully conformant without a registry.

name in the result set. §9.1 notes that ITS-REST’s name member carries [{namespace}::]{query-name} and SHOULD be emitted when answering a stored query. Under the registry a gateway MUST emit it, naming the gateway’s stored query, the definition the client invoked, and never a node’s copy. A client that got rows back for a name it did not ask for cannot detect that from the envelope unless the gateway says which name it answered. (N44.)