fix(bb-distributed-table): deterministic GSI sort-key tie ordering in the mock

[osama-rizk]

Card

Bug Bash board (Starter Kit, DX P3): "bb-distributed-table: position-tie ordering nondeterministic (mock vs prod)" — Map insertion order vs DDB sort-key order; tied positions render differently.
🔗 https://github.com/orgs/aws-amplify/projects/141/views/15?pane=issue&itemId=195534546

Problem

A GSI sort key need not be unique, so several items can share one sort-key value (e.g. a position field). In query, the mock collects items from a Map and sorts by the index sort key, returning 0 for equal values — so tied rows keep Map insertion order. That order depends on write order and on disk-reload order (.bb-data), so mock results are nondeterministic and can diverge from deployed behavior. DynamoDB orders index rows with equal sort keys by the base-table primary key.

Fix

Tie-break on the base-table primary key (partition key, then sort key) via a small compareByBaseKey helper, instead of falling back to insertion order. The whole index order — ties included — still reverses under order: 'desc'. No change when the sort key is unique (the common base-table case).

Testing

New query (index sort-key ties) block (index.test.ts): a byPosition GSI with several cards sharing position:

• ties order by the base key (cardId), and the same result holds regardless of write order (deterministic);
• order: 'desc' reverses ties too;
• primary ordering stays by the index sort key — the base key only breaks ties.

@aws-blocks/bb-distributed-table suite 144 pass / 0 fail.

Verification

npm run lint 0 errors · umbrella-changeset guard ✅. Internal change (private comparator) — no public API change. Documented in DESIGN.md D-DT-6.

Changeset

@aws-blocks/bb-distributed-table patch + @aws-blocks/blocks patch (umbrella re-export).

Why no real-DynamoDB e2e for the tie order

The fix makes the mock deterministic by tie-breaking on the base-table key. It matches DynamoDB's observed ordering, but AWS doesn't document a contractual guarantee for how index rows with equal sort keys are ordered. An e2e that asserts a specific tie order against real DynamoDB would therefore be asserting unspecified behavior — brittle, and liable to flake if the service's internal ordering ever shifts. So the e2e is intentionally out of scope; the value here is reproducible local ordering (covered by the write-order-convergence unit tests), not pinning DynamoDB's contract. Documented in DESIGN.md D-DT-6.

[changeset-bot]

🦋 Changeset detected

Latest commit: 44b2046

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 2 packages

Name	Type
@aws-blocks/bb-distributed-table	Patch
@aws-blocks/blocks	Patch

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR