Change-event callback order decision and oracle review

Reviewed code head: 63cc7122560cefbcfed7187abab7924c71302eff.
Starting head: 33a194941c8d51f8f98babb999fef2987dd6ff8b.
Source: DEC-01 in the code-weight audit's BUGS_AND_ORACLE_GAPS.md.
Primary owner: packages/db/tests/change-event-history-oracle.test.ts.

Decision and finding ledger

The maintainer decided that messages for different keys may appear in either order within one subscribeChanges callback. Messages for the same key retain their causal order. The public method and ChangeListener documentation now state this rule.

ID	Source claim and proposal	Technical verdict	PR action	Durable value
DEC-01.1	commitNextPendingTransactionBatch uses direct pending set order for changedKeys. STATE-10 may reorder callback messages. Compare batches as bags if order is free, or pin the order if promised.	Confirmed reordering risk. Cross-key order is free by maintainer decision. A whole-batch bag would erase same-key causal order.	Document the scoped contract and compare an ordered trace for each key.	The primary oracle and coverage map own the per-key law. STATE-10 may change cross-key order.

The audit note identified a real boundary and asked for a decision before changing tests. Its proposed alternatives were useful. The bag proposal needed the same-key qualification above. Reviewer assessment: technically accurate, high signal, and appropriately cautious about contract authority. Hire recommendation: yes for this class of review.

Reach and checker controls

A controlled public probe held a local transaction, queued and canceled a sync update for key 1, then completed direct edits of keys 2 and 1. The parent upsert map held [1, 2]; the direct set held [2, 1]. The final callback ended with update:2, update:1. This confirms that STATE-10 can change public cross-key order. The old owner passed 376 tests when a temporary production mutant reversed final sync events. It did not judge that order.

The new fixed history commits three sync transactions while publication is deferred. One callback contains insert, update, and delete messages for key 1, and insert plus two updates for key 2. A plain Map derives prior and final row values. The checker compares each key's ordered message trace, including type, value, prior value, and multiplicity. It does not compare positions across keys. It checks that publication produces exactly one callback and that final public rows match the model.

On the reviewed code head, the owner passed 377/377 tests. Two temporary production mutants challenged the new comparison:

Mutant	Result at the intended callback
Reverse the complete deferred publication list	Assertion failure. Key 1 arrived as delete, update, insert instead of insert, update, delete. Key 2's update sequence also reversed.
Reverse each sync transaction's final event list	Equivalent under this law. The focused test passed 1/1 because only distinct-key positions changed.

Both mutants were removed. The original code and final oracle pass together. The focused witness covers two keys, three immediate sync transactions, and one deferred callback. It does not establish every adapter, cancellation, reentrant callback, or arbitrary deferred history.

Oracle guide review

Requirement	Outcome
ORC-001 authority and limits	Pass. The maintainer decision and public API comments authorize the per-key law. The fixed history and limits appear above and in the executable owner.
ORC-002 independent judgment	Pass. A plain Map applies declared actions. It does not import Collection state, event composition, or key ordering.
ORC-003 visible responsibilities	Pass. The opening states the contract. applyModelOp and expectedEventTrace give the model. Fixed rounds give the grammar. Real sync commits and _deferPublication drive production. perKeyEventTrace compares the public callback.
ORC-004 generated grammar controls	Not triggered by the new fixed history. Existing generated local-mutation campaigns are unchanged. The fixed history uses legal absent-key inserts and present-key updates/deletes.
ORC-005 path and observation	Pass. The test reaches public subscribeChanges, observes zero callbacks before publication and one after, then compares per-key messages and final public rows.
ORC-006 checker calibration	Pass. Complete reversal fails at the per-key comparison. Distinct-key reversal passes at the same checkpoint. Neither is a setup failure or timeout.
ORC-007 fixed/random replay	Not triggered by this fixed witness. The owner's existing paired generated campaigns ran in the 377-test owner suite. Their replay interface is unchanged.
ORC-008 model-state minimality	Pass. The Map must retain each key's prior value to predict update and delete messages. Each per-key trace must retain order and duplicates. Different prior values or a reversed trace change the next public observation.
ORC-009 vocabulary mapping	Pass. One fixed round maps to one sync transaction. The model's Op is a declared sync action. Deferred publication combines three transactions into one callback. The Map is a reference model, not Collection state.
ORC-010 failure and cleanup	Pass. The shared cleanup helper preserves the primary mismatch and aggregates secondary failures. The driver releases its deferral, subscription, and Collection.
ORC-011 second formulation	Not triggered. No plausible fault shared by the simple Map and the production event derivation was named.
ORC-012 review evidence	This record gives the exact reviewed code head, applicable outcomes, non-applicable reasons, mutant classifications, and scope.

The loss audit finds one raw DEC-01 item and one disposition: resolved by a design decision and oracle law. No item lacks evidence. This PR changes no production event ordering. Future work on generated deferred histories belongs to the change-event history owner before claiming wider batch-shape coverage.