feat: multi-clause Cypher write composition (MERGE chains) via sequential staging

[bplatz]

Lifts the v1 restriction "MERGE must be the only write clause." A Cypher write statement may now chain write clauses — MERGE chains, CREATE+MERGE mixes, interleaved SET/REMOVE — with each clause observing the writes of the clauses before it and rows piping downstream, publishing as one atomic commit. The standard loading idioms now just work:

UNWIND $rows AS row
MERGE (a:Person {id: row.src})
MERGE (b:Person {id: row.dst})
MERGE (a)-[:KNOWS]->(b)

MATCH (p:Player)
MERGE (t:Team {name: p.team})
MERGE (p)-[:PLAYS_FOR]->(t)

Why a driver, not a rewrite

A single Txn evaluates its whole WHERE — including every MERGE NOT EXISTS guard — against one snapshot horizon, so it cannot express "later clause observes earlier clause" (the second MERGE's guard must see the first's creations). No single-transaction rewriting fixes that. Instead, the statement executes as an ordered sequence of sub-Txns over the same virtual-state machinery behind SPARQL ;-separated updates (D-10), now factored into a reusable SequentialStager: each clause stages against base + prior clauses' flakes, flakes fold last-wins re-stamped to the single final t+1, and one commit publishes — all-or-nothing.

What Cypher adds over SPARQL ;: row threading

Clauses pipe rows, not just graph state. The driver evaluates the read prefix as an ordinary read query into a row table (full read surface: MATCH, UNWIND, WITH incl. aggregation), then seeds each write clause with it — an UnresolvedPattern::Values of new PreBound binding cells, lossless for entities and typed literals. Per MERGE clause:

1. match probe — seeded VALUES ⋈ pattern against the virtual state;
2. dedup — absent rows key by their engine-evaluated identity tuple; the first row per distinct key creates (running ON CREATE SET);
3. re-bind — all rows re-match against the post-create state (Cypher's multi-match row multiplication included);
4. ON MATCH SET — applies to every non-creating row, including in-batch duplicate keys, which converges exactly on sequential per-row semantics.

CREATE-bound variables thread as reconstructed skolem Sids (VALUES-row ↔ solution order, pinned by test). Computed values in merge keys and SET positions ({name: p.team}, p.age + 1) hoist into engine-evaluated row columns before lowering. The previously-rejected node MERGE under a plain leading MATCH routes here too — one create per distinct key, every row bound, so the old "cartesian footgun" shape now has correct semantics.

Capability notes

• RETURN on multi-clause writes answers from the final row table with the full read expression surface — matched and created bindings, projections, modifiers — a strict superset of the created-entity-only reconstruction single-clause writes use. Embedded and Bolt return typed rows; HTTP carries the Cypher-JSON envelope back on the receipt. (Raft consensus supports sequential writes but rejects the RETURN-carrying combination pre-submission — its receipt path has no channel for rows.)
• All three write paths are wired: autocommit, Bolt explicit transactions (statements stage against the private state, so probes see earlier statements in the transaction), and the consensus committers — probes run under the write lock per retry attempt, preserving the existing no-TOCTOU contract, and probe views are policy-wrapped when governance carries policy inputs (same contract as conditional MERGE).
• In-batch duplicate keys: first row creates + ON CREATE SET, later rows match + ON MATCH SET — matching Neo4j's sequential LOAD CSV behavior. The single-clause UNWIND-batch last-wins dedup is now gated to single-clause statements (it keys on the first node MERGE and would drop legitimate rows of a chain).
• Deferred with clear errors: DELETE/FOREACH members in a chain, OPTIONAL MATCH / CALL { … } in the read prefix.

Non-impact

• JSON-LD / Turtle / SPARQL transaction paths untouched; stage() in fluree-db-transact unmodified.
• stage_transaction_from_txns keeps its single-op fast path; only its N≥2 loop body moved into SequentialStager (its 5 multi-op semantics tests pass unchanged).
• Single-clause Cypher writes keep their exact plans — detection fires only on statements that previously returned "unsupported" errors.

Testing

13 new API integration tests (it_cypher_seq_writes.rs) + 3 HTTP tests: chain idempotence, endpoint reuse, batch relationship upsert, MATCH…MERGE distinct-key creation, CREATE threading row-exactness, ON CREATE/ON MATCH branch firing across runs and within batches, interleaved SET, RETURN (embedded/Bolt/HTTP), zero-row no-ops, failing-clause atomicity, DELETE rejection, Bolt pipelining with read-your-writes. Full sweep of the six touched crates: 5,244 tests, 0 failures. Clippy all-features clean.

Design doc: docs/design/cypher-sequential-writes.md; Cypher guide updated.

Stacked on #1518 (base branch fix/cypher-kb-feedback).

[anh-h]

Great! This fixes the limitation I had worked around by splitting complex writes into sequential calls