Many writes, one UNWIND

Three earlier lessons leaned on this one package without opening it: L4 said writes are "coalesced" into UNWINDs, L9 said they flow through "two lanes with a DLQ + halt," and L31 said a statement with a WITH is "non-coalescable." All three live in pkg/graphwrite. This lesson opens it — and the central trick is a small piece of misdirection: a transaction object that doesn't actually run anything.

1 · The recorder is a Tx that buffers

Recorder implements the graphstore.Tx interface — but instead of executing, every neo4jExec call just appends the statement to a slice. Handlers call it once per event, writing clean one-event-at-a-time code; the recorder accumulates. When the batch closes, Statements() returns the buffer coalesced.

// handler code stays simple — one neo4jExec per event:
neo4jExec(ctx, tx, "MERGE (t {id:$tok})-[h:HOLDS]->(o {id:$holder}) SET h.qty=$q", params)
// …but tx is a *Recorder: that call RECORDS, it doesn't hit Memgraph.
// Statements() later folds all the recorded MERGEs into one UNWIND.

2 · coalesce by template — the core

coalesceByTemplate buckets the recorded statements by (Cypher text, sorted param-key set). Every statement sharing a template lands in one bucket; the bucket's rows are the per-statement params. At emit time each bucket becomes a single UNWIND $rows AS row <template>:

500 × "MERGE …HOLDS… SET h.qty=$q"  (one per Transfer)
        │  coalesceByTemplate
        ▼
1 × "UNWIND $rows AS row MERGE …HOLDS… SET h.qty=row.q"   with rows=[…500…]

3 · What's not coalescable — and L31's WITH

coalescable(s) is a four-gate predicate. A statement coalesces only if all hold:

Two levels of coalescing

The same function runs at two scopes. Intra-batch: within one applyBatch, fold repeated templates. Cross-entry (CoalesceAcrossEntries): the BatchAccumulator already runs N consecutive same-lane stream entries inside one ExecuteWrite (amortizing BEGIN/COMMIT); this flattens all their statements and runs the same coalesceByTemplate over the union — so a template repeated across entries collapses too. One coalescer, two fan-in levels.

4 · Lanes — partitioning the one writer

L9's "two lanes" live in lane_params.go. A (lane, chainID) pair derives a coherent set of Redis + lease coordinates (stream, consumer group, halt flag, lease key) via LaneParamsFor. The plan (FORTA-2843) is a physical split into a state lane and a meta lane under separate writers, so high-churn state writes can't head-of-line-block slower meta writes. Two guards keep it honest:

• The default lane ("") must derive bit-identical keys to the pre-lane wire — so shipping the lane machinery changes nothing until the split is deliberately turned on.
• AssertCoherent fails loudly at startup if a hand-assembled LaneParams has keys disagreeing on the lane — a misconfiguration caught before it can split-brain the stream.

5 · The DLQ — durability over XACK-and-forget

Finally L9's "DLQ + halt," and it's a direct enforcement of L8's block-determinism. The bug it fixed (dlq.go, FORTA-2642):

What you can now do

• Explain the recorder as a buffering Tx that lets handlers write one-event-at-a-time while the wire sees UNWINDs.
• Describe coalesceByTemplate (bucket by template+keys → one UNWIND) and the independence invariant it relies on.
• List the four coalescable gates and explain why WITH excludes a statement (closing L31).
• Distinguish intra-batch from cross-entry coalescing, and explain what lanes partition (and the default-lane bit-identical guard).
• Explain the DLQ-over-XACK fix and the halt-don't-skip rule as enforcement of L8 block-determinism.