Document why append may pair RETURNING rows with its input positionally (#120)

append walks the result set in lockstep with the list it was given, while
importEvents in the same class keys on the id it supplied and says why. Only one
of the two was explained, so the other read as an oversight.

It is not one: the NOT EXISTS is uncorrelated, so PostgreSQL evaluates it once as
an InitPlan and applies it as a One-Time Filter over the VALUES list, and every
node in that plan preserves order. Verified on PG16/17/18. Correlating that
predicate would let the planner turn it into an anti-join, which reorders --
measured at 1999 of 2000 rows mispaired, with positions still ascending, so a
defensive monotonicity check would not catch it either.

Javadoc only, no behaviour change.


Claude-Session: https://claude.ai/code/session_01JBdkFdTW5xgSmwMkSeiG9H

Co-authored-by: Claude <noreply@anthropic.com>

Author: vanrogu

sliceworkz-eventstore-infra-postgres/src/main/java/org/sliceworkz/eventstore/infra/postgres/PostgresEventStorageImpl.java

@@ -1329,6 +1329,26 @@ private long advisoryLockKey ( String scope ) {
 		}
 	}
 
+	/**
+	 * Appends events, pairing each {@code RETURNING} row with the input event at the same index.
+	 * <p>
+	 * Nothing promises that order — {@code RETURNING} is not in the SQL standard, and PostgreSQL
+	 * documents only "a row per row actually inserted". It holds because the {@code NOT EXISTS} below
+	 * is <em>uncorrelated</em>: it references the events table and bound parameters, never a column of
+	 * {@code new_events}. PostgreSQL therefore evaluates it once as an InitPlan and applies it as a
+	 * One-Time Filter over the VALUES list, and every node in that plan preserves order. Being
+	 * all-or-nothing is also what makes the {@code storedEvents.size() != events.size()} check below a
+	 * sound conflict detector — the statement inserts every row or none, never a subset.
+	 * <p>
+	 * Correlating that predicate with {@code new_events} would let the planner turn it into an
+	 * anti-join, which reorders and would silently mispair every event with another's id and position.
+	 * Note the rows would still carry ascending positions, since the reordering precedes the insert, so
+	 * a defensive monotonicity check would not catch it.
+	 * <p>
+	 * {@code importEvents} keys on the id it supplied instead, because {@code ON CONFLICT} makes its
+	 * result a subset of its input. That is not an option here: from PG18 the id comes from a
+	 * server-side {@code uuidv7()}, and {@code RETURNING} cannot return a source-only ordinal to key on.
+	 */
 	@Override
 	public List<StoredEvent> append(AppendCriteria appendCriteria, Optional<EventStreamId> streamId, List<EventToStore> events) {
 		checkNotClosed();