amduat/docs/tgk-ordering-enforcement.md

TGK Ordering Enforcement

Status: Draft Scope: Canonical ordering rules for TGK/STORE/1 and where to enforce them in adapters and query pipelines.

---

1. Purpose

TGK/STORE/1 defines a canonical deterministic ordering for all edge and neighbor query results. This document records the rule and the enforcement points so implementations do not drift.

---

2. Canonical Ordering Rules

2.1 Edge Ordering

All adjacency and scan results MUST be ordered by:

1. For each edge (edge_ref, body), form:

   order_key(edge_ref) = hash_id_bytes || digest_bytes

2. hash_id_bytes is edge_ref.hash_id encoded as big-endian u16.

3. digest_bytes is the raw edge_ref.digest.

4. Sort edges in ascending lexicographic order of order_key(edge_ref).

This is the normative ordering defined by TGK/STORE/1 and is equivalent to sorting by canonical ReferenceBytes.

2.2 Neighbor Ordering

If neighbors is implemented, neighbor results MUST be ordered by:

1. For each node n, form:

   node_order_key(n) = hash_id_bytes || digest_bytes

2. hash_id_bytes is n.hash_id encoded as big-endian u16.

3. digest_bytes is the raw n.digest.

4. Sort neighbors in ascending lexicographic order of node_order_key(n).

---

3. Enforcement Points

Ordering MUST be enforced by TGK/STORE/1 logic, not by backend defaults.

Acceptable enforcement points:

1. Adapter layer (preferred): apply ordering before returning GraphEdgeView lists.
2. Canonical result transformation layer: a shared sorting function used by all adapters.

Disallowed enforcement:

1. Relying on JanusGraph traversal order.
2. Relying on Elasticsearch sort order.
3. Any backend-specific implicit ordering.

---

4. Test Requirements

Conformance tests MUST verify:

1. Adjacency results are ordered per the canonical (hash_id, digest) rule.
2. scan_edges results follow the same ordering per page.
3. neighbors results use the canonical node ordering if the operation is exposed.
4. Cross-backend equivalence: the same snapshot yields identical ordered lists.

---

5. Implementation Notes

1. Sorting uses the canonical ReferenceBytes ordering for edge_ref and node references.
2. Ordering is snapshot-relative; it must be stable for a fixed snapshot.
3. If ES is used for candidate retrieval, the authoritative layer must re-apply ordering.